diff options
Diffstat (limited to 'local/mib2c-conf.d/mfd-readme.m2c')
| -rw-r--r-- | local/mib2c-conf.d/mfd-readme.m2c | 846 |
1 files changed, 846 insertions, 0 deletions
diff --git a/local/mib2c-conf.d/mfd-readme.m2c b/local/mib2c-conf.d/mfd-readme.m2c new file mode 100644 index 0000000..9aeef10 --- /dev/null +++ b/local/mib2c-conf.d/mfd-readme.m2c @@ -0,0 +1,846 @@ +######################################################################## +## generic include for XXX. Don't use directly. +## +## $Id: mfd-readme.m2c 12091 2005-04-18 22:05:47Z rstory $ +######################################################################## +@if $m2c_mark_boundary == 1@ +/** START code generated by $RCSfile$ $Revision: 12091 $ */ +@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 $RCSfile$ $Revision: 12091 $ */ +@end@ |