From: hanjun.guo@linaro.org (Hanjun Guo)
To: linux-arm-kernel@lists.infradead.org
Subject: [PATCH 19/19] Documentation: ACPI for ARM64
Date: Fri, 25 Jul 2014 18:55:07 +0800 [thread overview]
Message-ID: <53D2378B.20109@linaro.org> (raw)
In-Reply-To: <53D16F98.9080107@infradead.org>
Hi Randy,
Thank you for your careful review comments, I will update it in next version :)
Best Regards
Hanjun
On 2014-7-25 4:42, Randy Dunlap wrote:
> On 07/24/2014 06:00 AM, Hanjun Guo wrote:
>> From: Graeme Gregory <graeme.gregory@linaro.org>
>>
>> Add documentation for the guidelines of how to use ACPI
>> on ARM64.
>>
>> Signed-off-by: Graeme Gregory <graeme.gregory@linaro.org>
>> Signed-off-by: Hanjun Guo <hanjun.guo@linaro.org>
>> ---
>> Documentation/arm64/arm-acpi.txt | 240 ++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 240 insertions(+)
>> create mode 100644 Documentation/arm64/arm-acpi.txt
>>
>> diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.txt
>> new file mode 100644
>> index 0000000..12cd550
>> --- /dev/null
>> +++ b/Documentation/arm64/arm-acpi.txt
>> @@ -0,0 +1,240 @@
>> +ACPI on ARMv8 Servers
>> +---------------------
>> +
>> +ACPI will be used for ARMv8 general purpose servers designed to follow
>> +the SBSA specification (currently available to people with an ARM login at
>> +http://silver.arm.com)
>
> .com).
>
>> +
>> +The implemented ACPI version is 5.1 + errata as released by the UEFI Forum,
>> +which is available at <http://www.uefi.org/acpi/specs>.
>> +
>> +If the machine does not meet these requirements then it is likely that Device
>> +Tree (DT) is more suitable for the hardware.
>> +
>> +Relationship with Device Tree
>> +-----------------------------
>> +
>> +ACPI support in drivers and subsystems for ARMv8 should never be mutually
>> +exclusive with DT support at compile time.
>> +
>> +At boot time the kernel will only use one description method depending on
>> +parameters passed from the bootloader.
>> +
>> +Regardless of whether DT or ACPI is used, the kernel must always be capable
>> +of booting with either scheme.
>> +
>> +When booting using ACPI tables the /chosen node in DT will still be parsed
>> +to extract the kernel command line and initrd path. No other section of
>> +the DT will be used.
>> +
>> +Booting using ACPI tables
>> +-------------------------
>> +
>> +Currently, the only defined method to pass ACPI tables to the kernel on ARMv8
>> +is via the UEFI system configuration table.
>> +
>> +The UEFI implementation MUST set the ACPI_20_TABLE_GUID to point to the
>> +RSDP table (the table with the ACPI signature "RSD PTR ").
>> +
>> +The pointer to the RSDP table will be retrieved from EFI by the ACPI core.
>> +
>> +Processing of ACPI tables may be disabled by passing acpi=off on the kernel
>> +command line.
>> +
>> +DO use an XSDT, RSDTs are deprecated and should not be used on arm64. They
>
> XSDT;
>
>> +only allow for 32bit addresses.
>
> 32-bit
>
>> +
>> +DO NOT use the 32-bit address fields in the FADT, they are deprecated, the
>
> FADT; they are deprecated. The
>
>> +64-bit alternatives MUST be used.
>> +
>> +The minimum set of tables MUST include RSDP, XSDT, FACS, FADT, DSDT, MADT
>> +and GTDT. If PCI is used the MCFG table MUST also be present.
>> +
>> +ACPI Detection
>> +--------------
>> +
>> +Drivers should determine their probe() type by checking for ACPI_HANDLE,
>> +or .of_node, or other information in the device structure. This is
>> +detailed further in the "Driver Recomendations" section.
>
> Recommendations
>
>> +
>> +If the presence of ACPI needs to be detected at runtime, then check the value
>> +of acpi_disabled. If CONFIG_ACPI not being set acpi_disabled will always be 1.
>
> If CONFIG_ACPI is not set, acpi_disabled will always be 1.
>
>> +
>> +Device Enumeration
>> +------------------
>> +
>> +Device descriptions in ACPI should use standard recognised ACPI interfaces.
>> +These are far simpler than the information provided via Device Tree. Drivers
>> +should take into account this simplicity and work with sensible defaults.
>> +
>> +On no account should a Device Tree attempt to be replicated in ASL using such
>> +constructs as Name(KEY0, "Value1") type constructs. Additional driver specific
>> +data should be passed in the appropriate _DSM (ACPI Section 9.14.1) method or
>> +_DSD (ACPI Section 6.2.5). This data should be rare and not OS specific.
>> +
>> +Common _DSD bindings should be submitted to ASWG to be included in the
>> +document :-
>> +
>> +http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel.htm
>> +
>> +TODO: Clarification and examples from Juno implementation.
>> +
>> +Programmable Power Control Resources
>> +------------------------------------
>> +
>> +Programmable power control resources include such resources as voltage/current
>> +providers (regulators) and clock sources.
>> +
>> +For power control of these resources they should be represented with Power
>> +Resource Objects (ACPI Section 7.1). The ACPI core will then handle correctly
>> +enabling/disabling of resources as they are needed.
>> +
>> +There exists in the ACPI 5.1 specification no standard binding for these objects
>> +to enable programmable levels or rates so this should be avoid if possible and
>
> avoided
>
>> +the resources set to appropriate level by the firmware. If this is not possible
>
> levels
>
>> +then any manipulation should be abstracted in ASL.
>> +
>> +Each device in ACPI has D-states and these can be controlled through
>> +the optional methods _PS0..._PS3 where _PS0 is full on and _PS3 is full off.
>> +
>> +If either _PS0 or _PS3 is implemented, then the other method must also be
>> +implemented.
>> +
>> +If a device requires usage or setup of a power resource when on, the ASL
>> +should organise that it is allocated/enabled using the _PS0 method.
>> +
>> +Resources allocated/enabled in the _PS0 method should be disabled/de-allocated
>> +in the _PS3 method.
>> +
>> +Such code in _PS? methods will of course be very platform specific but
>> +should allow the driver to operate the device without special non standard
>
> non-standard
>
>> +values being read from ASL. Further, abstracting the use of these resources
>> +allows hardware revisions without requiring updates to the kernel.
>> +
>> +TODO: Clarification and examples from Juno implementation.
>> +
>> +Clocks
>> +------
>> +
>> +Like clocks that are part of the power resources there is no standard way
>> +to represent a clock tree in ACPI 5.1 in a similar manner to how it is
>> +described in DT.
>> +
>> +Devices affected by this include things like UARTs, SoC driven LCD displays,
>> +etc.
>> +
>> +The firmware for example UEFI should initialise these clocks to fixed working
>
> (for example, UEFI)
>
>> +values before the kernel is executed. If a driver requires to know rates of
>> +clocks set by firmware then they can be passed to kernel using _DSD.
>> +
>> +example :-
>> +
>> +Device (CLK0) {
>> + ...
>> +
>> + Name (_DSD, Package() {
>> + ToUUID("XXXXX"),
>> + Package() {
>> + Package(2) {"#clock-cells", 0},
>> + Package(2) {"clock-frequency", "10000"}
>> + }
>> + })
>> +
>> + ...
>> +}
>> +
>> +Device (USR1) {
>> + ...
>> +
>> + Name (_DSD, Package() {
>> + ToUUID("XXXXX"),
>> + Package() {
>> + Package(2) {"clocks", Package() {1, ^CLK0}}},
>> + }
>> + })
>> +
>> + ...
>> +}
>> +
>> +Driver Recommendations
>> +----------------------
>> +
>> +DO NOT remove any FDT handling when adding ACPI support for a driver, different
>
> driver. Different
>
>> +systems may use the same device.
>> +
>> +DO try and keep complex sections of ACPI and DT functionality seperate. This
>
> separate.
>
>> +may mean a patch to break out some complex DT to another function before
>> +the patch to add ACPI. This may happen in other functions but is most likely
>> +in probe function. This gives a clearer flow of data for reviewing driver
>> +source.
>> +
>> +probe() :-
>> +
>> +TODO: replace this with a specific real example from Juno?
>> +
>> +static int device_probe_dt(struct platform_device *pdev)
>> +{
>> + /* DT specific functionality */
>> + ...
>> +}
>> +
>> +static int device_probe_acpi(struct platform_device *pdev)
>> +{
>> + /* ACPI specific functionality */
>> + ...
>> +}
>> +
>> +static int device_probe(stuct platform_device *pdev)
>> +{
>> + ...
>> + acpi_handle handle = ACPI_HANDLE(&pdev->dev);
>> + struct device_node node = pdev->dev.of_node;
>> + ...
>> +
>> + if (node)
>> + ret = device_probe_dt(pdev);
>> + else if (handle)
>> + ret = device_probe_acpi(pdev);
>> + else
>> + /* other initialisation */
>> + ...
>> + /* Continue with any generic probe operations */
>> + ...
>> +}
>> +
>> +DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it clear
>> +the different names the driver is probed for, both from DT and from ACPI.
>> +
>> +module device tables :-
>> +
>> +static struct of_device_id virtio_mmio_match[] = {
>> + { .compatible = "virtio,mmio", },
>> + {},
>> +};
>> +MODULE_DEVICE_TABLE(of, virtio_mmio_match);
>> +
>> +static const struct acpi_device_id virtio_mmio_acpi_match[] = {
>> + { "LNRO0005", },
>> + { }
>> +};
>> +MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
>> +
>> +TODO: Add any other helpful rules that develop from Juno ACPI work.
>> +
>> +ASWG
>> +----
>> +
>> +The following areas are not yet well defined for ARM in the current ACPI
>> +specification and are expected to be worked through in the UEFI ACPI
>> +Specification Working Group (ASWG) <http://www.uefi.org/workinggroups>.
>> +Participation in this group is open to all UEFI members.
>> +
>> + - ACPI based CPU topology
>> + - ACPI based Power management
>> + - CPU idle control based on PSCI
>> + - CPU performance control (CPPC)
>> +
>> +No code shall be accepted into the kernel unless it complies with the released
>> +standards from UEFI ASWG. If there are features missing from ACPI to make it
>> +function on a platform ECRs should be submitted to ASWG and go through the
>
> on a platform, ECRs
>
>> +approval process.
>>
>
>
next prev parent reply other threads:[~2014-07-25 10:55 UTC|newest]
Thread overview: 131+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-07-24 13:00 [PATCH 00/19] Introduce ACPI for ARM64 based on ACPI 5.1 Hanjun Guo
2014-07-24 13:00 ` [PATCH 01/19] ARM64 / ACPI: Get RSDP and ACPI boot-time tables Hanjun Guo
2014-07-28 18:29 ` Sudeep Holla
2014-07-28 22:49 ` Graeme Gregory
2014-07-29 8:49 ` Sudeep Holla
2014-07-29 13:08 ` Hanjun Guo
2014-07-29 13:50 ` Sudeep Holla
2014-07-29 14:07 ` Hanjun Guo
2014-07-28 18:30 ` Sudeep Holla
2014-07-24 13:00 ` [PATCH 02/19] ARM64 / ACPI: Introduce early_param for "acpi" Hanjun Guo
2014-07-28 18:35 ` Sudeep Holla
2014-07-29 13:10 ` Hanjun Guo
2014-07-24 13:00 ` [PATCH 03/19] ARM64 / ACPI: Introduce lowlevel suspend function Hanjun Guo
2014-07-24 15:34 ` Mark Rutland
2014-07-25 10:42 ` Hanjun Guo
2014-07-28 18:28 ` Sudeep Holla
2014-07-29 13:00 ` Hanjun Guo
2014-07-24 13:00 ` [PATCH 04/19] ARM64 / ACPI: Introduce arch_fix_phys_package_id() for cpu topology Hanjun Guo
2014-07-24 14:43 ` Mark Brown
2014-07-25 10:32 ` Hanjun Guo
2014-07-28 18:51 ` Sudeep Holla
2014-08-01 6:35 ` Hanjun Guo
2014-08-01 10:48 ` Sudeep Holla
2014-07-24 13:00 ` [PATCH 05/19] ARM64 / ACPI: Make PCI optional for ACPI on ARM64 Hanjun Guo
2014-07-24 21:57 ` Naresh Bhat
2014-07-29 16:40 ` Sudeep Holla
2014-07-24 13:00 ` [PATCH 06/19] ARM64 / ACPI: Parse FADT table to get PSCI flags for PSCI init Hanjun Guo
2014-07-29 16:40 ` Sudeep Holla
2014-07-31 3:53 ` Hanjun Guo
2014-07-31 4:22 ` Olof Johansson
2014-07-31 10:23 ` Hanjun Guo
2014-08-20 15:02 ` Grant Likely
2014-08-20 15:00 ` Grant Likely
2014-08-20 15:29 ` Catalin Marinas
2014-08-20 15:43 ` graeme.gregory at linaro.org
2014-07-24 13:00 ` [PATCH 07/19] ARM64 / ACPI: Parse MADT to map logical cpu to MPIDR and get cpu_possible/present_map Hanjun Guo
2014-07-24 23:06 ` Naresh Bhat
2014-07-25 11:11 ` Hanjun Guo
2014-07-30 18:20 ` Sudeep Holla
2014-07-31 8:14 ` Hanjun Guo
2014-08-20 15:14 ` Grant Likely
2014-07-24 13:00 ` [PATCH 08/19] ACPI / table: Print GIC information when MADT is parsed Hanjun Guo
2014-07-30 18:21 ` Sudeep Holla
2014-07-31 8:15 ` Hanjun Guo
2014-07-24 13:00 ` [PATCH 09/19] ARM64 / ACPI: Move the initialization of cpu_logical_map(0) before acpi_boot_init() Hanjun Guo
2014-07-24 15:21 ` Mark Rutland
2014-07-25 10:39 ` Hanjun Guo
2014-07-25 12:18 ` Mark Rutland
2014-07-24 13:00 ` [PATCH 10/19] ARM64 / ACPI: Get the enable method for SMP initialization in ACPI way Hanjun Guo
2014-07-24 15:47 ` Mark Rutland
2014-07-25 10:51 ` Hanjun Guo
2014-07-25 12:24 ` Mark Rutland
2014-07-29 8:12 ` Hanjun Guo
2014-07-31 6:54 ` Olof Johansson
2014-07-31 10:57 ` Hanjun Guo
2014-08-04 9:56 ` Hanjun Guo
2014-07-31 18:52 ` Geoff Levand
2014-08-01 6:49 ` Hanjun Guo
2014-07-24 13:00 ` [PATCH 11/19] ACPI / processor: Make it possible to get CPU hardware ID via GICC Hanjun Guo
2014-07-24 13:00 ` [PATCH 12/19] ARM64 / ACPI: Introduce ACPI_IRQ_MODEL_GIC and register device's gsi Hanjun Guo
2014-07-24 13:00 ` [PATCH 13/19] ACPI / table: Add new function to get table entries Hanjun Guo
2014-07-24 13:00 ` [PATCH 14/19] ARM64 / ACPI: Add GICv2 specific ACPI boot support Hanjun Guo
2014-07-24 13:00 ` [PATCH 15/19] ARM64 / ACPI: Parse GTDT to initialize arch timer Hanjun Guo
2014-07-24 13:00 ` [PATCH 16/19] ARM64 / ACPI: Select ACPI_REDUCED_HARDWARE_ONLY if ACPI is enabled on ARM64 Hanjun Guo
2014-07-24 13:00 ` [PATCH 17/19] ARM64 / ACPI: If we chose to boot from acpi then disable FDT Hanjun Guo
2014-07-24 13:00 ` [PATCH 18/19] ARM64 / ACPI: Enable ARM64 in Kconfig Hanjun Guo
2014-07-24 13:00 ` [PATCH 19/19] Documentation: ACPI for ARM64 Hanjun Guo
2014-07-24 20:42 ` Randy Dunlap
2014-07-25 10:55 ` Hanjun Guo [this message]
[not found] ` <CAFoFrHaWWxRPRYM5+bWj0tGnz05SokqwVGejUCUi+U-KChFBdQ@mail.gmail.com>
2014-07-24 21:19 ` Randy Dunlap
2014-07-29 10:07 ` Christoffer Dall
2014-07-27 2:34 ` Olof Johansson
2014-07-28 8:42 ` Graeme Gregory
2014-07-28 16:23 ` Olof Johansson
2014-07-28 17:44 ` Mark Brown
2014-07-28 9:07 ` Arnd Bergmann
2014-07-28 9:23 ` Graeme Gregory
2014-07-28 10:46 ` Arnd Bergmann
2014-07-28 14:20 ` Andre Przywara
2014-07-28 15:23 ` Arnd Bergmann
2014-07-28 16:14 ` Andre Przywara
2014-07-29 9:17 ` Graeme Gregory
2014-07-29 10:07 ` Arnd Bergmann
2014-07-28 10:12 ` Mark Rutland
2014-07-28 16:33 ` Olof Johansson
2014-07-28 18:37 ` Mark Rutland
2014-07-28 18:44 ` Olof Johansson
2014-07-28 16:27 ` Olof Johansson
2014-07-28 17:00 ` Mark Rutland
2014-07-28 18:27 ` Olof Johansson
2014-08-12 18:23 ` Catalin Marinas
2014-08-13 23:41 ` Rafael J. Wysocki
2014-08-14 3:21 ` Hanjun Guo
2014-08-14 10:27 ` Catalin Marinas
2014-08-14 20:53 ` Arnd Bergmann
2014-08-15 1:02 ` Olof Johansson
2014-08-15 19:49 ` Arnd Bergmann
2014-08-15 23:19 ` Mark Brown
2014-08-16 12:51 ` graeme.gregory at linaro.org
2014-08-15 9:09 ` Hanjun Guo
2014-08-15 10:01 ` Catalin Marinas
2014-08-18 9:29 ` Hanjun Guo
2014-08-18 12:49 ` Mark Rutland
2014-08-20 22:17 ` Olof Johansson
2014-08-21 4:00 ` Hanjun Guo
2014-07-29 9:01 ` Hanjun Guo
2014-07-28 10:06 ` Mark Rutland
2014-07-28 16:44 ` Olof Johansson
2014-07-28 17:36 ` Mark Rutland
2014-07-28 18:34 ` Olof Johansson
2014-07-29 10:29 ` Christoffer Dall
2014-07-29 10:41 ` Arnd Bergmann
2014-07-29 10:55 ` Mark Rutland
2014-07-29 11:28 ` Mark Rutland
2014-07-29 12:37 ` Christoffer Dall
2014-07-29 12:52 ` Arnd Bergmann
2014-07-29 13:08 ` Mark Rutland
2014-07-29 13:31 ` Christoffer Dall
2014-07-29 14:04 ` Mark Rutland
2014-07-29 14:41 ` Arnd Bergmann
2014-07-29 15:01 ` Christoffer Dall
2014-07-30 6:47 ` Hanjun Guo
2014-07-30 7:14 ` Christoffer Dall
2014-07-30 9:36 ` Hanjun Guo
2014-07-29 13:33 ` Christoffer Dall
2014-07-29 7:58 ` Hanjun Guo
2014-07-29 10:30 ` Christoffer Dall
2014-08-15 22:43 ` Len Brown
2014-08-16 12:45 ` Graeme Gregory
2014-08-20 16:42 ` Grant Likely
2014-07-25 0:46 ` [PATCH 00/19] Introduce ACPI for ARM64 based on ACPI 5.1 Hanjun Guo
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=53D2378B.20109@linaro.org \
--to=hanjun.guo@linaro.org \
--cc=linux-arm-kernel@lists.infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).