|
|
| |
|
|
|
Instance Attribute Management
15.1 Overview
UDI provides the capability of associating attributes (information) with driver instances. These are called driver instance attributes. These attributes may be stored in a system-wide persistent storage database to allow the driver to maintain configuration and topology information across driver and system restarts. A driver restart is defined within the context of a particular driver instance, and is the period between when the driver detaches and then later reattaches to that instance. This may occur when the host system restarts or may be during a period when the host reclaims the resources of a driver instance that is not actively being used. A system restart is defined to be the period between when the host terminates and then later resumes operation. This most commonly is a system reboot, which may include system power cycling.
This section defines the interfaces used to read and modify the various driver attributes.
15.2 Instance Attribute Names
Instance attribute names may be composed of up to 31 ASCII characters plus a null terminator. Legal characters for attribute names consist of upper and lower case letters, digits, and the underscore character (`_'). In addition, the first character may be a percent-sign (`%'), a dollar-sign (`$'), a caret (`^'), or an at-sign (`@'); these prefix characters have special meanings, described below. All other characters are illegal.
Upper and lower case ASCII letters are treated identically when looking up existing attribute names (i.e. the matching is case-insensitive). It is environment implementation-specific whether or not alphabetic case is preserved in attribute names when creating or changing attributes. By convention, specific attribute names defined in UDI specifications are written in all lower case.
Each distinct name, even if it differs from another attribute name only by a prefix character, identifies a distinct attribute.
15.3 Persistence of Attributes
Attributes may be specified to be either persistent or volatile (non-persistent). Persistent attributes will be maintained in a persistent storage database and will be available across system restarts, whereas volatile attributes are only guaranteed to persist for the duration of the corresponding driver instance.
Certain environments will not be able to supply a modifiable persistent storage database (e.g. an embedded ROM-based environment). For these types of environments, any attempt to modify a persistent attribute value will result in a UDI_STAT_NOT_SUPPORTED error code. The driver may choose to ignore or otherwise handle this return value as determined by the driver implementation requirements.
Accesses to the persistent storage database will be implemented in an atomic manner. This means that any of the attribute management service calls documented in this section may be issued without concern about collision with other operations, although there is no guarantee as to the sequence of individual operations relative to operations issued by other driver regions.
15.4 Classes of Attributes
There are four principle classes of driver instance attributes:
- Instance-private attributes
- Enumeration attributes
- Sibling group attributes
- Parent-visible attributes
15.4.1 Instance-Private Attributes
These attributes are persistent or volatile attributes that are read and written via the service operations defined in this section. They are visible only to the driver instance to which they apply. These attributes may be used for any driver-related information.
Private persistent attribute names must begin with a percent-sign (`%') prefix character. Private volatile attribute names must begin with a dollar-sign (`$') prefix character.
15.4.2 Enumeration Attributes
Enumeration attributes are those attributes used in the enumeration operation to uniquely identify a child instance and its initial parameters. These attributes are typically specified in the Metalanguage Specification, and are provided by the driver's parent during enumeration. The enumeration attributes are set on the child instance before that instance is enabled; the enumeration attributes are set atomically (i.e. none of the attributes can be read or changed until all of the enumeration attributes for that child instance have been set).
Enumeration attributes may be read but not modified by the driver instance with which they are associated.
Enumeration attributes are not visible to the parent once enumerated.
Enumeration attribute names must begin without a special prefix character.
15.4.2.1 Generic Enumeration Attributes
There are four generically-accessible enumeration attributes: "identifier", "address_locator", "physical_locator", and "physical_label". These attributes, of type UDI_ATTR_STRING, are defined so as to allow environments to use these attributes in generic algorithms to identify and compare information about the devices in the system. This is useful in keeping the UDI environment isolated from the specifics of metalanguages and bus bindings.
15.4.2.1.1 identifier attribute
The contents of the "identifier" attribute must be defined in all metalanguages and bus bindings, and an appropriate value for this attribute must be provided on any child enumeration. This attribute is defined on a per-metalanguage/bus basis to provide information that can be used to uniquely identify a device as much as possible for the given I/O technology. In most cases, this will simply identify a type of device and multiple devices of the same type will have the same value, but where available, a serial number could be used to make the string truly unique.
15.4.2.1.2 address_locator attribute
The contents of the "address_locator" attribute must be defined in all metalanguages and bus bindings, and an appropriate value for this attribute must be provided on any child enumeration. This attribute is defined on a per-metalanguage/bus basis to provide information which can be used to address the device, relative to the enumerating parent.
15.4.2.1.3 physical_locator attribute
The "physical_locator" attribute is an optional attribute which may be non-existent for some metalanguages or bus bindings. Metalanguages or buses whose children are physical devices should specify this attribute whenever possible. When defined, this attribute is used to provide information about the physical location of a device, such as a slot number.
15.4.2.1.4 physical_label attribute
The "physical_label" attribute is an optional attribute which may be non-existent for some metalanguages or bus bindings. Metalanguages or buses whose children are physical devices should specify this attribute whenever possible. When defined, this attribute is used to provide information about the physical location of a device in terms of user-visible labeling, when known by the enumerating parent.
15.4.2.1.5 Generic Enumeration Attribute Example
As an example of the usage and combination of these attributes, the following environment is hypothesized:
- Child enumerated by Bus XYZ:
- identifier="<productid,vendorid>"
- address_locator="<dev_num,func_num>"
- physical_locator="<slot#>"
- physical_label="<chassis location>"
- Matches SCSI HBA in slot 3 with a dev_num,func_num of 0x1234,2 and a productid,vendorid of 0x8178,0x9004, which enumerates:
- identifier="<subset of INQUIRY data>"
- address_locator="<bus><target><lun>"
- physical_locator not used
- physical_label not used
- Matches External SCSI Disk Storage Unit at bus 1, target 4, luns 0,1
- Matches External SCSI Tape Device
For an operating system that represents the device node tree to the user via filesystem notation, the above locators might result in the following identification:
/devices/xyz/scsi3-1234,devbay2/tgt2-0,disk /devices/xyz/scsi3-1234,devbay2/tgt2-1,disk /devices/xyz/scsi3-1234,devbay2/tgt2-255,ses /devices/xyz/scsi3-1234,devbay2/tgt6-0,tapeNote - The above example does not reflect actual definitions for enumeration attributes nor actual devices and presents only one style of combining and representing locator attributes. The UDI drivers and metalanguages will define the actual device attributes and locator attributes and the environment is free to use this locator information for any style of representation that it chooses.
15.4.3 Sibling Group Attributes
Sibling group attributes are volatile attributes only; unlike instance-private attributes, they are global to all sibling instances in a sibling group. A sibling group is defined as the set of driver instances that share the same parent instance; i.e. siblings are the set of child instances enumerated by the parent at device enumeration time. It is important to note that sibling instances do not have to be instances of the same driver. For example, a PCI network adapter and a PCI SCSI adapter may be siblings if enumerated by the same PCI parent bus device. It is expected that filter and multiplexer modules will not appear in the sibling/parent relationship.
The attributes for the sibling group are effectively associated with the parent instance, although they are not visible to the parent itself. Instead, the sibling group attributes are visible to all members of that sibling group. Each sibling group member may read and write sibling attributes, although all sibling attributes are volatile and will not be available across system boots.
Sibling group attribute names must begin with a caret (`^') prefix character. Since they are global to all sibling group members, it is recommended that enumeration locator information for the relevant device be included in the attribute name in order to make the name unique. It is assumed that all siblings that need to share information using sibling attributes will use the same algorithm for unique differentiation of their attribute names and will therefore be able to locate these shared attributes.
15.4.4 Parent-Visible Attributes
Parent-visible attributes are attributes that are set on a child instance but which may be read (but not written) only by that instance's parent (and read and written by the environment). These attributes are used by the system administrator to specify configuration information about the child that may be needed by the parent. These types of attributes are defined by the parent driver instance or by the associated metalanguage.
Parent-visible attribute names must begin with an at-sign (`@') prefix character and are persistent.
15.4.5 Attribute Classification
The properties of each instance attribute class are summarized in the following table. For each class, the table specifies the prefix character for the class and whether or not attributes in that class are persistent. It also specifies which driver instances are allowed to write (set) and read (get) the attributes, relative to the driver instance with which the attributes are associated ("self"), and whether or not the attributes are intended to be customized by system administrators or other aspects of the environment. Drivers must provide reasonable default action in cases where custom attributes are not set. The "custom" declaration in the driver's static properties provides a way to guide administrative input of custom attributes.
Table 15-1 Instance Attribute Classification Table Attribute Class Prefix Persistent? Writable by Whom? Readable by Whom? Customized by Environment? Private Persistent Private Volatile Enumeration Sibling Group Parent-Visible
1Enumeration attributes are writable only at enumeration time (write-once semantics) by the parent via udi_enumerate_ack, not via udi_instance_attr_set. 15.5 Instance Attribute Services
This section describes the structural representation of the instance attributes and how they are manipulated by a UDI driver. The method and location of storing attributes is up to the environment implementation so long as it supports the requirements defined by this specification.
NAME udi_instance_attr_type_t
Instance attribute data-type type
#include <udi.h>typedef udi_ubit8_t udi_instance_attr_type_t; /* Instance Attribute Types */#define UDI_ATTR_NONE 0 #define UDI_ATTR_STRING 1 #define UDI_ATTR_ARRAY8 2 #define UDI_ATTR_UBIT32 3 #define UDI_ATTR_BOOLEAN 4 #define UDI_ATTR_FILE 5DESCRIPTION This type is used to identify the data type of an instance attribute. Instance attribute data types determine the storage requirements, encodings, and semantics of instance attribute values.
A list of supported instance attribute data type codes is given below, along with a description of each attribute.
UDI_ATTR_NONE indicates that an attribute has no current value. This type is only legal with an attribute length of zero.
UDI_ATTR_STRING identifies a null-terminated character string, consisting of Unicode characters encoded with the UTF-8 byte-stream character encoding. This encoding ensures that any byte in the string that has the 8th bit clear is in fact an ASCII character and not part of a multi-byte character. The null-terminator byte is considered part of the attribute value and is required.
UDI_ATTR_ARRAY8 identifies a sequence of udi_ubit8_t values.
UDI_ATTR_UBIT32 identifies a single udi_ubit32_t value. The attribute length for attributes of this type must be exactly sizeof(udi_ubit32_t).
UDI_ATTR_BOOLEAN identifies a single udi_boolean_t value. The attribute length for attributes of this type must be exactly sizeof(udi_boolean_t).
UDI_ATTR_FILE identifies a read-only attribute whose value is contained in a driver-provided external file. The attribute name must match a "readable_file" entry in the driver's persistent configuration information, optionally suffixed with a colon (`:') followed by ASCII digits representing a decimal integer up to 224-1. The suffix indicates the beginning file offset to read from; zero is the default. If this offset suffix is provided, it does not count as part of the actual attribute name, so does not have to fit within the 63-character limit.
NAME udi_instance_attr_get
Read an attribute value for a driver instance
#include <udi.h>void udi_instance_attr_get ( udi_instance_attr_get_call_t *callback, udi_cb_t *gcb, const char *attr_name, udi_ubit32_t child_ID, void *attr_value, udi_size_t attr_length ); typedef void udi_instance_attr_get_call_t ( udi_cb_t *gcb, udi_instance_attr_type_t attr_type, udi_size_t actual_length );ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
attr_name is a null-terminated string specifying the attribute name. See Section 15.2, "Instance Attribute Names", and the UDI_ATTR_FILE attribute type for rules on attribute names.
child_ID is the child ID associated with the specific child instance for which this attribute has been set if it is a parent-visible attribute (prefix character `@').
For parent-visible attributes, this argument must match a child_ID from a previous udi_enumerate_ack that has not been unenumerated; it is ignored for other types of attributes.attr_value is a pointer to a memory area to receive the attribute value.
attr_length is the length in bytes of the memory area pointed to by attr_value.
attr_type is the type specifier for the attribute value. See udi_instance_attr_type_t for details.
actual_length is the actual length of the attribute value, even if it could not fit in the attr_value memory area.
DESCRIPTION The udi_instance_attr_get function is used to obtain the value of a driver instance attribute. The returned attribute value will be written to the memory area specified by attr_value.
If attr_name contains a colon (`:'), the rest of the name must be an ASCII-encoded decimal number and attr_type must be UDI_ATTR_FILE. In this case, the number indicates the beginning file offset to read from, in bytes, starting from zero.
If the requested attribute does not exist, the callback routine will be called with an actual_length of 0 and an attr_type of UDI_ATTR_NONE.
Otherwise, actual_length will be set to the actual length of the attribute value, regardless of attr_length; in the case of UDI_ATTR_FILE with an offset specified, this will be the remaining length relative to the specified file. For attribute types other than UDI_ATTR_FILE, if actual_length exceeds attr_length, the contents of the attr_value memory area are unspecified; for UDI_ATTR_FILE, all valid bytes that fit will be filled in.
WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Standard Calling Sequences".
Use of the attr_name and attr_value parameters must conform to the rules described in Section 5.2.1.1, "Using Memory Pointers with Asynchronous Service Calls".
REFERENCES udi_instance_attr_type_t, udi_instance_attr_set
NAME udi_instance_attr_set
Set a driver instance attribute value
#include <udi.h>void udi_instance_attr_set { udi_instance_attr_set_call_t *callback, udi_cb_t *gcb, const char *attr_name, udi_ubit32_t child_ID, const void *attr_value, udi_size_t attr_length, udi_ubit8_t attr_type ); typedef void udi_instance_attr_set_call_t ( udi_cb_t *gcb, udi_status_t status );ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
attr_name is the name of the attribute whose value is to be set.
child_ID is the child ID associated with the specific child instance for which this attribute is to be set if it is a parent-visible attribute (prefix character `@').
For parent-visible attributes, this argument must match a child_ID from a previous udi_enumerate_ack that has not been unenumerated; it is ignored for other types of attributes.attr_value is a pointer to the attribute value to set. attr_value must be NULL if and only if attr_length is 0.
attr_length is the length of the value pointed to by attr_value.
attr_type is the type specifier for the attribute value. See udi_instance_attr_type_t for details. UDI_ATTR_FILE is not allowed with udi_instance_attr_set. attr_type must be UDI_ATTR_NONE if and only if attr_length is zero.
DESCRIPTION The udi_instance_attr_set function is used to set the value of a driver-instance attribute. The attribute to set is specified by attr_name and may be either a persistent or a volatile attribute depending on the attribute type (as indicated by a prefix character).
The attr_value, attr_length, and attr_type combine to specify the attribute value. If the attribute does not presently exist, it is created. If the current attribute type is different than attr_type, the attribute type will be changed to the newly specified type. If the attribute length attr_length is specified as zero, the attribute may be deleted from the database. In general, a zero-length attribute is indistinguishable from a non-existent attribute.
The length of the attribute value specified by attr_value and attr_length must not exceed the maximum length specified by the max_instance_attr_len member of the udi_limits_t structure.
The status value indicates the success or failure of the attribute modification operation.
The udi_instance_attr_set service call must not be used with the UDI_ATTR_FILE attribute type.
WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Standard Calling Sequences".
Use of the attr_name and attr_value parameters must conform to the rules described in Section 5.2.1.1, "Using Memory Pointers with Asynchronous Service Calls".
STATUS VALUE UDI_OK the attribute value was successfully modified.
UDI_STAT_RESOURCE_UNAVAIL the persistent storage database is full and this attribute could not be created or set in the database. The driver is not expected to retry the operation; it should consider this a permanent failure.
UDI_STAT_NOT_SUPPORTED the current environment does not allow modification of the persistent storage database. This error can only occur with persistent attributes.
REFERENCES udi_instance_attr_get, UDI_INSTANCE_ATTR_DELETE, udi_limits_t
NAME UDI_INSTANCE_ATTR_DELETE
Driver instance attribute delete macro
#include <udi.h>#define \ UDI_INSTANCE_ATTR_DELETE( \ callback, gcb, attr_name) \ udi_instance_attr_set( \ callback, gcb, attr_name, NULL, \ NULL, 0, UDI_ATTR_NONE);ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
attr_name is the name of the attribute to delete.
DESCRIPTION The UDI_INSTANCE_ATTR_DELETE macro is a convenience macro which may be used to remove a driver instance attribute. As defined above, this macro utilizes the udi_instance_attr_set service call and sets the attr_length parameter to zero to effect the deletion of the corresponding attribute.
The callback function specified for this macro must be of the udi_instance_attr_set_call_t type.
REFERENCES udi_instance_attr_set
NAME udi_instance_attr_list_t
Enumeration instance attribute list
#include <udi.h>typedef struct { char attr_name[UDI_MAX_ATTR_NAMELEN]; udi_ubit8_t attr_value[UDI_MAX_ATTR_SIZE]; udi_ubit8_t attr_length; udi_instance_attr_type_t attr_type; } udi_instance_attr_list_t; /* Instance attribute limits */#define UDI_MAX_ATTR_NAMELEN 32 #define UDI_MAX_ATTR_SIZE 64MEMBERS attr_name is the name of the instance attribute.
attr_value is the value of this instance attribute.
attr_length is the valid length (in bytes) of the attr_value and must not be zero.
attr_type is the attribute type as specified for udi_instance_attr_type_t. Must not be UDI_ATTR_NONE or UDI_ATTR_FILE.
DESCRIPTION The udi_instance_attr_list_t structure is used to hold a value used to pre-load an enumeration instance attribute. The MA allocates space for a contiguous array of these structures as a movable memory block in order to provide information describing a child instance in an enumeration operation (see "Enumeration Operations").
If attr_type is UDI_ATTR_UBIT32, the 32-bit value is encoded as a little-endian value in the first four bytes of attr_value, and attr_length must be 4. In this case, UDI_ATTR32_SET and UDI_ATTR32_GET must be used to access attr_value, or UDI_ATTR32_INIT must be used to statically initialize such a value before copying it into this structure.
REFERENCES udi_mem_alloc, udi_instance_attr_type_t, UDI_ATTR32_SET, UDI_ATTR32_GET, UDI_ATTR32_INIT
NAME UDI_ATTR32_SET/GET/INIT
Instance attribute encoding/decoding utilities
#include <udi.h>#define UDI_ATTR32_SET(aval, v) \ { udi_ubit32_t vtmp = (v); \ (aval)[0] = (vtmp) & 0xff; \ (aval)[1] = ((vtmp) >> 8) & 0xff; \ (aval)[2] = ((vtmp) >> 16) & 0xff; \ (aval)[3] = ((vtmp) >> 24) & 0xff; } #define UDI_ATTR32_GET(aval) \ ((aval)[0] + ((aval)[1] << 8) + \ ((aval)[2] << 16) + ((aval)[3] << 24)) #define UDI_ATTR32_INIT(v) \ { (v) & 0xff, ((v) >> 8) & 0xff, \ ((v) >> 16) & 0xff, ((v) >> 24) & 0xff }ARGUMENTS aval is the attr_value array which holds an encoded UDI_ATTR_UBIT32 instance attribute value.
v is the udi_ubit32_t value for the instance attribute.
DESCRIPTION These utility macros are used to access values in the attr_value member of a udi_instance_attr_list_t structure when attr_type is UDI_ATTR_UBIT32. In this case, the 32-bit unsigned integer value is encoded as a little-endian value in the first four bytes of attr_value.
UDI_ATTR32_SET assigns a udi_ubit32_t value to an attr_value array, using the above encoding.
UDI_ATTR32_GET extracts a udi_ubit32_t value from an attr_value array, using the above encoding.
UDI_ATTR32_INIT initializes an attr_value from a udi_ubit32_t constant value as a compile-time initializer.
REFERENCES udi_mem_alloc, udi_instance_attr_list_t, udi_instance_attr_type_t
| |
|
|
|