1 /*
2 *
3 * Copyright (c) 2003 The Regents of the University of California. All
4 * rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * - Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 *
13 * - Neither the name of the University nor the names of its
14 * contributors may be used to endorse or promote products derived
15 * from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS''
18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
19 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
20 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
21 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
24 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
25 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 *
29 */
30
31
32 /*
33 * link.h -- Header for defining link-layer interfaces in our system
34 *
35 * $Id: link.h,v 1.74 2005-09-22 03:10:13 girod Exp $
36 */
37
38 #include "libdev/packet_dev.h"
39 #include "libdev/status_dev.h"
40 #include "libdev/command_dev.h"
41 #include "libdev/packet_client.h"
42
43 /* needed for "remote timestamp" structure */
44
45 #include "timesync/sync.h"
46 #include <link/link_structs.h>
47 #include <link/link_headers.h>
48 #include <link/link_ioctls.h>
49 #include <link/link_parse.h>
50
51 #ifndef __LINK_H__
52 #define __LINK_H__
53
54 /********
55 ******** SEE link_structs.h FOR LINK_PKT_TYPE_T AND LINK_PKT_T
56 ********/
57
58 /*
59 * Link Library Interface
60 *
61 * The link library API contains several classes of objects
62 * for creating and using link interfaces:
63 *
64 * - link providers (lp_*)
65 * - link users (lu_*)
66 * - link passthrus (link_pass_*)
67 *
68 * See documentation for more details
69 */
70
71 /*
72 * common options that describe a link: the name, queuing options,
73 * private data pointer, etc.
74 *
75 * Note, interface class is only used by link providers, to group
76 * interfaces into classes, e.g. link layer, network layer, etc.
77 */
78
79 typedef struct link_opts {
80 char *name; /* the link name (e.g. udp0) */
81 char *if_class; /* the interface class (e.g. raw, link, network, etc) */
82 pd_queue_opts_t q_opts; /* Queue length and loopback options */
83 link_pkt_type_t pkt_type; /* packet type assoc with this link,
84 * if any. used to filter for uses,
85 * for debug purposes in provides */
86 void *data; /* Data pointer used by apps */
87 } link_opts_t;
88
89 char *link_name(link_opts_t *l_opts, char *suffix);
90 char *link_name_s(char *name, char *suffix);
91
92 /* does NOT run sim_path on the name.. used rarely */
93 char *link_name_s_nosim(char *name, char *suffix);
94
95 /********************************************************************/
96 /******************** Link Provider Interface ***********************/
97 /********************************************************************/
98
99 /* typedef link provider context */
100 typedef struct _lp_context lp_context_t;
101
102 #define LP_BLOCKED PD_BLOCKED
103
104 /*
105 * all memory is statically allocated, do not free
106 * data_len does not include header
107 */
108
109 typedef int (*lp_send_cb_t)(lp_context_t *lp, link_pkt_t *link_pkt,
110 int data_len, int loop_needed);
111 typedef int (*lp_enqueue_cb_t)(lp_context_t *lp, link_pkt_t *link_pkt,
112 int data_len);
113
114 /* optional ioctl() handler */
115 typedef int (* lp_ioctl_cb_t)(lp_context_t *lp, int cmd, void *arg);
116
117 /* optional notification of status request */
118 typedef int (*lp_status_cb_t)(lp_context_t *lp);
119
120 /* optional command callback function
121 * system will free parser state
122 * return EVENT_RENEW or EVENT_ERROR(errno) */
123 typedef int (*lp_command_cb_t)(lp_context_t *lp, parser_state_t *cmd_input);
124
125 /* optional notificaiton callback to set promisc mode */
126 typedef void (*lp_notify_cb_t)(lp_context_t *lp, int mode);
127
128 /*
129 * when reporting usage, report one entry per line, in the form
130 * " option: description\n"
131 * or " option=<argdesc>: description\n"
132 */
133
134 typedef void (*lp_command_usage_cb_t)(lp_context_t *lp, buf_t *fill_usage);
135
136 /* options available for link providers */
137 typedef struct lp_opts {
138 link_opts_t opts; /* common options */
139 char *description; /* our module's description */
140 lp_send_cb_t send; /* send callback */
141 lp_enqueue_cb_t enqueue; /* enqueue callback */
142 lp_ioctl_cb_t ioctl; /* ioctl callback */
143 lp_status_cb_t status_request; /* status callback */
144 lp_command_cb_t command_request; /* command callback */
145 lp_command_usage_cb_t usage; /* command usage callback */
146 lp_notify_cb_t promisc_mode; /* notification of change of promisc_mode */
147
148 /* Default status:
149 *
150 * + If you don't need the status info to be dynamic, set the values
151 * here in initial_status. ***Be sure to set MTU and if_id.***
152 * The link device will filter your packets based on destination
153 * set to if_id. If if_id is zero, (or if clients request promisc
154 * mode) it will allow all packets
155 *
156 * + If you want the status to be dynamic, e.g. reflecting changing
157 * characteristics of the underlying layers, or of hardware that
158 * can be dynamic, then you need not set this; use push_status to
159 * push new status info as needed and optionally implement a status
160 * handler callback which will be called every time status is
161 * requested.
162 */
163
164 link_status_t initial_status; /* initial/default status info */
165
166 /* options */
167 int no_auto_mtu_check:1; /* disable auto MTU check */
168 int we_are_root:1; /* we are the root dev */
169 int stat_notify_all_requests:1; /* if we want notification on all
170 * requests, not just periodic
171 * refreshes.. */
172 int root_refresh_interval; /* if root, defaults to 10000(ms) */
173 char *root_trace; /* lowest level device, e.g. eth0 */
174 loc_t antenna_offset; /* position offset of antenna */
175 } lp_opts_t;
176
177
178 int lp_register(lp_opts_t *opts, lp_context_t **ref);
179 void lp_destroy(lp_context_t *context);
180
181 /* generally used only by ceiling array */
182 void lp_register_in_class(char *class_name, char *link_name);
183
184 /* if a channel model is active, lp_register will report
185 * a retval of LP_CHANNEL_MODEL_ACTIVE, indicating that your
186 * driver should go "dormant" because the devices are provided
187 * by the channel simulator */
188 #define LP_CHANNEL_MODEL_ACTIVE -2
189
190 /* lp_check_sim() returns true if we are overridden by a sim component */
191 int lp_check_sim(lp_opts_t *opts);
192
193 /* upcalls to pass data to clients */
194 void lp_receive(lp_context_t *lp, const link_pkt_t *data, int data_len);
195 void lp_loop_receive(lp_context_t *lp, const link_pkt_t *data, int data_len);
196 int lp_loop_needed(lp_context_t *lp);
197 void lp_unblock(lp_context_t *lp, int retval);
198
199 /* accessors */
200 lp_opts_t *lp_opts(lp_context_t *lp);
201 void *lp_data(lp_context_t *lp);
202 link_pkt_t *lp_get_outgoing_pkt(lp_context_t *lp);
203 int lp_get_outgoing_datalen(lp_context_t *lp);
204 int lp_get_promisc_state(lp_context_t *lp);
205
206 /* push updated status info to the link provider instance */
207 void lp_push_status(lp_context_t *lp, link_status_t *new_status);
208
209 /* update the root trace string */
210 void lp_update_root_trace(lp_context_t *context, const char *trace, const char *description);
211
212 /* get the name of the link subdevice */
213 char *lp_name(lp_context_t *lp, char *suffix);
214
215 /* used to append usage information for standard commands */
216 void lp_add_standard_usage(buf_t *buf, char *cmd);
217
218 /* report error counts */
219 void lp_report_tx_error(lp_context_t *lp);
220 void lp_report_rx_error(lp_context_t *lp);
221
222
223 /********************************************************************/
224 /*********************** Link User Interface ************************/
225 /********************************************************************/
226
227 /* typedef link user context */
228 typedef struct _lu_context lu_context_t;
229
230 /* reception of new data
231 * NOTE: link_pkt_t is allocated, the callback is expected to free it! */
232 typedef int (*lu_pkt_receive_cb_t)(lu_context_t *lu, link_pkt_t *pkt, ssize_t data_len);
233
234
235 /* notification of new status / writability */
236 typedef int (*lu_notify_cb_t)(lu_context_t *lu);
237
238
239 /* options struct for opening a link user connection */
240 typedef struct lu_opts {
241 link_opts_t opts; /* common options */
242 lu_pkt_receive_cb_t receive; /* Callback when packets arrive */
243 lu_notify_cb_t writable; /* ...when the dev is writable */
244 lu_notify_cb_t status_notify; /* ...when the status changes */
245 lu_notify_cb_t configure; /* ...when the link is opened */
246 int promisc; /* set promisc mode to active, passive, or none
247 * (see link_ioctls.h) */
248 int blocking_writes; /* enable send() to block */
249 } lu_opts_t;
250
251
252 /* connecting and disconnecting from a link */
253 int lu_open(lu_opts_t *opts, lu_context_t **ref);
254 void lu_destroy(lu_context_t *lu);
255
256 /* return current poll flags for this link user, or -1 if error */
257 int lu_poll(lu_context_t *lu);
258
259 /* send a packet to the link, data_len is length of the payload */
260 int lu_send(lu_context_t *lu, link_pkt_t *pkt, ssize_t data_len);
261 int lu_set_blocking_mode(lu_context_t *lu, int blocking);
262
263 /* Simpler function to send a packet if user does not have to set too many
264 * fields in the link_pkt struct.
265 * Returns -1 on failure, and 0 on success */
266 gint lu_send_simple(lu_context_t *lu, if_id_t dst, if_id_t src,
267 int pkt_type, void* pkt, ssize_t data_len);
268
269 /* control event enable */
270 void lu_writable_cb_set_enable(lu_context_t *lu, int enable);
271 void lu_readable_cb_set_enable(lu_context_t *lu, int enable);
272 int lu_writable_cb_get_enable(lu_context_t *lu);
273 int lu_readable_cb_get_enable(lu_context_t *lu);
274
275 /* retrieve link status, or just mtu or interface id */
276 int lu_status(lu_context_t *lu, link_status_t *status_return);
277 int lu_force_status(lu_context_t *lu, link_status_t *status_return);
278 int lu_get_mtu(lu_context_t *lu, uint16_t *mtu);
279 int lu_get_if_id(lu_context_t *lu, if_id_t *if_id);
280 int lu_get_root_link_dev(lu_context_t *lu, char *device);
281
282 /* issue command to link command device */
283 int lu_printf_command(lu_context_t *lu, const char *fmt, ...)
284 __attribute__ ((format (printf, 2, 3)));
285
286 /* issue ioctl command */
287 int lu_ioctl(lu_context_t *lu, int cmd, void *arg);
288
289 /* setting promiscuous mode to active, passive,
290 * or none (see link_ioctls.h) */
291 int lu_set_promisc(lu_context_t *lu, int enable);
292
293 /* accessor functions */
294 lu_opts_t *lu_opts(lu_context_t *lu);
295 void *lu_data(lu_context_t *lu);
296
297 /* create link device name */
298 char *lu_name(lu_context_t *lu, char *suffix);
299
300
301 /*
302 * link_status_t related functions
303 */
304
305 int link_status_to_buf(buf_t *buf, link_status_t *stat);
306 int link_hdr_to_buf(buf_t *buf, link_pkt_t *hdr);
307 int link_type_to_buf(buf_t *buf, link_pkt_t *hdr);
308
309 /********************************************************************/
310 /****************** Command Line Helper Functions *******************/
311 /********************************************************************/
312
313
314 /*
315 * Simple command line helper functions
316 */
317
318 /* parses out the --uses flag, or uses default if not found */
319 char *link_parse_uses(int *argc, char **argv, char *default_name);
320
321
322 char **link_parse_uses_multi(int *argc, char **argv, char *default_name);
323 char *link_parse_provides(int *argc, char **argv, char *default_name);
324 char **link_parse_provides_multi(int *argc, char **argv, char *default_name);
325 char *link_parse_if_class(int *argc, char **argv, char *default_class);
326 char *link_parse_uses_class(int *argc, char **argv, char *default_class);
327
328 /* Translates the link->type field based on pre-defined enum in
329 * link_structs.h */
330 char *link_translate_pkt_type(int link_type);
331 int link_parse_pkt_type(char *type);
332
333
334 /******************** CL Helper Data Structures *********************/
335
336 /* helper struct to parse command line arguments for used and provided
337 * link interfaces */
338 typedef struct link_ifs {
339 link_opts_t *provides; /* link interfaces provided */
340 int num_provided; /* number of interfaces provided */
341 link_opts_t *uses; /* link interfaces used */
342 int num_used; /* number of interfaces used */
343 } link_ifs_t;
344
345
346 void link_config(link_ifs_t *ifs, int *argc, char **argv);
347 int link_addone(link_opts_t **opts, char *string);
348
349 void link_usage(char **usage, char **expl);
350
351 /*********** Various utilities for dealing with a link_pkt **********/
352
353 /*
354 * Link receipts.. metadata about a previously sent packet
355 */
356
357 int link_receipt_is_requested(link_pkt_t *pkt);
358 int link_receipt_request(link_pkt_t *pkt, void *info);
359 int link_receipt_for_us(link_pkt_t *pkt);
360
361
362 #endif /* __LINK_H__ */
363
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.