########################################################################
## generic include for XXX. Don't use directly.
##
########################################################################
@if $m2c_mark_boundary == 1@
/** START code generated by mfd-readme.m2c */
@end@
########################################################################
##
@open ${name}-README-FIRST.txt@
************************************************************************
${name} README
------------------------------------------------------------------------
This document describes the results of the mib2c code generation
system using the mfd code generation template. The resulting files
are documented both in this README file as well as per-table specific
README files. All of the files generated by this run of mib2c will
begin with the ${name} prefix.
Quick Start
-----------
For those interested in a quick start, to get a pseudo-todo list, try
this command in directory with the generated code:
grep -n "TODO:" *.[ch] | sed 's/\([^ ]*\) \(.*\)TODO\(.*\)/\3 (\1)/' | sort -n
Key:
:o: Optional
:r: Recommended
:M: Mandatory
:A: Advanced users
This will give you and ordered list of places in the code that you
may (or must) take a closer look at).
You may also want to take a look at the on-line tutorial, found here:
http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mfd/index.html
MIBs For Dummies Overview
-------------------------
The MIBs For Dummies (MFD) configuration files have been written to help
SNMP novices implement SNMP MIBs. This section will be a brief
introduction to some of the general concepts you should be familar with.
Managed Information Base (MIB)
------------------------------
A SNMP MIB (Managed information base) is a text file that describes the
syntax for some set of data objects. The MIB creates a correlation
between an ASCII name for an object and a number OID (Object Identifier).
The SNMP protocol communicates information using the OIDs, and the MIB
allows tools to display a name, which we humans find easier to deal with.
To use an analogy, a MIB is much like a menu at a restaurant. If you've
ever been to a reataurant and ordered a meal, and later received a bill
that simply had '#6' on it, you get the idea. The name is easier for
the customers to remember, and the waiters and chefs use the number for
efficency.
Scalars
-------
A scalar variable is a unique object in a MIB which can represent
a single value. For example, the SNMP standard MIB-II defines a
variable, sysContact.0, which is a string containing the contact
information for the person in charge of a particular agent. Note
that scalar variable always end with '.0'.
Rows and Tables
---------------
When a group of related attributes occur more than once, they can be
grouped together in a table. A table has an index, which uniquely
identifies a particular row, and data columns, which contain the
attributes for that row.
For example, the SNMP standard MIB-II defines a table, ifTable, which
contains information on the ethernet interfaces on a system.
Data Structures
---------------
The code generated by the MFD configuration files has a few important
structures.
The Data Context
----------------
The data context structure should contain the necessary information
to provide the data for the columns in a given row. As long as you
can extract the data for a column for the data context, the data context
can be anything you want: a pointer to an existing structure, the
parameters needed for a function call or an actual copy of the data.
By default, a data context structure is generated with storage for
all the data in a row. Information on changing the default is presented
later on in this help.
The MIB Context
---------------
The MIB context structure is generated with storage for all the
indexes of a table. This data will be used when searching for the
correct row to process for a request.
The Row Request Context
-----------------------
Each table will have a unique data structure for holding data during
the processing of a particular row. The row request context contains
the registration context (that you supply during initilization),
the data context, the MIB context, the undo context (for settable
tables) and other data. There is also a netsnmp_data_list, which can
be used to temporary storage during processing.
The Table Registration Pointer
------------------------------
During initilization, you may provide a pointer to arbitrary data for
you own use. This pointer will be saved in the row request context,
and is passed as a parameter to several functions. It is not required,
and is provided as a way for you to access table specific data in
the generated code.
These files are top-level files potentially useful for all the tables:
------------------------------------------------------------------------
File : ${name}_Makefile
----------------------------------------------------------------------
Purpose : Make file for compiling a (sub)agent. This file is only
useful if you don't want to compile your code directly
into the Net-SNMP master agent.
Editable: Optional
Usage : make -f ${name}_Makefile
File : ${name}_subagent.c
----------------------------------------------------------------------
Purpose : This file contains a main() function for an agent or
sub-agent and is compiled using the Makefile above.
Table specific README files
------------------------------------------------------------------------
Each table for which code was generated has its own README file
describing the files specifically associated with each table. You
should probably read these next:
@foreach $table table@
@ include m2c_setup_table.m2i@
${name}-README-${table}.txt
@end@
These are miscellaneous auto-generated code files you generally
shouldn't edit. They contain code that ties your code together with
the Net-SNMP agent.
------------------------------------------------------------------------
@if $m2c_create_fewer_files == 1@
File : ${name}.c
Purpose : Initilization for the entire module set, including the
SNMP tables.
@end@
File : ${name}.h
Purpose : Header file for the module set. Includes config_require
macros to auto-load the other code pieces when compiled
into the agent.
@if $m2c_create_fewer_files != 1@
File : ${name}_oids.h
Purpose : C #define definitions of the tables, columns, and OIDs
File : ${name}_enums.h
Purpose : C #define definitions of the enumerated type values for
each column of each table that requires them.
@else@
File : ${name}_constants.h
Purpose : C #define definitions of the tables, columns, OIDs, enumerated
type values for each column of each table that requires them.
@end@
File : ${name}_interface.c
Purpose : MFD interface to Net-SNMP. This auto-generated code ties the
functions you will fill out to the code that the agent needs.
########################################################################
@foreach $table table@
@ include m2c_setup_table.m2i@
@ open ${name}-README-${table}.txt@
************************************************************************
${context} README
------------------------------------------------------------------------
This readme file describes the code generated by mib2c (using the MIBs
for Dummies (MFD) configuration file). The code generated was
generated specifically for the following SNMP table:
${context}
Your code will be called when the snmp agent receives requests for
the ${context} table. The agent will start by looking for the right
row in your existing data to operate on, if one exists.
Configuration Variables
------------------------------------------------------------
Some variables used for code generation may be set to affect the code
generation. You may override these variables by setting them in the
file ${m2c_defaults_dir}table-${context}.m2d, and then re-running mib2c.
m2c_table_settable (currently '$m2c_table_settable')
--------------------------------------------------------
This variable determines whether or not code is generated to support
MIB object which have an access of read-write or read-create. The
default is set based on whether or not the table contains writable
objects, but can be over-ridden.
Syntax: @eval $@m2c_table_settable = 0@
m2c_table_dependencies (currently '$m2c_table_dependencies')
--------------------------------------------------------
This variable determines whether or not code is generated to support
checking dependencies between columns, rows or tables. The default
is set based on whether or not the table contains writable objects,
but can be over-ridden.
Syntax: @eval $@m2c_table_dependencies = 0@
m2c_table_row_creation (currently '$m2c_table_row_creation')
--------------------------------------------------------
This variable determines whether or not code is generated to support
checking creation of new rows via SNMP. The default is set based on
whether or not the table contains read-create objects, but can be
over-ridden.
Syntax: @eval $@m2c_table_row_creation = 0@
m2c_context_reg (currently '$m2c_context_reg')
--------------------------------------------------------
This variable contains the structure name to typedef for the
${context}_registration.
During initilization, you will provide a pointer to a structure of
this type. This pointer is used as a parameter to many functions so
that you have access to your registration data. The default is a
netsnmp_data_list pointer, which will allow you to keep multiple
pointers tagged by a text name. If you have a new or existing structure
you would rather use, you can redefine this variable.
To avoid regenerating code, you may also change this typedef directly
in the ${table}.h header.
Syntax: @eval $@m2c_context_reg = "struct my_registration_context@
m2c_data_context (currently '$m2c_data_context')
--------------------------------------------------------
This variable contains the structure name to typedef for the
${context}_data.
This typedef is used in the row request context structure for the table,
${context}_rowreq_ctx.
The typedef in the primary table context will be used for the data and
undo structure types. This structure should contain all the data
needed for all the columns in the table. The default is 'generated',
which will cuase a new data strcuture to be generated with data members
for each column.
To avoid regenerating code, you may also change this typedef directly
in the ${table}.h header.
Syntax: @eval $@m2c_data_context = "struct my_data_context"@
m2c_data_allocate (currently '$m2c_data_allocate')
--------------------------------------------------------
This variable determines whether or not the data context (see above)
requires memory to be allocated. The default generated data structure
does not. If you are using a custom data context which needs to
allocate memory, override this value and two additional functions
will be generated:
${context}_allocate_data
${context}_release_data
Syntax: @eval $@m2c_data_allocate = 1@
m2c_data_init (currently '$m2c_data_init')
--------------------------------------------------------
This variable determines whether or not the data context (see above)
or any other items you have added to the table context requires
initialization. The default generated data structure does not. If you
are using a custom data context or have added items needing initialization
to the table context, override this value and two additional functions
will be generated:
${context}_rowreq_ctx_init
${context}_rowreq_ctx_cleanup
Syntax: @eval $m2c_data_init = 1@
m2c_table_access (currently '$m2c_table_access')
------------------------------------------------------------------
This variable determines which data interface will be use to generate
code for looking up data for a given index. The default is the
'container-cached' access code, which caches the data in a netsnmp-
container (usually a sorted array).
Available options can be determined by checking for mib2c configuration
files that begin with 'mfd-access-*'.
Syntax: @eval $@m2c_table_access = '$m2c_table_access'@
m2c_include_examples (currently '$m2c_include_examples')
------------------------------------------------------------------
This variable determines whether or not to generate example code. The
default is to generate example code.
Syntax: @eval $@m2c_include_examples = 0@
m2c_data_transient (currently '$m2c_data_transient')
------------------------------------------------------------------
This variable determines how the generated example code deals with the
data during data lookup. See the table readme file for details on how
the current table access method interprets this value. In general,
a value of 0 indicates persistent data, 1 indicates semi-transient and
2 indicates transient data.
Syntax: @eval $@m2c_data_transient = 0@
Index(es) for the ${context} table
------------------------------------------------------------
The index(es) for the ${context} table are:
@foreach $node index@
@ include m2c_setup_node.m2i@
$node:
Syntax: $node.syntax
DataType: $node.perltype
ASN type: $node.type
C-code type: $m2c_decl
@end@ # foreach
You should know how to set all these values from your data context,
${context}_data.
************************************************************************
${context} File Overview
------------------------------------------------------------------------
Several files have been generated to implement the ${context}
table. We'll go through these files, one by one, explaining each and
letting you know which you need to edit.
File: ${name}_data_access.[c|h]
------------------------------------------------------------------------
The ${name}_data_access file contains the interface to your data in
its raw format. These functions are used to build the row cache or
locate the row (depending on the table access method).
Set MIB context
-----------------
TODO : Set MIB index values
FUNC : ${context}_indexes_set
WHERE: ${context}_data_access.c
This is a convenience function for setting the index context from
the native C data. Where necessary, value mapping should be done.
@if $mfd_readme_verbose == 1@
This function should update the table index values (found in
tbl_idx) for the given raw data.
@end@
@ eval $m2c_processing_type = 'r'@
@ include mfd-access-${m2c_table_access}-defines.m2i@
@if $m2c_create_fewer_files != 1@
File: ${name}_enums.h
@else@
File: ${name}_constants.h
@end@
------------------------------------------------------------------------
This file contains macros for mapping enumeration values when the
enumerated values defined by the MIB do not match the values used
internally.
Review this file to see if any values need to be updated.
@if $m2c_create_fewer_files != 1@
File: ${name}_data_get.c
@else@
File: ${name}.c; GET support
@end@
------------------------------------------------------------------------
@ if ("$m2c_data_allocate" eq "yes") && ("$m2c_data_context" ne "generated")@
Allocate data context
---------------------
TODO : allocate memory for a data context
FUNC : ${context}_allocate_data
This function will be called to allocate memory for a data context
when a new row request context is being created, or to create an
undo context while processing a set request.
Release data context
-------
TODO : release memory allocated for a data context
FUNC : ${context}_release_data
This function will be called to release any resources held by a
data or undo context. It will be called when a row request context
is released, or during cleanup after a set request.
@ end@
@ foreach $node index@
@ include m2c_setup_node.m2i@
@ if ($m2c_skip_mapping != 1)@
Map native data to MIB format
-----------------------------
TODO : convert data from its native format to the format required by the MIB
FUNC : ${node}_map
This function should map between the native format of the node data to
the format or values required by the MIB. For example, a C boolean value
for a MIB node with the TruthValue syntax needs to map the value C
false(0) to TruthValue false(2).
@ end@ #// skip mapping
@ end@ // foreach index
@ foreach $node nonindex@
@ include m2c_setup_node.m2i@
@ if ($m2c_skip_mapping != 1)@
Map native data to MIB format
-----------------------------
TODO : convert data from its native format to the format required by the MIB
FUNC : ${node}_map
This function should map between the native format of the node data to
the format or values required by the MIB. For example, a C boolean value
for a MIB node with the TruthValue syntax needs to map the value C
false(0) to TruthValue false(2).
@ end@ #// skip mapping
Get data for column
-------------------
TODO : retrieve column data from raw data
FUNC : ${node}_get
@ ifconf syntax-$node.syntax-readme.m2i@
@ include syntax-$node.syntax-readme.m2i@
@ elsif ($node.enums == 1) && ("$node.perltype" eq "BITS")@
Since this column has enumerated BITS, you should update or replace the
IS_SET_* macros to properly determine whether or not a particular bit
should be set.
@ end@
@ end@
@if $m2c_create_fewer_files != 1@
File: ${name}_data_set.c
@else@
File: ${name}.c; SET support
@end@
------------------------------------------------------------------------
@if $m2c_table_settable == 0@
This table does not support set requests.
@else@
This code was generated based on the following assumptions or settings:
@ if $m2c_table_dependencies == 1@
1) None of the values for this table have DEPENDENCIES on other objects.
@ else@
1) Some of the values for this table have DEPENDENCIES on other objects.
@ end@
@ if $mfd_readme_verbose != 0@
DEPENDENCIES on other objects complicates SET request processing. When
one or more columns in a table depend on another object (in the same
table, or in another table), a DEPENDENCY exists. For example, if you
have a table that determine a color with three columns (red, green and
blue) that define the percentage of each primary color, the total for
the three columns must equal 100 percent. So, in addition to checking
that each colums has a valid value between 0 and 100, the total of
all three columns must equal 100.
Set $@m2c_table_dependencies = 0 in ${m2c_defaults_dir}table-${table}.m2d
and regenerate code if this assumption is incorrect.
@ end@
@if $m2c_table_row_creation == 1@
2) This table supports ROW CREATION.
@else@
2) This table does not support ROW CREATION.
@end@
@if $mfd_readme_verbose != 0@
Supporting ROW CREATION allows new rows to be created via SNMP requests.
@end@
@if $m2c_table_row_creation == 1@
To support row creation, the index component of an incoming set request must
be validated. A funciton is generated for each individual index component,
and another for validating all the index components together.
@ foreach $node externalindex@
@ include m2c_setup_node.m2i@
Validate external index
-----------------------
TODO : validate the specified external index component
FUNC : ${context}_${node}_check_index
@ end@ # foreach externalindex
@ foreach $node internalindex@
@ include m2c_setup_node.m2i@
Validate index component
------------------------
TODO : validate the specified index component
FUNC : ${node}_check_index
@ end@
Validate index
--------------
TODO : check that all index components are valid
FUNC : ${context}_validate_index
@end@
@ if $m2c_table_dependencies == 1@
Check dependencies
------------------
TODO : check that all dependencies have been satisfied
FUNC : ${context}_check_dependencies
This function will be called after all the individual columns have been
set to their new values. Check for any dependencies between rows or
tables in this function.
@ end@
Undo setup
----------
TODO : save data for undo
FUNC : ${context}_undo_setup
This function will be called before the individual undo_setup functions are
called. This is where you should save any undo information which is not
directly related to a particular column. This function will only be called
once per row. After this function is called, any column which is being
set will have its individual node undo_setup function called.
@ foreach $node nonindex@
@ include m2c_setup_node.m2i@
@ if $node.settable == 0@
@ next@ # skip to next column
@ end@
Check value for column
----------------------
TODO : perform additional validations on values for a set request
FUNC : ${node}_check_value
The generated code will automatically validate incoming requests against
all the requirements specified by the syntax of the MIB. However, it is
often the case that additional requirements are specified in the
description of a MIB object. Those type of validations should be checked
in this function.
Undo setup for column
---------------------
TODO : save the value for column
FUNC : ${node}_undo_setup
After the table level undo setup function has been called, the individual
node undo setup functions will be called for columns which are being set.
Set value for column
--------------------
TODO : set the value for column
FUNC : ${node}_set
After all the validations have been passed, this function will be called to
set the new value.
Undo value for column
---------------------
TODO : undo set for column
FUNC : ${node}_undo
If an error occurs after a column has been set, this function will be called
to undo the set and restore the previous state.
@ end@ # nonindex
Commit changes
--------------
TODO : commit changes
FUNC : ${context}_commit
After all values have been set, the commit function will be called.
@ if $m2c_irreversible_commit == 1@
Commit irreversible changes
---------------------------
FUNC: ${context}_irreversible_commit
This special mode is reserved for committing changes which can not be undone.
(e.g. launching a rocket). It is called after all normal commits have
succeeded.
@ end@
@end@ # settable
************************************************************************
${context} Reference
------------------------------------------------------------------------
Function flow
----------------------------------------------------
To give you the general idea of how the functions flow works, this
example flow is from a complete table implementation.
NOTE: Depending on your configuration, some of the functions used in the
examples below may not have been generated for the
${context} table.
Conversely, the examples below may not include some functions that
were generated for the ${context} table.
To watch the flow of the ${context} table, use the
following debug tokens:
snmp_agent
helper:table:req
${context}
verbose:${context}
internal:${context}
e.g.
snmpd -f -Le -D${context},verbose:${context},internal:${context}
@if $m2c_create_fewer_files == 1@
@ eval $tmp_mfd_rm_set = "xxx.c"@
@ eval $tmp_mfd_rm_get = "xxx.c"@
@else@
@ eval $tmp_mfd_rm_set = "xxx_data_set.c"@
@ eval $tmp_mfd_rm_get = "xxx_data_get.c"@
@end@
Initialization
--------------------------------
init_xxxTable: called xxx.c
initialize_table_xxxTable xxx.c
_xxxTable_initialize_interface xxx_interface.c
xxxTable_init_data xxx_data_access.c
_xxxTable_container_init xxx_interface.c
xxxTable_container_init xxx_data_access.c
GET Request
--------------------------------
_cache_load xxx_interface.c
xxxTable_cache_load xxx_data_access.c
xxxTable_allocate_rowreq_ctx xxx_interface.c
xxxTable_allocate_data $tmp_mfd_rm_get
xxxTable_rowreq_ctx_init $tmp_mfd_rm_get
xxxTable_indexes_set $tmp_mfd_rm_get
xxxTable_indexes_set_tbl_idx $tmp_mfd_rm_get
xxxTable_pre_request
_mfd_xxxTable_object_lookup xxx_interface.c
xxxTable_row_prep xxx_data_access.c
_mfd_xxxTable_get_values xxx_interface.c
_mfd_xxxTable_get_column xxx_interface.c
yyy_get $tmp_mfd_rm_get
xxxTable_post_request
GETNEXT Request
--------------------------------
_cache_load ...
xxxTable_pre_request ...
_mfd_xxxTable_object_lookup ...
_mfd_xxxTable_get_values ...
xxxTable_post_request ...
SET Request: success
--------------------------------
_cache_load ...
xxxTable_pre_request
_mfd_xxxTable_object_lookup ...
_mfd_xxxTable_check_objects xxx_interface.c
_xxxTable_check_column xxx_interface.c
yyy_check_value $tmp_mfd_rm_set
_mfd_xxxTable_undo_setup xxx_interface.c
xxxTable_allocate_data ...
xxxTable_undo_setup xxx_interface.c
_xxxTable_undo_setup_column xxx_interface.c
yyy_undo_setup $tmp_mfd_rm_set
_mfd_xxxTable_set_values xxx_interface.c
_xxxTable_set_column xxx_interface.c
yyy_set $tmp_mfd_rm_set
_mfd_xxxTable_check_dependencies xxx_interface.c
xxxTable_check_dependencies $tmp_mfd_rm_set
_mfd_xxxTable_commit xxx_interface.c
xxxTable_commit $tmp_mfd_rm_set
_mfd_xxxTable_undo_cleanup xxx_interface.c
xxxTable_undo_cleanup $tmp_mfd_rm_set
xxxTable_release_data ...
xxxTable_post_request ...
SET Request: row creation
--------------------------------
_cache_load ...
xxxTable_pre_request
_mfd_xxxTable_object_lookup ...
xxxTable_index_from_oid xxx_interface.c
xxxTable_allocate_rowreq_ctx ...
...
_xxxTable_check_indexes xxx_interface.c
yyy_check_index $tmp_mfd_rm_set
xxxTable_validate_index $tmp_mfd_rm_set
_mfd_xxxTable_check_objects ...
_xxxTable_check_column ...
yyy_check_value ...
_xxxTable_check_column ...
yyy_check_value ...
_mfd_xxxTable_undo_setup ...
_mfd_xxxTable_set_values ...
_mfd_xxxTable_check_dependencies ...
_mfd_xxxTable_commit ...
_mfd_xxxTable_undo_cleanup ...
xxxTable_post_request ...
SET Resuest: value error
--------------------------------
_cache_load ...
xxxTable_pre_request ...
_mfd_xxxTable_object_lookup ...
_mfd_xxxTable_check_objects ...
_xxxTable_check_column ...
yyy_check_value ...
ERROR:"yyy value not supported"
xxxTable_post_request ...
SET Request: commit failure
--------------------------------
_cache_load ...
xxxTable_pre_request ...
_mfd_xxxTable_object_lookup ...
_mfd_xxxTable_check_objects ...
_mfd_xxxTable_undo_setup ...
_mfd_xxxTable_set_values ...
_mfd_xxxTable_check_dependencies ...
_mfd_xxxTable_commit ...
xxxTable_commit ...
ERROR: bad rc -1
_mfd_xxxTable_undo_commit xxx_interface.c
xxxTable_undo_commit $tmp_mfd_rm_set
_mfd_xxxTable_undo_values xxx_interface.c
_xxxTable_undo_column xxx_interface.c
yyy_undo $tmp_mfd_rm_set
_mfd_xxxTable_undo_cleanup ...
xxxTable_post_request ...
Row release (user initiated)
--------------------------------
xxxTable_release_rowreq_ctx xxx_interface.c
xxxTable_rowreq_ctx_cleanup $tmp_mfd_rm_get
xxxTable_release_data $tmp_mfd_rm_get
Table / column details
----------------------------------------------------
@ include details-table.m2i@
@ foreach $node column@
@ include m2c_setup_node.m2i@
@ include details-node.m2i@
@ end@
@end@ # foreach table
##
########################################################################
@if $m2c_mark_boundary == 1@
/** END code generated by mfd-readme.m2c */
@end@