3 Module Attributes

This chapter describes the module attribute table and the operations that can be performed on it to:

Retrieve data from the table

Set data in the table

It also describes entries in the table and how to manipulate the values of the attributes.

3.1 The Attribute Table

Every kernel module must have one attribute table that defines some of the data for the kernel module. The system administrator can use settable attributes in the attribute table to tune the module.

Note

If your kernel module does not have any defined attributes, you still must provide an attribute table with one terminating NULL entry.

The name of the attribute table is the module name followed by _attributes. For example, for the example.mod kernel module, the attribute table is named example_attributes.

The attribute table is an array of the data structure cfg_subsys_attr_t (defined in /usr/include/sys/sysconfig.h). Each cfg_subsys_attr_t data structure defines an attribute for your module. There are no required attributes for this table.

An attribute table entry comprises one instance of the cfg_subsys_attr_t data structure. The last table entry must be all zeros. Section 3.2 describes the fields in an attribute table entry.

3.2 Attribute Table Entry

An attribute table entry is one instance of the cfg_subsys_attr_t data structure. An entry is composed of many fields, which are defined in the following list:

addr (caddr_t)
Specifies the kernel address of the location that holds the value of the attribute. Using this address, the module framework returns the attribute's value during a CFG_OP_QUERY request and changes the value with a CFG_OP_RECONFIGURE request. As a result, the configure routine does not need to do additional processing. If you do not provide an address, the configure routine must separately handle value retrieval and deposit.
If the attribute supports the CFG_OP_CONFIGURE or CFG_OP_RECONFIGURE request operation, then the address given in this field must be a writable location. That is, do not make it a location of the type const.

name (char [])
Specifies the ASCII name of the attribute. The name must be between two and CFG_ATTR_NAME_SZ characters in length, including the terminating null character.
To create a name for your attribute, follow these conventions:
- Use lowercase letters, unless capitals make better sense (for example, when using an acronym in the attribute name, such as MAC_address).
- Use an underscore to separate parts of the name.
- Create intuitive names; do not overabbreviate names.
- Do not begin the name of the attribute with either Method_ or Device_. The module framework reserves names that begin with these strings.

min_val and max_val (ulong)
Define the mininum and maximum allowed values for the attributes. The module framework interprets the contents of these two fields differently, depending on the data type of the attribute. If the attribute is one of the integer data types, these fields contain the minimum and maximum integer values the attribute can have. For attributes with the CFG_ATTR_STRTYPE data type, these fields contain the minimum and maximum lengths of the string. For attributes with the CFG_ATTR_BINTYPE data type, these fields contain the minimum and maximum numbers of bytes allowed.

val_size (ulong)
If the attribute is a binary type, this field contains the current size (in bytes) of the attribute value. This field is not used if the attribute is an integer or string.

type (uchar)
Specifies the data type of the value for this attribute. See Section 3.2.1 for a list of values for this field.

operation (uchar)
Specifies the operations that the module allows on this attribute (for example, initialize or query). This field is a bit mask. See Section 3.2.2 for a list of values for this field.

3.2.1 Attribute Data Types

The following data types are supported for attribute table entries:

CFG_ATTR_STRTYPE - A null-terminated array of characters

CFG_ATTR_INTTYPE - A 32-bit signed integer

CFG_ATTR_UINTTYPE - A 32-bit unsigned integer

CFG_ATTR_LONGTYPE - A 64-bit signed integer

CFG_ATTR_ULONGTYPE - A 64-bit unsigned integer

CFG_ATTR_BINTYPE - An array of bytes

CFG_ATTR_UCHARTYPE - An 8-bit unsigned char (byte)

CFG_ATTR_USHORTTYPE - A 16-bit unsigned short

CFG_ATTR_INTARRAYTYPE - An array of 32-bit signed integers

CFG_ATTR_UINTARRAYTYPE - An array of 32-bit unsigned integers

CFG_ATTR_LONGARRAYTYPE - An array of 64-bit signed longs

CFG_ATTR_ULONGARRAYTYPE - An array of 64-bit unsigned longs

