diff options
author | Jonathan Herman <hermanjl@cs.unc.edu> | 2013-01-17 16:15:55 -0500 |
---|---|---|
committer | Jonathan Herman <hermanjl@cs.unc.edu> | 2013-01-17 16:15:55 -0500 |
commit | 8dea78da5cee153b8af9c07a2745f6c55057fe12 (patch) | |
tree | a8f4d49d63b1ecc92f2fddceba0655b2472c5bd9 /Documentation/acpi | |
parent | 406089d01562f1e2bf9f089fd7637009ebaad589 (diff) |
Patched in Tegra support.
Diffstat (limited to 'Documentation/acpi')
-rw-r--r-- | Documentation/acpi/apei/einj.txt | 63 | ||||
-rw-r--r-- | Documentation/acpi/enumeration.txt | 227 | ||||
-rw-r--r-- | Documentation/acpi/initrd_table_override.txt | 94 |
3 files changed, 11 insertions, 373 deletions
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt index e20b6daaced..5cc699ba545 100644 --- a/Documentation/acpi/apei/einj.txt +++ b/Documentation/acpi/apei/einj.txt | |||
@@ -47,61 +47,20 @@ directory apei/einj. The following files are provided. | |||
47 | 47 | ||
48 | - param1 | 48 | - param1 |
49 | This file is used to set the first error parameter value. Effect of | 49 | This file is used to set the first error parameter value. Effect of |
50 | parameter depends on error_type specified. | 50 | parameter depends on error_type specified. For memory error, this is |
51 | physical memory address. Only available if param_extension module | ||
52 | parameter is specified. | ||
51 | 53 | ||
52 | - param2 | 54 | - param2 |
53 | This file is used to set the second error parameter value. Effect of | 55 | This file is used to set the second error parameter value. Effect of |
54 | parameter depends on error_type specified. | 56 | parameter depends on error_type specified. For memory error, this is |
55 | 57 | physical memory address mask. Only available if param_extension | |
56 | - notrigger | 58 | module parameter is specified. |
57 | The EINJ mechanism is a two step process. First inject the error, then | ||
58 | perform some actions to trigger it. Setting "notrigger" to 1 skips the | ||
59 | trigger phase, which *may* allow the user to cause the error in some other | ||
60 | context by a simple access to the cpu, memory location, or device that is | ||
61 | the target of the error injection. Whether this actually works depends | ||
62 | on what operations the BIOS actually includes in the trigger phase. | ||
63 | |||
64 | BIOS versions based in the ACPI 4.0 specification have limited options | ||
65 | to control where the errors are injected. Your BIOS may support an | ||
66 | extension (enabled with the param_extension=1 module parameter, or | ||
67 | boot command line einj.param_extension=1). This allows the address | ||
68 | and mask for memory injections to be specified by the param1 and | ||
69 | param2 files in apei/einj. | ||
70 | |||
71 | BIOS versions using the ACPI 5.0 specification have more control over | ||
72 | the target of the injection. For processor related errors (type 0x1, | ||
73 | 0x2 and 0x4) the APICID of the target should be provided using the | ||
74 | param1 file in apei/einj. For memory errors (type 0x8, 0x10 and 0x20) | ||
75 | the address is set using param1 with a mask in param2 (0x0 is equivalent | ||
76 | to all ones). For PCI express errors (type 0x40, 0x80 and 0x100) the | ||
77 | segment, bus, device and function are specified using param1: | ||
78 | |||
79 | 31 24 23 16 15 11 10 8 7 0 | ||
80 | +-------------------------------------------------+ | ||
81 | | segment | bus | device | function | reserved | | ||
82 | +-------------------------------------------------+ | ||
83 | |||
84 | An ACPI 5.0 BIOS may also allow vendor specific errors to be injected. | ||
85 | In this case a file named vendor will contain identifying information | ||
86 | from the BIOS that hopefully will allow an application wishing to use | ||
87 | the vendor specific extension to tell that they are running on a BIOS | ||
88 | that supports it. All vendor extensions have the 0x80000000 bit set in | ||
89 | error_type. A file vendor_flags controls the interpretation of param1 | ||
90 | and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor | ||
91 | documentation for details (and expect changes to this API if vendors | ||
92 | creativity in using this feature expands beyond our expectations). | ||
93 | |||
94 | Example: | ||
95 | # cd /sys/kernel/debug/apei/einj | ||
96 | # cat available_error_type # See which errors can be injected | ||
97 | 0x00000002 Processor Uncorrectable non-fatal | ||
98 | 0x00000008 Memory Correctable | ||
99 | 0x00000010 Memory Uncorrectable non-fatal | ||
100 | # echo 0x12345000 > param1 # Set memory address for injection | ||
101 | # echo 0xfffffffffffff000 > param2 # Mask - anywhere in this page | ||
102 | # echo 0x8 > error_type # Choose correctable memory error | ||
103 | # echo 1 > error_inject # Inject now | ||
104 | 59 | ||
60 | Injecting parameter support is a BIOS version specific extension, that | ||
61 | is, it only works on some BIOS version. If you want to use it, please | ||
62 | make sure your BIOS version has the proper support and specify | ||
63 | "param_extension=y" in module parameter. | ||
105 | 64 | ||
106 | For more information about EINJ, please refer to ACPI specification | 65 | For more information about EINJ, please refer to ACPI specification |
107 | version 4.0, section 17.5 and ACPI 5.0, section 18.6. | 66 | version 4.0, section 17.5. |
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt deleted file mode 100644 index 54469bc81b1..00000000000 --- a/Documentation/acpi/enumeration.txt +++ /dev/null | |||
@@ -1,227 +0,0 @@ | |||
1 | ACPI based device enumeration | ||
2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
3 | ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus, | ||
4 | SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave | ||
5 | devices behind serial bus controllers. | ||
6 | |||
7 | In addition we are starting to see peripherals integrated in the | ||
8 | SoC/Chipset to appear only in ACPI namespace. These are typically devices | ||
9 | that are accessed through memory-mapped registers. | ||
10 | |||
11 | In order to support this and re-use the existing drivers as much as | ||
12 | possible we decided to do following: | ||
13 | |||
14 | o Devices that have no bus connector resource are represented as | ||
15 | platform devices. | ||
16 | |||
17 | o Devices behind real busses where there is a connector resource | ||
18 | are represented as struct spi_device or struct i2c_device | ||
19 | (standard UARTs are not busses so there is no struct uart_device). | ||
20 | |||
21 | As both ACPI and Device Tree represent a tree of devices (and their | ||
22 | resources) this implementation follows the Device Tree way as much as | ||
23 | possible. | ||
24 | |||
25 | The ACPI implementation enumerates devices behind busses (platform, SPI and | ||
26 | I2C), creates the physical devices and binds them to their ACPI handle in | ||
27 | the ACPI namespace. | ||
28 | |||
29 | This means that when ACPI_HANDLE(dev) returns non-NULL the device was | ||
30 | enumerated from ACPI namespace. This handle can be used to extract other | ||
31 | device-specific configuration. There is an example of this below. | ||
32 | |||
33 | Platform bus support | ||
34 | ~~~~~~~~~~~~~~~~~~~~ | ||
35 | Since we are using platform devices to represent devices that are not | ||
36 | connected to any physical bus we only need to implement a platform driver | ||
37 | for the device and add supported ACPI IDs. If this same IP-block is used on | ||
38 | some other non-ACPI platform, the driver might work out of the box or needs | ||
39 | some minor changes. | ||
40 | |||
41 | Adding ACPI support for an existing driver should be pretty | ||
42 | straightforward. Here is the simplest example: | ||
43 | |||
44 | #ifdef CONFIG_ACPI | ||
45 | static struct acpi_device_id mydrv_acpi_match[] = { | ||
46 | /* ACPI IDs here */ | ||
47 | { } | ||
48 | }; | ||
49 | MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); | ||
50 | #endif | ||
51 | |||
52 | static struct platform_driver my_driver = { | ||
53 | ... | ||
54 | .driver = { | ||
55 | .acpi_match_table = ACPI_PTR(mydrv_acpi_match), | ||
56 | }, | ||
57 | }; | ||
58 | |||
59 | If the driver needs to perform more complex initialization like getting and | ||
60 | configuring GPIOs it can get its ACPI handle and extract this information | ||
61 | from ACPI tables. | ||
62 | |||
63 | Currently the kernel is not able to automatically determine from which ACPI | ||
64 | device it should make the corresponding platform device so we need to add | ||
65 | the ACPI device explicitly to acpi_platform_device_ids list defined in | ||
66 | drivers/acpi/scan.c. This limitation is only for the platform devices, SPI | ||
67 | and I2C devices are created automatically as described below. | ||
68 | |||
69 | SPI serial bus support | ||
70 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
71 | Slave devices behind SPI bus have SpiSerialBus resource attached to them. | ||
72 | This is extracted automatically by the SPI core and the slave devices are | ||
73 | enumerated once spi_register_master() is called by the bus driver. | ||
74 | |||
75 | Here is what the ACPI namespace for a SPI slave might look like: | ||
76 | |||
77 | Device (EEP0) | ||
78 | { | ||
79 | Name (_ADR, 1) | ||
80 | Name (_CID, Package() { | ||
81 | "ATML0025", | ||
82 | "AT25", | ||
83 | }) | ||
84 | ... | ||
85 | Method (_CRS, 0, NotSerialized) | ||
86 | { | ||
87 | SPISerialBus(1, PolarityLow, FourWireMode, 8, | ||
88 | ControllerInitiated, 1000000, ClockPolarityLow, | ||
89 | ClockPhaseFirst, "\\_SB.PCI0.SPI1",) | ||
90 | } | ||
91 | ... | ||
92 | |||
93 | The SPI device drivers only need to add ACPI IDs in a similar way than with | ||
94 | the platform device drivers. Below is an example where we add ACPI support | ||
95 | to at25 SPI eeprom driver (this is meant for the above ACPI snippet): | ||
96 | |||
97 | #ifdef CONFIG_ACPI | ||
98 | static struct acpi_device_id at25_acpi_match[] = { | ||
99 | { "AT25", 0 }, | ||
100 | { }, | ||
101 | }; | ||
102 | MODULE_DEVICE_TABLE(acpi, at25_acpi_match); | ||
103 | #endif | ||
104 | |||
105 | static struct spi_driver at25_driver = { | ||
106 | .driver = { | ||
107 | ... | ||
108 | .acpi_match_table = ACPI_PTR(at25_acpi_match), | ||
109 | }, | ||
110 | }; | ||
111 | |||
112 | Note that this driver actually needs more information like page size of the | ||
113 | eeprom etc. but at the time writing this there is no standard way of | ||
114 | passing those. One idea is to return this in _DSM method like: | ||
115 | |||
116 | Device (EEP0) | ||
117 | { | ||
118 | ... | ||
119 | Method (_DSM, 4, NotSerialized) | ||
120 | { | ||
121 | Store (Package (6) | ||
122 | { | ||
123 | "byte-len", 1024, | ||
124 | "addr-mode", 2, | ||
125 | "page-size, 32 | ||
126 | }, Local0) | ||
127 | |||
128 | // Check UUIDs etc. | ||
129 | |||
130 | Return (Local0) | ||
131 | } | ||
132 | |||
133 | Then the at25 SPI driver can get this configation by calling _DSM on its | ||
134 | ACPI handle like: | ||
135 | |||
136 | struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; | ||
137 | struct acpi_object_list input; | ||
138 | acpi_status status; | ||
139 | |||
140 | /* Fill in the input buffer */ | ||
141 | |||
142 | status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", | ||
143 | &input, &output); | ||
144 | if (ACPI_FAILURE(status)) | ||
145 | /* Handle the error */ | ||
146 | |||
147 | /* Extract the data here */ | ||
148 | |||
149 | kfree(output.pointer); | ||
150 | |||
151 | I2C serial bus support | ||
152 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
153 | The slaves behind I2C bus controller only need to add the ACPI IDs like | ||
154 | with the platform and SPI drivers. However the I2C bus controller driver | ||
155 | needs to call acpi_i2c_register_devices() after it has added the adapter. | ||
156 | |||
157 | An I2C bus (controller) driver does: | ||
158 | |||
159 | ... | ||
160 | ret = i2c_add_numbered_adapter(adapter); | ||
161 | if (ret) | ||
162 | /* handle error */ | ||
163 | |||
164 | of_i2c_register_devices(adapter); | ||
165 | /* Enumerate the slave devices behind this bus via ACPI */ | ||
166 | acpi_i2c_register_devices(adapter); | ||
167 | |||
168 | Below is an example of how to add ACPI support to the existing mpu3050 | ||
169 | input driver: | ||
170 | |||
171 | #ifdef CONFIG_ACPI | ||
172 | static struct acpi_device_id mpu3050_acpi_match[] = { | ||
173 | { "MPU3050", 0 }, | ||
174 | { }, | ||
175 | }; | ||
176 | MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); | ||
177 | #endif | ||
178 | |||
179 | static struct i2c_driver mpu3050_i2c_driver = { | ||
180 | .driver = { | ||
181 | .name = "mpu3050", | ||
182 | .owner = THIS_MODULE, | ||
183 | .pm = &mpu3050_pm, | ||
184 | .of_match_table = mpu3050_of_match, | ||
185 | .acpi_match_table ACPI_PTR(mpu3050_acpi_match), | ||
186 | }, | ||
187 | .probe = mpu3050_probe, | ||
188 | .remove = mpu3050_remove, | ||
189 | .id_table = mpu3050_ids, | ||
190 | }; | ||
191 | |||
192 | GPIO support | ||
193 | ~~~~~~~~~~~~ | ||
194 | ACPI 5 introduced two new resources to describe GPIO connections: GpioIo | ||
195 | and GpioInt. These resources are used be used to pass GPIO numbers used by | ||
196 | the device to the driver. For example: | ||
197 | |||
198 | Method (_CRS, 0, NotSerialized) | ||
199 | { | ||
200 | Name (SBUF, ResourceTemplate() | ||
201 | { | ||
202 | GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, | ||
203 | IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", | ||
204 | 0x00, ResourceConsumer,,) | ||
205 | { | ||
206 | // Pin List | ||
207 | 0x0055 | ||
208 | } | ||
209 | ... | ||
210 | |||
211 | Return (SBUF) | ||
212 | } | ||
213 | } | ||
214 | |||
215 | These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" | ||
216 | specifies the path to the controller. In order to use these GPIOs in Linux | ||
217 | we need to translate them to the Linux GPIO numbers. | ||
218 | |||
219 | The driver can do this by including <linux/acpi_gpio.h> and then calling | ||
220 | acpi_get_gpio(path, gpio). This will return the Linux GPIO number or | ||
221 | negative errno if there was no translation found. | ||
222 | |||
223 | Other GpioIo parameters must be converted first by the driver to be | ||
224 | suitable to the gpiolib before passing them. | ||
225 | |||
226 | In case of GpioInt resource an additional call to gpio_to_irq() must be | ||
227 | done before calling request_irq(). | ||
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt deleted file mode 100644 index 35c3f541547..00000000000 --- a/Documentation/acpi/initrd_table_override.txt +++ /dev/null | |||
@@ -1,94 +0,0 @@ | |||
1 | Overriding ACPI tables via initrd | ||
2 | ================================= | ||
3 | |||
4 | 1) Introduction (What is this about) | ||
5 | 2) What is this for | ||
6 | 3) How does it work | ||
7 | 4) References (Where to retrieve userspace tools) | ||
8 | |||
9 | 1) What is this about | ||
10 | --------------------- | ||
11 | |||
12 | If the ACPI_INITRD_TABLE_OVERRIDE compile option is true, it is possible to | ||
13 | override nearly any ACPI table provided by the BIOS with an instrumented, | ||
14 | modified one. | ||
15 | |||
16 | For a full list of ACPI tables that can be overridden, take a look at | ||
17 | the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/osl.c | ||
18 | All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should | ||
19 | be overridable, except: | ||
20 | - ACPI_SIG_RSDP (has a signature of 6 bytes) | ||
21 | - ACPI_SIG_FACS (does not have an ordinary ACPI table header) | ||
22 | Both could get implemented as well. | ||
23 | |||
24 | |||
25 | 2) What is this for | ||
26 | ------------------- | ||
27 | |||
28 | Please keep in mind that this is a debug option. | ||
29 | ACPI tables should not get overridden for productive use. | ||
30 | If BIOS ACPI tables are overridden the kernel will get tainted with the | ||
31 | TAINT_OVERRIDDEN_ACPI_TABLE flag. | ||
32 | Complain to your platform/BIOS vendor if you find a bug which is so sever | ||
33 | that a workaround is not accepted in the Linux kernel. | ||
34 | |||
35 | Still, it can and should be enabled in any kernel, because: | ||
36 | - There is no functional change with not instrumented initrds | ||
37 | - It provides a powerful feature to easily debug and test ACPI BIOS table | ||
38 | compatibility with the Linux kernel. | ||
39 | |||
40 | |||
41 | 3) How does it work | ||
42 | ------------------- | ||
43 | |||
44 | # Extract the machine's ACPI tables: | ||
45 | cd /tmp | ||
46 | acpidump >acpidump | ||
47 | acpixtract -a acpidump | ||
48 | # Disassemble, modify and recompile them: | ||
49 | iasl -d *.dat | ||
50 | # For example add this statement into a _PRT (PCI Routing Table) function | ||
51 | # of the DSDT: | ||
52 | Store("HELLO WORLD", debug) | ||
53 | iasl -sa dsdt.dsl | ||
54 | # Add the raw ACPI tables to an uncompressed cpio archive. | ||
55 | # They must be put into a /kernel/firmware/acpi directory inside the | ||
56 | # cpio archive. | ||
57 | # The uncompressed cpio archive must be the first. | ||
58 | # Other, typically compressed cpio archives, must be | ||
59 | # concatenated on top of the uncompressed one. | ||
60 | mkdir -p kernel/firmware/acpi | ||
61 | cp dsdt.aml kernel/firmware/acpi | ||
62 | # A maximum of: #define ACPI_OVERRIDE_TABLES 10 | ||
63 | # tables are currently allowed (see osl.c): | ||
64 | iasl -sa facp.dsl | ||
65 | iasl -sa ssdt1.dsl | ||
66 | cp facp.aml kernel/firmware/acpi | ||
67 | cp ssdt1.aml kernel/firmware/acpi | ||
68 | # Create the uncompressed cpio archive and concatenate the original initrd | ||
69 | # on top: | ||
70 | find kernel | cpio -H newc --create > /boot/instrumented_initrd | ||
71 | cat /boot/initrd >>/boot/instrumented_initrd | ||
72 | # reboot with increased acpi debug level, e.g. boot params: | ||
73 | acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF | ||
74 | # and check your syslog: | ||
75 | [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT] | ||
76 | [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD" | ||
77 | |||
78 | iasl is able to disassemble and recompile quite a lot different, | ||
79 | also static ACPI tables. | ||
80 | |||
81 | |||
82 | 4) Where to retrieve userspace tools | ||
83 | ------------------------------------ | ||
84 | |||
85 | iasl and acpixtract are part of Intel's ACPICA project: | ||
86 | http://acpica.org/ | ||
87 | and should be packaged by distributions (for example in the acpica package | ||
88 | on SUSE). | ||
89 | |||
90 | acpidump can be found in Len Browns pmtools: | ||
91 | ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump | ||
92 | This tool is also part of the acpica package on SUSE. | ||
93 | Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels: | ||
94 | /sys/firmware/acpi/tables | ||