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