DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
TOC PREV NEXT INDEX

Static Driver Properties

30

30.1 Overview

This chapter defines static driver properties and how they are included with UDI drivers as an addition to the driver code itself.

Static driver properties are attributes of a driver or library that are known and fixed in advance of compiling its source code. These are generally properties that the environment into which a driver is being installed might need to know about prior to linking, loading and/or running the driver. For this reason, static driver properties are stored with the driver in such a way that they can be easily extracted without running the driver. The same is true for UDI libraries.

30.1.1 UDI Modules

UDI drivers and libraries are compiled and linked into binary object files called modules. A module is the basic unit of loadability. That is, each module can potentially be loaded at separate times or into separate domains, but all code and data in one module is loaded together. In this context, loading refers to any process through which an instance of the module code and data is made available for execution; this might involve dynamic loading into an already-running system or it might simply mean linking into a static image for use at a subsequent system reboot. Modules must not reference symbols in other modules (even within the same driver) or in the surrounding system except as included in explicitly exported/imported interfaces (see the "Requires Declaration" and the "Provides Declaration").

Three types of binary modules are supported:

  1. primary driver module
  2. secondary driver module
  3. library module (including metalanguage libraries)

Each driver module contains the code to handle one or more region types that a driver supports (see Section 30.6.8, "Region Declaration" for more details on region types). No two modules for a driver may handle the same region type. The driver module that handles the driver's primary region (region index zero) is called the primary driver module; all other driver modules, if any, are called secondary driver modules. Each driver module has its own udi_init_info structure (see udi_init_info).

UDI libraries each consist of at most one library module and zero or more exported header files. UDI libraries provide functions that can be called by UDI drivers, but maintain no state of their own. Library modules do not have udi_init_info structures and will not have any region data associated with them. However, if a library is a metalanguage library (i.e. implements a metalanguage API), then it will have a udi_meta_init structure, which serves a similar purpose as a driver's udi_init_info structure.

Each UDI driver or library shall include as part of its source code a static properties file, named "udiprops.txt". At compile/build time, a special utility program called "udimkpkg" (see Section 32.3) attaches the property values from udiprops.txt to the binary object file for the driver's primary module or the library's sole module, in a fashion appropriate to the particular binary object file format used. Header-only libraries have no modules to compile, so their static properties remain as a text file.

A package component can either be a driver or a library. A library component must have exactly one library module and no driver modules (except for header-only libraries, which have no modules). A driver component must have exactly one primary driver module, zero or more secondary driver modules, and no library modules. Each component must have one udiprops.txt file.

30.2 Basic Syntax

The following rules describe the basic structure of a static properties file.

30.3 Property Declaration Syntax

Each non-blank logical line of a static properties file is interpreted as a property declaration. The first token on the line identifies the property or type of property that is being declared. Additional tokens provide values for the property. Definitions below describe the tokens required for each type of property declaration.

The first declaration in the file must be a "properties_version" declaration, which specifies the version of the static property syntax and semantics used for the file. The current version is "0x101": 

properties_version 0x101

Properties version 0x101 encompasses all of the rules and definitions in this chapter, including basic syntax and all property declaration definitions. Static properties files that specify this properties version must only include declarations defined for this version. Future versions of this specification may define additional properties versions, with their own set of definitions and rules. The two least-significant hexadecimal digits of the properties version represents the minor number; the rest of the hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e. a strict superset).1

Environments that support any particular properties version are also required to support all subsequent versions with the same major version number; if they do not specifically support the later version, they shall ignore all unrecognized declarations. Environments are required to refuse to install UDI modules that have static properties files with major version numbers that they do not support.

After the "properties_version" declaration, all remaining declarations may appear in any order, except as described for the "module" and "locale" declarations.

In the descriptions below, "<msgnum>" (or "<msgnum1>", ...) is an ASCII-encoded decimal number used to select a (single-line) message string from a message declaration (described in the next section); leading zeros are ignored for purposes of comparing two message numbers. Message numbers are interpreted relative to each driver, so there is no need for the driver writer to generate numbers that are unique with respect to any other driver. The value of <msgnum> must be 1..216-1 (i.e. a 16-bit value with 0 reserved as illegal).

While drivers must provide the message strings that are specified to be required, environments that choose not to present messages to the user are free to ignore any or all message strings.

30.4 Common Property Declarations

This section lists those property declarations that apply to all types of modules.

30.4.1 Supplier Declaration

Exactly one "supplier" declaration must be included: 

supplier <msgnum>

The supplier message string is used to display the verbose, human-readable name of the supplier of the driver or library. This name should be chosen to be as unique as possible, but the supplier is not required to guarantee that it is globally unique with respect to other suppliers.

30.4.2 Contact Declaration

One or more "contact" declarations must be included: 

contact <msgnum>

The contact message string(s) supplement the "supplier" string with more detailed contact information in cases where verbose output is required. Each contact declaration corresponds to a separate line in the contact info listing. The contact info should generally include at least an e-mail address or URL.

30.4.3 Name Declaration

Exactly one "name" declaration must be included: 

