FD.io VPP  v19.01.3-6-g70449b9b9
Vector Packet Processing
session.api
Go to the documentation of this file.
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 {
31  u64 options[16];
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 {
58  u8 segment_name[128];
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 {
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 {
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 {
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 {
115  u8 segment_name[128];
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 {
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 {
143  u8 uri[128];
144 };
145 /** *** Will be DEPRECATED. Use message queue instead. *** */
146 define bind_uri_reply {
153  u8 lcl_ip[16];
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 {
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 {
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 {
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 {
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 {
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 {
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 {
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 {
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 {
300  u8 ip[16];
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 {
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 {
340  u64 options[16];
343  u8 ip[16];
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 {
369  u8 lcl_ip[16];
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 {
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 {
415  u8 segment_name[128];
416  u8 lcl_ip[16];
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 {
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 {
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 {
481  u8 segment_name[128];
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 {
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 {
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 {
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 {
561  u8 lcl_ip[16];
563  u8 rmt_ip[16];
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 {
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 {
607  u8 lcl_ip[16];
609  u8 rmt_ip[16];
616  u8 tag[64];
617 };
618 
619 /*
620  * Local Variables:
621  * eval: (c-set-style "gnu")
622  * End:
623  */
unsigned long u64
Definition: types.h:89
unsigned char u8
Definition: types.h:56
unsigned int u32
Definition: types.h:88
option version
Definition: session.api:16
unsigned short u16
Definition: types.h:57
signed int i32
Definition: types.h:77