src/vnet/session/session.api

   1 /*
   2  * Copyright (c) 2015-2019 Cisco and/or its affiliates.
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 option version = "1.7.0";
  17
  18 /** \brief client->vpp, attach application to session layer
  19         ### WILL BE DEPRECATED POST 20.01 ###
  20     @param client_index - opaque cookie to identify the sender
  21     @param context - sender context, to match reply w/ request
  22     @param initial_segment_size - size of the initial shm segment to be
  23                                                           allocated
  24     @param options - segment size, fifo sizes, etc.
  25     @param namespace_id_len - length of the namespace id c-string
  26     @param namespace_id - 0 terminted c-string
  27 */
  28  define application_attach {
  29     u32 client_index;
  30     u32 context;
  31     u32 initial_segment_size;
  32     u64 options[16];
  33     u8 namespace_id_len;
  34     u8 namespace_id [64];
  35  };
  36
  37  /** \brief Application attach reply
  38         ### WILL BE DEPRECATED POST 20.01 ###
  39     @param context - sender context, to match reply w/ request
  40     @param retval - return code for the request
  41     @param app_event_queue_address - vpp event queue address or 0 if this
  42                                          connection shouldn't send events
  43     @param n_fds - number of fds exchanged
  44     @param fd_flags - set of flags that indicate which fds are to be expected
  45                                   over the socket (set only if socket transport available)
  46     @param segment_size - size of first shm segment
  47     @param segment_name_length - length of segment name
  48     @param segment_name - name of segment client needs to attach to
  49     @param app_index - index of the newly created app
  50     @param segment_handle - handle for segment
  51 */
  52 define application_attach_reply {
  53     u32 context;
  54     i32 retval;
  55     u64 app_event_queue_address;
  56     u8 n_fds;
  57     u8 fd_flags;
  58     u32 segment_size;
  59     u8 segment_name_length;
  60     u8 segment_name[128];
  61     u32 app_index;
  62     u64 segment_handle;
  63 };
  64
  65 /** \brief Application attach to session layer
  66     @param client_index - opaque cookie to identify the sender
  67     @param context - sender context, to match reply w/ request
  68     @param options - segment size, fifo sizes, etc.
  69     @param namespace_id_len - length of the namespace id c-string
  70     @param namespace_id - 0 terminted c-string
  71 */
  72  define app_attach {
  73     u32 client_index;
  74     u32 context;
  75     u64 options[16];
  76     u8 namespace_id_len;
  77     u8 namespace_id[64];
  78  };
  79
  80  /** \brief Application attach reply
  81     @param context - sender context, to match reply w/ request
  82     @param retval - return code for the request
  83     @param app_mq - app message queue
  84     @param vpp_ctrl_mq - vpp message queue for control events that should
  85                                          be handled in main thread, i.e., bind/connect
  86     @param vpp_ctrl_mq_thread_index - thread index of the ctrl mq
  87     @param app_index - index of the newly created app
  88     @param n_fds - number of fds exchanged
  89     @param fd_flags - set of flags that indicate which fds are to be expected
  90                                   over the socket (set only if socket transport available)
  91     @param segment_size - size of first shm segment
  92     @param segment_name_length - length of segment name
  93     @param segment_name - name of segment client needs to attach to
  94     @param segment_handle - handle for segment
  95 */
  96 define app_attach_reply {
  97     u32 context;
  98     i32 retval;
  99     u64 app_mq;
 100     u64 vpp_ctrl_mq;
 101     u8 vpp_ctrl_mq_thread;
 102     u32 app_index;
 103     u8 n_fds;
 104     u8 fd_flags;
 105     u32 segment_size;
 106     u8 segment_name_length;
 107     u8 segment_name[128];
 108     u64 segment_handle;
 109 };
 110
 111 /** \brief Application add TLS certificate
 112     @param client_index - opaque cookie to identify the sender
 113     @param context - sender context, to match reply w/ request
 114     @param cert_len - certificate length
 115     @param cert - certificate as a string
 116 */
 117 autoreply define application_tls_cert_add {
 118     u32 client_index;
 119     u32 context;
 120     u32 app_index;
 121     u16 cert_len;
 122     u8 cert[cert_len];
 123 };
 124
 125 /** \brief Application add TLS key
 126     @param client_index - opaque cookie to identify the sender
 127     @param context - sender context, to match reply w/ request
 128     @param key_len - certificate length
 129     @param key - PEM encoded key as a string
 130 */
 131 autoreply define application_tls_key_add {
 132     u32 client_index;
 133     u32 context;
 134     u32 app_index;
 135     u16 key_len;
 136     u8 key[key_len];
 137 };
 138
 139  /** \brief client->vpp, attach application to session layer
 140         ### WILL BE DEPRECATED POST 20.01 ###
 141     @param client_index - opaque cookie to identify the sender
 142     @param context - sender context, to match reply w/ request
 143 */
 144 autoreply define application_detach {
 145     u32 client_index;
 146     u32 context;
 147  };
 148
 149 /** \brief vpp->client, please map an additional shared memory segment
 150     @param client_index - opaque cookie to identify the sender
 151     @param context - sender context, to match reply w/ request
 152         @param fd_flags - set of flags that indicate which, if any, fds are
 153                                           to be expected over the socket. This is set only if
 154                                           socket transport available
 155     @param segment_size - size of the segment to be mapped
 156     @param segment_name - name of the segment to be mapped
 157     @param segment_handle - unique identifier for segment
 158 */
 159 autoreply define map_another_segment {
 160     u32 client_index;
 161     u32 context;
 162     u8 fd_flags;
 163     u32 segment_size;
 164     u8 segment_name[128];
 165     u64 segment_handle;
 166 };
 167
 168 /** \brief vpp->client unmap shared memory segment
 169     @param client_index - opaque cookie to identify the sender
 170     @param context - sender context, to match reply w/ request
 171     @param segment_name - segment name
 172     @param segment_handle - handle of the segment to be unmapped
 173 */
 174 autoreply define unmap_segment {
 175     u32 client_index;
 176     u32 context;
 177     u64 segment_handle;
 178 };
 179
 180  /** \brief Bind to a given URI
 181         ### WILL BE DEPRECATED POST 20.01 ###
 182     @param client_index - opaque cookie to identify the sender
 183     @param context - sender context, to match reply w/ request
 184     @param accept_cookie - sender accept cookie, to identify this bind flavor
 185     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 186                  "tcp://::/0/80" [ipv6] etc.
 187     @param options - socket options, fifo sizes, etc.
 188 */
 189 autoreply define bind_uri {
 190   u32 client_index;
 191   u32 context;
 192   u32 accept_cookie;
 193   u8 uri[128];
 194 };
 195
 196 /** \brief Unbind a given URI
 197         ### WILL BE DEPRECATED POST 20.01 ###
 198     @param client_index - opaque cookie to identify the sender
 199     @param context - sender context, to match reply w/ request
 200     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 201                  "tcp://::/0/80" [ipv6], etc.
 202     @param options - socket options, fifo sizes, etc.
 203 */
 204 autoreply define unbind_uri {
 205   u32 client_index;
 206   u32 context;
 207   u8 uri[128];
 208 };
 209
 210 /** \brief Connect to a given URI
 211         ### WILL BE DEPRECATED POST 20.01 ###
 212     @param client_index - opaque cookie to identify the sender
 213     @param context - sender context, to match reply w/ request
 214     @param client_queue_address - binary API client queue address. Used by
 215                                                           local server when connect was redirected.
 216     @param options - socket options, fifo sizes, etc. passed by vpp to the
 217                                  server when redirecting connects
 218     @param uri - a URI, e.g. "tcp4://0.0.0.0/0/80"
 219                  "tcp6://::/0/80" [ipv6], etc.
 220 */
 221 autoreply define connect_uri {
 222   u32 client_index;
 223   u32 context;
 224   u64 client_queue_address;
 225   u64 options[16];
 226   u8 uri[128];
 227 };
 228
 229 /** \brief bidirectional disconnect API
 230         ### WILL BE DEPRECATED POST 20.01 ###
 231     @param client_index - opaque cookie to identify the sender
 232                           client to vpp direction only
 233     @param context - sender context, to match reply w/ request
 234     @param handle - session handle obtained from accept/connect
 235 */
 236 define disconnect_session {
 237   u32 client_index;
 238   u32 context;
 239   u64 handle;
 240 };
 241
 242 /** \brief bidirectional disconnect reply API
 243         ### WILL BE DEPRECATED POST 20.01 ###
 244     @param client_index - opaque cookie to identify the sender
 245                           client to vpp direction only
 246     @param context - sender context, to match reply w/ request
 247     @param retval - return code for the request
 248     @param handle - session handle
 249 */
 250 define disconnect_session_reply {
 251   u32 context;
 252   i32 retval;
 253   u64 handle;
 254 };
 255
 256 /** \brief Bind to an ip:port pair for a given transport protocol
 257         ### WILL BE DEPRECATED POST 20.01 ###
 258     @param client_index - opaque cookie to identify the sender
 259     @param context - sender context, to match reply w/ request
 260     @param wrk_index - index of worker requesting the bind
 261     @param vrf - bind namespace
 262     @param is_ip4 - flag that is 1 if ip address family is IPv4
 263     @param ip - ip address
 264     @param port - port
 265     @param proto - protocol 0 - TCP 1 - UDP
 266     @param options - socket options, fifo sizes, etc.
 267 */
 268 autoreply define bind_sock {
 269   u32 client_index;
 270   u32 context;
 271   u32 wrk_index;
 272   u32 vrf;
 273   u8 is_ip4;
 274   u8 ip[16];
 275   u16 port;
 276   u8 proto;
 277   u64 options[16];
 278 };
 279
 280 /** \brief Unbind
 281         ### WILL BE DEPRECATED POST 20.01 ###s
 282     @param client_index - opaque cookie to identify the sender
 283     @param context - sender context, to match reply w/ request
 284     @param wrk_index - index of worker requesting the bind
 285     @param handle - bind handle obtained from bind reply
 286 */
 287 autoreply define unbind_sock {
 288   u32 client_index;
 289   u32 context;
 290   u32 wrk_index;
 291   u64 handle;
 292 };
 293
 294 /** \brief Connect to a remote peer
 295         ### WILL BE DEPRECATED POST 20.01 ###
 296     @param client_index - opaque cookie to identify the sender
 297     @param context - sender context, to match reply w/ request
 298     @param wrk_index - worker that requests the connect
 299     @param client_queue_address - client's API queue address. Non-zero when
 300                                   used to perform redirects
 301     @param options - socket options, fifo sizes, etc. when doing redirects
 302     @param vrf - connection namespace
 303     @param is_ip4 - flag that is 1 if ip address family is IPv4
 304     @param ip - ip address
 305     @param port - port
 306     @param proto - protocol 0 - TCP 1 - UDP
 307     @param hostname-len - length of hostname
 308     @param hostname - destination's hostname. If present, used by protocols
 309                                           like tls.
 310     @param parent_handle - handle of parent session (e.g. for opening quic streams).
 311 */
 312 autoreply define connect_sock {
 313   u32 client_index;
 314   u32 context;
 315   u32 wrk_index;
 316   u64 client_queue_address;
 317   u64 options[16];
 318   u32 vrf;
 319   u8 is_ip4;
 320   u8 ip[16];
 321   u16 port;
 322   u8 proto;
 323   u64 parent_handle;
 324   u8 hostname_len;
 325   u8 hostname[hostname_len];
 326 };
 327
 328 /** \brief ask app to add a new cut-through registration
 329         ### WILL BE DEPRECATED POST 20.01 ###
 330     @param client_index - opaque cookie to identify the sender
 331                           client to vpp direction only
 332     @param context - sender context, to match reply w/ request
 333     @param evt_q_address - address of the mq in ssvm segment
 334     @param peer_evt_q_address - address of peer's mq in ssvm segment
 335     @param wrk_index - index of worker to receive the registration
 336     @param n_fds - number of fds exchanged
 337     @param fd_flags - flag indicating the fds that will be exchanged over
 338                                   api socket
 339 */
 340 autoreply define app_cut_through_registration_add
 341 {
 342   u32 client_index;
 343   u32 context;
 344   u64 evt_q_address;
 345   u64 peer_evt_q_address;
 346   u32 wrk_index;
 347   u8 n_fds;
 348   u8 fd_flags;
 349 };
 350
 351 /** \brief add/del application worker
 352     @param client_index - opaque cookie to identify the sender
 353                           client to vpp direction only
 354     @param context - sender context, to match reply w/ request
 355     @param app_index - application index
 356     @param wrk_index - worker index, if a delete
 357     @param is_add - set if an add
 358 */
 359 define app_worker_add_del
 360 {
 361   u32 client_index;
 362   u32 context;
 363   u32 app_index;
 364   u32 wrk_index;
 365   u8 is_add;
 366 };
 367
 368 /** \brief Reply for app worker add/del
 369     @param context - returned sender context, to match reply w/ request
 370     @param retval - return code
 371     @param wrk_index - worker index, if add
 372     @param app_event_queue_address - vpp event queue address of new worker
 373     @param n_fds - number of fds exchanged
 374     @param fd_flags - set of flags that indicate which fds are to be expected
 375                                   over the socket (set only if socket transport available)
 376     @param segment_name_length - length of segment name
 377     @param segment_name - name of segment client needs to attach to
 378     @param segment_handle - handle for segment
 379 */
 380 define app_worker_add_del_reply
 381 {
 382   u32 context;
 383   i32 retval;
 384   u32 wrk_index;
 385   u64 app_event_queue_address;
 386   u8 n_fds;
 387   u8 fd_flags;
 388   u8 segment_name_length;
 389   u8 segment_name[128];
 390   u64 segment_handle;
 391   u8 is_add;
 392 };
 393
 394 /** \brief enable/disable session layer
 395     @param client_index - opaque cookie to identify the sender
 396                           client to vpp direction only
 397     @param context - sender context, to match reply w/ request
 398     @param is_enable - disable session layer if 0, enable otherwise
 399 */
 400 autoreply define session_enable_disable {
 401   u32 client_index;
 402   u32 context;
 403   u8 is_enable;
 404 };
 405
 406 /** \brief add/del application namespace
 407     @param client_index - opaque cookie to identify the sender
 408                           client to vpp direction only
 409     @param context - sender context, to match reply w/ request
 410     @param secret - secret shared between app and vpp
 411     @param sw_if_index - local interface that "supports" namespace. Set to
 412                          ~0 if no preference
 413     @param ip4_fib_id - id of ip4 fib that "supports" the namespace. Ignored
 414                         if sw_if_index set.
 415     @param ip6_fib_id - id of ip6 fib that "supports" the namespace. Ignored
 416                         if sw_if_index set.
 417     @param namespace_id_len - length of namespace id lower
 418     @param namespace_id - namespace id
 419 */
 420 define app_namespace_add_del {
 421   u32 client_index;
 422   u32 context;
 423   u64 secret;
 424   u32 sw_if_index;
 425   u32 ip4_fib_id;
 426   u32 ip6_fib_id;
 427   u8 namespace_id_len;
 428   u8 namespace_id[64];
 429 };
 430
 431 /** \brief Reply for app namespace add/del
 432     @param context - returned sender context, to match reply w/ request
 433     @param retval - return code
 434     @param appns_index - app namespace index
 435 */
 436 define app_namespace_add_del_reply
 437 {
 438   u32 context;
 439   i32 retval;
 440   u32 appns_index;
 441 };
 442
 443 /** \brief add/del session rule
 444     @param client_index - opaque cookie to identify the sender
 445                           client to vpp direction only
 446     @param context - sender context, to match reply w/ request
 447     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 448     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 449     @param lcl_ip - local ip
 450     @param lcl_plen - local prefix length
 451     @param rmt_ip - remote ip
 452     @param rmt_ple - remote prefix length
 453     @param lcl_port - local port
 454     @param rmt_port - remote port
 455     @param action_index - the only action defined now is forward to
 456                           application with index action_index
 457     @param is_add - flag to indicate if add or del
 458     @param appns_index - application namespace where rule is to be applied to
 459     @param scope - flag that indicates scope of the rule: global or local.
 460                    If 0, default is global, 1 is global 2 is local, 3 is both
 461 */
 462 autoreply define session_rule_add_del {
 463   u32 client_index;
 464   u32 context;
 465   u8 transport_proto;
 466   u8 is_ip4;
 467   u8 lcl_ip[16];
 468   u8 lcl_plen;
 469   u8 rmt_ip[16];
 470   u8 rmt_plen;
 471   u16 lcl_port;
 472   u16 rmt_port;
 473   u32 action_index;
 474   u8 is_add;
 475   u32 appns_index;
 476   u8 scope;
 477   u8 tag[64];
 478 };
 479
 480 /** \brief Dump session rules
 481     @param client_index - opaque cookie to identify the sender
 482     @param context - sender context, to match reply w/ request
 483  */
 484 define session_rules_dump
 485 {
 486   u32 client_index;
 487   u32 context;
 488 };
 489
 490 /** \brief Session rules details
 491     @param context - sender context, to match reply w/ request
 492     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 493     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 494     @param lcl_ip - local ip
 495     @param lcl_plen - local prefix length
 496     @param rmt_ip - remote ip
 497     @param rmt_ple - remote prefix length
 498     @param lcl_port - local port
 499     @param rmt_port - remote port
 500     @param action_index - the only action defined now is forward to
 501                           application with index action_index
 502     @param appns_index - application namespace where rule is to be applied to
 503     @param scope - flag that indicates scope of the rule: global or local.
 504                    If 0, default is global, 1 is global 2 is local, 3 is both
 505   */
 506 define session_rules_details
 507 {
 508   u32 context;
 509   u8 transport_proto;
 510   u8 is_ip4;
 511   u8 lcl_ip[16];
 512   u8 lcl_plen;
 513   u8 rmt_ip[16];
 514   u8 rmt_plen;
 515   u16 lcl_port;
 516   u16 rmt_port;
 517   u32 action_index;
 518   u32 appns_index;
 519   u8 scope;
 520   u8 tag[64];
 521 };
 522
 523 /*
 524  * Local Variables:
 525  * eval: (c-set-style "gnu")
 526  * End:
 527  */