name <msgnum>

The name message string is used to display the verbose, human-readable name of the driver (as opposed to names for individual devices supported by the driver) or library. This name should be chosen to be as unique as possible, but the supplier is not required to guarantee that it is globally unique with respect to other drivers or libraries from the same supplier or from other suppliers.

30.4.4 Shortname Declaration

Exactly one "shortname" declaration must be included: 

shortname <name_string>

The <name_string> string provides a recommended shorthand name for the driver or library. The environment may choose to use this name as is, modify it, or ignore it entirely. The string must be from 1 to 8 characters long and must consist only of upper and lower case letters, digits, and the underscore character (`_'). This name should be chosen to be as unique as possible, but the supplier is not required to guarantee that it is globally unique with respect to other drivers or libraries from the same supplier or from other suppliers.

30.4.5 Release Declaration

Exactly one "release" declaration must be included: 

release <sequence_number> <release_string>

The <release_string> string identifies a release of the driver or library, in "user-friendly" form, that may be presented to users to let them know which release of the driver or library that they are using. <sequence_number> is a number encoded as for UDI_ATTR_UBIT32 (see Table 30-1, "Enumeration Attribute Value Encoding") that may be used for automatic release comparisons; larger numbers represent more recent releases. Neither of these is related to the properties version or to any UDI interface version.

30.4.6 Requires Declaration

One or more "requires" declarations must be included: 

requires <interface_name> <version_number>

Each "requires" declaration specifies a set of programming interfaces (and the associated semantics) that the driver or library uses, and the version of those interfaces to which it conforms. <interface_name> is a string of up to 32 ASCII letters, digits or underscore characters, and <version_number> is a number encoded as a hexadecimal string of up to 4 digits preceded by "0x". The combination of interface name and version number must match an interface version supported on the target system.

No two "requires" declarations for the same driver or library may have the same <interface_name>.

Specifying the module's requirements allows the environment to provide support for the module that is specific to its needs. Environments may choose to support multiple versions of any given interface. Larger version numbers represent more recent versions for a given interface name.

All UDI drivers and libraries must include the following "requires" declaration: 

requires udi 0x101

Additional "requires" statements for each of the other UDI interfaces used by the driver must be included; interface names corresponding to other UDI Specifications are defined in those specifications. Library modules may also define and export their own interface names, as described in Section 30.5.1, "Provides Declaration".

The two least-significant hexadecimal digits of the version represents the minor number; the rest of the hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e. a strict superset).

If the interface name begins with a percent-sign (`%'), the required interface must match a "provides" declaration in the same package collection.

If a "requires" declaration precedes any "module" declarations, it applies to all modules of the driver or library. Otherwise, it applies only to the most recently declared module.

The "requires" declaration indicates both an external symbol dependency for linking/loading, and a compile-time dependency on any header files exported by the providing library. To express a dependency only on header files, use "source_requires".

30.4.7 Module Declaration

One or more "module" declarations must be included, except in a library that only exports header files: 

module <filename>

Each "module" declaration denotes a module that is part of this driver or library. Drivers must have at least one module declaration. Libraries must have at most one module declaration.

The <filename> string provides the name of a binary module file; it must be a local name, without any path separators. No two "module" declarations in the same file may use the same <filename> string.

For binary distributions, the module files are included in the distribution, having been previously built in a UDI build environment. Module files are not distributed with source-only distributions, but will instead be built when the driver source code is compiled and linked on the target system.

The following declaration types are sensitive to ordering relative to "module" declarations: "region", "requires", "source_files", and "source_requires". See each of these declaration sections for more details.

30.4.8 Locale Declaration

One or more optional "locale" declarations may be included: 

locale <locale>

Each "locale" declaration changes the locale to which subsequent "message" and "disaster_message" declarations in the same file apply. Until the first "locale" declaration in a particular file (udiprops.txt or a message file) is encountered, the "C" locale will be used for "message" and "disaster_message" declarations in that file.

The locale specifier, <locale>, is in the following form, which is a subset of the POSIX locale specifier format described in ISO/IEC 9945-1: 

language[_territory]

The language specifier is a two- or three-letter language code as defined by ISO 639-2/T, or the special "POSIX" locale designator, "C". The territory code is an optional specifier, separated from the language specifier by an underscore, that indicates a particular territory or area in which the language is used differently from other areas. The territory code is a two- or three-letter country code as defined by ISO 3166.

At any given time, the environment will determine, in an environment-specific fashion (typically administrator driven), what is the current locale for a particular driver. As message strings are accessed (by driver request or by the environment), the environment will pick a message with the selected number that was associated with the current locale. If it can't find one, it tries to find the same message number in the "C" locale. If it can't find the message there either, it will construct a string, in either the "C" locale or the current locale, to the effect of: 

[Unknown message number <msgnum>.]

30.4.9 Message Declaration

One or more optional "message" declarations may be included: 

message <msgnum> { <text> }

Each "message" declaration provides text for a given message number, <msgnum>, for a particular locale (see the "locale" declaration). If multiple declarations are given for the same message number in the same locale, the environment may choose any one of the message texts.

The valid range for <msgnum> is 1..216-1 (i.e. a 16-bit value with 0 being reserved as an illegal message number).

The actual message string used will consist of each of the <text> tokens, along with any intervening whitespace, but not any preceding and trailing whitespace. Any whitespace between tokens is treated as a single space character when the message text is used. Each <text> token is encoded as for UDI_ATTR_STRING in Table 30-1. This encoding supports escape sequences that represent characters that can't be included directly in a token.

Some messages are referenced by other declarations and may be used by the environment. Others may be used by the driver modules themselves, for the purpose of tracing and logging, by specifying the desired <msgnum> as an argument to udi_trace_write or udi_log_write. These message strings may contain format codes as for udi_snprintf.

Environment implementations may choose to manage message strings in any number of ways. They may be accessed directly from the driver properties or the messages files, or they may first be copied into a central message database, possibly with a different format. They may be individually fetched as needed, or they may all be pre-loaded into memory when the corresponding driver is loaded. In fact, an extreme environment could even discard all messages. In any case, none of these environment implementation choices is visible to the driver.

30.4.10 Disaster_message Declaration

One or more optional "disaster_message" declarations may be included: 

disaster_message <msgnum> { <text> }

Any "disaster_message" declaration is treated the same as a "message" declaration, except that it is intended specifically for messages that will be used to log messages with UDI_LOG_DISASTER severity. As such, some environments that don't pre-load all messages may choose to pre-load just the disaster messages so they're guaranteed to be available during system abort handling.

30.4.11 Message_file Declaration

One or more optional "message_file" declarations may be included: 

message_file <filename>

Each "message_file" declaration denotes an external text file that includes additional message string definitions for this driver, besides any that may be included in the static driver properties file itself. The <filename> string must name a file that is included with the rest of the driver files, including the static driver properties file, in the same directory; it must be a local name, without any path separators.

Message files are distributed as separate files from the main driver file(s), even for binary distributions.

Message files have the same format as udiprops.txt, and must also begin with a "properties_version" declaration. Aside from the "properties_version" declaration, however, the only declarations legal in a message file are "message", "disaster_message", and "locale".

Message files must not be larger than 16 MB.

30.5 Property Declarations for Libraries

The property declarations in this section apply only to library modules.

30.5.1 Provides Declaration

One or more "provides" declarations must be included: 

provides <interface_name> <version_number> [include-file ...]

Each "provides" declaration specifies a set of programming interfaces (and the associated semantics) that the library provides for use by other libraries or drivers, along with the supported version of those interfaces. <interface_name> is a string of up to 32 ASCII letters, digits or underscore characters (defined in each specification as described in the "requires" declaration), and <version_number> is a number encoded as a hexadecimal string of up to 4 digits preceded by "0x". The combination of interface name and version number must be globally unique.

The two least-significant hexadecimal digits of the version represents the minor number; the rest of the hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e. a strict superset).

