Copyright (c) 2001, Sun Microsystems, Inc., All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#include <sys/ddi.h> #include <sys/sunddi.h> int ddi_prop_lookup_int_array(dev_t match_dev, dev_info_t *dip, uint_t flags, char *name, int **datap, uint_t *nelementsp);
int ddi_prop_lookup_int64_array(dev_t match_dev, dev_info_t *dip, uint_t flags, char *name, int64_t **datap, uint_t *nelementsp);
int ddi_prop_lookup_string_array(dev_t match_dev, dev_info_t *dip, uint_t flags, char *name, char ***datap, uint_t *nelementsp);
int ddi_prop_lookup_string(dev_t match_dev, dev_info_t *dip, uint_t flags, char *name, char **datap);
int ddi_prop_lookup_byte_array(dev_t match_dev, dev_info_t *dip, uint_t flags, char *name, uchar_t **datap, uint_t *nelementsp);
void ddi_prop_free(void *data);
Device number associated with property or DDI_DEV_T_ANY.
Pointer to the device info node of device whose property list should be searched.
Possible flag values are some combination of: DDI_PROP_DONTPASS
Do not pass request to parent device information node if the property is not found.
Do not look at PROM properties (ignored on platforms that do not support PROM properties).
String containing the name of the property.
The address of an unsigned integer which, upon successful return, will contain the number of elements accounted for in the memory pointed at by datap. The elements are either integers, strings or bytes depending on the interface used.
ddi_prop_lookup_int_array()
The address of a pointer to an array of integers which, upon successful return, will point to memory containing the integer array property value.
The address of a pointer to an array of 64-bit integers which, upon successful return, will point to memory containing the integer array property value.
The address of a pointer to an array of strings which, upon successful return, will point to memory containing the array of strings. The array of strings is formatted as an array of pointers to NULL terminated strings, much like the argv argument to execve(2).
The address of a pointer to a string which, upon successful return, will point to memory containing the NULL terminated string value of the property.
The address of pointer to an array of bytes which, upon successful return, will point to memory containing the byte array value of the property.
Solaris DDI specific (Solaris DDI).
The property look up routines search for and, if found, return 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:
1. Search software properties created by the driver.
2. Search the software properties created by the system (or nexus nodes in the device info tree).
3. Search the driver global properties list.
4. If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist).
5. If DDI_PROP_DONTPASS is not set, pass this request to the parent device information node.
6. Return DDI_PROP_NOT_FOUND.
Usually, the match_dev argument should be set to the actual device number that this property is associated with. However, if the match_dev argument is DDI_DEV_T_ANY, the property look up routines will match the request regardless of the actual match_dev the property was created with. If a property was created with match_dev set to DDI_DEV_T_NONE, then the only way to look up this property is with a match_dev set to DDI_DEV_T_ANY. PROM properties are always created with match_dev set to DDI_DEV_T_NONE.
name must always be set to the name of the property being looked up.
For the routines ddi_prop_lookup_int_array(), ddi_prop_lookup_int64_array(), ddi_prop_lookup_string_array(), ddi_prop_lookup_string(), and ddi_prop_lookup_byte_array(), datap is the address of a pointer which, upon successful return, will point to memory containing the value of the property. In each case *datap points to a different type of property value. See the individual descriptions of the routines below for details on the different return values. nelementsp is the address of an unsigned integer which, upon successful return, will contain the number of integer, string or byte elements accounted for in the memory pointed at by *datap.
All of the property look up routines may block to allocate memory needed to hold the value of the property.
When a driver has obtained a property with any look up routine and is finished with that property, it must be freed by calling ddi_prop_free(). ddi_prop_free() must be called with the address of the allocated property. For instance, if one called ddi_prop_lookup_int_array() with datap set to the address of a pointer to an integer, &my_int_ptr, then the companion free call would be ddi_prop_free(my_int_ptr). ddi_prop_lookup_int_array()
This routine searches for and returns an array of integer property values. An array of integers is defined to *nelementsp number of 4 byte long integer elements. datap should be set to the address of a pointer to an array of integers which, upon successful return, will point to memory containing the integer array value of the property.
This routine searches for and returns an array of 64-bit integer property values. The array is defined to be *nelementsp number of int64_t elements. datap should be set to the address of a pointer to an array of int64_t's which, upon successful return, will point to memory containing the integer array value of the property. This routine will not search the PROM for 64-bit property values.
This routine searches for and returns a property that is an array of strings. datap should be set to address of a pointer to an array of strings which, upon successful return, will point to memory containing the array of strings. The array of strings is formatted as an array of pointers to null-terminated strings, much like the argv argument to execve(2).
This routine searches for and returns a property that is a null-terminated string. datap should be set to the address of a pointer to string which, upon successful return, will point to memory containing the string value of the property.
This routine searches for and returns a property that is an array of bytes. datap should be set to the address of a pointer to an array of bytes which, upon successful return, will point to memory containing the byte array value of the property.
Frees the resources associated with a property previously allocated using ddi_prop_lookup_int_array(), ddi_prop_lookup_int64_array(), ddi_prop_lookup_string_array(), ddi_prop_lookup_string(), or ddi_prop_lookup_byte_array().
The functions ddi_prop_lookup_int_array(), ddi_prop_lookup_int64_array(), ddi_prop_lookup_string_array(), ddi_prop_lookup_string(), and ddi_prop_lookup_byte_array() return the following values: DDI_PROP_SUCCESS
Upon success.
If an attempt is made to look up a property with match_dev equal to DDI_DEV_T_NONE, name is NULL or name is the null string.
Property not found.
Property explicitly not defined (see ddi_prop_undefine(9F)).
The value of the property cannot be decoded.
These functions can be called from user or kernel context.
Example 1 Using ddi_prop_lookup_int_array()
The following example demonstrates the use of ddi_prop_lookup_int_array().
int *options;
int noptions;
/*
* Get the data associated with the integer "options" property
* array, along with the number of option integers
*/
if (ddi_prop_lookup_int_array(DDI_DEV_T_ANY, xx_dip, 0,
"options", &options, &noptions) == DDI_PROP_SUCCESS) {
/*
* Do "our thing" with the options data from the property
*/
xx_process_options(options, noptions);
/*
* Free the memory allocated for the property data
*/
ddi_prop_free(options);
}
execve(2), ddi_prop_exists(9F), ddi_prop_get_int(9F), ddi_prop_remove(9F), ddi_prop_undefine(9F), ddi_prop_update(9F)
Writing Device Drivers