Writing Device Drivers

Properties

Properties are name-value pairs defined by the PROM or the kernel at boot time, by hardware configuration files, or by calls to ddi_prop_create(9F). These interfaces handle creating, modifying, retrieving, and reporting properties.

int ddi_prop_create(dev_t dev, dev_info_t *dip,  	
			int flags, char *name, caddr_t valuep, int length);

ddi_prop_create(9F) creates a property of the name pointed to by name and the value pointed to by valuep.

int ddi_prop_modify(dev_t dev, dev_info_t *dip,  	
			int flags, char *name, caddr_t valuep, int length);

ddi_prop_modify(9F) changes the value of the property identified by name to the value pointed to by valuep.

int ddi_prop_update_int_array(dev_t dev, 
			dev_info_t *dip, char *name, int *data, u_int nelements);

int ddi_prop_update_int(dev_t dev, dev_info_t *dip,  	
			char *name, int data);

int ddi_prop_update_string_array(dev_t dev,  	
			dev_info_t *dip, char *name, char **data, u_int nelements);

int ddi_prop_update_string(dev_t dev, dev_info_t *dip,  	
			char *name, char *data);

int ddi_prop_update_byte_array(dev_t dev, 
			dev_info_t *dip, char *name, u_char *data, u_int nelements);

The property update routines search for and, if found, modify the value of a given property. Properties are searched for based on the dip, name, dev, and the type of the data (integer, string, or byte). The driver software properties list is searched. If the property is found, it is updated with the supplied value. If the property is not found on this list, a new property is created with the value supplied.

For example, if a driver attempts to update the foo property, a property named foo is searched for on the driver's software property list. If foo is found, the value is updated. If foo is not found, a new property named foo is created on the driver's software property list with the supplied value, even if a foo property exists on another property list (such as a PROM property list).

For the routines ddi_prop_update_int_array(9F), ddi_prop_update_string_array(9F), ddi_prop_update_string(9F), and ddi_prop_update_byte_array(9F), data is a pointer which points to memory containing the value of the property. In each case data points to a different type of property value.

int ddi_prop_remove(dev_t dev, dev_info_t *dip, char *name);

ddi_prop_remove(9F) frees the resources associated with the property identified by name.

void ddi_prop_remove_all(dev_info_t *dip);

ddi_prop_remove_all(9F) frees the resources associated with all properties belonging to dip. ddi_prop_remove_all(9F) should be called in the detach(9E) entry point if the driver defines properties.

int ddi_prop_undefine(dev_t dev, dev_info_t *dip,  	
			int flags, char *name);

ddi_prop_undefine(9F) marks the value of the property identified by name as temporarily undefined. The property continues to exist, however, and may be redefined later using ddi_prop_modify(9F).

int ddi_prop_op(dev_t dev, dev_info_t *dip,  	
			ddi_prop_op_t prop_op, int flags, char *name, caddr_t valuep, 
			int *lengthp);

ddi_prop_op(9F) is the generic interface for retrieving properties. ddi_prop_op(9F) should be used as the prop_op(9E) entry in the cb_ops(9S) structure if the driver does not have a prop_op(9E) routine. See "Properties" for more information.

int ddi_getprop(dev_t dev, dev_info_t *dip, int flags,  	
			char *name, int defvalue);

ddi_getprop(9F) is a wrapper around ddi_prop_op(9F). It can be used to retrieve Boolean and integer-sized properties.

int ddi_prop_exists(dev_t match_dev, dev_info_t *dip,  	
			u_int flags, char *name);

ddi_prop_exists(9F) checks for the existence of a property regardless of the property value data type.

int ddi_prop_get_int(dev_t match_dev, dev_info_t *dip,  			
			u_int flags, char *name, int defvalue);

ddi_prop_get_int(9F) searches for an integer property and, if found, returns the value of the property.

int ddi_getlongprop(dev_t dev, dev_info_t *dip,  	
			int flags, char *name, caddr_t valuep, int *lengthp);

ddi_getlongprop(9F) is a wrapper around ddi_prop_op(9F). It is used to retrieve properties having values of arbitrary length. The value returned is stored in a buffer allocated by kmem_alloc(9F), which the driver must free with kmem_free(9F) when the value is no longer needed.

int ddi_getlongprop_buf(dev_t dev, dev_info_t *dip,  	
			int flags, char *name, caddr_t
valuep,  	int *lengthp);

ddi_getlongprop_buf(9F) is a wrapper around ddi_prop_op(9F). It is used retrieve a property having a value of arbitrary length and to copy that value into a buffer supplied by the driver. valuep must point to this buffer.

int ddi_prop_lookup_int_array(dev_t match_dev,  
				dev_info_t *dip,u_int flags, char *name, int **datap, 
			u_int *nelementsp);

int ddi_prop_lookup_string_array(dev_t match_dev,  	
			dev_info_t *dip, u_int flags, char *name,  	
			char **datap, u_int *nelementsp);

int ddi_prop_lookup_string(dev_t match_dev,  	
			dev_info_t *dip, u_int flags, char *name, char **datap);

int ddi_prop_lookup_byte_array(dev_t match_dev,  	
			dev_info_t *dip,u_int flags, char *name, u_char **datap, 
			u_int *nelementsp);

void ddi_prop_free(void *data);

The property lookup routines search for and, if bound, returns the value of a given property. Properties are searched for based on the dip, name, match_dev, and the type of the data (integer, string, or byte). The property search order is as follows:

Search software properties created by the driver.
Search the software properties created by the system (or nexus nodes in the device info tree).
Search the driver global properties list.
If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist).
If DDI_PROP_DONTPASS is not set, pass this request to the parent device information node.
Return DDI_PROP_NOT_FOUND.

int ddi_getproplen(dev_t dev, dev_info_t *dip,  	
			int flags, char *name, int *lengthp);

ddi_getproplen(9F) is a wrapper around ddi_prop_op(9F) that passes back in the location pointed to by lengthp the length of the property identified by name.