The fourth and following parameters on the provides line list zero or more C header files that contain exported public definitions for the library being provided. These header files will be made available to any modules specifying this library via a corresponding requires declaration; those modules may include the header files by simple filename reference (in angle brackets); no path prefix is required.

By default, if no "symbols" declarations are associated with this "provides" declaration, all global symbols exported by the library are available as part of the specified interface. Libraries that support more than one interface or version will need finer control. To do this, they can use the "symbols" declaration. Any library that has multiple "provides" declarations must include "symbols" declarations that correspond to each of the "provides" declarations. For libraries with a single "provides" declaration, "symbols" is optional.

If the interface name begins with a percent-sign (`%'), this interface is visible only to modules in the same package collection. Otherwise the library is available for use by any UDI package installed into the system and will be referenced by a "requires" declaration in that driver's installation. To avoid conflicts with this global namespace, the following naming convention is recommended for the <interface_name> parameter when it does not begin with `%':

  1. It should be a trademarked name owned by the supplying company, or
  2. It should begin with the supplying company's stock symbol followed by an underscore if that company is publicly traded, or
  3. It should start with an underscore followed by the company or organization's name or commonly used acronym, or
  4. It should start with two underscores followed by the developer's name or similar identification if not affiliated with any company or organization.

The "symbols" declaration type is sensitive to ordering relative to "provides" declarations. See the "Symbols Declaration" section for more details.

30.5.2 Symbols Declaration

Zero or more "symbols" declarations may be included: 

symbols { [ <library_symbol> as ] <provided_symbol> }

Each "symbols" declaration specifies a set of symbols in the library that are associated with a particular interface version provided by the library. "Symbols" declarations apply to the most recently declared "provides" declaration preceding the "symbols" declaration. "Symbols" declarations must not precede the first "provides" declaration. Multiple "symbols" declarations may be provided for the same "provides" declaration.

For any interface version with one or more corresponding "symbols" declarations, only the listed <provided_symbol> names will be available to other libraries or drivers that import these symbols via a "requires" declaration. If a listed symbol has a <library_symbol> associated with it (before the preceding "as" keyword), then the symbol named <library_symbol> in the library will be used to resolve references to the <provided_symbol> name; otherwise, the <provided_symbol> name will also be used as the library symbol name.

The ability to resolve references to one symbol as another symbol in the library allows a library to support multiple versions of an interface, even if the library's implementation for some symbols is different for different versions.

All symbol names in "symbols" declarations are spelled as they would be in a C language source file, regardless of how they might appear in a symbol table in an object file. Some language or object file conventions modify symbol names before placing them into a symbol table (for example, by prefixing with an underscore character).

30.5.3 Category Declaration

One optional "category" declaration may be included in a library that is used as a metalanguage library: 

category <msgnum>

The category message string is a human-readable brief (two or three word) description of the category of device supported by drivers that use this metalanguage as a child metalanguage. While the overall type of device can be inferred from the driver's "requires" declarations, it may be desirable to supplement this categorization with a more specific description.

Each metalanguage that can be used as a child metalanguage specifies a category name (in English) to be used for its "category" declaration. The message text for the POSIX ("C") locale for this "category" declaration must exactly match the specified category name, since driver documentation may refer to these strings.

Environments may choose to group drivers by category for purposes of presenting lists of drivers to administrators, and to use the category message strings from the associated libraries to present a heading for each group. If a driver falls into multiple categories (because it has multiple child metalanguages), it is recommended but not required that it be listed in all categories to which it belongs.

The category name must be phrased as a appropriate for a table heading, and thus must be a plural (or collective) noun phrase. Examples of possible category names are listed below. Refer to metalanguage specifications for the official names. 

SCSI Host Bus Adapters
 
Network Interface Cards
 
Communications Cards
 
Video Cards
 
Sound Boards
 
Miscellaneous

30.6 Property Declarations for Drivers

The property declarations in this section apply only to drivers.

30.6.1 Meta Declaration

One "meta" declaration must be included for each type of metalanguage used by the driver: 

meta <meta_idx> <interface_name>

A "meta" declaration indicates a metalanguage that may be used by this driver. The <interface_name> string must be the same as the <interface_name> in a "requires" declaration for this driver.

The <meta_idx> specified in the "meta" declaration is an ASCII-encoded decimal number from 1 to 255 that is used to distinguish one metalanguage declaration from another (0 is reserved for the Management Metalanguage) and is used to refer to this metalanguage in other declarations and in the driver's udi_init_info structure.

The <meta_idx> number must be unique with respect to all "meta" declarations for this driver.

30.6.2 Child_bind_ops Declaration

Exactly one "child_bind_ops" declaration must be included for each type of child binding ops index supported by the driver: 

child_bind_ops <meta_idx> <region_idx> <ops_idx>

A "child_bind_ops" declaration indicates a metalanguage that may be used to bind children to this driver. Some drivers may support multiple child metalanguages.

The <meta_idx> token is an ASCII-encoded decimal number from 1 to 255 that is used to distinguish one metalanguage declaration from another and must match a corresponding "meta" declaration. It must also match the meta_idx value specified in the driver's udi_ops_init_t structures corresponding to <ops_idx>. The meta_ops_num for this udi_ops_init_t structure must refer to an ops vector type that is suitable for use with child bind channels (as indicated by the relationship value in the metalanguage library's udi_ops_vec_template_t). For more information, see udi_ops_init_t and udi_mei_ops_vec_template_t.

