From patchwork Thu Jul 24 13:00:25 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hanjun Guo X-Patchwork-Id: 34220 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-pa0-f71.google.com (mail-pa0-f71.google.com [209.85.220.71]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 3571220C7F for ; Thu, 24 Jul 2014 13:04:55 +0000 (UTC) Received: by mail-pa0-f71.google.com with SMTP id et14sf18555983pad.6 for ; Thu, 24 Jul 2014 06:04:54 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:delivered-to:from:to:cc:subject :date:message-id:in-reply-to:references:sender:precedence:list-id :x-original-sender:x-original-authentication-results:mailing-list :list-post:list-help:list-archive:list-unsubscribe; bh=0PvoMhQ2+dWEDvz90rupUdXlrUyL0E24lFacb6pu4Bo=; b=k/3AJZuYmRhyoK94P3KtxQVuRsMwoX8N2G0FDyuXmbQB/ZlXguNfYCq/xn5P2+a6w5 PYwxfAAlRwL0SbydcTg8OkseqJCYhNCMoLG1yO8Epm/YA+Qo12Ntq3jtv4rmW2vQpE1D 8thJLGMXnb3r/1w6tp1f3M/BfGocs5keucyaWq9ij5tGnZ7LPNPKVW3sRPRWVvxn9N+X Qa9jpnik6ZBT9+02mv90FnLldGwWrU6QvdizkcFA/YOXBIlvwZbmK/ia3vJZ8cyToScE d8qTPsL1BGGl1ws9XAcB7ZLgfd5uJZNvEc6S7LuRIPt/E0bXpSJXHtjsMjM5BXLipuiF zYyw== X-Gm-Message-State: ALoCoQkEyQ6K53PvhLI7qyRjKM3eVo9nAr+Y1CIq8m7bGSzQ2VlnarikTASwzLaYkAH5NbiEWuS3 X-Received: by 10.70.140.107 with SMTP id rf11mr2638820pdb.1.1406207094538; Thu, 24 Jul 2014 06:04:54 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.101.80 with SMTP id t74ls757107qge.32.gmail; Thu, 24 Jul 2014 06:04:54 -0700 (PDT) X-Received: by 10.220.81.194 with SMTP id y2mr11868754vck.29.1406207094328; Thu, 24 Jul 2014 06:04:54 -0700 (PDT) Received: from mail-vc0-f179.google.com (mail-vc0-f179.google.com [209.85.220.179]) by mx.google.com with ESMTPS id hw3si4878643vdb.67.2014.07.24.06.04.54 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 24 Jul 2014 06:04:54 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.220.179 as permitted sender) client-ip=209.85.220.179; Received: by mail-vc0-f179.google.com with SMTP id hq11so4804415vcb.38 for ; Thu, 24 Jul 2014 06:04:54 -0700 (PDT) X-Received: by 10.52.37.81 with SMTP id w17mr3111099vdj.95.1406207093936; Thu, 24 Jul 2014 06:04:53 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.221.37.5 with SMTP id tc5csp363131vcb; Thu, 24 Jul 2014 06:04:53 -0700 (PDT) X-Received: by 10.68.97.129 with SMTP id ea1mr9982106pbb.73.1406207093097; Thu, 24 Jul 2014 06:04:53 -0700 (PDT) Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id bu17si2990333pdb.75.2014.07.24.06.04.51 for ; Thu, 24 Jul 2014 06:04:51 -0700 (PDT) Received-SPF: none (google.com: linux-kernel-owner@vger.kernel.org does not designate permitted sender hosts) client-ip=209.132.180.67; Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932950AbaGXNEk (ORCPT + 13 others); Thu, 24 Jul 2014 09:04:40 -0400 Received: from mail-pd0-f180.google.com ([209.85.192.180]:58761 "EHLO mail-pd0-f180.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932836AbaGXNEf (ORCPT ); Thu, 24 Jul 2014 09:04:35 -0400 Received: by mail-pd0-f180.google.com with SMTP id y13so3608423pdi.11 for ; Thu, 24 Jul 2014 06:04:34 -0700 (PDT) X-Received: by 10.68.253.73 with SMTP id zy9mr10226028pbc.114.1406207073915; Thu, 24 Jul 2014 06:04:33 -0700 (PDT) Received: from localhost ([183.247.163.231]) by mx.google.com with ESMTPSA id l3sm5586340pbq.8.2014.07.24.06.04.27 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 24 Jul 2014 06:04:33 -0700 (PDT) From: Hanjun Guo To: Catalin Marinas , "Rafael J. Wysocki" , Mark Rutland Cc: Graeme Gregory , Arnd Bergmann , Grant Likely , Sudeep Holla , Will Deacon , Jason Cooper , Marc Zyngier , Bjorn Helgaas , Daniel Lezcano , Mark Brown , Robert Richter , Lv Zheng , Robert Moore , Lorenzo Pieralisi , Liviu Dudau , Randy Dunlap , Charles.Garcia-Tobin@arm.com, linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, linaro-acpi-private@linaro.org, Hanjun Guo Subject: [PATCH 19/19] Documentation: ACPI for ARM64 Date: Thu, 24 Jul 2014 21:00:25 +0800 Message-Id: <1406206825-15590-20-git-send-email-hanjun.guo@linaro.org> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1406206825-15590-1-git-send-email-hanjun.guo@linaro.org> References: <1406206825-15590-1-git-send-email-hanjun.guo@linaro.org> Sender: linux-kernel-owner@vger.kernel.org Precedence: list List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: hanjun.guo@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.220.179 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , From: Graeme Gregory Add documentation for the guidelines of how to use ACPI on ARM64. Signed-off-by: Graeme Gregory Signed-off-by: Hanjun Guo --- 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) + +The implemented ACPI version is 5.1 + errata as released by the UEFI Forum, +which is available at . + +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 +only allow for 32bit addresses. + +DO NOT use the 32-bit address fields in 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. + +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. + +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 +the resources set to appropriate level by the firmware. If this is not possible +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 +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 +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 +systems may use the same device. + +DO try and keep complex sections of ACPI and DT functionality seperate. This +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) . +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 +approval process.