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