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