Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Add back README files from mib2c

  • Loading branch information...
commit 8d7efff9165d60d960cb80cd428028f15c6e449e 1 parent 4ecf0c6
@vincentbernat authored
View
167 agentx-c-mib2c/ethtoolStatTable-README-FIRST.txt
@@ -0,0 +1,167 @@
+************************************************************************
+ethtoolStatTable 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 ethtoolStatTable 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 : ethtoolStatTable_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 ethtoolStatTable_Makefile
+
+
+ File : ethtoolStatTable_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:
+
+ ethtoolStatTable-README-ethtoolStatTable.txt
+
+
+
+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.
+------------------------------------------------------------------------
+ File : ethtoolStatTable.h
+ Purpose : Header file for the module set. Includes config_require
+ macros to auto-load the other code pieces when compiled
+ into the agent.
+
+ File : ethtoolStatTable_oids.h
+ Purpose : C #define definitions of the tables, columns, and OIDs
+
+ File : ethtoolStatTable_enums.h
+ Purpose : C #define definitions of the enumerated type values for
+ each column of each table that requires them.
+
+ File : ethtoolStatTable_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.
+
View
475 agentx-c-mib2c/ethtoolStatTable-README-ethtoolStatTable.txt
@@ -0,0 +1,475 @@
+************************************************************************
+ethtoolStatTable 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:
+
+ ethtoolStatTable
+
+ Your code will be called when the snmp agent receives requests for
+ the ethtoolStatTable 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 defaults/table-ethtoolStatTable.m2d, and then re-running mib2c.
+
+ m2c_table_settable (currently '0')
+ --------------------------------------------------------
+ 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 '0')
+ --------------------------------------------------------
+ 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 '0')
+ --------------------------------------------------------
+ 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 'netsnmp_data_list')
+ --------------------------------------------------------
+ This variable contains the structure name to typedef for the
+ ethtoolStatTable_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 ethtoolStatTable.h header.
+
+ Syntax: @eval $m2c_context_reg = "struct my_registration_context@
+
+
+ m2c_data_context (currently 'generated')
+ --------------------------------------------------------
+ This variable contains the structure name to typedef for the
+ ethtoolStatTable_data.
+
+ This typedef is used in the row request context structure for the table,
+ ethtoolStatTable_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 ethtoolStatTable.h header.
+
+ Syntax: @eval $m2c_data_context = "struct my_data_context"@
+
+
+ m2c_data_allocate (currently '0')
+ --------------------------------------------------------
+ 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:
+
+ ethtoolStatTable_allocate_data
+ ethtoolStatTable_release_data
+
+ Syntax: @eval $m2c_data_allocate = 1@
+
+
+ m2c_data_init (currently '1')
+ --------------------------------------------------------
+ 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:
+
+ ethtoolStatTable_rowreq_ctx_init
+ ethtoolStatTable_rowreq_ctx_cleanup
+
+ Syntax: @eval 1 = 1@
+
+
+ m2c_table_access (currently 'container-cached')
+ ------------------------------------------------------------------
+ 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 = 'container-cached'@
+
+
+ m2c_include_examples (currently '1')
+ ------------------------------------------------------------------
+ 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 '2')
+ ------------------------------------------------------------------
+ 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 ethtoolStatTable table
+ ------------------------------------------------------------
+ The index(es) for the ethtoolStatTable table are:
+
+ ifIndex:
+ Syntax: InterfaceIndex
+ DataType: INTEGER32
+ ASN type: ASN_INTEGER
+ C-code type: long
+ ethtoolStatName:
+ Syntax: EthtoolStatString
+ DataType: OCTETSTR
+ ASN type: ASN_OCTET_STR
+ C-code type: char
+
+ You should know how to set all these values from your data context,
+ ethtoolStatTable_data.
+
+
+************************************************************************
+ethtoolStatTable File Overview
+------------------------------------------------------------------------
+ Several files have been generated to implement the ethtoolStatTable
+ table. We'll go through these files, one by one, explaining each and
+ letting you know which you need to edit.
+
+
+File: ethtoolStatTable_data_access.[c|h]
+------------------------------------------------------------------------
+ The ethtoolStatTable_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 : ethtoolStatTable_indexes_set
+ WHERE: ethtoolStatTable_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.
+
+ This function should update the table index values (found in
+ tbl_idx) for the given raw data.
+
+
+ container summary
+ ------------------------
+ The container data access code is for cases when you want to
+ store your data in the agent/sub-agent.
+
+ ... to be continued...
+
+
+ cache summary
+ ------------------------
+ The container-cached data access code is for cases when you want to
+ cache your data in the agent/sub-agent.
+
+ ... to be continued...
+
+
+
+
+File: ethtoolStatTable_enums.h
+------------------------------------------------------------------------
+ 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.
+
+
+File: ethtoolStatTable_data_get.c
+------------------------------------------------------------------------
+ Get data for column
+ -------------------
+ TODO : retrieve column data from raw data
+ FUNC : ethtoolStat_get
+
+
+
+File: ethtoolStatTable_data_set.c
+------------------------------------------------------------------------
+
+ This table does not support set requests.
+
+
+************************************************************************
+ethtoolStatTable 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
+ ethtoolStatTable table.
+
+ Conversely, the examples below may not include some functions that
+ were generated for the ethtoolStatTable table.
+
+To watch the flow of the ethtoolStatTable table, use the
+following debug tokens:
+
+ snmp_agent
+ helper:table:req
+ ethtoolStatTable
+ verbose:ethtoolStatTable
+ internal:ethtoolStatTable
+
+e.g.
+ snmpd -f -Le -DethtoolStatTable,verbose:ethtoolStatTable,internal:ethtoolStatTable
+
+
+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 xxx_data_get.c
+ xxxTable_rowreq_ctx_init xxx_data_get.c
+ xxxTable_indexes_set xxx_data_get.c
+ xxxTable_indexes_set_tbl_idx xxx_data_get.c
+
+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 xxx_data_get.c
+
+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 xxx_data_set.c
+
+_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 xxx_data_set.c
+
+_mfd_xxxTable_set_values xxx_interface.c
+ _xxxTable_set_column xxx_interface.c
+ yyy_set xxx_data_set.c
+
+_mfd_xxxTable_check_dependencies xxx_interface.c
+ xxxTable_check_dependencies xxx_data_set.c
+
+_mfd_xxxTable_commit xxx_interface.c
+ xxxTable_commit xxx_data_set.c
+
+_mfd_xxxTable_undo_cleanup xxx_interface.c
+ xxxTable_undo_cleanup xxx_data_set.c
+ 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 xxx_data_set.c
+ xxxTable_validate_index xxx_data_set.c
+
+_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 xxx_data_set.c
+
+_mfd_xxxTable_undo_values xxx_interface.c
+ _xxxTable_undo_column xxx_interface.c
+ yyy_undo xxx_data_set.c
+
+_mfd_xxxTable_undo_cleanup ...
+xxxTable_post_request ...
+
+
+Row release (user initiated)
+--------------------------------
+xxxTable_release_rowreq_ctx xxx_interface.c
+ xxxTable_rowreq_ctx_cleanup xxx_data_get.c
+ xxxTable_release_data xxx_data_get.c
+
+
+
+Table / column details
+----------------------------------------------------
+/**********************************************************************
+ **********************************************************************
+ ***
+ *** Table ethtoolStatTable
+ ***
+ **********************************************************************
+ **********************************************************************/
+/*
+ * ETHTOOL-MIB::ethtoolStatTable is subid 1 of ethtool.
+ * Its status is Current.
+ * OID: .1.3.6.1.4.1.39178.100.1.1, length: 10
+*/
+
+/*---------------------------------------------------------------------
+ * ETHTOOL-MIB::ethtoolStatEntry.ethtoolStatName
+ * ethtoolStatName is subid 1 of ethtoolStatEntry.
+ * Its status is Current, and its access level is NoAccess.
+ * OID: .1.3.6.1.4.1.39178.100.1.1.1.1
+ * Description:
+Name of the statistic as returned by ETHTOOL ioctl.
+ *
+ * Attributes:
+ * accessible 0 isscalar 0 enums 0 hasdefval 0
+ * readable 0 iscolumn 1 ranges 1 hashint 1
+ * settable 0
+ * hint: 32a
+ *
+ * Ranges: 1 - 32;
+ *
+ * Its syntax is EthtoolStatString (based on perltype OCTETSTR)
+ * The net-snmp type is ASN_OCTET_STR. The C type decl is char (char)
+ * This data type requires a length. (Max 32)
+ *
+ *
+ *
+ * NOTE: NODE ethtoolStatName IS NOT ACCESSIBLE
+ *
+ *
+ */
+/*---------------------------------------------------------------------
+ * ETHTOOL-MIB::ethtoolStatEntry.ethtoolStat
+ * ethtoolStat is subid 2 of ethtoolStatEntry.
+ * Its status is Current, and its access level is ReadOnly.
+ * OID: .1.3.6.1.4.1.39178.100.1.1.1.2
+ * Description:
+Value of the statistic as returned by ETHTOOL ioctl.
+ *
+ * Attributes:
+ * accessible 1 isscalar 0 enums 0 hasdefval 0
+ * readable 1 iscolumn 1 ranges 0 hashint 0
+ * settable 0
+ *
+ *
+ * Its syntax is COUNTER64 (based on perltype COUNTER64)
+ * The net-snmp type is ASN_COUNTER64. The C type decl is U64 (U64)
+ */
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.