When the driver is being bound to a child using the specified ops index, its end of the bind channel will be anchored using <ops_idx> in a region of type <region_idx>.

Note - It is legal, though unusual, to have a driver with no "child_bind_ops" declarations. Such a driver can have no children, and is thus really an application running as a UDI driver.

30.6.3 Parent_bind_ops Declaration

Exactly one "parent_bind_ops" declaration must be included for each type of parent metalanguage supported by the driver: 

parent_bind_ops <meta_idx> <region_idx> <ops_idx> <bind_cb_idx>

A "parent_bind_ops" declaration indicates a metalanguage that may be used to bind parents to this driver. Some drivers may support multiple parent metalanguages.

The <meta_idx> token is an ASCII-encoded decimal number from 1 to 255 that is used to distinguish one metalanguage declaration from another and must match a corresponding "meta" declaration. It must also match the meta_idx value specified in the driver's udi_ops_init_t structures corresponding to <ops_idx>. The meta_ops_num for this udi_ops_init_t structure must refer to an ops vector type that is suitable for use with parent bind channels (as indicated by the relationship value in the metalanguage library's udi_ops_vec_template_t). For more information, see udi_ops_init_t and udi_mei_ops_vec_template_t.

When the driver is being bound to a parent using the specified metalanguage, its end of the bind channel will be anchored using <ops_idx> in a region of type <region_idx>. Depending on the settings for this region index in the driver's udi_init_info structures, this will either be a newly-created region or an existing static primary or secondary region.

The <bind_cb_idx> token is the index value of the control block that will be used by this driver to send the metalanguage-specific bind request to the parent driver when a UDI_CHANNEL_BOUND event indication for this type of binding is received. The <bind_cb_idx> value must correspond to the cb_idx of a udi_cb_init_t structure that describes the requirements of the control block to be used; the Management Agent will pass a pre-allocated control block of this type in the bind_cb field of the UDI_CHANNEL_BOUND event indication. If the bind_cb_idx value is zero, no control block will be pre-allocated or passed to the driver.

