diff options
author | Mika Westerberg <mika.westerberg@linux.intel.com> | 2013-10-17 18:14:00 +0300 |
---|---|---|
committer | Graeme Gregory <graeme.gregory@linaro.org> | 2014-06-03 09:24:30 +0100 |
commit | 6aae5f0650e8ea11cd55174aadccca65e325236b (patch) | |
tree | f5aaa35414a7d2ef4b2ae738016f1d1130610488 | |
parent | 331f5103b4d3aa39e705dc35e61a9f6582eb7875 (diff) | |
download | leg-kernel-6aae5f0650e8ea11cd55174aadccca65e325236b.tar.gz |
ACPI: Document ACPI device specific properties
This document describes the data format and interfaces of ACPI device
specific properties.
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
-rw-r--r-- | Documentation/acpi/properties.txt | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/Documentation/acpi/properties.txt b/Documentation/acpi/properties.txt new file mode 100644 index 000000000000..987486067109 --- /dev/null +++ b/Documentation/acpi/properties.txt @@ -0,0 +1,224 @@ +ACPI device properties +====================== +This document describes the format and interfaces of Device Tree style +properties attached to ACPI devices. + +1. Introduction +--------------- +In systems that use ACPI and want to take advantage of device specific +properties, there needs to be a standard way to return and extract +name-value pairs for a given ACPI device. + +An ACPI device that wants to export its properties must implement a +method called _PRP that doesn't take arguments and returns a package of +packages: + + Method (_PRP, 0, NotSerialized) + { + Return (Package () { + Package () { "name1", <VALUE1> }, + Package () { "name2", <VALUE2> }, + ... + }) + } + +In each returned package, the first item must be string and it is called +name. Type of value can be anything and depends on name. + +An example device where we might need properties is a GPIO keys device. +In addition to the GpioIo/GpioInt resources the driver needs to know how +to map each GpioIo resource to the corresponding Linux input event. + +To solve this we add following Device Tree properties to the ACPI device +representing the GPIO keys device: + + Method (_PRP, 0, NotSerialized) + { + Return (Package () { + Package() { "poll-interval", 100 }, + Package() { "autorepeat" }, + Package() { "linux,code", Package () { 105, 108, 103, 106 } }, + Package() { "linux,input-type", Package () { 1, 1, 1, 1 } }, + }) + } + +2. Formal definition of properties +---------------------------------- +Following chapters define currently supported properties. For these there +exists an ACPI helper function that can be used to extract the property +value in suitable format. + +2.1 Integer types +----------------- +In ACPI integer is always 64-bit. However, for drivers the full range is +typically not needed thus we provide a set of functions which convert the +returned 64-bit integer to a smaller Linux integer type. + +An integer property looks like this: + + Package () { "poll-interval", 100 }, + Package () { "i2c-sda-hold-time-ns", 300 }, + Package () { "clock-frequency", 400000 }, + +The following helper functions can be used to extract integer properties: + + int acpi_dev_get_property_u64(struct acpi_device *adev, + const char *name, u64 *value); + int acpi_dev_get_property_u32(struct acpi_device *adev, + const char *name, u32 *value); + int acpi_dev_get_property_u16(struct acpi_device *adev, + const char *name, u16 *value); + int acpi_dev_get_property_u8(struct acpi_device *adev, + const char *name, u8 *value); + +Each function takes the ACPI device pointer and property name. If an +integer property with given name is found, it is cast to the desired Linux +integer type and returned in value parameter. Functions return 0 if the +property is found and is of correct type. Otherwise return value is +negative errno. + +2.2 Integer arrays +------------------ +An integer array is a package holding only integers. Arrays can be used to +represent different things like Linux input key codes to GPIO mappings, pin +control settings, dma request lines etc. + +An integer array looks like this: + + Package () { "data_width", Package () { 3, 3, 0, 0 } }, + Package () { + "max8952,dvs-mode-microvolt", + Package () { + 1250000, + 1200000, + 1050000, + 950000, + } + } + +Note that an ACPI buffer is also u8 array and that is supported by +acpi_dev_get_property_array_u8(). Buffer looks like this: + + Package () { "init-seq", Buffer () { 0xff, 0xfe, 0xfd, 0xa } }, + +Thee helper functions that can be used to extract integer array properties +are listed below: + + int acpi_dev_get_property_array_u64(struct acpi_device *adev, + const char *name, u64 *values, + size_t nvalues); + int acpi_dev_get_property_array_u32(struct acpi_device *adev, + const char *name, u32 *values, + size_t nvalues); + int acpi_dev_get_property_array_u16(struct acpi_device *adev, + const char *name, u16 *values, + size_t nvalues); + int acpi_dev_get_property_array_u8(struct acpi_device *adev, + const char *name, u8 *values, + size_t nvalues); + +All functions copy the resulting values cast to a requested type to the +caller supplied array. Functions return size of the actual array. This can +be useful if caller doesn't know size of the array beforehand. + +2.3 Strings +----------- +String properties can be used to describe many things like labels for GPIO +buttons, compability ids etc. + +A string property looks like this: + + Package () { "linux,default-trigger", "backlight" }, + Package () { "label", "Status-LED" }, + +One helper function is provided that can be used to extract strings: + + int acpi_dev_get_property_string(struct acpi_device *adev, + const char *name, const char **value); + +Note that the function doesn't copy the returned string but instead the +value is modified to point to the string property itself. The memory is +owned by the associated ACPI device object and released when it is removed. + +2.4 String arrays +----------------- +String arrays can be useful in describing list of labels, names for DMA +channels etc. + +A string array property looks like this: + + Package () { "dma-names", Package () { "tx", "rx", "rx-tx" } }, + Package () { "clock-output-names", Package () { "pll", "pll-switched" } }, + +The following function can be used to extract string arrays: + + int acpi_dev_get_property_array_string(struct acpi_device *adev, + const char *name, + const char **values, + size_t nvalues); + +Note that same memory management rules apply here than with +acpi_dev_get_property_string(). + +2.5 Object references +--------------------- +An ACPI object reference is used to refer some object in the namespace. For +example if this device has dependencies with some other object, an object +reference can be used. + +An object reference looks like this: + + Package () { "gpio-controller", \_SB.PCI0.GPI0 }, + +Object references can be extracted with the following helper function: + + int acpi_dev_get_property_reference(struct acpi_device *adev, + const char *name, + acpi_handle *obj_handle); + +The referenced ACPI object handle is passed in obj_handle parameter if the +property is found. + +2.6 Raw properties +------------------ +In some cases there is no helper function provided that could be used to +translate the returned property value to a suitable Linux data type. Here +using raw properties come handy. + +Let's take for example the following property: + + Package () { + "linux,keys", + Package () { + { 105, 1, "minnow_btn0" }, + { 108, 1, "minnow_btn1" }, + { 103, 1, "minnow_btn2" }, + { 106, 1, "minnow_btn3" }, + } + }, + +Since there is no helper funtion that could understand the above, we use +acpi_dev_get_property() interface, which returns the raw ACPI object. We +then process this returned object to extract our data: + + const union acpi_object *obj; + int ret; + + ret = acpi_dev_get_property(adev, "linux,keys", ACPI_TYPE_PACKAGE, + &obj); + if (!ret) { + const union acpi_object *value; + + /* + * Now go through each entry in the package and extract the + * three values in a tuple. + */ + for (i = 0; i < obj->package.count; i++) { + value = &obj->package.elements[i]; + + if (value->type != ACPI_TYPE_PACKAGE) + return -EINVAL; + + ... + } + } |