blob: 9e352f08dff39c3adcf1dc111834d7e1502f78d2 [file] [log] [blame]
:: # Copyright 2013, Big Switch Networks, Inc.
:: #
:: # LoxiGen is licensed under the Eclipse Public License, version 1.0 (EPL), with
:: # the following special exception:
:: #
:: # LOXI Exception
:: #
:: # As a special exception to the terms of the EPL, you may distribute libraries
:: # generated by LoxiGen (LoxiGen Libraries) under the terms of your choice, provided
:: # that copyright and licensing notices generated by LoxiGen are not altered or removed
:: # from the LoxiGen Libraries and the notice provided below is (i) included in
:: # the LoxiGen Libraries, if distributed in source code form and (ii) included in any
:: # documentation for the LoxiGen Libraries, if distributed in binary form.
:: #
:: # Notice: "Copyright 2013, Big Switch Networks, Inc. This library was generated by the LoxiGen Compiler."
:: #
:: # You may not use this file except in compliance with the EPL or LOXI Exception. You may obtain
:: # a copy of the EPL at:
:: #
:: # http://www.eclipse.org/legal/epl-v10.html
:: #
:: # Unless required by applicable law or agreed to in writing, software
:: # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
:: # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
:: # EPL for the specific language governing permissions and limitations
:: # under the EPL.
::
/* Copyright 2013, Big Switch Networks, Inc. */
/**
* @file of_doc.h
* @brief Documentation of sample functions
*
* This file is for documentation purposes only
*
* Once the code is in a working state, this documentation will be
* transfered to the actual source files
*
* The functions documented here are simple templates for accessors that
* are used for all accessor members of LOCI objects. Data types are
* divided into:
*
* @li @c scalar Things like uint8_t, uint16_t, of_mac_addr_t as well as
* fixed length strings
* @li @c octets Arbitrary length strings of binary data
* @li @c composite Data members which are structures
* @li @c list The list abstraction for data members
* @li @c list_element An element of a list (usually a composite object)
*
* List elements get special treatment for iterating across a list or
* appending new entries to the list. All others have 'set' and 'get'
* operations.
*
* Scalars operations are "stateless" in that they simply
* update the underlying data or return that data.
*
* Composites and list members update structures to point to the
* underlying data. As a result, care must be taken that objects are
* not freed when linked composite or list members remain referring to
* the underlying data structure. Currently: Note that reference
* counting won't solve this with the current approach as the
* referring objects may be automatic and not subject to alloc/free
* operations.
*/
/**
* Generic documentation for scalar get methods
* @param obj The object being accessed
* @param value A pointer to a scalar instance of the proper type
* @return OF_ERROR_XXX
*
* Accesses the underlying wire buffer at the appropriate offset to
* retrieve and convert the value, placing the result in *value.
*
* Examples of scalar types include:
* @li uint8_t
* @li uint16_t
* @li uint32_t
* @li uint64_t
* @li of_mac_addr_t
*
* Examples calls include:
* @li rv = of_port_status_reason_get(obj, &reason)
* @li rv = of_table_mod_config_get(obj, &config)
*
* An object instance can call directly as:
* @li rv = obj->reason_get(obj, &reason); obj is an of_table_mod_t *
* @li rv = obj->config_get(obj, &config); obj is an of_table_mod_t *
*/
extern int of_object_scalar_member_get(of_object_t *obj, uint32_t *value);
/**
* Generic documentation for scalar set methods
* @param obj The object being accessed
* @param value Call by value parameter with the value to set
* @return OF_ERROR_XXX
*
* Converts value to the proper wire representation and writes it to
* the underlying wire buffer at the appropriate offset.
*/
extern int of_object_scalar_member_set(of_object_t *obj, uint32_t value);
/**
* Generic documentation for an octets data get method
* @param obj The object being accessed
* @param value A pointer to an of_octets_t structure to be filled out
* @return OF_ERROR_XXX
*
* NOTE:
* Sets *bytes to the number of bytes in the octet string.
*/
extern int of_object_octets_member_data_get(of_object_t *obj, of_octets_t *value);
/**
* Generic documentation for an octets data set method
* @param obj The object being accessed
* @param value Pointer to an of_octets_t structure pointing to memory from
* which data will be copied to wire buffer
* @return OF_ERROR_XXX
*
* Copies data from the memory pointed to by value into the underlying
* wire buffer, extending the buffer if necessary. The length of obj
* is updated.
*
* If the length of obj changes (because the existing octets instance is of
* a different length) its internal length accessor is called to update
* anything tracking its length. This may call the object's parent
* length accessor with the update.
*/
extern int of_object_octets_member_data_set(of_object_t *obj, of_octets_t *value);
/**
* Generic documentation for an octets pointer get method
* @param obj The object being accessed
* @param value Pointer to an of_octets_t structure to be initialized
* @return OF_ERROR_XXX
*
* Set the octets object *value to point to the underlying data buffer. The
* length member of *value is set as well.
*
* The result should be treated as READ ONLY information as modifying
* the buffer could cause corruption of the underlying LOCI object.
* To change the value (especially the length) of an octets data member,
* allocate and set a memory buffer and use the octets_member_data_set
* function.
*/
extern int of_object_octets_member_ptr_get(of_object_t *obj, of_octets_t *value);
/**
* Generic documentation for a composite sub-object get method
* @param obj The object being accessed
* @param value Pointer to an object (the sub-object) of the proper type
* @return OF_ERROR_XXX
*
* A composite is a structure with multiple components. On a 'get'
* operation, a pointer (value) to an unused instance of the appropriate
* type is passed to this routine. That instance is intialized with the
* proper accessor functions for the sub-object type and the wire object
* is set up to point to obj's wire buffer at the appropriate offset.
*
* If changes are made to the sub-object (*value) and those changes
* affect the length, then the corresponding composite_set must be
* called to commit those changes to the parent.
*/
extern int of_object_composite_member_get(of_object_t *obj,
of_object_t *value);
/**
* Generic documentation for a composite sub-object set method
* @param obj The object being accessed
* @param value Pointer to an object (the sub-object) of the proper type
* @return OF_ERROR_XXX
*
* A composite is a structure with multiple components. On a 'set'
* operation, a pointer (value) to an instance of the appropriate type
* is passed to this routine.
*
* If the parent (obj) and the child (value) point to the same underlying
* wire object, then the changes to the underlying buffer are already
* recorded.
*
* Otherwise, any existing value of the sub-object is replaced
* by copying the wire buffer contents from value's wire buffer to obj's
* wire buffer at the appropriate offset.
*
* In either case, the length of the parent will be updated if it changes.
*/
extern int of_object_composite_member_set(of_object_t *obj,
of_object_t *value);
/**
* Generic documentation for a list sub-object get method
* @param obj The object being accessed
* @param value Pointer to an object (the list sub-object)
* @return OF_ERROR_XXX
*
* A list is an array of instances of objects of a common (possibly
* polymorphic) type. On a 'get' operation, a pointer (value) to an
* unused instance of the appropriate list type is passed to this
* routine. That instance is intialized with the proper accessor
* functions for the list type and the wire object is set up to point
* to obj's wire buffer at the appropriate offset.
*
* Currently, the list object returned by a 'get' operation should not
* be altered, although changes that do not affect the length of
* sub-objects will work.
*
* Rather, lists should either be cleared and set from completely new
* instances using 'list_set', or they may be built using the append
* operations described below.
*
* @sa of_object_list_append_bind
* @sa of_object_list_append
*/
extern int of_object_list_member_get(of_object_t *obj,
of_list_object_t *value);
/**
* Generic documentation for a list entry first call
* @param obj The list object being accessed
* @param value Pointer to a generic list entry instance
* @return OF_ERROR_RANGE if the list is empty
*
* A list is an array of instances of objects of a common (possibly
* polymorphic) type.
*
* This routine is intended for iterating through a list for
* reading. Normally a 'get' operation will be done on the parent
* of the list to retrieve (a pointer to) the list, and then this routine
* will be called to set up a generic entry representing the first
* element of the list.
*
* @sa of_object_list_entry_next
*/
extern int of_object_list_entry_first(of_list_object_t *obj,
of_object_t *value);
/**
* Generic documentation for a list entry next call
* @param obj The list object being accessed
* @param value Pointer to a generic list entry instance
* @return OF_ERROR_RANGE if the value already points to the last item
* in the list
* A list is an array of instances of objects of a common (possibly
* polymorphic) type.
*
* The corresponding list_entry_first must be called on the pair of
* parameters initially. There after, this routine will advance the
* pointers in the wire object of value to the subsequent entry in the
* list.
*
* Changes should not be made to list items using these routines,
* although 'set' operations which do not change the length of the
* instance will work.
*
* @sa of_object_list_entry_first
*/
extern int of_object_list_entry_next(of_list_object_t *obj,
of_object_t *value);
/**
* Generic documentation for a list append bind function
* @param obj The list object being accessed
* @param value Pointer to a generic list entry instance
* @return OF_ERROR_XXX
*
* A list is an array of instances of objects of a common (possibly
* polymorphic) type.
*
* This function prepares the list for the process of appending an
* item to its tail. The parameter value is a pointer to a generic
* list entry instance. Its wire buffer is bound to that of the list
* at the end of the list. The length of the list is updated according
* to the current value setting which must be accurate.
*
* Note that since the child has not been bound to a buffer, no
* values have been properly recorded for the object; they must
* be set after this _bind call.
*
* @sa of_object_list_entry_append
*/
extern int of_object_list_entry_append_bind(of_list_object_t *obj,
of_object_t *value);
/**
* Generic documentation for a list append function
* @param obj The list object being accessed
* @param value Pointer to a list object to be appended
* @return OF_ERROR_XXX
*
* A list is an array of instances of objects of a common (possibly
* polymorphic) type.
*
* This function takes a fully formed list entry, value, and copies
* that value to the end of the list. No object ownership changes
* with this call.
*
* @sa of_object_list_entry_append_bind
*/
extern int of_object_list_entry_append(of_list_object_t *obj,
of_object_t *value);
/* This is from loci.h */
/**
* Inheritance super class for of_queue_prop
*
* This class is the union of of_queue_prop classes. You can refer
* to it untyped by refering to the member 'header' whose structure
* is common across all sub-classes.
*/
union of_queue_prop_u {
of_queue_prop_header_t header; /* Generic instance */
of_queue_prop_min_rate_t min_rate;
of_queue_prop_max_rate_t max_rate;
of_queue_prop_experimenter_t experimenter;
};
/**
* Inheritance super class for of_action
*
* This class is the union of of_action classes. You can refer
* to it untyped by refering to the member 'header' whose structure
* is common across all sub-classes.
*/
union of_action_u {
of_action_header_t header; /* Generic instance */
of_action_copy_ttl_out_t copy_ttl_out;
of_action_set_mpls_tc_t set_mpls_tc;
of_action_set_field_t set_field;
of_action_set_nw_tos_t set_nw_tos;
of_action_dec_mpls_ttl_t dec_mpls_ttl;
of_action_set_nw_dst_t set_nw_dst;
of_action_set_mpls_label_t set_mpls_label;
of_action_group_t group;
of_action_set_nw_src_t set_nw_src;
of_action_set_vlan_vid_t set_vlan_vid;
of_action_set_mpls_ttl_t set_mpls_ttl;
of_action_pop_vlan_t pop_vlan;
of_action_set_tp_dst_t set_tp_dst;
of_action_pop_mpls_t pop_mpls;
of_action_push_vlan_t push_vlan;
of_action_set_vlan_pcp_t set_vlan_pcp;
of_action_enqueue_t enqueue;
of_action_set_tp_src_t set_tp_src;
of_action_experimenter_t experimenter;
of_action_set_nw_ttl_t set_nw_ttl;
of_action_copy_ttl_in_t copy_ttl_in;
of_action_set_nw_ecn_t set_nw_ecn;
of_action_strip_vlan_t strip_vlan;
of_action_set_dl_dst_t set_dl_dst;
of_action_push_mpls_t push_mpls;
of_action_dec_nw_ttl_t dec_nw_ttl;
of_action_set_dl_src_t set_dl_src;
of_action_set_queue_t set_queue;
of_action_output_t output;
};
/**
* Inheritance super class for of_instruction
*
* This class is the union of of_instruction classes. You can refer
* to it untyped by refering to the member 'header' whose structure
* is common across all sub-classes.
*/
union of_instruction_u {
of_instruction_header_t header; /* Generic instance */
of_instruction_clear_actions_t clear_actions;
of_instruction_write_actions_t write_actions;
of_instruction_goto_table_t goto_table;
of_instruction_apply_actions_t apply_actions;
of_instruction_experimenter_t experimenter;
of_instruction_write_metadata_t write_metadata;
};
/**
* Inheritance super class for of_oxm
*
* This class is the union of of_oxm classes. You can refer
* to it untyped by refering to the member 'header' whose structure
* is common across all sub-classes.
*/
union of_oxm_u {
of_oxm_header_t header; /* Generic instance */
of_oxm_ipv6_flabel_t ipv6_flabel;
of_oxm_ipv6_dst_masked_t ipv6_dst_masked;
of_oxm_vlan_pcp_t vlan_pcp;
of_oxm_ipv4_src_t ipv4_src;
of_oxm_ipv6_dst_t ipv6_dst;
of_oxm_arp_tpa_t arp_tpa;
of_oxm_icmpv6_type_t icmpv6_type;
of_oxm_arp_sha_t arp_sha;
of_oxm_ipv6_src_t ipv6_src;
of_oxm_sctp_src_t sctp_src;
of_oxm_icmpv6_code_t icmpv6_code;
of_oxm_metadata_masked_t metadata_masked;
of_oxm_eth_src_masked_t eth_src_masked;
of_oxm_eth_dst_t eth_dst;
of_oxm_ipv6_nd_sll_t ipv6_nd_sll;
of_oxm_mpls_tc_t mpls_tc;
of_oxm_arp_op_t arp_op;
of_oxm_vlan_vid_masked_t vlan_vid_masked;
of_oxm_eth_type_t eth_type;
of_oxm_in_phy_port_t in_phy_port;
of_oxm_vlan_vid_t vlan_vid;
of_oxm_arp_tha_t arp_tha;
of_oxm_arp_tpa_masked_t arp_tpa_masked;
of_oxm_in_port_t in_port;
of_oxm_ip_dscp_t ip_dscp;
of_oxm_sctp_dst_t sctp_dst;
of_oxm_icmpv4_code_t icmpv4_code;
of_oxm_eth_dst_masked_t eth_dst_masked;
of_oxm_tcp_src_t tcp_src;
of_oxm_ip_ecn_t ip_ecn;
of_oxm_ipv6_src_masked_t ipv6_src_masked;
of_oxm_ipv4_src_masked_t ipv4_src_masked;
of_oxm_udp_dst_t udp_dst;
of_oxm_arp_spa_t arp_spa;
of_oxm_ipv6_nd_target_t ipv6_nd_target;
of_oxm_ipv4_dst_t ipv4_dst;
of_oxm_ipv4_dst_masked_t ipv4_dst_masked;
of_oxm_eth_src_t eth_src;
of_oxm_udp_src_t udp_src;
of_oxm_ipv6_nd_tll_t ipv6_nd_tll;
of_oxm_icmpv4_type_t icmpv4_type;
of_oxm_mpls_label_t mpls_label;
of_oxm_tcp_dst_t tcp_dst;
of_oxm_ip_proto_t ip_proto;
of_oxm_metadata_t metadata;
of_oxm_arp_spa_masked_t arp_spa_masked;
};