bge: Avoid accessing invalid internal memory region on BCM5906
[dragonfly.git] / sys / netgraph / ng_parse.h
CommitLineData
984263bc
MD
1
2/*
3 * ng_parse.h
4 *
5 * Copyright (c) 1999 Whistle Communications, Inc.
6 * All rights reserved.
7 *
8 * Subject to the following obligations and disclaimer of warranty, use and
9 * redistribution of this software, in source or object code forms, with or
10 * without modifications are expressly permitted by Whistle Communications;
11 * provided, however, that:
12 * 1. Any and all reproductions of the source or object code must include the
13 * copyright notice above and the following disclaimer of warranties; and
14 * 2. No rights are granted, in any manner or form, to use Whistle
15 * Communications, Inc. trademarks, including the mark "WHISTLE
16 * COMMUNICATIONS" on advertising, endorsements, or otherwise except as
17 * such appears in the above copyright notice or in the software.
18 *
19 * THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
20 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
21 * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
22 * INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
23 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
24 * WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
25 * REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
26 * SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
27 * IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
28 * RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
29 * WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
30 * PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
31 * SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
32 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 * THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
35 * OF SUCH DAMAGE.
36 *
37 * Author: Archie Cobbs <archie@freebsd.org>
38 *
39 * $Whistle: ng_parse.h,v 1.2 1999/11/29 01:43:48 archie Exp $
40 * $FreeBSD: src/sys/netgraph/ng_parse.h,v 1.2.4.4 2002/07/02 23:44:03 archie Exp $
f15ba1a8 41 * $DragonFly: src/sys/netgraph/ng_parse.h,v 1.4 2007/06/03 20:51:10 dillon Exp $
984263bc
MD
42 */
43
44#ifndef _NETGRAPH_PARSE_H_
45#define _NETGRAPH_PARSE_H_
46
1bd40720
MD
47#ifndef _SYS_TYPES_H_
48#include <sys/types.h>
49#endif
50
984263bc
MD
51/*
52
53 This defines a library of routines for converting between various C
54 language types in binary form and ASCII strings. Types are user
55 definable. Several pre-defined types are supplied, for some common
56 C types: structures, variable and fixed length arrays, integer types,
57 variable and fixed length strings, IP addresses, etc.
58
59 A netgraph node type may provide a list of types that correspond to
60 the structures it expects to send and receive in the arguments field
61 of a control message. This allows these messages to be converted
62 between their native binary form and the corresponding ASCII form.
63
64 A future use of the ASCII form may be for inter-machine communication
65 of control messages, because the ASCII form is machine independent
66 whereas the native binary form is not.
67
68 Syntax
69 ------
70
71 Structures:
72
73 '{' [ <name>=<value> ... ] '}'
74
75 Omitted fields have their default values by implication.
76 The order in which the fields are specified does not matter.
77
78 Arrays:
79
80 '[' [ [index=]<value> ... ] ']'
81
82 Element value may be specified with or without the "<index>=" prefix;
83 If omitted, the index after the previous element is used.
84 Omitted fields have their default values by implication.
85
86 Strings:
87
88 "foo bar blah\r\n"
89
90 That is, strings are specified just like C strings. The usual
91 backslash escapes are accepted.
92
93 Other simple types (integers, IP addresses) have their obvious forms.
94
95 Example
96 -------
97
98 Suppose we have a netgraph command that takes as an argument
99 a 'struct foo' shown below. Here is an example of a possible
100 value for the structure, and the corresponding ASCII encoding
101 of that value:
102
103 Structure Binary value
104 --------- ------------
105
106 struct foo {
107 struct in_addr ip; 01 02 03 04
108 int bar; 00 00 00 00
109 char label[8]; 61 62 63 0a 00 00 00 00
110 u_char alen; 03 00
111 short ary[0]; 05 00 00 00 0a 00
112 };
113
114 ASCII value
115 -----------
116
117 { ip=1.2.3.4 label="abc\n" alen=3 ary=[ 5 2=10 ] }
118
119 Note that omitted fields and array elements get their default
120 values ("bar" and ary[2]), and that the alignment is handled
121 automatically (the extra 00 byte after "num"). Also, since byte
122 order and alignment are inherently machine dependent, so is this
123 conversion process. The above example shows an x86 (little
124 endian) encoding. Also the above example is tricky because the
125 structure is variable length, depending on 'alen', the number of
126 elements in the array 'ary'.
127
128 Here is how one would define a parse type for the above structure,
129 subclassing the pre-defined types below. We construct the type in
130 a 'bottom up' fashion, defining each field's type first, then the
131 type for the whole structure ('//' comments used to avoid breakage).
132
133 // Super-type info for 'label' field
134 struct ng_parse_fixedstring_info foo_label_info = { 8 };
135
136 // Parse type for 'label' field
137 struct ng_parse_type foo_label_type = {
138 &ng_parse_fixedstring_type // super-type
139 &foo_label_info // super-type info
140 };
141
142 #define OFFSETOF(s, e) ((char *)&((s *)0)->e - (char *)((s *)0))
143
144 // Function to compute the length of the array 'ary', which
145 // is variable length, depending on the previous field 'alen'.
146 // Upon entry 'buf' will be pointing at &ary[0].
147 int
148 foo_ary_getLength(const struct ng_parse_type *type,
149 const u_char *start, const u_char *buf)
150 {
151 const struct foo *f;
152
153 f = (const struct foo *)(buf - OFFSETOF(struct foo, ary));
154 return f->alen;
155 }
156
157 // Super-type info for 'ary' field
158 struct ng_parse_array_info foo_ary_info = {
159 &ng_parse_int16_type, // element type
160 &foo_ary_getLength // func to get array length
161 }
162
163 // Parse type for 'ary' field
164 struct ng_parse_type foo_ary_type = {
165 &ng_parse_array_type, // super-type
166 &foo_ary_info // super-type info
167 };
168
169 // Super-type info for struct foo
170 struct ng_parse_struct_field foo_fields[] = {
171 { "ip", &ng_parse_ipaddr_type },
172 { "bar", &ng_parse_int32_type },
173 { "label", &foo_label_type },
174 { "alen", &ng_parse_uint8_type },
175 { "ary", &foo_ary_type },
176 { NULL }
177 };
178
179 // Parse type for struct foo
180 struct ng_parse_type foo_type = {
181 &ng_parse_struct_type, // super-type
182 &foo_fields // super-type info
183 };
184
185 To define a type, you can define it as a sub-type of a predefined
186 type as shown above, possibly overriding some of the predefined
187 type's methods, or define an entirely new syntax, with the restriction
188 that the ASCII representation of your type's value must not contain
189 any whitespace or any of these characters: { } [ ] = "
190
191 See ng_ksocket.c for an example of how to do this for 'struct sockaddr'.
192 See ng_parse.c to see implementations of the pre-defined types below.
193
194*/
195
196/************************************************************************
197 METHODS REQUIRED BY A TYPE
198 ************************************************************************/
199
200/*
201 * Three methods are required for a type. These may be given explicitly
202 * or, if NULL, inherited from the super-type. The 'getDefault' method
203 * is always optional; the others are required if there is no super-type.
204 */
205
206struct ng_parse_type;
207
208/*
209 * Convert ASCII to binary according to the supplied type.
210 *
211 * The ASCII characters begin at offset *off in 'string'. The binary
212 * representation is put into 'buf', which has at least *buflen bytes.
213 * 'start' points to the first byte output by ng_parse() (ie, start <= buf).
214 *
215 * Upon return, *buflen contains the length of the new binary data, and
216 * *off is updated to point just past the end of the parsed range of
217 * characters, or, in the case of an error, to the offending character(s).
218 *
219 * Return values:
220 * 0 Success; *buflen holds the length of the data
221 * and *off points just past the last char parsed.
222 * EALREADY Field specified twice
223 * ENOENT Unknown field
224 * E2BIG Array or character string overflow
225 * ERANGE Output was longer than *buflen bytes
226 * EINVAL Parse failure or other invalid content
227 * ENOMEM Out of memory
228 * EOPNOTSUPP Mandatory array/structure element missing
229 */
230typedef int ng_parse_t(const struct ng_parse_type *type, const char *string,
231 int *off, const u_char *start,
232 u_char *buf, int *buflen);
233
234/*
235 * Convert binary to ASCII according to the supplied type.
236 *
237 * The results are put into 'buf', which is at least buflen bytes long.
238 * *off points to the current byte in 'data' and should be updated
239 * before return to point just past the last byte unparsed.
240 *
241 * Returns:
242 * 0 Success
243 * ERANGE Output was longer than buflen bytes
244 */
245typedef int ng_unparse_t(const struct ng_parse_type *type,
246 const u_char *data, int *off, char *buf, int buflen);
247
248/*
249 * Compute the default value according to the supplied type.
250 *
251 * Store the result in 'buf', which is at least *buflen bytes long.
252 * Upon return *buflen contains the length of the output.
253 *
254 * Returns:
255 * 0 Success
256 * ERANGE Output was longer than *buflen bytes
257 * EOPNOTSUPP Default value is not specified for this type
258 */
259typedef int ng_getDefault_t(const struct ng_parse_type *type,
260 const u_char *start, u_char *buf, int *buflen);
261
262/*
263 * Return the alignment requirement of this type. Zero is same as one.
264 */
265typedef int ng_getAlign_t(const struct ng_parse_type *type);
266
267/************************************************************************
268 TYPE DEFINITION
269 ************************************************************************/
270
271/*
272 * This structure describes a type, which may be a sub-type of another
273 * type by pointing to it with 'supertype' and possibly omitting methods.
274 * Typically the super-type requires some type-specific info, which is
275 * supplied by the 'info' field.
276 *
277 * The 'private' field is ignored by all of the pre-defined types.
278 * Sub-types may use it as they see fit.
279 *
280 * The 'getDefault' method may always be omitted (even if there is no
281 * super-type), which means the value for any item of this type must
282 * always be explicitly given.
283 */
284struct ng_parse_type {
285 const struct ng_parse_type *supertype; /* super-type, if any */
286 const void *info; /* type-specific info */
287 void *private; /* client private info */
288 ng_parse_t *parse; /* parse method */
289 ng_unparse_t *unparse; /* unparse method */
290 ng_getDefault_t *getDefault; /* get default value method */
291 ng_getAlign_t *getAlign; /* get alignment */
292};
293
294/************************************************************************
295 PRE-DEFINED TYPES
296 ************************************************************************/
297
298/*
299 * STRUCTURE TYPE
300 *
301 * This type supports arbitrary C structures. The normal field alignment
302 * rules for the local machine are applied. Fields are always parsed in
303 * field order, no matter what order they are listed in the ASCII string.
304 *
305 * Default value: Determined on a per-field basis
306 * Additional info: struct ng_parse_struct_field *
307 */
308extern const struct ng_parse_type ng_parse_struct_type;
309
310/* Each field has a name, type, and optional alignment override. If the
311 override is non-zero, the alignment is determined from the field type.
312 Note: add an extra struct ng_parse_struct_field with name == NULL
313 to indicate the end of the list. */
314struct ng_parse_struct_field {
315 const char *name; /* field name */
316 const struct ng_parse_type *type; /* field type */
317 int alignment; /* override alignment */
318};
319
320/*
321 * FIXED LENGTH ARRAY TYPE
322 *
323 * This type supports fixed length arrays, having any element type.
324 *
325 * Default value: As returned by getDefault for each index
326 * Additional info: struct ng_parse_fixedarray_info *
327 */
328extern const struct ng_parse_type ng_parse_fixedarray_type;
329
330/*
331 * Get the default value for the element at index 'index'. This method
332 * may be NULL, in which case the default value is computed from the
333 * element type. Otherwise, it should fill in the default value at *buf
334 * (having size *buflen) and update *buflen to the length of the filled-in
335 * value before return. If there is not enough routine return ERANGE.
336 */
337typedef int ng_parse_array_getDefault_t(const struct ng_parse_type *type,
338 int index, const u_char *start,
339 u_char *buf, int *buflen);
340
341struct ng_parse_fixedarray_info {
342 const struct ng_parse_type *elementType;
343 int length;
344 ng_parse_array_getDefault_t *getDefault;
345};
346
347/*
348 * VARIABLE LENGTH ARRAY TYPE
349 *
350 * Same as fixed length arrays, except that the length is determined
351 * by a function instead of a constant value.
352 *
353 * Default value: Same as with fixed length arrays
354 * Additional info: struct ng_parse_array_info *
355 */
356extern const struct ng_parse_type ng_parse_array_type;
357
358/*
359 * Return the length of the array. If the array is a field in a structure,
360 * all prior fields are guaranteed to be filled in already. Upon entry,
361 * 'start' is equal to the first byte parsed in this run, while 'buf' points
362 * to the first element of the array to be filled in.
363 */
364typedef int ng_parse_array_getLength_t(const struct ng_parse_type *type,
365 const u_char *start, const u_char *buf);
366
367struct ng_parse_array_info {
368 const struct ng_parse_type *elementType;
369 ng_parse_array_getLength_t *getLength;
370 ng_parse_array_getDefault_t *getDefault;
371};
372
373/*
374 * ARBITRARY LENGTH STRING TYPE
375 *
376 * For arbirary length, NUL-terminated strings.
377 *
378 * Default value: Empty string
379 * Additional info: None required
380 */
381extern const struct ng_parse_type ng_parse_string_type;
382
383/*
384 * BOUNDED LENGTH STRING TYPE
385 *
386 * These are strings that have a fixed-size buffer, and always include
387 * a terminating NUL character.
388 *
389 * Default value: Empty string
390 * Additional info: struct ng_parse_fixedstring_info *
391 */
392extern const struct ng_parse_type ng_parse_fixedstring_type;
393
394struct ng_parse_fixedstring_info {
395 int bufSize; /* size of buffer (including NUL) */
396};
397
398/*
399 * COMMONLY USED BOUNDED LENGTH STRING TYPES
400 */
f15ba1a8
MD
401extern const struct ng_parse_type ng_parse_nodebuf_type; /* NG_NODESIZ */
402extern const struct ng_parse_type ng_parse_hookbuf_type; /* NG_HOOKSIZ */
403extern const struct ng_parse_type ng_parse_pathbuf_type; /* NG_PATHSIZ */
404extern const struct ng_parse_type ng_parse_typebuf_type; /* NG_TYPESIZ */
405extern const struct ng_parse_type ng_parse_cmdbuf_type; /* NG_CMDSTRSIZ */
984263bc
MD
406
407/*
408 * INTEGER TYPES
409 *
410 * Default value: 0
411 * Additional info: None required
412 */
413extern const struct ng_parse_type ng_parse_int8_type;
414extern const struct ng_parse_type ng_parse_int16_type;
415extern const struct ng_parse_type ng_parse_int32_type;
416extern const struct ng_parse_type ng_parse_int64_type;
417
418/* Same thing but unparse as unsigned quantities */
419extern const struct ng_parse_type ng_parse_uint8_type;
420extern const struct ng_parse_type ng_parse_uint16_type;
421extern const struct ng_parse_type ng_parse_uint32_type;
422extern const struct ng_parse_type ng_parse_uint64_type;
423
424/* Same thing but unparse as hex quantities, e.g., "0xe7" */
425extern const struct ng_parse_type ng_parse_hint8_type;
426extern const struct ng_parse_type ng_parse_hint16_type;
427extern const struct ng_parse_type ng_parse_hint32_type;
428extern const struct ng_parse_type ng_parse_hint64_type;
429
430/*
431 * IP ADDRESS TYPE
432 *
433 * Default value: 0.0.0.0
434 * Additional info: None required
435 */
436extern const struct ng_parse_type ng_parse_ipaddr_type;
437
438/*
439 * VARIABLE LENGTH BYTE ARRAY TYPE
440 *
441 * The bytes are displayed in hex. The ASCII form may be either an
442 * array of bytes or a string constant, in which case the array is
443 * zero-filled after the string bytes.
444 *
445 * Default value: All bytes are zero
446 * Additional info: ng_parse_array_getLength_t *
447 */
448extern const struct ng_parse_type ng_parse_bytearray_type;
449
450/*
451 * NETGRAPH CONTROL MESSAGE TYPE
452 *
453 * This is the parse type for a struct ng_mesg.
454 *
455 * Default value: All fields zero
456 * Additional info: None required
457 */
458extern const struct ng_parse_type ng_parse_ng_mesg_type;
459
460/************************************************************************
461 CONVERSTION AND PARSING ROUTINES
462 ************************************************************************/
463
464/* Tokens for parsing structs and arrays */
465enum ng_parse_token {
466 T_LBRACE, /* '{' */
467 T_RBRACE, /* '}' */
468 T_LBRACKET, /* '[' */
469 T_RBRACKET, /* ']' */
470 T_EQUALS, /* '=' */
471 T_STRING, /* string in double quotes */
472 T_ERROR, /* error parsing string in double quotes */
473 T_WORD, /* anything else containing no whitespace */
474 T_EOF, /* end of string reached */
475};
476
477/*
478 * See typedef ng_parse_t for definition
479 */
480extern int ng_parse(const struct ng_parse_type *type, const char *string,
481 int *off, u_char *buf, int *buflen);
482
483/*
484 * See typedef ng_unparse_t for definition (*off assumed to be zero).
485 */
486extern int ng_unparse(const struct ng_parse_type *type,
487 const u_char *data, char *buf, int buflen);
488
489/*
490 * See typedef ng_getDefault_t for definition
491 */
492extern int ng_parse_getDefault(const struct ng_parse_type *type,
493 u_char *buf, int *buflen);
494
495/*
496 * Parse a token: '*startp' is the offset to start looking. Upon
497 * successful return, '*startp' equals the beginning of the token
498 * and '*lenp' the length. If error, '*startp' points at the
499 * offending character(s).
500 */
501extern enum ng_parse_token ng_parse_get_token(const char *s,
502 int *startp, int *lenp);
503
504/*
505 * Like above, but specifically for getting a string token and returning
506 * the string value. The string token must be enclosed in double quotes
507 * and the normal C backslash escapes are recognized. The caller must
508 * eventually free() the returned result. Returns NULL if token is
509 * not a string token, or parse or other error.
510 */
511extern char *ng_get_string_token(const char *s, int *startp, int *lenp);
512
513/*
514 * Convert a raw string into a doubly-quoted string including any
515 * necessary backslash escapes. Caller must free the result.
516 * Returns NULL if ENOMEM.
517 */
518extern char *ng_encode_string(const char *s);
519
520#endif /* _NETGRAPH_PARSE_H_ */
521