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