Drivers with no "parent_bind_ops" declarations can have no parents and are thus called orphan drivers. Orphan drivers control no actual devices, but still present the device model(s) appropriate to the child metalanguage(s) they support. (Sometimes the term pseudo-device driver or pseudo-driver is also used to refer to orphan drivers as well as other drivers that do not directly control actual devices.) Orphan drivers are treated specially in the following ways:

30.6.4 Internal_bind_ops Declaration

Exactly one "internal_bind_ops" declaration must be included for each type of secondary region: 

internal_bind_ops <meta_idx> <region_idx> \

		<primary_ops_idx> <secondary_ops_idx> \

		<bind_cb_idx>

A "internal_bind_ops" declaration indicates a metalanguage that may be used between regions internal to this driver. There must be a one-to-one correspondence between "internal_bind_ops" declarations and "region" declarations, based on matching <region_idx> values, except for region index zero (the primary region).

The <meta_idx> token is an ASCII-encoded decimal number from 1 to 255 that is used to distinguish one metalanguage declaration from another and must match a corresponding "meta" declaration. It must also match the meta_idx value specified in the driver's udi_ops_init_t structures corresponding to both <primary_ops_idx> and <secondary_ops_idx>. The meta_ops_num for these udi_ops_init_t structures must refer to ops vector types that are suitable for use with internal bind channels (as indicated by the relationship value in the metalanguage library's udi_ops_vec_template_t). For more information, see udi_ops_init_t and udi_mei_ops_vec_template_t.

When a secondary region of this type is created, an internal bind channel will be created by the environment, with the primary region's end of the channel anchored using <primary_ops_idx> and with the secondary region's end anchored using <secondary_ops_idx>.

The <bind_cb_idx> token is the index value of the control block that will be used by this driver to send the metalanguage-specific bind request to the parent driver when a UDI_CHANNEL_BOUND event indication for this type of binding is received. The <bind_cb_idx> value must correspond to the cb_idx of a udi_cb_init_t structure that describes the requirements of the control block to be used; the Management Agent will pass a pre-allocated control block of this type in the bind_cb field of the UDI_CHANNEL_BOUND event indication. If the bind_cb_idx value is zero, no control block will be pre-allocated or passed to the driver.

30.6.5 Device Declaration

One or more "device" declarations must be included for non-orphan drivers: 

device <msgnum> <meta_idx> { <attr_name> <attr_type> <attr_value> }

The "device" declarations describe the device(s) that can be supported by this driver. There will be one declaration for each model of device. The message string is used to describe the particular device selected by the declaration; the corresponding message referenced is intended to be a verbose human-readable device name (see Section 30.4.9, "Message Declaration").

The attribute name and value pairs are matched against the enumeration attribute of devices that are possible candidates for being managed by this driver. The set of valid enumeration attribute names is specified by the instance attribute bindings of the selected parent metalanguage, as indicated by a "parent_bind_ops" declaration with matching <meta_idx>. It is illegal to specify an attribute name that is not a parent metalanguage enumeration attribute or to specify an attribute value that is out of range.

If two or more "device" declarations for the same driver use the same <msg_num>, the "multi_parent" declaration must also be present, and the environment may bind multiple parents to this driver of different types (as indicated by the <meta_idx> values, which must be different for each of these "device" declarations). Any "device" declarations with differing <msg_num> values identify distinct types of devices and only one of which will be bound to a single instance of this driver.

If any specified attributes do not match the corresponding enumeration attribute of a device instance, then this driver will not be used for that device instance. If multiple "device" declarations (from multiple drivers or from the same driver) match a given device instance, only those with the most attribute pairs specified are considered matches. It is environment implementation dependent what the behavior is when multiple candidates match the same device, but it shall not be considered a driver error.

