api_common.h revision 8229580e
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
145/* api_shared.c prototypes */
146void vl_msg_api_handler (void *the_msg);
147void vl_msg_api_handler_no_free (void *the_msg);
148void vl_msg_api_handler_no_trace_no_free (void *the_msg);
149void vl_msg_api_trace_only (void *the_msg);
150void vl_msg_api_cleanup_handler (void *the_msg);
151void vl_msg_api_replay_handler (void *the_msg);
152void vl_msg_api_socket_handler (void *the_msg);
153void vl_msg_api_set_handlers (int msg_id, char *msg_name,
154			      void *handler,
155			      void *cleanup,
156			      void *endian,
157			      void *print, int msg_size, int traced);
158void vl_msg_api_clean_handlers (int msg_id);
159void vl_msg_api_config (vl_msg_api_msg_config_t *);
160void vl_msg_api_set_cleanup_handler (int msg_id, void *fp);
161void vl_msg_api_queue_handler (svm_queue_t * q);
162
163void vl_msg_api_barrier_sync (void) __attribute__ ((weak));
164void vl_msg_api_barrier_release (void) __attribute__ ((weak));
165#ifdef BARRIER_TRACING
166void vl_msg_api_barrier_trace_context (const char *context)
167  __attribute__ ((weak));
168#else
169#define vl_msg_api_barrier_trace_context(X)
170#endif
171void vl_msg_api_free (void *);
172void vl_noop_handler (void *mp);
173void vl_msg_api_increment_missing_client_counter (void);
174void vl_msg_api_post_mortem_dump (void);
175void vl_msg_api_post_mortem_dump_enable_disable (int enable);
176void vl_msg_api_register_pd_handler (void *handler,
177				     u16 msg_id_host_byte_order);
178int vl_msg_api_pd_handler (void *mp, int rv);
179
180void vl_msg_api_set_first_available_msg_id (u16 first_avail);
181u16 vl_msg_api_get_msg_ids (const char *name, int n);
182u32 vl_msg_api_get_msg_index (u8 * name_and_crc);
183void *vl_msg_push_heap (void);
184void vl_msg_pop_heap (void *oldheap);
185
186typedef clib_error_t *(vl_msg_api_init_function_t) (u32 client_index);
187
188typedef struct _vl_msg_api_init_function_list_elt
189{
190  struct _vl_msg_api_init_function_list_elt *next_init_function;
191  vl_msg_api_init_function_t *f;
192} _vl_msg_api_function_list_elt_t;
193
194typedef struct
195{
196  u32 major;
197  u32 minor;
198  u32 patch;
199  char name[64];
200} api_version_t;
201
202/** API main structure, used by both vpp and binary API clients */
203typedef struct
204{
205  /** Message handler vector  */
206  void (**msg_handlers) (void *);
207  /** Plaform-dependent (aka hardware) message handler vector */
208  int (**pd_msg_handlers) (void *, int);
209
210  /** non-default message cleanup handler vector */
211  void (**msg_cleanup_handlers) (void *);
212
213  /** Message endian handler vector */
214  void (**msg_endian_handlers) (void *);
215
216  /** Message print function vector */
217  void (**msg_print_handlers) (void *, void *);
218
219  /** Message name vector */
220  const char **msg_names;
221
222  /** Don't automatically free message buffer vetor */
223  u8 *message_bounce;
224
225  /** Message is mp safe vector */
226  u8 *is_mp_safe;
227
228  /** Allocator ring vectors (in shared memory) */
229  struct ring_alloc_ *arings;
230
231  /** Number of times that the ring allocator failed */
232  u32 ring_misses;
233
234  /** Number of garbage-collected message buffers */
235  u32 garbage_collects;
236
237  /** Number of missing clients / failed message sends */
238  u32 missing_clients;
239
240  /** Received message trace configuration */
241  vl_api_trace_t *rx_trace;
242
243  /** Sent message trace configuration */
244  vl_api_trace_t *tx_trace;
245
246  /** Print every received message */
247  int msg_print_flag;
248
249  /** Current trace configuration */
250  trace_cfg_t *api_trace_cfg;
251
252  /** Current process PID */
253  int our_pid;
254
255  /** Current binary api segment descriptor */
256  svm_region_t *vlib_rp;
257
258  /** Primary api segment descriptor */
259  svm_region_t *vlib_primary_rp;
260
261  /** Vector of all mapped shared-VM segments */
262  svm_region_t **vlib_private_rps;
263  svm_region_t **mapped_shmem_regions;
264
265  /** Binary API shared-memory segment header pointer */
266  struct vl_shmem_hdr_ *shmem_hdr;
267
268  /** vlib/vpp only: vector of client registrations */
269  vl_api_registration_t **vl_clients;
270
271  /** vlib/vpp only: serialized (message, name, crc) table */
272  u8 *serialized_message_table_in_shmem;
273
274  /** First available message ID, for theplugin msg allocator */
275  u16 first_available_msg_id;
276
277  /** Message range by name hash */
278  uword *msg_range_by_name;
279
280  /** vector of message ranges */
281  vl_api_msg_range_t *msg_ranges;
282
283  /** uid for the api shared memory region */
284  int api_uid;
285
286  /** gid for the api shared memory region */
287  int api_gid;
288
289  /** base virtual address for global VM region */
290  u64 global_baseva;
291
292  /** size of the global VM region */
293  u64 global_size;
294
295  /** size of the API region */
296  u64 api_size;
297
298  /** size of the global VM private mheap */
299  u64 global_pvt_heap_size;
300
301  /** size of the api private mheap */
302  u64 api_pvt_heap_size;
303
304  /** Peer input queue pointer */
305  svm_queue_t *vl_input_queue;
306
307  /**
308   * All VLIB-side message handlers use my_client_index to identify
309   * the queue / client. This works in sim replay.
310   */
311  int my_client_index;
312  /**
313   * This is the (shared VM) address of the registration,
314   * don't use it to id the connection since it can't possibly
315   * work in simulator replay.
316   */
317  vl_api_registration_t *my_registration;
318
319  /** vpp/vlib input queue length */
320  u32 vlib_input_queue_length;
321
322  /** client message index hash table */
323  uword *msg_index_by_name_and_crc;
324
325  /** api version list */
326  api_version_t *api_version_list;
327
328  /** Shared VM binary API region name */
329  const char *region_name;
330
331  /** Chroot path to the shared memory API files */
332  const char *root_path;
333
334  /** Replay in progress? */
335  int replay_in_progress;
336
337  /** Dump (msg-name, crc) snapshot here at startup */
338  u8 *save_msg_table_filename;
339
340  /** List of API client reaper functions */
341  _vl_msg_api_function_list_elt_t *reaper_function_registrations;
342
343  /** Bin API thread handle */
344  pthread_t rx_thread_handle;
345
346  /** event log */
347  elog_main_t *elog_main;
348  int elog_trace_api_messages;
349
350} api_main_t;
351
352extern api_main_t api_main;
353
354#endif /* included_api_common_h */
355
356/*
357 * fd.io coding-style-patch-verification: ON
358 *
359 * Local Variables:
360 * eval: (c-set-style "gnu")
361 * End:
362 */
363