src/vnet/session/session.api

   1 /*
   2  * Copyright (c) 2015-2019 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.6.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 autoreply define bind_uri {
 140   u32 client_index;
 141   u32 context;
 142   u32 accept_cookie;
 143   u8 uri[128];
 144 };
 145
 146 /** \brief Unbind a given URI
 147     @param client_index - opaque cookie to identify the sender
 148     @param context - sender context, to match reply w/ request
 149     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 150                  "tcp://::/0/80" [ipv6], etc.
 151     @param options - socket options, fifo sizes, etc.
 152 */
 153 autoreply define unbind_uri {
 154   u32 client_index;
 155   u32 context;
 156   u8 uri[128];
 157 };
 158
 159 /** \brief Connect to a given URI
 160     @param client_index - opaque cookie to identify the sender
 161     @param context - sender context, to match reply w/ request
 162     @param client_queue_address - binary API client queue address. Used by
 163                                                           local server when connect was redirected.
 164     @param options - socket options, fifo sizes, etc. passed by vpp to the
 165                                  server when redirecting connects
 166     @param uri - a URI, e.g. "tcp4://0.0.0.0/0/80"
 167                  "tcp6://::/0/80" [ipv6], etc.
 168 */
 169 autoreply define connect_uri {
 170   u32 client_index;
 171   u32 context;
 172   u64 client_queue_address;
 173   u64 options[16];
 174   u8 uri[128];
 175 };
 176
 177 /** \brief bidirectional disconnect API
 178     @param client_index - opaque cookie to identify the sender
 179                           client to vpp direction only
 180     @param context - sender context, to match reply w/ request
 181     @param handle - session handle obtained from accept/connect
 182 */
 183 define disconnect_session {
 184   u32 client_index;
 185   u32 context;
 186   u64 handle;
 187 };
 188
 189 /** \brief bidirectional disconnect reply API
 190     @param client_index - opaque cookie to identify the sender
 191                           client to vpp direction only
 192     @param context - sender context, to match reply w/ request
 193     @param retval - return code for the request
 194     @param handle - session handle
 195 */
 196 define disconnect_session_reply {
 197   u32 context;
 198   i32 retval;
 199   u64 handle;
 200 };
 201
 202 /** \brief Bind to an ip:port pair for a given transport protocol
 203     @param client_index - opaque cookie to identify the sender
 204     @param context - sender context, to match reply w/ request
 205     @param wrk_index - index of worker requesting the bind
 206     @param vrf - bind namespace
 207     @param is_ip4 - flag that is 1 if ip address family is IPv4
 208     @param ip - ip address
 209     @param port - port
 210     @param proto - protocol 0 - TCP 1 - UDP
 211     @param options - socket options, fifo sizes, etc.
 212 */
 213 autoreply define bind_sock {
 214   u32 client_index;
 215   u32 context;
 216   u32 wrk_index;
 217   u32 vrf;
 218   u8 is_ip4;
 219   u8 ip[16];
 220   u16 port;
 221   u8 proto;
 222   u64 options[16];
 223 };
 224
 225 /** \brief Unbind
 226     @param client_index - opaque cookie to identify the sender
 227     @param context - sender context, to match reply w/ request
 228     @param wrk_index - index of worker requesting the bind
 229     @param handle - bind handle obtained from bind reply
 230 */
 231 autoreply define unbind_sock {
 232   u32 client_index;
 233   u32 context;
 234   u32 wrk_index;
 235   u64 handle;
 236 };
 237
 238 /** \brief Connect to a remote peer
 239     @param client_index - opaque cookie to identify the sender
 240     @param context - sender context, to match reply w/ request
 241     @param wrk_index - worker that requests the connect
 242     @param client_queue_address - client's API queue address. Non-zero when
 243                                   used to perform redirects
 244     @param options - socket options, fifo sizes, etc. when doing redirects
 245     @param vrf - connection namespace
 246     @param is_ip4 - flag that is 1 if ip address family is IPv4
 247     @param ip - ip address
 248     @param port - port
 249     @param proto - protocol 0 - TCP 1 - UDP
 250     @param hostname-len - length of hostname
 251     @param hostname - destination's hostname. If present, used by protocols
 252                                           like tls.
 253     @param transport_opts - transport option (e.g. session id for quic).
 254 */
 255 autoreply define connect_sock {
 256   u32 client_index;
 257   u32 context;
 258   u32 wrk_index;
 259   u64 client_queue_address;
 260   u64 options[16];
 261   u32 vrf;
 262   u8 is_ip4;
 263   u8 ip[16];
 264   u16 port;
 265   u8 proto;
 266   u8 hostname_len;
 267   u8 hostname[hostname_len];
 268   u64 transport_opts;
 269 };
 270
 271 /** \brief ask app to add a new cut-through registration
 272     @param client_index - opaque cookie to identify the sender
 273                           client to vpp direction only
 274     @param context - sender context, to match reply w/ request
 275     @param evt_q_address - address of the mq in ssvm segment
 276     @param peer_evt_q_address - address of peer's mq in ssvm segment
 277     @param wrk_index - index of worker to receive the registration
 278     @param n_fds - number of fds exchanged
 279     @param fd_flags - flag indicating the fds that will be exchanged over
 280                                   api socket
 281 */
 282 autoreply define app_cut_through_registration_add
 283 {
 284   u32 client_index;
 285   u32 context;
 286   u64 evt_q_address;
 287   u64 peer_evt_q_address;
 288   u32 wrk_index;
 289   u8 n_fds;
 290   u8 fd_flags;
 291 };
 292
 293 /** \brief add/del application worker
 294     @param client_index - opaque cookie to identify the sender
 295                           client to vpp direction only
 296     @param context - sender context, to match reply w/ request
 297     @param app_index - application index
 298     @param wrk_index - worker index, if a delete
 299     @param is_add - set if an add
 300 */
 301 define app_worker_add_del
 302 {
 303   u32 client_index;
 304   u32 context;
 305   u32 app_index;
 306   u32 wrk_index;
 307   u8 is_add;
 308 };
 309
 310 /** \brief Reply for app worker add/del
 311     @param context - returned sender context, to match reply w/ request
 312     @param retval - return code
 313     @param wrk_index - worker index, if add
 314     @param app_event_queue_address - vpp event queue address of new worker
 315     @param n_fds - number of fds exchanged
 316     @param fd_flags - set of flags that indicate which fds are to be expected
 317                                   over the socket (set only if socket transport available)
 318     @param segment_name_length - length of segment name
 319     @param segment_name - name of segment client needs to attach to
 320     @param segment_handle - handle for segment
 321 */
 322 define app_worker_add_del_reply
 323 {
 324   u32 context;
 325   i32 retval;
 326   u32 wrk_index;
 327   u64 app_event_queue_address;
 328   u8 n_fds;
 329   u8 fd_flags;
 330   u8 segment_name_length;
 331   u8 segment_name[128];
 332   u64 segment_handle;
 333   u8 is_add;
 334 };
 335
 336 /** \brief enable/disable session layer
 337     @param client_index - opaque cookie to identify the sender
 338                           client to vpp direction only
 339     @param context - sender context, to match reply w/ request
 340     @param is_enable - disable session layer if 0, enable otherwise
 341 */
 342 autoreply define session_enable_disable {
 343   u32 client_index;
 344   u32 context;
 345   u8 is_enable;
 346 };
 347
 348 /** \brief add/del application namespace
 349     @param client_index - opaque cookie to identify the sender
 350                           client to vpp direction only
 351     @param context - sender context, to match reply w/ request
 352     @param secret - secret shared between app and vpp
 353     @param sw_if_index - local interface that "supports" namespace. Set to
 354                          ~0 if no preference
 355     @param ip4_fib_id - id of ip4 fib that "supports" the namespace. Ignored
 356                         if sw_if_index set.
 357     @param ip6_fib_id - id of ip6 fib that "supports" the namespace. Ignored
 358                         if sw_if_index set.
 359     @param namespace_id_len - length of namespace id lower
 360     @param namespace_id - namespace id
 361 */
 362 define app_namespace_add_del {
 363   u32 client_index;
 364   u32 context;
 365   u64 secret;
 366   u32 sw_if_index;
 367   u32 ip4_fib_id;
 368   u32 ip6_fib_id;
 369   u8 namespace_id_len;
 370   u8 namespace_id[64];
 371 };
 372
 373 /** \brief Reply for app namespace add/del
 374     @param context - returned sender context, to match reply w/ request
 375     @param retval - return code
 376     @param appns_index - app namespace index
 377 */
 378 define app_namespace_add_del_reply
 379 {
 380   u32 context;
 381   i32 retval;
 382   u32 appns_index;
 383 };
 384
 385 /** \brief add/del session rule
 386     @param client_index - opaque cookie to identify the sender
 387                           client to vpp direction only
 388     @param context - sender context, to match reply w/ request
 389     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 390     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 391     @param lcl_ip - local ip
 392     @param lcl_plen - local prefix length
 393     @param rmt_ip - remote ip
 394     @param rmt_ple - remote prefix length
 395     @param lcl_port - local port
 396     @param rmt_port - remote port
 397     @param action_index - the only action defined now is forward to
 398                           application with index action_index
 399     @param is_add - flag to indicate if add or del
 400     @param appns_index - application namespace where rule is to be applied to
 401     @param scope - flag that indicates scope of the rule: global or local.
 402                    If 0, default is global, 1 is global 2 is local, 3 is both
 403 */
 404 autoreply define session_rule_add_del {
 405   u32 client_index;
 406   u32 context;
 407   u8 transport_proto;
 408   u8 is_ip4;
 409   u8 lcl_ip[16];
 410   u8 lcl_plen;
 411   u8 rmt_ip[16];
 412   u8 rmt_plen;
 413   u16 lcl_port;
 414   u16 rmt_port;
 415   u32 action_index;
 416   u8 is_add;
 417   u32 appns_index;
 418   u8 scope;
 419   u8 tag[64];
 420 };
 421
 422 /** \brief Dump session rules
 423     @param client_index - opaque cookie to identify the sender
 424     @param context - sender context, to match reply w/ request
 425  */
 426 define session_rules_dump
 427 {
 428   u32 client_index;
 429   u32 context;
 430 };
 431
 432 /** \brief Session rules details
 433     @param context - sender context, to match reply w/ request
 434     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 435     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 436     @param lcl_ip - local ip
 437     @param lcl_plen - local prefix length
 438     @param rmt_ip - remote ip
 439     @param rmt_ple - remote prefix length
 440     @param lcl_port - local port
 441     @param rmt_port - remote port
 442     @param action_index - the only action defined now is forward to
 443                           application with index action_index
 444     @param appns_index - application namespace where rule is to be applied to
 445     @param scope - flag that indicates scope of the rule: global or local.
 446                    If 0, default is global, 1 is global 2 is local, 3 is both
 447   */
 448 define session_rules_details
 449 {
 450   u32 context;
 451   u8 transport_proto;
 452   u8 is_ip4;
 453   u8 lcl_ip[16];
 454   u8 lcl_plen;
 455   u8 rmt_ip[16];
 456   u8 rmt_plen;
 457   u16 lcl_port;
 458   u16 rmt_port;
 459   u32 action_index;
 460   u32 appns_index;
 461   u8 scope;
 462   u8 tag[64];
 463 };
 464
 465 /*
 466  * Local Variables:
 467  * eval: (c-set-style "gnu")
 468  * End:
 469  */