api_common.h revision 684fb6e9
1/*
2 *------------------------------------------------------------------
3 * api_common.h
4 *
5 * Copyright (c) 2009-2015 Cisco and/or its affiliates.
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at:
9 *
10 *     http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *------------------------------------------------------------------
18 */
19
20#ifndef included_api_common_h
21#define included_api_common_h
22
23/** \file API common definitions
24 * See api_doc.md for more info
25 */
26
27#include <vppinfra/clib_error.h>
28#include <vppinfra/elog.h>
29#include <vlibapi/api_types.h>
30#include <svm/svm_common.h>
31#include <svm/queue.h>
32
33/** API registration types
34 */
35typedef enum
36{
37  REGISTRATION_TYPE_FREE = 0,
38  REGISTRATION_TYPE_SHMEM,	/**< Shared memory connection */
39  REGISTRATION_TYPE_SOCKET_LISTEN, /**< Socket listener  */
40  REGISTRATION_TYPE_SOCKET_SERVER, /**< Socket server */
41  REGISTRATION_TYPE_SOCKET_CLIENT, /**< Socket client */
42} vl_registration_type_t;
43
44/** An API client registration, only in vpp/vlib */
45
46typedef struct vl_api_registration_
47{
48  vl_registration_type_t registration_type; /**< type */
49
50  /** Index in VLIB's brain (not shared memory). */
51  u32 vl_api_registration_pool_index;
52
53  u8 *name;			/**< Client name */
54
55  /* Zombie apocalypse checking */
56  f64 last_heard;
57  int last_queue_head;
58  int unanswered_pings;
59
60  /** shared memory only: pointer to client input queue */
61  svm_queue_t *vl_input_queue;
62  svm_region_t *vlib_rp;
63  void *shmem_hdr;
64
65  /* socket server and client */
66  u32 clib_file_index;		/**< Socket only: file index */
67  i8 *unprocessed_input;	/**< Socket only: pending input */
68  u32 unprocessed_msg_length;	/**< Socket only: unprocssed length */
69  u8 *output_vector;		/**< Socket only: output vector */
70  int *additional_fds_to_close;
71
72  /* socket client only */
73  u32 server_handle;		/**< Socket client only: server handle */
74  u32 server_index;		/**< Socket client only: server index */
75} vl_api_registration_t;
76
77#define VL_API_INVALID_FI ((u32)~0)
78
79/** Trace configuration for a single message */
80typedef struct
81{
82  int size;			/**< for sanity checking */
83  int trace_enable;		/**< trace this message  */
84  int replay_enable;		/**< This message can be replayed  */
85} trace_cfg_t;
86
87/**
88 * API trace state
89 */
90typedef struct
91{
92  u8 endian;			/**< trace endianness */
93  u8 enabled;			/**< trace is enabled  */
94  u8 wrapped;			/**< trace has wrapped */
95  u8 pad;
96  u32 nitems;			/**< Number of trace records */
97  u32 curindex;			/**< Current index in circular buffer  */
98  u8 **traces;			/**< Trace ring */
99} vl_api_trace_t;
100
101/** Trace RX / TX enum */
102typedef enum
103{
104  VL_API_TRACE_TX,
105  VL_API_TRACE_RX,
106} vl_api_trace_which_t;
107
108#define VL_API_LITTLE_ENDIAN 0x00
109#define VL_API_BIG_ENDIAN 0x01
110
111/** Message range (belonging to a plugin) */
112typedef struct
113{
114  u8 *name;			/**< name of the plugin  */
115  u16 first_msg_id;		/**< first assigned message ID */
116  u16 last_msg_id;		/**< last assigned message ID */
117} vl_api_msg_range_t;
118
119/** Message configuration definition */
120typedef struct
121{
122  int id;			/**< the message ID */
123  char *name;			/**< the message name */
124  u32 crc;			/**< message definition CRC  */
125  void *handler;		/**< the message handler  */
126  void *cleanup;		/**< non-default message cleanup handler */
127  void *endian;			/**< message endian function  */
128  void *print;			/**< message print function  */
129  int size;			/**< message size  */
130  int traced;			/**< is this message to be traced?  */
131  int replay;			/**< is this message to be replayed?  */
132  int message_bounce;		/**< do not free message after processing */
133  int is_mp_safe;		/**< worker thread barrier required?  */
134} vl_msg_api_msg_config_t;
135
136/** Message header structure */
137typedef struct msgbuf_
138{
139  svm_queue_t *q; /**< message allocated in this shmem ring  */
140  u32 data_len;			 /**< message length not including header  */
141  u32 gc_mark_timestamp;	 /**< message garbage collector mark TS  */
142  u8 data[0];			 /**< actual message begins here  */
143} msgbuf_t;
144
145CLIB_NOSANITIZE_ADDR static inline void
146VL_MSG_API_UNPOISON (const void *a)
147{
148  const msgbuf_t *m = &((const msgbuf_t *) a)[-1];
149  CLIB_MEM_UNPOISON (m, sizeof (*m) + ntohl (m->data_len));
150}
151
152CLIB_NOSANITIZE_ADDR static inline void
153VL_MSG_API_SVM_QUEUE_UNPOISON (const svm_queue_t * q)
154{
155  CLIB_MEM_UNPOISON (q, sizeof (*q) + q->elsize * q->maxsize);
156}
157
158static inline void
159VL_MSG_API_POISON (const void *a)
160{
161  const msgbuf_t *m = &((const msgbuf_t *) a)[-1];
162  CLIB_MEM_POISON (m, sizeof (*m) + ntohl (m->data_len));
163}
164
165/* api_shared.c prototypes */
166void vl_msg_api_handler (void *the_msg);
167void vl_msg_api_handler_no_free (void *the_msg);
168void vl_msg_api_handler_no_trace_no_free (void *the_msg);
169void vl_msg_api_trace_only (void *the_msg);
170void vl_msg_api_cleanup_handler (void *the_msg);
171void vl_msg_api_replay_handler (void *the_msg);
172void vl_msg_api_socket_handler (void *the_msg);
173void vl_msg_api_set_handlers (int msg_id, char *msg_name,
174			      void *handler,
175			      void *cleanup,
176			      void *endian,
177			      void *print, int msg_size, int traced);
178void vl_msg_api_clean_handlers (int msg_id);
179void vl_msg_api_config (vl_msg_api_msg_config_t *);
180void vl_msg_api_set_cleanup_handler (int msg_id, void *fp);
181void vl_msg_api_queue_handler (svm_queue_t * q);
182
183void vl_msg_api_barrier_sync (void) __attribute__ ((weak));
184void vl_msg_api_barrier_release (void) __attribute__ ((weak));
185#ifdef BARRIER_TRACING
186void vl_msg_api_barrier_trace_context (const char *context)
187  __attribute__ ((weak));
188#else
189#define vl_msg_api_barrier_trace_context(X)
190#endif
191void vl_msg_api_free (void *);
192void vl_noop_handler (void *mp);
193void vl_msg_api_increment_missing_client_counter (void);
194void vl_msg_api_post_mortem_dump (void);
195void vl_msg_api_post_mortem_dump_enable_disable (int enable);
196void vl_msg_api_register_pd_handler (void *handler,
197				     u16 msg_id_host_byte_order);
198int vl_msg_api_pd_handler (void *mp, int rv);
199
200void vl_msg_api_set_first_available_msg_id (u16 first_avail);
201u16 vl_msg_api_get_msg_ids (const char *name, int n);
202u32 vl_msg_api_get_msg_index (u8 * name_and_crc);
203void *vl_msg_push_heap (void);
204void vl_msg_pop_heap (void *oldheap);
205
206typedef clib_error_t *(vl_msg_api_init_function_t) (u32 client_index);
207
208typedef struct _vl_msg_api_init_function_list_elt
209{
210  struct _vl_msg_api_init_function_list_elt *next_init_function;
211  vl_msg_api_init_function_t *f;
212} _vl_msg_api_function_list_elt_t;
213
214typedef struct
215{
216  u32 major;
217  u32 minor;
218  u32 patch;
219  char name[64];
220} api_version_t;
221
222/** API main structure, used by both vpp and binary API clients */
223typedef struct
224{
225  /** Message handler vector  */
226  void (**msg_handlers) (void *);
227  /** Plaform-dependent (aka hardware) message handler vector */
228  int (**pd_msg_handlers) (void *, int);
229
230  /** non-default message cleanup handler vector */
231  void (**msg_cleanup_handlers) (void *);
232
233  /** Message endian handler vector */
234  void (**msg_endian_handlers) (void *);
235
236  /** Message print function vector */
237  void (**msg_print_handlers) (void *, void *);
238
239  /** Message name vector */
240  const char **msg_names;
241
242  /** Don't automatically free message buffer vetor */
243  u8 *message_bounce;
244
245  /** Message is mp safe vector */
246  u8 *is_mp_safe;
247
248  /** Allocator ring vectors (in shared memory) */
249  struct ring_alloc_ *arings;
250
251  /** Number of times that the ring allocator failed */
252  u32 ring_misses;
253
254  /** Number of garbage-collected message buffers */
255  u32 garbage_collects;
256
257  /** Number of missing clients / failed message sends */
258  u32 missing_clients;
259
260  /** Received message trace configuration */
261  vl_api_trace_t *rx_trace;
262
263  /** Sent message trace configuration */
264  vl_api_trace_t *tx_trace;
265
266  /** Print every received message */
267  int msg_print_flag;
268
269  /** Current trace configuration */
270  trace_cfg_t *api_trace_cfg;
271
272  /** Current process PID */
273  int our_pid;
274
275  /** Current binary api segment descriptor */
276  svm_region_t *vlib_rp;
277
278  /** Primary api segment descriptor */
279  svm_region_t *vlib_primary_rp;
280
281  /** Vector of all mapped shared-VM segments */
282  svm_region_t **vlib_private_rps;
283  svm_region_t **mapped_shmem_regions;
284
285  /** Binary API shared-memory segment header pointer */
286  struct vl_shmem_hdr_ *shmem_hdr;
287
288  /** vlib/vpp only: vector of client registrations */
289  vl_api_registration_t **vl_clients;
290
291  /** vlib/vpp only: serialized (message, name, crc) table */
292  u8 *serialized_message_table_in_shmem;
293
294  /** First available message ID, for theplugin msg allocator */
295  u16 first_available_msg_id;
296
297  /** Message range by name hash */
298  uword *msg_range_by_name;
299
300  /** vector of message ranges */
301  vl_api_msg_range_t *msg_ranges;
302
303  /** uid for the api shared memory region */
304  int api_uid;
305
306  /** gid for the api shared memory region */
307  int api_gid;
308
309  /** base virtual address for global VM region */
310  u64 global_baseva;
311
312  /** size of the global VM region */
313  u64 global_size;
314
315  /** size of the API region */
316  u64 api_size;
317
318  /** size of the global VM private mheap */
319  u64 global_pvt_heap_size;
320
321  /** size of the api private mheap */
322  u64 api_pvt_heap_size;
323
324  /** Peer input queue pointer */
325  svm_queue_t *vl_input_queue;
326
327  /**
328   * All VLIB-side message handlers use my_client_index to identify
329   * the queue / client. This works in sim replay.
330   */
331  int my_client_index;
332  /**
333   * This is the (shared VM) address of the registration,
334   * don't use it to id the connection since it can't possibly
335   * work in simulator replay.
336   */
337  vl_api_registration_t *my_registration;
338
339  /** vpp/vlib input queue length */
340  u32 vlib_input_queue_length;
341
342  /** client message index hash table */
343  uword *msg_index_by_name_and_crc;
344
345  /** api version list */
346  api_version_t *api_version_list;
347
348  /** Shared VM binary API region name */
349  const char *region_name;
350
351  /** Chroot path to the shared memory API files */
352  const char *root_path;
353
354  /** Replay in progress? */
355  int replay_in_progress;
356
357  /** Dump (msg-name, crc) snapshot here at startup */
358  u8 *save_msg_table_filename;
359
360  /** List of API client reaper functions */
361  _vl_msg_api_function_list_elt_t *reaper_function_registrations;
362
363  /** Bin API thread handle */
364  pthread_t rx_thread_handle;
365
366  /** event log */
367  elog_main_t *elog_main;
368  int elog_trace_api_messages;
369
370} api_main_t;
371
372extern __thread api_main_t *my_api_main;
373extern api_main_t api_global_main;
374
375always_inline api_main_t *
376vlibapi_get_main (void)
377{
378  return my_api_main;
379}
380
381always_inline void
382vlibapi_set_main (api_main_t * am)
383{
384  my_api_main = am;
385}
386
387#endif /* included_api_common_h */
388
389/*
390 * fd.io coding-style-patch-verification: ON
391 *
392 * Local Variables:
393 * eval: (c-set-style "gnu")
394 * End:
395 */
396