blob: 9e352f08dff39c3adcf1dc111834d7e1502f78d2 [file] [log] [blame]
Rich Lanea06d0c32013-03-25 08:52:03 -07001:: # Copyright 2013, Big Switch Networks, Inc.
2:: #
3:: # LoxiGen is licensed under the Eclipse Public License, version 1.0 (EPL), with
4:: # the following special exception:
5:: #
6:: # LOXI Exception
7:: #
8:: # As a special exception to the terms of the EPL, you may distribute libraries
9:: # generated by LoxiGen (LoxiGen Libraries) under the terms of your choice, provided
10:: # that copyright and licensing notices generated by LoxiGen are not altered or removed
11:: # from the LoxiGen Libraries and the notice provided below is (i) included in
12:: # the LoxiGen Libraries, if distributed in source code form and (ii) included in any
13:: # documentation for the LoxiGen Libraries, if distributed in binary form.
14:: #
15:: # Notice: "Copyright 2013, Big Switch Networks, Inc. This library was generated by the LoxiGen Compiler."
16:: #
17:: # You may not use this file except in compliance with the EPL or LOXI Exception. You may obtain
18:: # a copy of the EPL at:
19:: #
20:: # http://www.eclipse.org/legal/epl-v10.html
21:: #
22:: # Unless required by applicable law or agreed to in writing, software
23:: # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
24:: # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
25:: # EPL for the specific language governing permissions and limitations
26:: # under the EPL.
27::
28/* Copyright 2013, Big Switch Networks, Inc. */
29
30/**
31 * @file of_doc.h
32 * @brief Documentation of sample functions
33 *
34 * This file is for documentation purposes only
35 *
36 * Once the code is in a working state, this documentation will be
37 * transfered to the actual source files
38 *
39 * The functions documented here are simple templates for accessors that
40 * are used for all accessor members of LOCI objects. Data types are
41 * divided into:
42 *
43 * @li @c scalar Things like uint8_t, uint16_t, of_mac_addr_t as well as
44 * fixed length strings
45 * @li @c octets Arbitrary length strings of binary data
46 * @li @c composite Data members which are structures
47 * @li @c list The list abstraction for data members
48 * @li @c list_element An element of a list (usually a composite object)
49 *
50 * List elements get special treatment for iterating across a list or
51 * appending new entries to the list. All others have 'set' and 'get'
52 * operations.
53 *
54 * Scalars operations are "stateless" in that they simply
55 * update the underlying data or return that data.
56 *
57 * Composites and list members update structures to point to the
58 * underlying data. As a result, care must be taken that objects are
59 * not freed when linked composite or list members remain referring to
60 * the underlying data structure. Currently: Note that reference
61 * counting won't solve this with the current approach as the
62 * referring objects may be automatic and not subject to alloc/free
63 * operations.
64 */
65
66
67
68/**
69 * Generic documentation for scalar get methods
70 * @param obj The object being accessed
71 * @param value A pointer to a scalar instance of the proper type
72 * @return OF_ERROR_XXX
73 *
74 * Accesses the underlying wire buffer at the appropriate offset to
75 * retrieve and convert the value, placing the result in *value.
76 *
77 * Examples of scalar types include:
78 * @li uint8_t
79 * @li uint16_t
80 * @li uint32_t
81 * @li uint64_t
82 * @li of_mac_addr_t
83 *
84 * Examples calls include:
85 * @li rv = of_port_status_reason_get(obj, &reason)
86 * @li rv = of_table_mod_config_get(obj, &config)
87 *
88 * An object instance can call directly as:
89 * @li rv = obj->reason_get(obj, &reason); obj is an of_table_mod_t *
90 * @li rv = obj->config_get(obj, &config); obj is an of_table_mod_t *
91 */
92extern int of_object_scalar_member_get(of_object_t *obj, uint32_t *value);
93
94/**
95 * Generic documentation for scalar set methods
96 * @param obj The object being accessed
97 * @param value Call by value parameter with the value to set
98 * @return OF_ERROR_XXX
99 *
100 * Converts value to the proper wire representation and writes it to
101 * the underlying wire buffer at the appropriate offset.
102 */
103extern int of_object_scalar_member_set(of_object_t *obj, uint32_t value);
104
105/**
106 * Generic documentation for an octets data get method
107 * @param obj The object being accessed
108 * @param value A pointer to an of_octets_t structure to be filled out
109 * @return OF_ERROR_XXX
110 *
111 * NOTE:
112 * Sets *bytes to the number of bytes in the octet string.
113 */
114extern int of_object_octets_member_data_get(of_object_t *obj, of_octets_t *value);
115
116/**
117 * Generic documentation for an octets data set method
118 * @param obj The object being accessed
119 * @param value Pointer to an of_octets_t structure pointing to memory from
120 * which data will be copied to wire buffer
121 * @return OF_ERROR_XXX
122 *
123 * Copies data from the memory pointed to by value into the underlying
124 * wire buffer, extending the buffer if necessary. The length of obj
125 * is updated.
126 *
127 * If the length of obj changes (because the existing octets instance is of
128 * a different length) its internal length accessor is called to update
129 * anything tracking its length. This may call the object's parent
130 * length accessor with the update.
131 */
132extern int of_object_octets_member_data_set(of_object_t *obj, of_octets_t *value);
133
134/**
135 * Generic documentation for an octets pointer get method
136 * @param obj The object being accessed
137 * @param value Pointer to an of_octets_t structure to be initialized
138 * @return OF_ERROR_XXX
139 *
140 * Set the octets object *value to point to the underlying data buffer. The
141 * length member of *value is set as well.
142 *
143 * The result should be treated as READ ONLY information as modifying
144 * the buffer could cause corruption of the underlying LOCI object.
145 * To change the value (especially the length) of an octets data member,
146 * allocate and set a memory buffer and use the octets_member_data_set
147 * function.
148 */
149extern int of_object_octets_member_ptr_get(of_object_t *obj, of_octets_t *value);
150
151/**
152 * Generic documentation for a composite sub-object get method
153 * @param obj The object being accessed
154 * @param value Pointer to an object (the sub-object) of the proper type
155 * @return OF_ERROR_XXX
156 *
157 * A composite is a structure with multiple components. On a 'get'
158 * operation, a pointer (value) to an unused instance of the appropriate
159 * type is passed to this routine. That instance is intialized with the
160 * proper accessor functions for the sub-object type and the wire object
161 * is set up to point to obj's wire buffer at the appropriate offset.
162 *
163 * If changes are made to the sub-object (*value) and those changes
164 * affect the length, then the corresponding composite_set must be
165 * called to commit those changes to the parent.
166 */
167extern int of_object_composite_member_get(of_object_t *obj,
168 of_object_t *value);
169
170/**
171 * Generic documentation for a composite sub-object set method
172 * @param obj The object being accessed
173 * @param value Pointer to an object (the sub-object) of the proper type
174 * @return OF_ERROR_XXX
175 *
176 * A composite is a structure with multiple components. On a 'set'
177 * operation, a pointer (value) to an instance of the appropriate type
178 * is passed to this routine.
179 *
180 * If the parent (obj) and the child (value) point to the same underlying
181 * wire object, then the changes to the underlying buffer are already
182 * recorded.
183 *
184 * Otherwise, any existing value of the sub-object is replaced
185 * by copying the wire buffer contents from value's wire buffer to obj's
186 * wire buffer at the appropriate offset.
187 *
188 * In either case, the length of the parent will be updated if it changes.
189 */
190extern int of_object_composite_member_set(of_object_t *obj,
191 of_object_t *value);
192
193/**
194 * Generic documentation for a list sub-object get method
195 * @param obj The object being accessed
196 * @param value Pointer to an object (the list sub-object)
197 * @return OF_ERROR_XXX
198 *
199 * A list is an array of instances of objects of a common (possibly
200 * polymorphic) type. On a 'get' operation, a pointer (value) to an
201 * unused instance of the appropriate list type is passed to this
202 * routine. That instance is intialized with the proper accessor
203 * functions for the list type and the wire object is set up to point
204 * to obj's wire buffer at the appropriate offset.
205 *
206 * Currently, the list object returned by a 'get' operation should not
207 * be altered, although changes that do not affect the length of
208 * sub-objects will work.
209 *
210 * Rather, lists should either be cleared and set from completely new
211 * instances using 'list_set', or they may be built using the append
212 * operations described below.
213 *
214 * @sa of_object_list_append_bind
215 * @sa of_object_list_append
216 */
217extern int of_object_list_member_get(of_object_t *obj,
218 of_list_object_t *value);
219
220/**
221 * Generic documentation for a list entry first call
222 * @param obj The list object being accessed
223 * @param value Pointer to a generic list entry instance
224 * @return OF_ERROR_RANGE if the list is empty
225 *
226 * A list is an array of instances of objects of a common (possibly
227 * polymorphic) type.
228 *
229 * This routine is intended for iterating through a list for
230 * reading. Normally a 'get' operation will be done on the parent
231 * of the list to retrieve (a pointer to) the list, and then this routine
232 * will be called to set up a generic entry representing the first
233 * element of the list.
234 *
235 * @sa of_object_list_entry_next
236 */
237extern int of_object_list_entry_first(of_list_object_t *obj,
238 of_object_t *value);
239
240/**
241 * Generic documentation for a list entry next call
242 * @param obj The list object being accessed
243 * @param value Pointer to a generic list entry instance
244 * @return OF_ERROR_RANGE if the value already points to the last item
245 * in the list
246
247 * A list is an array of instances of objects of a common (possibly
248 * polymorphic) type.
249 *
250 * The corresponding list_entry_first must be called on the pair of
251 * parameters initially. There after, this routine will advance the
252 * pointers in the wire object of value to the subsequent entry in the
253 * list.
254 *
255 * Changes should not be made to list items using these routines,
256 * although 'set' operations which do not change the length of the
257 * instance will work.
258 *
259 * @sa of_object_list_entry_first
260 */
261extern int of_object_list_entry_next(of_list_object_t *obj,
262 of_object_t *value);
263
264/**
265 * Generic documentation for a list append bind function
266 * @param obj The list object being accessed
267 * @param value Pointer to a generic list entry instance
268 * @return OF_ERROR_XXX
269 *
270 * A list is an array of instances of objects of a common (possibly
271 * polymorphic) type.
272 *
273 * This function prepares the list for the process of appending an
274 * item to its tail. The parameter value is a pointer to a generic
275 * list entry instance. Its wire buffer is bound to that of the list
276 * at the end of the list. The length of the list is updated according
277 * to the current value setting which must be accurate.
278 *
279 * Note that since the child has not been bound to a buffer, no
280 * values have been properly recorded for the object; they must
281 * be set after this _bind call.
282 *
283 * @sa of_object_list_entry_append
284 */
285extern int of_object_list_entry_append_bind(of_list_object_t *obj,
286 of_object_t *value);
287
288/**
289 * Generic documentation for a list append function
290 * @param obj The list object being accessed
291 * @param value Pointer to a list object to be appended
292 * @return OF_ERROR_XXX
293 *
294 * A list is an array of instances of objects of a common (possibly
295 * polymorphic) type.
296 *
297 * This function takes a fully formed list entry, value, and copies
298 * that value to the end of the list. No object ownership changes
299 * with this call.
300 *
301 * @sa of_object_list_entry_append_bind
302 */
303extern int of_object_list_entry_append(of_list_object_t *obj,
304 of_object_t *value);
305
306/* This is from loci.h */
307
308/**
309 * Inheritance super class for of_queue_prop
310 *
311 * This class is the union of of_queue_prop classes. You can refer
312 * to it untyped by refering to the member 'header' whose structure
313 * is common across all sub-classes.
314 */
315
316union of_queue_prop_u {
317 of_queue_prop_header_t header; /* Generic instance */
318 of_queue_prop_min_rate_t min_rate;
319 of_queue_prop_max_rate_t max_rate;
320 of_queue_prop_experimenter_t experimenter;
321};
322
323/**
324 * Inheritance super class for of_action
325 *
326 * This class is the union of of_action classes. You can refer
327 * to it untyped by refering to the member 'header' whose structure
328 * is common across all sub-classes.
329 */
330
331union of_action_u {
332 of_action_header_t header; /* Generic instance */
333 of_action_copy_ttl_out_t copy_ttl_out;
334 of_action_set_mpls_tc_t set_mpls_tc;
335 of_action_set_field_t set_field;
336 of_action_set_nw_tos_t set_nw_tos;
337 of_action_dec_mpls_ttl_t dec_mpls_ttl;
338 of_action_set_nw_dst_t set_nw_dst;
339 of_action_set_mpls_label_t set_mpls_label;
340 of_action_group_t group;
341 of_action_set_nw_src_t set_nw_src;
342 of_action_set_vlan_vid_t set_vlan_vid;
343 of_action_set_mpls_ttl_t set_mpls_ttl;
344 of_action_pop_vlan_t pop_vlan;
345 of_action_set_tp_dst_t set_tp_dst;
346 of_action_pop_mpls_t pop_mpls;
347 of_action_push_vlan_t push_vlan;
348 of_action_set_vlan_pcp_t set_vlan_pcp;
349 of_action_enqueue_t enqueue;
350 of_action_set_tp_src_t set_tp_src;
351 of_action_experimenter_t experimenter;
352 of_action_set_nw_ttl_t set_nw_ttl;
353 of_action_copy_ttl_in_t copy_ttl_in;
354 of_action_set_nw_ecn_t set_nw_ecn;
355 of_action_strip_vlan_t strip_vlan;
356 of_action_set_dl_dst_t set_dl_dst;
357 of_action_push_mpls_t push_mpls;
358 of_action_dec_nw_ttl_t dec_nw_ttl;
359 of_action_set_dl_src_t set_dl_src;
360 of_action_set_queue_t set_queue;
361 of_action_output_t output;
362};
363
364/**
365 * Inheritance super class for of_instruction
366 *
367 * This class is the union of of_instruction classes. You can refer
368 * to it untyped by refering to the member 'header' whose structure
369 * is common across all sub-classes.
370 */
371
372union of_instruction_u {
373 of_instruction_header_t header; /* Generic instance */
374 of_instruction_clear_actions_t clear_actions;
375 of_instruction_write_actions_t write_actions;
376 of_instruction_goto_table_t goto_table;
377 of_instruction_apply_actions_t apply_actions;
378 of_instruction_experimenter_t experimenter;
379 of_instruction_write_metadata_t write_metadata;
380};
381
382/**
383 * Inheritance super class for of_oxm
384 *
385 * This class is the union of of_oxm classes. You can refer
386 * to it untyped by refering to the member 'header' whose structure
387 * is common across all sub-classes.
388 */
389
390union of_oxm_u {
391 of_oxm_header_t header; /* Generic instance */
392 of_oxm_ipv6_flabel_t ipv6_flabel;
393 of_oxm_ipv6_dst_masked_t ipv6_dst_masked;
394 of_oxm_vlan_pcp_t vlan_pcp;
395 of_oxm_ipv4_src_t ipv4_src;
396 of_oxm_ipv6_dst_t ipv6_dst;
397 of_oxm_arp_tpa_t arp_tpa;
398 of_oxm_icmpv6_type_t icmpv6_type;
399 of_oxm_arp_sha_t arp_sha;
400 of_oxm_ipv6_src_t ipv6_src;
401 of_oxm_sctp_src_t sctp_src;
402 of_oxm_icmpv6_code_t icmpv6_code;
403 of_oxm_metadata_masked_t metadata_masked;
404 of_oxm_eth_src_masked_t eth_src_masked;
405 of_oxm_eth_dst_t eth_dst;
406 of_oxm_ipv6_nd_sll_t ipv6_nd_sll;
407 of_oxm_mpls_tc_t mpls_tc;
408 of_oxm_arp_op_t arp_op;
409 of_oxm_vlan_vid_masked_t vlan_vid_masked;
410 of_oxm_eth_type_t eth_type;
411 of_oxm_in_phy_port_t in_phy_port;
412 of_oxm_vlan_vid_t vlan_vid;
413 of_oxm_arp_tha_t arp_tha;
414 of_oxm_arp_tpa_masked_t arp_tpa_masked;
415 of_oxm_in_port_t in_port;
416 of_oxm_ip_dscp_t ip_dscp;
417 of_oxm_sctp_dst_t sctp_dst;
418 of_oxm_icmpv4_code_t icmpv4_code;
419 of_oxm_eth_dst_masked_t eth_dst_masked;
420 of_oxm_tcp_src_t tcp_src;
421 of_oxm_ip_ecn_t ip_ecn;
422 of_oxm_ipv6_src_masked_t ipv6_src_masked;
423 of_oxm_ipv4_src_masked_t ipv4_src_masked;
424 of_oxm_udp_dst_t udp_dst;
425 of_oxm_arp_spa_t arp_spa;
426 of_oxm_ipv6_nd_target_t ipv6_nd_target;
427 of_oxm_ipv4_dst_t ipv4_dst;
428 of_oxm_ipv4_dst_masked_t ipv4_dst_masked;
429 of_oxm_eth_src_t eth_src;
430 of_oxm_udp_src_t udp_src;
431 of_oxm_ipv6_nd_tll_t ipv6_nd_tll;
432 of_oxm_icmpv4_type_t icmpv4_type;
433 of_oxm_mpls_label_t mpls_label;
434 of_oxm_tcp_dst_t tcp_dst;
435 of_oxm_ip_proto_t ip_proto;
436 of_oxm_metadata_t metadata;
437 of_oxm_arp_spa_masked_t arp_spa_masked;
438};
439