src/vnet/session/session.api

   1 /*
   2  * Copyright (c) 2015-2016 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.2.1";
  17
  18 /** \brief client->vpp, attach application to session layer
  19     @param client_index - opaque cookie to identify the sender
  20     @param context - sender context, to match reply w/ request
  21     @param initial_segment_size - size of the initial shm segment to be
  22                                                           allocated
  23     @param options - segment size, fifo sizes, etc.
  24     @param namespace_id_len - length of the namespace id c-string
  25     @param namespace_id - 0 terminted c-string
  26 */
  27  define application_attach {
  28     u32 client_index;
  29     u32 context;
  30     u32 initial_segment_size;
  31     u64 options[16];
  32     u8 namespace_id_len;
  33     u8 namespace_id [64];
  34  };
  35
  36  /** \brief Application attach reply
  37     @param context - sender context, to match reply w/ request
  38     @param retval - return code for the request
  39     @param app_event_queue_address - vpp event queue address or 0 if this
  40                                          connection shouldn't send events
  41     @param n_fds - number of fds exchanged
  42     @param fd_flags - set of flags that indicate which fds are to be expected
  43                                   over the socket (set only if socket transport available)
  44     @param segment_size - size of first shm segment
  45     @param segment_name_length - length of segment name
  46     @param segment_name - name of segment client needs to attach to
  47 */
  48 define application_attach_reply {
  49     u32 context;
  50     i32 retval;
  51     u64 app_event_queue_address;
  52     u8 n_fds;
  53     u8 fd_flags;
  54     u32 segment_size;
  55     u8 segment_name_length;
  56     u8 segment_name[128];
  57 };
  58
  59 /** \brief Application add TLS certificate
  60     @param client_index - opaque cookie to identify the sender
  61     @param context - sender context, to match reply w/ request
  62     @param cert_len - certificate length
  63     @param cert - certificate as a string
  64 */
  65 autoreply define application_tls_cert_add {
  66     u32 client_index;
  67     u32 context;
  68     u32 app_index;
  69     u16 cert_len;
  70     u8 cert[cert_len];
  71 };
  72
  73 /** \brief Application add TLS key
  74     @param client_index - opaque cookie to identify the sender
  75     @param context - sender context, to match reply w/ request
  76     @param key_len - certificate length
  77     @param key - PEM encoded key as a string
  78 */
  79 autoreply define application_tls_key_add {
  80     u32 client_index;
  81     u32 context;
  82     u32 app_index;
  83     u16 key_len;
  84     u8 key[key_len];
  85 };
  86
  87  /** \brief client->vpp, attach application to session layer
  88     @param client_index - opaque cookie to identify the sender
  89     @param context - sender context, to match reply w/ request
  90 */
  91 autoreply define application_detach {
  92     u32 client_index;
  93     u32 context;
  94  };
  95
  96 /** \brief vpp->client, please map an additional shared memory segment
  97     @param client_index - opaque cookie to identify the sender
  98     @param context - sender context, to match reply w/ request
  99         @param fd_flags - set of flags that indicate which, if any, fds are
 100                                           to be expected over the socket. This is set only if
 101                                           socket transport available
 102     @param segment_size - size of the segment to be mapped
 103     @param segment_name - name of the segment to be mapped
 104 */
 105 autoreply define map_another_segment {
 106     u32 client_index;
 107     u32 context;
 108     u8 fd_flags;
 109     u32 segment_size;
 110     u8 segment_name[128];
 111 };
 112
 113 /** \brief vpp->client unmap shared memory segment
 114     @param client_index - opaque cookie to identify the sender
 115     @param context - sender context, to match reply w/ request
 116     @param segment_name -
 117 */
 118 autoreply define unmap_segment {
 119     u32 client_index;
 120     u32 context;
 121     u8 segment_name[128];
 122 };
 123
 124  /** \brief Bind to a given URI
 125     @param client_index - opaque cookie to identify the sender
 126     @param context - sender context, to match reply w/ request
 127     @param accept_cookie - sender accept cookie, to identify this bind flavor
 128     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 129                  "tcp://::/0/80" [ipv6] etc.
 130     @param options - socket options, fifo sizes, etc.
 131 */
 132 define bind_uri {
 133   u32 client_index;
 134   u32 context;
 135   u32 accept_cookie;
 136   u8 uri[128];
 137 };
 138 /** *** Will be DEPRECATED. Use message queue instead. *** */
 139 define bind_uri_reply {
 140   u32 context;
 141   u64 handle;
 142   i32 retval;
 143   u64 rx_fifo;
 144   u64 tx_fifo;
 145   u8 lcl_is_ip4;
 146   u8 lcl_ip[16];
 147   u16 lcl_port;
 148   u64 vpp_evt_q;
 149 };
 150
 151 /** \brief Unbind a given URI
 152     @param client_index - opaque cookie to identify the sender
 153     @param context - sender context, to match reply w/ request
 154     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 155                  "tcp://::/0/80" [ipv6], etc.
 156     @param options - socket options, fifo sizes, etc.
 157 */
 158 autoreply define unbind_uri {
 159   u32 client_index;
 160   u32 context;
 161   u8 uri[128];
 162 };
 163
 164 /** \brief Connect to a given URI
 165     @param client_index - opaque cookie to identify the sender
 166     @param context - sender context, to match reply w/ request
 167     @param client_queue_address - binary API client queue address. Used by
 168                                                           local server when connect was redirected.
 169     @param options - socket options, fifo sizes, etc. passed by vpp to the
 170                                  server when redirecting connects
 171     @param uri - a URI, e.g. "tcp4://0.0.0.0/0/80"
 172                  "tcp6://::/0/80" [ipv6], etc.
 173 */
 174 autoreply define connect_uri {
 175   u32 client_index;
 176   u32 context;
 177   u64 client_queue_address;
 178   u64 options[16];
 179   u8 uri[128];
 180 };
 181
 182 /** \brief vpp->client, accept this session
 183         *** Will be DEPRECATED. Use message queue instead. ***
 184     @param context - sender context, to match reply w/ request
 185     @param listener_handle - tells client which listener this pertains to
 186     @param handle - unique session identifier
 187     @param rx_fifo_address - rx (vpp -> vpp-client) fifo address
 188     @param tx_fifo_address - tx (vpp-client -> vpp) fifo address
 189     @param vpp_event_queue_address - vpp's event queue address or client's
 190                                                                         event queue for cut through
 191     @param server_event_queue_address - server's event queue address for
 192                                                                            cut through sessions
 193     @param port - remote port
 194     @param is_ip4 - 1 if the ip is ip4
 195     @param ip - remote ip
 196 */
 197 define accept_session {
 198   u32 client_index;
 199   u32 context;
 200   u64 listener_handle;
 201   u64 handle;
 202   u64 server_rx_fifo;
 203   u64 server_tx_fifo;
 204   u64 vpp_event_queue_address;
 205   u64 server_event_queue_address;
 206   u16 port;
 207   u8 is_ip4;
 208   u8 ip[16];
 209 };
 210
 211 /** \brief client->vpp, reply to an accept message
 212         *** Will be DEPRECATED. Use message queue instead. ***
 213     @param context - sender context, to match reply w/ request
 214     @param retval - return code for the request
 215     @param session_index - session index from accept_session / connect_reply
 216     @param session_thread_index - thread index from accept_session /
 217                                   connect_reply
 218 */
 219 define accept_session_reply {
 220   u32 context;
 221   i32 retval;
 222   u64 handle;
 223 };
 224
 225 /** \brief bidirectional disconnect API
 226     @param client_index - opaque cookie to identify the sender
 227                           client to vpp direction only
 228     @param context - sender context, to match reply w/ request
 229     @param handle - session handle obtained from accept/connect
 230 */
 231 define disconnect_session {
 232   u32 client_index;
 233   u32 context;
 234   u64 handle;
 235 };
 236
 237 /** \brief bidirectional disconnect reply API
 238         *** Will be DEPRECATED. Use message queue instead. ***
 239     @param client_index - opaque cookie to identify the sender
 240                           client to vpp direction only
 241     @param context - sender context, to match reply w/ request
 242     @param retval - return code for the request
 243     @param handle - session handle
 244 */
 245 define disconnect_session_reply {
 246   u32 context;
 247   i32 retval;
 248   u64 handle;
 249 };
 250
 251 /** \brief vpp->client reset session API
 252         *** Will be DEPRECATED. Use message queue instead. ***
 253     @param client_index - opaque cookie to identify the sender
 254                           client to vpp direction only
 255     @param context - sender context, to match reply w/ request
 256     @param handle - session handle obtained via accept/connects
 257 */
 258 define reset_session {
 259   u32 client_index;
 260   u32 context;
 261   u64 handle;
 262 };
 263
 264 /** \brief client->vpp reset session reply
 265         *** Will be DEPRECATED. Use message queue instead. ***
 266     @param context - sender context, to match reply w/ request
 267     @param retval - return code for the request
 268     @param handle - session handle obtained via accept/connect
 269 */
 270 define reset_session_reply {
 271   u32 context;
 272   i32 retval;
 273   u64 handle;
 274 };
 275
 276 /** \brief Bind to an ip:port pair for a given transport protocol
 277     @param client_index - opaque cookie to identify the sender
 278     @param context - sender context, to match reply w/ request
 279     @param wrk_index - index of worker requesting the bind
 280     @param vrf - bind namespace
 281     @param is_ip4 - flag that is 1 if ip address family is IPv4
 282     @param ip - ip address
 283     @param port - port
 284     @param proto - protocol 0 - TCP 1 - UDP
 285     @param options - socket options, fifo sizes, etc.
 286 */
 287 define bind_sock {
 288   u32 client_index;
 289   u32 context;
 290   u32 wrk_index;
 291   u32 vrf;
 292   u8 is_ip4;
 293   u8 ip[16];
 294   u16 port;
 295   u8 proto;
 296   u64 options[16];
 297 };
 298
 299 /** \brief Unbind
 300     @param client_index - opaque cookie to identify the sender
 301     @param context - sender context, to match reply w/ request
 302     @param wrk_index - index of worker requesting the bind
 303     @param handle - bind handle obtained from bind reply
 304 */
 305 autoreply define unbind_sock {
 306   u32 client_index;
 307   u32 context;
 308   u32 wrk_index;
 309   u64 handle;
 310 };
 311
 312 /** \brief Connect to a remote peer
 313     @param client_index - opaque cookie to identify the sender
 314     @param context - sender context, to match reply w/ request
 315     @param wrk_index - worker that requests the connect
 316     @param client_queue_address - client's API queue address. Non-zero when
 317                                   used to perform redirects
 318     @param options - socket options, fifo sizes, etc. when doing redirects
 319     @param vrf - connection namespace
 320     @param is_ip4 - flag that is 1 if ip address family is IPv4
 321     @param ip - ip address
 322     @param port - port
 323     @param proto - protocol 0 - TCP 1 - UDP
 324     @param hostname-len - length of hostname
 325     @param hostname - destination's hostname. If present, used by protocols
 326                                           like tls.
 327 */
 328 autoreply define connect_sock {
 329   u32 client_index;
 330   u32 context;
 331   u32 wrk_index;
 332   u64 client_queue_address;
 333   u64 options[16];
 334   u32 vrf;
 335   u8 is_ip4;
 336   u8 ip[16];
 337   u16 port;
 338   u8 proto;
 339   u8 hostname_len;
 340   u8 hostname[hostname_len];
 341 };
 342
 343 /** \brief Bind reply
 344         *** Will be DEPRECATED. Use message queue instead. ***
 345     @param context - sender context, to match reply w/ request
 346     @param handle - bind handle
 347     @param retval - return code for the request
 348     @param lcl_is_ip4 - local ip address type
 349     @param lcl_ip6 - local ip address
 350     @param lcl_port - local port
 351     @param rx_fifo - rx fifo address if allocated (connectionless)
 352     @param tx_fifo - tx fifo address if allocated (connectionless)
 353     @param vpp_evt_q - vpp event queue address (connectionless)
 354     @param segment_name_length - length of segment name
 355     @param segment_name - name of segment client needs to attach to
 356 */
 357 define bind_sock_reply {
 358   u32 context;
 359   u64 handle;
 360   i32 retval;
 361   u8 lcl_is_ip4;
 362   u8 lcl_ip[16];
 363   u16 lcl_port;
 364   u64 rx_fifo;
 365   u64 tx_fifo;
 366   u64 vpp_evt_q;
 367   u32 segment_size;
 368   u8 segment_name_length;
 369   u8 segment_name[128];
 370 };
 371
 372 /* Dummy connect message -- needed to satisfy api generators
 373 *
 374 *  NEVER USED, doxygen tags elided on purpose.
 375 */
 376 define connect_session {
 377   u32 client_index;
 378   u32 context;
 379 };
 380
 381 /** \brief vpp/server->client, connect reply -- used for all connect_* messages
 382         *** Will be DEPRECATED. Use message queue instead. ***
 383     @param context - sender context, to match reply w/ request
 384     @param retval - return code for the request
 385     @param handle - connection handle
 386     @param server_rx_fifo - rx (vpp -> vpp-client) fifo address
 387     @param server_tx_fifo - tx (vpp-client -> vpp) fifo address
 388     @param vpp_event_queue_address - vpp's event queue address
 389     @param client_event_queue_address - client's event queue address
 390     @param segment_size - size of segment to be attached. Only for redirects.
 391     @param segment_name_length - non-zero if the client needs to attach to
 392                                  the fifo segment
 393     @param segment_name - set if the client needs to attach to the segment
 394     @param lcl_ip - local ip for connection
 395     @param is_ip4 - flag to indicate if ip is v4 or v6
 396     @param lcl_port - local port
 397 */
 398 define connect_session_reply {
 399   u32 context;
 400   i32 retval;
 401   u64 handle;
 402   u64 server_rx_fifo;
 403   u64 server_tx_fifo;
 404   u64 vpp_event_queue_address;
 405   u64 client_event_queue_address;
 406   u32 segment_size;
 407   u8 segment_name_length;
 408   u8 segment_name[128];
 409   u8 lcl_ip[16];
 410   u8 is_ip4;
 411   u16 lcl_port;
 412 };
 413
 414 /** \brief ask app to add a new cut-through registration
 415     @param client_index - opaque cookie to identify the sender
 416                           client to vpp direction only
 417     @param context - sender context, to match reply w/ request
 418     @param evt_q_address - address of the mq in ssvm segment
 419     @param peer_evt_q_address - address of peer's mq in ssvm segment
 420     @param wrk_index - index of worker to receive the registration
 421     @param n_fds - number of fds exchanged
 422     @param fd_flags - flag indicating the fds that will be exchanged over
 423                                   api socket
 424 */
 425 autoreply define app_cut_through_registration_add
 426 {
 427   u32 client_index;
 428   u32 context;
 429   u64 evt_q_address;
 430   u64 peer_evt_q_address;
 431   u32 wrk_index;
 432   u8 n_fds;
 433   u8 fd_flags;
 434 };
 435
 436 /** \brief add/del application worker
 437     @param client_index - opaque cookie to identify the sender
 438                           client to vpp direction only
 439     @param context - sender context, to match reply w/ request
 440     @param app_api_index - explicit client api index
 441     @param wrk_index - worker index, if a delete
 442     @param is_add - set if an add
 443 */
 444 define app_worker_add_del
 445 {
 446   u32 client_index;
 447   u32 context;
 448   u32 app_api_index;
 449   u32 wrk_index;
 450   u8 is_add;
 451 };
 452
 453 /** \brief Reply for app worker add/del
 454     @param context - returned sender context, to match reply w/ request
 455     @param retval - return code
 456     @param wrk_index - worker index, if add
 457     @param app_event_queue_address - vpp event queue address of new worker
 458     @param n_fds - number of fds exchanged
 459     @param fd_flags - set of flags that indicate which fds are to be expected
 460                                   over the socket (set only if socket transport available)
 461     @param segment_name_length - length of segment name
 462     @param segment_name - name of segment client needs to attach to
 463 */
 464 define app_worker_add_del_reply
 465 {
 466   u32 context;
 467   i32 retval;
 468   u32 wrk_index;
 469   u64 app_event_queue_address;
 470   u8 n_fds;
 471   u8 fd_flags;
 472   u8 segment_name_length;
 473   u8 segment_name[128];
 474   u8 is_add;
 475 };
 476
 477 /** \brief enable/disable session layer
 478     @param client_index - opaque cookie to identify the sender
 479                           client to vpp direction only
 480     @param context - sender context, to match reply w/ request
 481     @param is_enable - disable session layer if 0, enable otherwise
 482 */
 483 autoreply define session_enable_disable {
 484   u32 client_index;
 485   u32 context;
 486   u8 is_enable;
 487 };
 488
 489 /** \brief add/del application namespace
 490     @param client_index - opaque cookie to identify the sender
 491                           client to vpp direction only
 492     @param context - sender context, to match reply w/ request
 493     @param secret - secret shared between app and vpp
 494     @param sw_if_index - local interface that "supports" namespace. Set to
 495                                                 ~0 if no preference
 496     @param ip4_fib_id - id of ip4 fib that "supports" the namespace. Ignored
 497                                                 if sw_if_index set.
 498     @param ip6_fib_id - id of ip6 fib that "supports" the namespace. Ignored
 499                                                 if sw_if_index set.
 500     @param namespace_id_len - length of namespace id lower
 501     @param namespace_id - namespace id
 502 */
 503 define app_namespace_add_del {
 504   u32 client_index;
 505   u32 context;
 506   u64 secret;
 507   u32 sw_if_index;
 508   u32 ip4_fib_id;
 509   u32 ip6_fib_id;
 510   u8 namespace_id_len;
 511   u8 namespace_id[64];
 512 };
 513
 514 /** \brief Reply for app namespace add/del
 515     @param context - returned sender context, to match reply w/ request
 516     @param retval - return code
 517     @param appns_index - app namespace index
 518 */
 519 define app_namespace_add_del_reply
 520 {
 521   u32 context;
 522   i32 retval;
 523   u32 appns_index;
 524 };
 525
 526 /** \brief add/del session rule
 527     @param client_index - opaque cookie to identify the sender
 528                           client to vpp direction only
 529     @param context - sender context, to match reply w/ request
 530     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 531     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 532     @param lcl_ip - local ip
 533     @param lcl_plen - local prefix length
 534     @param rmt_ip - remote ip
 535     @param rmt_ple - remote prefix length
 536     @param lcl_port - local port
 537     @param rmt_port - remote port
 538     @param action_index - the only action defined now is forward to
 539                                                   application with index action_index
 540         @param is_add - flag to indicate if add or del
 541         @param appns_index - application namespace where rule is to be applied
 542                                                  to
 543         @param scope - flag that indicates scope of the rule: global or local.
 544                                    If 0, default is global, 1 is global 2 is local, 3 is
 545                                    both
 546 */
 547 autoreply define session_rule_add_del {
 548   u32 client_index;
 549   u32 context;
 550   u8 transport_proto;
 551   u8 is_ip4;
 552   u8 lcl_ip[16];
 553   u8 lcl_plen;
 554   u8 rmt_ip[16];
 555   u8 rmt_plen;
 556   u16 lcl_port;
 557   u16 rmt_port;
 558   u32 action_index;
 559   u8 is_add;
 560   u32 appns_index;
 561   u8 scope;
 562   u8 tag[64];
 563 };
 564
 565 /** \brief Dump session rules
 566     @param client_index - opaque cookie to identify the sender
 567     @param context - sender context, to match reply w/ request
 568  */
 569 define session_rules_dump
 570 {
 571   u32 client_index;
 572   u32 context;
 573 };
 574
 575 /** \brief Session rules details
 576         @param context - sender context, to match reply w/ request
 577     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 578     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 579     @param lcl_ip - local ip
 580     @param lcl_plen - local prefix length
 581     @param rmt_ip - remote ip
 582     @param rmt_ple - remote prefix length
 583     @param lcl_port - local port
 584     @param rmt_port - remote port
 585     @param action_index - the only action defined now is forward to
 586                                                   application with index action_index
 587         @param appns_index - application namespace where rule is to be applied
 588                                                  to
 589         @param scope - flag that indicates scope of the rule: global or local.
 590                                    If 0, default is global, 1 is global 2 is local, 3 is
 591                                    both
 592   */
 593 define session_rules_details
 594 {
 595   u32 context;
 596   u8 transport_proto;
 597   u8 is_ip4;
 598   u8 lcl_ip[16];
 599   u8 lcl_plen;
 600   u8 rmt_ip[16];
 601   u8 rmt_plen;
 602   u16 lcl_port;
 603   u16 rmt_port;
 604   u32 action_index;
 605   u32 appns_index;
 606   u8 scope;
 607   u8 tag[64];
 608 };
 609
 610 /*
 611  * Local Variables:
 612  * eval: (c-set-style "gnu")
 613  * End:
 614  */