The <attr_value> string must be a single token. Its encoding depends on the type of the enumeration instance attribute (see udi_instance_attr_type_t), as indicated by <attr_type>, according to the following table. <attr_type> must be one of the tokens in the Type Name column of this table.
Table 30-1 Enumeration Attribute Value Encoding
Attribute Type Type Name Encoding
UDI_ATTR_STRING string Literal string value, except that whitespace and hash (`#') characters cannot be included directly, so escape sequences from Table 30-2 are used to represent these characters. Matching is case-sensitive.
UDI_ATTR_UBIT32 ubit32 The numeric value may be encoded either as an ASCII-encoded decimal string, or as a hexadecimal string preceded by "0x". Matching is case-insensitive.
UDI_ATTR_BOOLEAN boolean True values are encoded as the single character, "T"; false values are encoded as the single character, "F". Matching is case-insensitive.
UDI_ATTR_ARRAY8 array Each byte of the value is encoded as two ASCII-encoded hex digits, with no prefixes or punctuation. The first pair of digits corresponds to the first byte in the array, and so on. All digits must be specified, even if they are zero. Matching is case-insensitive.
For portability concern, the UDI_ATTR_ARRAY8 enumeration attribute value should not exceed UDI_MIN_INSTANCE_ATTR_LIMIT as documented by udi_limits_t.
Table 30-2 UDI_ATTR_STRING Escape Sequences
2-Character Escape Sequence Interpretation
\_
space
\H
hash character (`#')
\\
backslash (`\')
\p
Paragraph BreakFor "message" and "disaster_message" declarations only.May optionally be used by the environment when it formats a message to present to users. The manner in which a paragraph break is rendered is unspecified.
\m<msgnum>
Embedded MessageFor "message" and "disaster_message" declarations only.The text for the specified message number is recursively embedded into the message text that included this escape sequence. The resulting message text, after escape and whitespace processing must not exceed 2000 bytes. At most three (3) levels of nested embedding-not including the original message-may be used.
all others
All other escape sequences (as identified by the initial backslash character) are illegal. The result of using an illegal escape sequence is indeterminate and implementation-specific.

Values for enumeration attributes of other types not listed in Table 30-1 cannot be used in property declarations.

30.6.6 Enumerates Declaration

One or more optional "enumerates" declarations may be included: 

enumerates <msgnum> <min_num> <max_num> <meta_idx> \

		{ <attr_name> <attr_type> <attr_value> }

Each "enumerates" declaration describes a type of (actual or pseudo) child device that this driver is likely to enumerate when used with a device who's "device" declaration has a matching <msgnum>. This can be used as a hint to the environment, for example to help choose drivers to pre-load in a static environment, or, on the opposite end of the spectrum to allow drivers to be automatically loaded as they are accessed by applications.

As with "device" declarations, "enumerates" specifies a metalanguage and a set of enumeration attributes. The driver is not required to guarantee that it will enumerate the devices for which it includes "enumerates" declarations, but it should only list devices that are highly likely, to avoid incurring excessive performance penalties.

The <min_num> and <max_num> values, represented as ASCII-encoded decimal numbers from zero to 232-1, indicate the expected range for the number of device instances of this type that will be enumerated per parent instance. <max_num> must be greater than or equal to <min_num>.

30.6.7 Multi_parent Declaration

One optional "multi_parent" declaration may be included: 

multi_parent

The "multi_parent" declaration indicates that each instance of the driver may be bound to multiple parent instances (using either the same or different metalanguages); this is typically used for multiplexers. If a driver does not include "multi_parent" in its static properties, it is guaranteed to be bound to at most one parent per instance at any time.

30.6.8 Region Declaration

One "region" declaration must be included for each type of region used by the driver: 

region <region_idx> { <region_attribute> <value> }

Each "region" declaration describes a type of region for this driver. A declaration for region index zero is always required; this specifies attributes of the driver's primary region. The region index is specified as an ASCII-encoded decimal number. No two "region" declarations in the same file may have the same region index.

"Region" declarations must not precede the first "module" declaration. The most recently declared module preceding any "region" declaration must be the module that handles this region index.

Valid values for <region_attribute> and <value> are shown in the following table. The same <region_attribute> must not be listed twice in the same "region" declaration.
Table 30-3 Region Attributes
<region_attribute> <value> Meaning
type normal A normal region. This is the default value for this attribute.
type fp Regions of this type may use floating point operations and data types.
binding static Exactly one region of this type will be created by the environment for each driver instance, when that instance is created. The primary region must have this attribute value. This id the default value for this attribute.
binding dynamic Regions of this type are to be created only when parent or child bindings for this region index are performed. One region is created for each such binding. See the "parent_bind_ops" and "child_bind_ops" declarations.
priority lo Regions of this type should be scheduled, if possible, at a lower priority than other regions for this driver that have higher priority values.
priority med Regions of this type should, if possible, be scheduled ahead of regions whose priority attribute is set to lo and behind regions whose priority attribute is set to hi. This is the default value for this attribute.
priority hi Regions of this type should be scheduled, if possible, at a higher priority than other regions for this driver that have lower priority values (lo or med).
latency powerfail_warning Regions of this type service devices that may deliver early warning of impending power failures. Some environments will consider this the most critical type of event to be serviced quickly.
latency overrunable Regions of this type service devices that are overrunable without possibility of retry. That is, if they are not serviced soon enough, they may permanently lose data.
latency retryable Regions of this type service devices that are overrunable but with the possibility of retry. That is, if they are not serviced soon enough, they may lose data but it can be recovered by retrying the operation.
latency non_overrunable Regions of this type service devices that are not overrunable. That is, they will maintain data associated with all outstanding operations until serviced, no matter how long it takes. This is the default value for this attribute.
latency non_critical Regions of this type service devices that are not overrunable and are also considered non-critical relative to other devices. In other words, all other devices may be serviced in preference to a non-critical device if they both have service pending at the same time. Typically this is used for slow, infrequently-used devices like floppy disks.
overrun_time <nanoseconds> For regions with overrunnable or retryable latency, this attribute indicates the typical time to overrun, in nanoseconds. The nanoseconds value must be in the range 1..232-1.

30.6.9 Readable_file Declaration

One or more optional "readable_file" declarations may be included: 

readable_file <filename>

Each "readable_file" declaration denotes a file that may be read by the driver at run time. The <filename> string must name a file that is included with the rest of the driver files, including the static driver properties file, in the same directory; it must be a local name, without any path separators.

Readable files are distributed as separate files from the main driver file(s), even for binary distributions.

The driver can read the contents of readable files by using udi_instance_attr_get with "<filename>" as the attribute name. See Section 15.2, "Instance Attribute Names" for restrictions on attribute names. This will yield an attribute of type UDI_ATTR_FILE. Readable files are treated as raw binary files and are not in any way preprocessed by the environment.

The following files must not be used as readable files: udiprops.txt, any file used as a message file (see the "message_file" declaration), or any of the driver's source files (see the "source_files" declaration) or module files (see the "module" declaration). Readable files must not be larger than 16 MB.

30.6.10 Custom Declaration

One or more optional "custom" declarations may be included: 

custom <attr_name> <scope> <msgnum1> <msgnum2> <msgnum3> <choices> <device>

Each "custom" declaration describes a custom configuration parameter for this driver. The environment will provide a way for the administrator or integrator to set values for each of these parameters. The selected parameter values are made available to the driver via its instance attributes.

<attr_name> is the name of the instance attribute that will be used to represent the value of this parameter. This must be a private-persistent or parent-visible attribute. If it is parent-visible, it applies separately to each child created. The driver can access these values using instance attribute services (see Chapter 15, "Instance Attribute Management").

<scope> determines the applicability of this parameter to the various device instances covered by this driver or, in the case of parent-visible attributes, the child device instances applicable to this driver, according to the following table:
Table 30-4 Custom Parameter Scope
Value of <scope> Meaning
device The parameter applies to each device instance independently, and is required for all device instances.
device_optional The parameter applies to each device instance independently, and is optional.
driver The parameter applies to all device instances covered by the driver and will be set to the same value for each one. The parameter is required for all device instances.
driver_optional The parameter applies to all device instances covered by the driver and will be set to the same value for each one. The parameter is optional.

<msgnum1> provides the "user-friendly" name for the parameter. It should concisely (about one to three words) elucidate the meaning of the parameter in a form that could be used as a table heading, a menu option or in prose such as "Would you like to change the <msgnum1> parameter?". The specification of <msgnum1> must be a single token and may using the encodings specified in Table 30-2.

<msgnum2> provides a description of the parameter that can be presented to the user to help them understand what the parameter represents. It should be in the form of one or more complete sentences and may consists of multiple paragraphs (though environments are not required to display the message as multiple paragraphs). If the description text refers to any parameter name, it should use the name given by <msgnum1> rather than <attr_name>. The specification of <msgnum2> must be a single token and may use the encodings specified in Table 30-2.

<msgnum3> indicates a sub-category of parameters to which this parameter belongs. Some environments may group parameters by sub-category when presenting lists of parameters to the user. If <msgnum3> is non-zero, the corresponding message string may be used as a heading for the sub-category. Examples of possible sub-categories include "Basic" vs "Advanced" and "Ethernet" vs "Token Ring". The specification of <msgnum3> must be a single token and may use the encodings specified in Table 30-2.

<choices> describes the set of valid values for the parameter, and is constructed as follows: 

<attr_type> <default_value> \

	( mutex { <value> }2+ end | \

	  range <min_value> <max_value> <stride> | \

	  any | \

	  only )

<attr_type> is the type of the instance attribute that will be used to represent the value of this parameter. This must be one of the Type Names listed in Table 30-1, "Enumeration Attribute Value Encoding".

<default_value> provides the default value for a parameter, and is encoded as for <attr_value> in "device" declarations (see Table 30-1) except when <attr_type> is "string". If the <attr_type> is "string" then the <default_value> and all other values specified for this parameter are ASCII encoded numeric values representing message numbers; if such attribute values are presented to a user, they shall be presented with the text of these message strings in the user's current locale, but the C locale string shall be used when setting the actual attribute value (which will be of type UDI_ATTR_STRING).

The remainder of the <choices> clause begins with a keyword identifying the type of choice available. The mutex keyword indicates a mutually-exclusive set of at least two alternatives, terminated by the end keyword. The range keyword, which is only valid when <attr_type> is "ubit32", indicates a range of choices beginning with <min_value>, incrementing by <stride>, until the value exceeds <max_value>. The any keyword indicates that any value appropriate for the attribute type may be used. The only keyword indicates that the only valid value is <default_value>.

<value>, <min_value>, <max_value>, <attr_value>, <attr_value2> and <stride>, if provided, are encoded as shown in Table 30-1.

<device> is zero if this "custom" declaration applies to all types of devices supported by this driver. Otherwise, it is the <msgnum> of a corresponding "device" declaration, and the parameter applies only to devices of that type.

30.6.11 Config_choices Declaration

One or more "config_choices" declarations must be included for each <msgnum> used in a "device" declaration for a non-self-identifying bus (e.g. legacy ISA). The "config_choices" declaration is only supported for such devices. 

config_choices <msgnum> { <attr_name> <choices> }

These declarations are used for devices on buses that have device configuration attributes that can't be read by generic software (legacy ISA, for example). Such devices will generally require explicit user configuration. The "config_choices" declarations provide default choices for these configuration attributes. The <attr_name> string(s) must correspond to valid enumeration attributes, as described for "device" declarations. The <choices> clause describes a set of parameter value choices, as in the "custom" declaration.

The <msgnum> value must match a <msgnum> used in a "device" declaration. This associates one or more default settings with a given device declaration. If there are more than one for the same device, they represent alternate choices. It is environment implementation dependent how the choice between alternates is made. Environments may choose to ignore some or all "config_choices" declarations.

For devices that have factory default settings, the first "config_choices" declaration for such a device should represent the factory defaults.

30.7 Build-Only Properties

The property declarations in this section apply only when building drivers or libraries from source. These declarations are stripped out by the udimkpkg utility program (see Section 32.3) when it attaches static driver properties to binary object files for binary distributions.

30.7.1 Source_files Declaration

One or more optional "source_files" declarations may be included: 

source_files { <filespec> }

"Source_files" declarations are used only when building (or re-building) a driver or library from source code. Binary-only distributions need not have any "source_files" declarations.

The list of <filespec> names specifies the list of C source files that must be compiled and linked in order to build this module. If this static properties file is for a binary-only distribution, no source files will be listed; otherwise, there must be at least one source file for each module. C source file names must be less than 64 characters long, and must end in ".c" or ".h".

The "source_files" declaration is sensitive to ordering relative to "compile_options" declarations. See Section 30.7.2, "Compile_options Declaration", for more details.

30.7.2 Compile_options Declaration

One or more optional "compile_options" declarations may be included: 

compile_options { <option> }

"Compile_options" declarations are used only when building (or re-building) a driver or library from source code. Binary-only distributions need not have any "compile_options" declarations.

"Compile_options" declarations apply to any "source_files" declarations following the "compile_options" declaration, until the next "compile_options" declaration. Each "compile_options" decalaration overrides the preceding one.

If no "compile_options" declarations precede a particular "source_files" declaration, the corresponding source files will be compiled without any special compile options.

Valid compile options are listed in the following table.
Table 30-5 Compile Options
<option> Description
-D<name>
 Causes <name> to be defined as a macro to be replaced by "1", as if by a #define directive.
-D<name>=<token>
 Causes <name> to be defined as a macro to be replaced by <token>, as if by a #define directive.
-U<name>
 Causes <name> to be undefined as a macro, as if by a #undef directive. Overrides any -D compile options.

Traditional compile options, such as -g or -O, are not supported, since they will be provided generically by the udibuild utility program (see Section 32.2).

30.7.3 Source_requires Declaration

One or more optional "source_requires" declarations may be included: 

source_requires <interface_name> <version_number>

Each "source_requires" declaration is treated exactly like a "requires" declaration, except that it is used only when the driver or library is compiled/built from source.

"Source_requires" declarations are used only when building (or re-building) a driver or library from source code. Binary-only distributions need not have any "source_requires" declarations.

30.8 Sample Static Driver Properties File

The following example shows what a static driver properties file for a network interface card driver from the XYZ Company might look like. 

properties_version 0x101
 
supplier 1
 
contact 2
 
name 3
 
shortname xyznic
 
release 5 1.0b5
 
requires udi 0x101
 
requires udi_physio 0x101
 
requires udi_bridge 0x101
 
meta 1 udi_bridge
 
requires udi_nic 0x101
 
meta 2 udi_nic
 
parent_bind_ops 1 0 1 0
 
child_bind_ops 2 0 2
 
device 5 1 bus_type string pci pci_vendor_id ubit32 1234 \

		pci_device_id ubit32 19
 
enumerates 5 1 1 2 if_num ubit32 0 if_media string fe
 
custom %media_type driver 10 11 0 string 12 \

		mutex 12 13 end 0
 
message 1 XYZ Corporation
 
message 2 support@xyz.com
 
message 3 XYZ 552x LAN Driver
 
message 5 xyz5524 10/100Base-T
 
message 10 Media Type
 
message 11 The Media Type parameter indicates the type of network

	to which the card is connected. This may be "\m12" or

	"\m13".
 
message 12 Ethernet
 
message 13 Token Ring
 
locale piglatin
 
message 10 Ediamay ypetay
 
message 11 Ethay Ediamay Ypetay arameterpay indicatesyay ethay

	ypetay ofyay etworknay otay ichwhay ethay ardcay isyay

	onnectedcay. Isthay aymay ebay "\m12" oryay

	"\m13".
 
message 12 Ethernetyay
 
message 13 Okentay Ingray
 
module xyznicd
 
region 0

1As an exception to this version compatibility, version 1.0 (0x100) is not forward compatible with any other versions bearing the major number of 1; version 1.0 of the specification cannot be wholly implemented as a functional product.

TOC PREV NEXT INDEX