CFG_ATTR_STRARRAYTYPE - An array of pointers to null-terminated strings

3.2.2 Operations Allowed on an Attribute

You can set the operation field in an attribute table entry to any combination of the following request codes:

CFG_OP_CONFIGURE

The value of the attribute can be modified during initialization using a data value from the /etc/sysconfigtab file. (Section 10.1.5 describes how to create the /etc/sysconfigtab file.) If the kernel address for the attribute is specified in the attribute table, the initialization occurs before the module framework calls the kernel module's configure routine with the CFG_OP_CONFIGURE request code. If the attribute's address is not specified, the configure routine must perform the modification itself.

Setting this flag in the operator field allows the system administrator to set the value of the attribute through the /etc/sysconfigtab file. This gives the system administrator the ability to tune your module each time that it is loaded.

CFG_OP_QUERY

Setting this flag allows users or applications to retrieve the value of the attribute. The module framework can read the attribute and return it to applications. The attribute's value is retrieved after the module framework calls the kernel module's configure routine with the CFG_OP_QUERY request code. (See Section 3.3.)

CFG_OP_RECONFIGURE

Setting this flag allows users or applications to modify the value of the attribute at any time after the kernel module is up and running. The module framework sets the value before it calls the configure routine with the CFG_OP_RECONFIGURE request code. (See Section 3.4.)

CFG_HIDDEN_ATTR

Setting this flag prevents the attribute from being displayed in the output of a cfg_subsys_query_all operation.

Note

If you do not specify the kernel address of an attribute in the attribute table, the configure routine must handle the setting, resetting, and retrieval of the attribute value by itself. The module framework cannot perform these actions automatically unless you supply the kernel address of the attribute.

3.3 Attribute Get Requests

When an application wants to get attribute values of a kernel module, it calls the cfg_subsys_query(3)routine or the cfg_subsys_query_all(3) routine in the /usr/ccs/lib/libcfg.a library. The library makes the request to the module framework.

The module framework validates the requests to get the valid attribute values. After successful validation, the module framework calls the configure routine with the CFG_OP_QUERY request code. Figure 3-1 illustrates these relationships.

Figure 3-1: Attribute Get Requests

The following list presents the sequence of steps in an attribute get request:

The application requests specific attributes or all attributes by calling the appropriate library routine in /usr/ccs/lib/libcfg.a.

The library passes the request to the module framework.

The module framework calls the configure routine with CFG_OP_QUERY.

The configure routine handles returning values for the requested attributes whose address is not specified in the attribute table.

The configure routine returns control to the module framework.

The module framework handles returning values for the requested attributes whose address is specified in the attribute table.

Consider the following when you use attribute get requests:

You do not have to process a CFG_OP_QUERY request in your configure routine; you can simply return ESUCCESS.

If you do not keep some or all of your attributes up-to-date, you may bring them up-to-date when you receive the CFG_OP_QUERY request.

To determine which attributes are being requested, use the indata parameter. The status field of each cfg_attr_t data structure whose address is available to the module framework will be set to CFG_ATTR_PENDING during the CFG_OP_QUERY request; whereas the status field for each attribute that cannot be handled by the module framework will be set to CFG_ATTR_ESUBSYS.

3.4 Attribute Set Requests

When an application wants to set attribute values of a kernel module, it calls the cfg_subsys_reconfig(3) routine in the /usr/ccs/lib/libcfg.a library. The library makes the request to the module framework.

The module framework sets the values of the requested attributes, then calls the configure routine with the CFG_OP_RECONFIGURE request code. The kernel module evaluates these values and functions accordingly. Figure 3-2 illustrates these relationships.

Figure 3-2: Attribute Set Requests

The following list presents the sequence of steps in an attribute set request:

The application requests to set the values of specific attributes.

The library passes the request to the module framework.

The module framework determines whether the new value falls within the range that is specified in the attribute table and sets the status of each attribute. If the value determination succeeds, the module framework sets the attribute's value to the new value.

The module framework calls the configure routine with CFG_OP_RECONFIGURE.

The kernel module evaluates the new values and executes based on those values.