From patchwork Tue Apr 23 16:28:38 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Changbin Du X-Patchwork-Id: 10913347 X-Patchwork-Delegate: bhelgaas@google.com Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9D3251708 for ; Tue, 23 Apr 2019 16:31:45 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8B709286A0 for ; Tue, 23 Apr 2019 16:31:45 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7FCB4286BD; Tue, 23 Apr 2019 16:31:45 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B8DCF286AC for ; Tue, 23 Apr 2019 16:31:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728928AbfDWQbn (ORCPT ); Tue, 23 Apr 2019 12:31:43 -0400 Received: from mail-pg1-f193.google.com ([209.85.215.193]:37701 "EHLO mail-pg1-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728482AbfDWQbm (ORCPT ); Tue, 23 Apr 2019 12:31:42 -0400 Received: by mail-pg1-f193.google.com with SMTP id e6so7873389pgc.4; Tue, 23 Apr 2019 09:31:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Prs13uumP0773MSiQbjuvT9efNoJVi6FQqnUexJvg8g=; b=rjghSho7xkjeZmJL8597zdtYOso+alElu5k+HS1/1loCha0Beots4yjS8JgZ5cSb3w CBao1RVpMpW0sINNHM9Elh076BxZjs2MaFgMp6zeyWsv9iQLMRqmB2rEIrbr2AnAtsBZ 1VLSEGNXv47smuPVHQUpIJc8hCyQvkmr5Zml+JWAF+bfJ1OzczA+GM9x87YIqcJGBiqI VhqF8/61ewDgmrtBYxDF0ICru7cAY5CReN9eX28QZcfR3QfisTB9fk85tkAktNo9lTnn xGFTGZdIFMutTP3W2wJNydQw13u6q4t9peUl8d0Qduo7pgXEK3sKRXu06c5isQ/zUZIB kaSw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Prs13uumP0773MSiQbjuvT9efNoJVi6FQqnUexJvg8g=; b=mnWHz7PiBRJjNZj4WCx/OLMx8Dccl2wztBzsLNqEfVf8UB79iGipD1z6aLoKblIFfF ccBCjvtrgfVuUzumiUpdKPAJivi2MGvt4/8ypic/SCM2dL80BhzaEzNz8pb4dnKFECdc ocnIl6Gqs/zDGfHL5j67MUycHquDqD8NkNPh4xcmq36kZfvLpGMoTlBKrFlYDuv11Vd6 lkt3V4HTlhyx2Yh4n4/j9V8JDK3MU1giTSGT2zzoHU9cOqaTqlGkaTEzZYxkOy+OeRyb VttQ7ScfxApH+eM0PUUY9VUi3KIgSDZj3wV/Df/1/qzvPeNrU0z13QnAACwGYI4WSnyJ iWGQ== X-Gm-Message-State: APjAAAV8wG/B0XP2zyLZxwR+9H5AgreksBpyIkzoRGCvz8ZNyQ2Bmlj9 PSa/6WJGK3m8TRglTG02zzU= X-Google-Smtp-Source: APXvYqxpu7K7PxTXe34D8AwDLAVBpa3TfqeGU5Mhyhe6gG6Q46dupcmSA/6Ca4Errq0l88ks7JZCxQ== X-Received: by 2002:a62:12c9:: with SMTP id 70mr27302569pfs.156.1556037101303; Tue, 23 Apr 2019 09:31:41 -0700 (PDT) Received: from localhost.localdomain ([104.238.181.70]) by smtp.gmail.com with ESMTPSA id v1sm24364801pff.81.2019.04.23.09.31.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 23 Apr 2019 09:31:40 -0700 (PDT) From: Changbin Du To: Jonathan Corbet Cc: Bjorn Helgaas , rjw@rjwysocki.net, linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, tglx@linutronix.de, mingo@redhat.com, x86@kernel.org, fenghua.yu@intel.com, linuxppc-dev@lists.ozlabs.org, linux-acpi@vger.kernel.org, linux-gpio@vger.kernel.org, mchehab+samsung@kernel.org, Changbin Du Subject: [PATCH v4 09/63] Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST Date: Wed, 24 Apr 2019 00:28:38 +0800 Message-Id: <20190423162932.21428-10-changbin.du@gmail.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com> References: <20190423162932.21428-1-changbin.du@gmail.com> MIME-Version: 1.0 Sender: linux-pci-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-pci@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du --- Documentation/acpi/method-customizing.txt | 73 ----------------- Documentation/firmware-guide/acpi/index.rst | 3 +- .../acpi/method-customizing.rst | 82 +++++++++++++++++++ 3 files changed, 84 insertions(+), 74 deletions(-) delete mode 100644 Documentation/acpi/method-customizing.txt create mode 100644 Documentation/firmware-guide/acpi/method-customizing.rst diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt deleted file mode 100644 index 7235da975f23..000000000000 --- a/Documentation/acpi/method-customizing.txt +++ /dev/null @@ -1,73 +0,0 @@ -Linux ACPI Custom Control Method How To -======================================= - -Written by Zhang Rui - - -Linux supports customizing ACPI control methods at runtime. - -Users can use this to -1. override an existing method which may not work correctly, - or just for debugging purposes. -2. insert a completely new method in order to create a missing - method such as _OFF, _ON, _STA, _INI, etc. -For these cases, it is far simpler to dynamically install a single -control method rather than override the entire DSDT, because kernel -rebuild/reboot is not needed and test result can be got in minutes. - -Note: Only ACPI METHOD can be overridden, any other object types like - "Device", "OperationRegion", are not recognized. Methods - declared inside scope operators are also not supported. -Note: The same ACPI control method can be overridden for many times, - and it's always the latest one that used by Linux/kernel. -Note: To get the ACPI debug object output (Store (AAAA, Debug)), - please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output". - -1. override an existing method - a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT, - just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat" - b) disassemble the table by running "iasl -d dsdt.dat". - c) rewrite the ASL code of the method and save it in a new file, - d) package the new file (psr.asl) to an ACPI table format. - Here is an example of a customized \_SB._AC._PSR method, - - DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715) - { - Method (\_SB_.AC._PSR, 0, NotSerialized) - { - Store ("In AC _PSR", Debug) - Return (ACON) - } - } - Note that the full pathname of the method in ACPI namespace - should be used. - e) assemble the file to generate the AML code of the method. - e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result) - If parameter "-vw 6084" is not supported by your iASL compiler, - please try a newer version. - f) mount debugfs by "mount -t debugfs none /sys/kernel/debug" - g) override the old method via the debugfs by running - "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method" - -2. insert a new method - This is easier than overriding an existing method. - We just need to create the ASL code of the method we want to - insert and then follow the step c) ~ g) in section 1. - -3. undo your changes - The "undo" operation is not supported for a new inserted method - right now, i.e. we can not remove a method currently. - For an overridden method, in order to undo your changes, please - save a copy of the method original ASL code in step c) section 1, - and redo step c) ~ g) to override the method with the original one. - - -Note: We can use a kernel with multiple custom ACPI method running, - But each individual write to debugfs can implement a SINGLE - method override. i.e. if we want to insert/override multiple - ACPI methods, we need to redo step c) ~ g) for multiple times. - -Note: Be aware that root can mis-use this driver to modify arbitrary - memory and gain additional rights, if root's privileges got - restricted (for example if root is not allowed to load additional - modules after boot). diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 61d67763851b..d1d069b26bbc 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,5 +10,6 @@ ACPI Support namespace enumeration osi + method-customizing DSD-properties-rules - gpio-properties + gpio-properties \ No newline at end of file diff --git a/Documentation/firmware-guide/acpi/method-customizing.rst b/Documentation/firmware-guide/acpi/method-customizing.rst new file mode 100644 index 000000000000..32eb1cdc1549 --- /dev/null +++ b/Documentation/firmware-guide/acpi/method-customizing.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Linux ACPI Custom Control Method How To +======================================= + +:Author: Zhang Rui + + +Linux supports customizing ACPI control methods at runtime. + +Users can use this to: + +1. override an existing method which may not work correctly, + or just for debugging purposes. +2. insert a completely new method in order to create a missing + method such as _OFF, _ON, _STA, _INI, etc. + +For these cases, it is far simpler to dynamically install a single +control method rather than override the entire DSDT, because kernel +rebuild/reboot is not needed and test result can be got in minutes. + +.. note:: Only ACPI METHOD can be overridden, any other object types like + "Device", "OperationRegion", are not recognized. Methods + declared inside scope operators are also not supported. +.. note:: The same ACPI control method can be overridden for many times, + and it's always the latest one that used by Linux/kernel. +.. note:: To get the ACPI debug object output (Store (AAAA, Debug)), + please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output". + +1. override an existing method +============================== +a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT, + just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat" +b) disassemble the table by running "iasl -d dsdt.dat". +c) rewrite the ASL code of the method and save it in a new file, +d) package the new file (psr.asl) to an ACPI table format. + Here is an example of a customized \_SB._AC._PSR method:: + + DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715) + { + Method (\_SB_.AC._PSR, 0, NotSerialized) + { + Store ("In AC _PSR", Debug) + Return (ACON) + } + } + + Note that the full pathname of the method in ACPI namespace + should be used. +e) assemble the file to generate the AML code of the method. + e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result) + If parameter "-vw 6084" is not supported by your iASL compiler, + please try a newer version. +f) mount debugfs by "mount -t debugfs none /sys/kernel/debug" +g) override the old method via the debugfs by running + "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method" + +2. insert a new method +====================== +This is easier than overriding an existing method. +We just need to create the ASL code of the method we want to +insert and then follow the step c) ~ g) in section 1. + +3. undo your changes +==================== +The "undo" operation is not supported for a new inserted method +right now, i.e. we can not remove a method currently. +For an overridden method, in order to undo your changes, please +save a copy of the method original ASL code in step c) section 1, +and redo step c) ~ g) to override the method with the original one. + + +.. note:: We can use a kernel with multiple custom ACPI method running, + But each individual write to debugfs can implement a SINGLE + method override. i.e. if we want to insert/override multiple + ACPI methods, we need to redo step c) ~ g) for multiple times. + +.. note:: Be aware that root can mis-use this driver to modify arbitrary + memory and gain additional rights, if root's privileges got + restricted (for example if root is not allowed to load additional + modules after boot).