Properties and Events

Properties and events are user-defined, name-value pair structures that are managed using the DDI/DKI interfaces. This chapter provides information on the following subjects:

• "Device Property Names"

• "Creating and Updating Properties"

• "Looking up Properties"

• "prop_op() Entry Point"

• "How Drivers Track Events: ddi_log_sysevent()"

• "Event Name-Value Pairs"

Device Properties

Device attribute (or device-related) information can be represented by a name-value pair notation called a property.

A reg property, for example, represents device registers and onboard memory. The reg property is a software abstraction that describes device hardware registers; its value encodes the device register address location and size. Drivers use the reg property to access device registers.

Another example is the interrupt property. An interrupt property represents the device interrupt. Its value encodes the device-interrupt PIN number.

The value of a property can be one of five types:

• A byte array that has an arbitrary length and whose value is a series of bytes

• An integer property whose value is an integer

• An integer array property whose value is an array of integers

• A string property whose value is a NULL-terminated string

• A string array property whose value is a list of NULL-terminated strings

A property that has no value is known as a Boolean property. It is considered to be true if it exists and false if it doesn't exist.

Device Property Names

Strictly speaking, DDI/DKI software property names are not restricted in any way; however, there are certain recommended uses. As defined in IEEE 1275-1994 (the Standard for Boot Firmware), a property "is a human readable text string consisting of one to thirty-one printable characters. Property names shall not contain upper case characters or the characters "/", "\", ":", "[", "]" and "@". Property names beginning with the character "+" are reserved for use by future revisions of IEEE 1275-1994." By convention, underscores are not used in property names; use a hyphen (-) instead. Also by convention, property names ending with the question mark character (auto-boot?) contain values that are strings, typically TRUE or FALSE.

Predefined property names are listed in publications of the IEEE 1275 Working Group. See http://playground.sun.com/1275 for information on how to obtain these publications. For a discussion of adding properties in driver configuration files, see driver.conf(4). The pm(9P) and pm-components(9P) man pages shows how properties are used in power management. Read the sd(7D) man page as an example of how properties should be documented in device driver man pages.

Creating and Updating Properties

To create a property for a driver, or to update an existing property, use one of the DDI driver update interfaces, such as ddi_prop_update_int(9F) or ddi_prop_update_string(9F), with the appropriate type for the property you want to create. (See Table 4-1 for a list of available property interfaces.) These interfaces are typically called from the driver's attach(9E) entry point. In this example, the attach() routine creates a string property called pm-hardware-state and gives it the value needs-suspend-resume:

     /* The following code is to tell cpr that this device
     * needs to be suspended and resumed.
     */
    (void) ddi_prop_update_string(device, dip,
         "pm-hardware-state", "needs-suspend-resume");

Looking up Properties

A driver can request a property from its parent, which in turn might ask its parent. The driver can control whether the request can go higher than its parent.

For example, the example driver below, "esp," maintains an integer property for each target called targetx-sync-speed, where "x" is the target number. The prtconf(1M) command in its verbose mode displays driver properties. The following example shows a partial listing for the "esp" driver.

% prtconf -v
...
       esp, instance #0
            Driver software properties:
                name <target2-sync-speed> length <4>
                    value <0x00000fa0>.
...

The following table provides a summary of the property interfaces.

Table 4-1 Property Interface Uses

Whenever possible, use 64-bit versions of int property interfaces (such as ddi_prop_update_int64(9F)) instead of 32-bit versions (such as ddi_prop_update_int(9F)).

prop_op() Entry Point

ddi_prop_op(9F) can be used as a device driver's prop_op(9E) entry point when ddi_prop_op() is defined within the driver's cb_ops(9S) structure. ddi_prop_op() allows leaf devices to search for and obtain a property value from the device's property list.

It is sometimes useful for a device driver to define a driver-specific prop_op() routine within cb_ops rather than invoking ddi_prop_op(). For example, this is appropriate if a driver maintains a property whose value changes frequently. Changing such a value with ddi_prop_update() would not be efficient. In this case, the driver is responsible for updating the property value and should maintain a copy of the property value either within its soft state structure or in a driver variable.

The prop_op(9E) entry point reports the values of certain driver or device properties to the system. In many cases, the ddi_prop_op(9F) routine may be used as the driver's prop_op() entry point in the cb_ops(9S) structure. ddi_prop_op() performs all of the required processing and is sufficient for drivers that do not need to perform any special processing when handling a device property request.

However, there are cases when the driver must provide a prop_op() entry point. For example, if a driver maintains a property whose value changes frequently, updating the property with ddi_prop_update(9F) each time the value changes may not be efficient. Instead, the driver can maintain a local copy of the property in the instance's soft state. The driver updates the shadow copy in the soft state when the value of the property changes and does not call one of the ddi_prop_update() routines. In this case, the prop_op() entry point would need to intercept requests for this property and call one of the ddi_prop_update() routines to update the value of the property before passing the request to ddi_prop_op() to process the property request.

In Example 4-1, prop_op() intercepts requests for the temperature property. The driver updates a variable in the state structure whenever the property changes but only updates the property when a request is made. It then uses the system routine ddi_prop_op() to process the property request. If the property request is not specific to a device, the driver does not intercept the request. This is indicated when the value of the dev parameter is equal to DDI_DEV_T_ANY (the wildcard device number).

Example 4-1 prop_op(9E) Routine

static int
xxprop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
    int flags, char *name, caddr_t valuep, int *lengthp)
{
        minor_t instance;
        struct xxstate *xsp;
        if (dev != DDI_DEV_T_ANY) {
                return (ddi_prop_op(dev, dip, prop_op, flags, name,
                    valuep, lengthp));
        }

        instance = getminor(dev);
        xsp = ddi_get_soft_state(statep, instance);
        if (xsp == NULL)
                return (DDI_PROP_NOTFOUND);
        if (strcmp(name, "temperature") == 0) {
                ddi_prop_update_int(dev, dip, name, temperature);
        }

        /* other cases */    
}