This article talks about the of functions used for extracting property values.
For related subjects, please refer to the SOC Table of Contents.
The properties of device tree nodes store the information required by drivers, thus extraction is extremely important. The Linux kernel uses the property structure to represent its properties; the structure is defined in include/linux/of.h, with the following content on lines 35 to 43:
struct property{
char *name; // Property name
int length; // Property length
void *value; // Property value
struct property *next; // Next property
unsigned long _flags;
unsigned int unique_id;
struct bin_attribute attr;
};
The Linux kernel provides 8 of functions used for extracting property values.
of_find_property
This function is used to search for the specified property, and has the following formatting:
struct property *of_find_property(const struct device_node *np, const char *name, int *lenp);
np is the device node.
name is the name of the property.
lenp is the number of bytes of the property value.
The function will return the found property.
of_property_count_elems_of_size
This function is used to obtain the number of elements in a property. For example, the reg property has an array value, the function can be used to find out the size of the array. The formatting is as follows:
int of_property_count_elems_of_size(const struct device_node *np, const char *propname, int elem_size);
np is the device node.
proname is the name of the property to have its elements counted.
elem_size is the length of the element.
The function will return the number of elements in found in the property.
of_property_read_u32_index
This function is used to obtain values under specified index from properties that have the unsigned 32-bit data type. Property values are arrays composed of unsigned 32-bit data. If a property has many unsigned 32-bit data values, we can use this function to obtain the index data values. Formatting is as follows:
int of_property_read_u32_index(const struct device_node *np, const char *propname, u32 index, u32 *out_value);
np is the device node.
proname is the name of the property to be read.
index is the index of the value to be read.
out-value is the value read.
The function will return 0 if the read was successful, 1 if the read was unsuccessful, -EINVAL if the property doesn’t exist, -ENODATA if there isn’t readable data, and -EOVERFLOW if property value list is too small.
of_property_read_string
This function is mainly used to read string values from properties, using the following format:
int of_property_read_string(struct device_node *np, const char *propname, const char **out_string);
np is the device node.
proname is the name of the property to be read.
out-string is the array value read.
The function will return 0 if the read was successful and will return a negative value of it wasn’t.
of_property_read_u8_array
of_property_read_u16_array
of_property_read_u32_array
of_property_read_u64_array
These 4 functions read property values from unsigned 8-bit, unsigned 16-bit, unsigned 32-bit, and unsigned 64-bit type arrays respectively. Most reg properties have array data, thus we can use these 4 functions to read all the data from the reg property all at once. They have the following format:
int of_property_read_u8_array(const struct device_node *np, const char *propname, u8 *out_values, size_t sz); int of_property_read_u16_array(const struct device_node *np, const char *propname, u16 *out_values, size_t sz); int of_property_read_u32_array(const struct device_node *np, const char *propname, u32 *out_values, size_t sz); int of_property_read_u64_array(const struct device_node *np, const char *propname, u64 *out_values, size_t sz);
np is the device node.
proname is the name of the property to be read.
out-value is the array value read, being u8, u16, u32, and u64 respectively.
sz is the number of elements in the array to be read.
The function will return 0 if the read was successful, a negative value if it wasn’t, -EINVAL if the property doesn’t exist, -ENODATA if there isn’t data to be read, and -EOVERFLOW if property value list is too small.
of_property_read_u8
of_property_read_u16
of_property_read_u32
of_property_read_u64
These 4 functions are used specifically to read properties with only one integer value, for u8, u16, u32, and u64 type properties respectively. The formatting is as follows:
int of_property_read_u8(const struct device_node *np, const char *propname, u8 *out_value, int of_property_read_u16(const struct device_node *np, const char *propname, u16 *out_value, int of_property_read_u32(const struct device_node *np, const char *propname, u32 *out_value, int of_property_read_u64(const struct device_node *np, const char *propname, u64 *out_value);
np is the device node.
proname is the name of the property to be read.
out-value is the array value read, being u8, u16, u32, and u64 respectively.
sz is the number of elements in the array to be read.
The function will return 0 if the read was successful, a negative value if it wasn’t, -EINVAL if the property doesn’t exist, -ENODATA if there isn’t data to be read, and -EOVERFLOW if property value list is too small.
of_n_addr_cells
This function is mainly used to obtain the #address-cells property value, using the following format:
int of_n_addr_cells(struct device_node *np);
np is the device node.
The function will return the obtained #address-cells property value.
of_n_size_cells
This function is mainly used to obtain the #size-cells property value, using the following format:
int of_n_size_cells(struct device_node *np);
np is the device node.
The function will return the obtained #size-cells property value.
