Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

On 04/21/2016 07:37 AM, Alexey Klimov wrote:
> Hi Al,
> 
> I hope you don't mind if I put few minor questions here.
> 
> On Mon, Apr 18, 2016 at 8:32 PM, Al Stone  wrote:
>> The ACPI 6.1 specification was recently released at the end of January
>> 2016, but the arm64 kernel documentation for the use of ACPI was written
>> for the 5.1 version of the spec.  There were significant additions to the
>> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
>> added to make it easier to define processors and low power idle states,
>> as well as the 6.1 addition allowing regular interrupts (not just from
>> GPIO) be used to signal ACPI general purpose events.
>>
>> This patch reflects going back through and examining the specs in detail
>> and updating content appropriately.  Whilst there, a few odds and ends of
>> typos were caught as well.  This brings the documentation up to date with
>> ACPI 6.1 for arm64.
> 
> Why linux-acpi is not in the destination list?

No particular reason; I can add it to the next version, but this was meant
to be arm64-specific documentation that just happens to be a user of ACPI.
There are no changes to ACPI itself implied or intended.

>> Changes for v4:
>>-- Clarify that IORT can sometimes be optional (Jon Masters).
>>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>>   no substantive information and doing so simplifies maintenance of
>>   this document over time.  These have been replaced with a simpler
>>   notice that states that unless otherwise noted, do what the APCI
>>   specification says is needed.
>>-- Corrected the _OSI object usage recommendation; it described kernel
>>   behavior that does not exist (Al Stone).
>>
>> Changes for v3:
>>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>>-- Whitespace cleanup as pointed out by checkpatch
>>
>> Changes for v2:
>>-- Clean up white space (Harb Abdulhahmid)
>>-- Clarification on _CCA usage (Harb Abdulhamid)
>>-- IORT moved to required from recommended (Hanjun Guo)
>>-- Clarify IORT description (Hanjun Guo)
>>
>> Signed-off-by: Al Stone 
>> Cc: Catalin Marinas 
>> Cc: Will Deacon 
>> Cc: Jonathan Corbet 
>> ---
>>  Documentation/arm64/acpi_object_usage.txt | 347 
>> --
>>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>>  2 files changed, 212 insertions(+), 163 deletions(-)
>>
>> diff --git a/Documentation/arm64/acpi_object_usage.txt
>> b/Documentation/arm64/acpi_object_usage.txt
>> index a6e1a18..3891750 100644
>> --- a/Documentation/arm64/acpi_object_usage.txt
>> +++ b/Documentation/arm64/acpi_object_usage.txt
>> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the
>> following categories:
> 
> [..]
> 
>> == Memory-mapped ConFiGuration space ==
>> @@ -176,14 +192,38 @@ MPST   Section 5.2.21 (signature == "MPST")
>> == Memory Power State Table ==
>> Optional, not currently supported.
>>
>> +MSCT   Section 5.2.19 (signature == "MSCT")
>> +   == Maximum System Characteristic Table ==
>> +   Optional, not currently supported.
>> +
>>  MSDM   Signature Reserved (signature == "MSDM")
>> == Microsoft Data Management table ==
>> Microsoft only table, will not be supported.
>>
>> -MSCT   Section 5.2.19 (signature == "MSCT")
>> -   == Maximum System Characteristic Table ==
>> +NFIT   Section 5.2.25 (signature == "NFIT")
>> +   == NVDIMM Firmware Interface Table ==
>> Optional, not currently supported.
>>
>> +OEMx   Signature of "OEMx" only
>> +   == OEM Specific Tables ==
>> +   All tables starting with a signature of "OEM" are reserved for OEM
>> +   use.  Since these are not meant to be of general use but are limited
>> +   to very specific end users, they are not recommended for use and are
>> +   not supported by the kernel for arm64.
>> +
>> +PCCT   Section 14.1 (signature == "PCCT)
>> +   == Platform Communications Channel Table ==
>> +   Recommend for use on arm64, and required when using CPPC to control
>> +   power on the platform.
> 
> Could you please check corectness of this sentence?
> 
> If I remember correctly CPPC may operate via PCC interface but there is no
> strict requirement to implement control mechanism via PCC.

On double checking, no, it is not a strict requirement to use PCC.  So this
should probably be something like:

Recommended for use on arm64; use of PCC is recommended when using
CPPC.

>> using CPPC to control power on the platform
> 
> Sorry, I think I need to disagree.
> Main description of CPPC says that CPPC defines mechanism to manage 
> performance
> of logical processor.

Ah.  Yup, CPPC is just for processors.  Thanks for catching that.

> What do you think about "to control performance on the platform"?
> (or maybe "to control performance and power 

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

On 04/21/2016 07:37 AM, Alexey Klimov wrote:
> Hi Al,
> 
> I hope you don't mind if I put few minor questions here.
> 
> On Mon, Apr 18, 2016 at 8:32 PM, Al Stone  wrote:
>> The ACPI 6.1 specification was recently released at the end of January
>> 2016, but the arm64 kernel documentation for the use of ACPI was written
>> for the 5.1 version of the spec.  There were significant additions to the
>> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
>> added to make it easier to define processors and low power idle states,
>> as well as the 6.1 addition allowing regular interrupts (not just from
>> GPIO) be used to signal ACPI general purpose events.
>>
>> This patch reflects going back through and examining the specs in detail
>> and updating content appropriately.  Whilst there, a few odds and ends of
>> typos were caught as well.  This brings the documentation up to date with
>> ACPI 6.1 for arm64.
> 
> Why linux-acpi is not in the destination list?

No particular reason; I can add it to the next version, but this was meant
to be arm64-specific documentation that just happens to be a user of ACPI.
There are no changes to ACPI itself implied or intended.

>> Changes for v4:
>>-- Clarify that IORT can sometimes be optional (Jon Masters).
>>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>>   no substantive information and doing so simplifies maintenance of
>>   this document over time.  These have been replaced with a simpler
>>   notice that states that unless otherwise noted, do what the APCI
>>   specification says is needed.
>>-- Corrected the _OSI object usage recommendation; it described kernel
>>   behavior that does not exist (Al Stone).
>>
>> Changes for v3:
>>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>>-- Whitespace cleanup as pointed out by checkpatch
>>
>> Changes for v2:
>>-- Clean up white space (Harb Abdulhahmid)
>>-- Clarification on _CCA usage (Harb Abdulhamid)
>>-- IORT moved to required from recommended (Hanjun Guo)
>>-- Clarify IORT description (Hanjun Guo)
>>
>> Signed-off-by: Al Stone 
>> Cc: Catalin Marinas 
>> Cc: Will Deacon 
>> Cc: Jonathan Corbet 
>> ---
>>  Documentation/arm64/acpi_object_usage.txt | 347 
>> --
>>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>>  2 files changed, 212 insertions(+), 163 deletions(-)
>>
>> diff --git a/Documentation/arm64/acpi_object_usage.txt
>> b/Documentation/arm64/acpi_object_usage.txt
>> index a6e1a18..3891750 100644
>> --- a/Documentation/arm64/acpi_object_usage.txt
>> +++ b/Documentation/arm64/acpi_object_usage.txt
>> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the
>> following categories:
> 
> [..]
> 
>> == Memory-mapped ConFiGuration space ==
>> @@ -176,14 +192,38 @@ MPST   Section 5.2.21 (signature == "MPST")
>> == Memory Power State Table ==
>> Optional, not currently supported.
>>
>> +MSCT   Section 5.2.19 (signature == "MSCT")
>> +   == Maximum System Characteristic Table ==
>> +   Optional, not currently supported.
>> +
>>  MSDM   Signature Reserved (signature == "MSDM")
>> == Microsoft Data Management table ==
>> Microsoft only table, will not be supported.
>>
>> -MSCT   Section 5.2.19 (signature == "MSCT")
>> -   == Maximum System Characteristic Table ==
>> +NFIT   Section 5.2.25 (signature == "NFIT")
>> +   == NVDIMM Firmware Interface Table ==
>> Optional, not currently supported.
>>
>> +OEMx   Signature of "OEMx" only
>> +   == OEM Specific Tables ==
>> +   All tables starting with a signature of "OEM" are reserved for OEM
>> +   use.  Since these are not meant to be of general use but are limited
>> +   to very specific end users, they are not recommended for use and are
>> +   not supported by the kernel for arm64.
>> +
>> +PCCT   Section 14.1 (signature == "PCCT)
>> +   == Platform Communications Channel Table ==
>> +   Recommend for use on arm64, and required when using CPPC to control
>> +   power on the platform.
> 
> Could you please check corectness of this sentence?
> 
> If I remember correctly CPPC may operate via PCC interface but there is no
> strict requirement to implement control mechanism via PCC.

On double checking, no, it is not a strict requirement to use PCC.  So this
should probably be something like:

Recommended for use on arm64; use of PCC is recommended when using
CPPC.

>> using CPPC to control power on the platform
> 
> Sorry, I think I need to disagree.
> Main description of CPPC says that CPPC defines mechanism to manage 
> performance
> of logical processor.

Ah.  Yup, CPPC is just for processors.  Thanks for catching that.

> What do you think about "to control performance on the platform"?
> (or maybe "to control performance and power on the platform")
> 
> Thanks,
> Alexey
> 

Perhaps just "using CPPC to control performance and power for 

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

On 04/19/2016 05:15 AM, Lorenzo Pieralisi wrote:
> On Mon, Apr 18, 2016 at 01:32:22PM -0600, Al Stone wrote:
>> The ACPI 6.1 specification was recently released at the end of January
>> 2016, but the arm64 kernel documentation for the use of ACPI was written
>> for the 5.1 version of the spec.  There were significant additions to the
>> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
>> added to make it easier to define processors and low power idle states,
>> as well as the 6.1 addition allowing regular interrupts (not just from
>> GPIO) be used to signal ACPI general purpose events.
>>
>> This patch reflects going back through and examining the specs in detail
>> and updating content appropriately.  Whilst there, a few odds and ends of
>> typos were caught as well.  This brings the documentation up to date with
>> ACPI 6.1 for arm64.
>>
[snip...]

>> @@ -185,9 +185,22 @@ tables (all section numbers refer to the ACPI 5.1 
>> specfication):
>>  -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
>> Table), section 5.2.6, specifically Table 5-31.
>>  
>> +-- If booting without a console= kernel parameter is
>> +   supported, the SPCR (Serial Port Console Redirection table),
>> +   section 5.2.6, specifically Table 5-31.
>> +
>> +-- If virtualization is supported, the IORT (Input Output Remapping
>> +   Table, section 5.2.6, specifically Table 5-31.
> 
> Why only "If virtualization is supported" ? Missing closing bracket.

Hrm.  I guess that is an unnecessary qualification.

> I still question sections of this document that IMHO do not belong
> in the kernel documentation (but in the ACPI specs - eg _PRx methods
> usage), anyway the information seems accurate so, pending changes above:
> 
> Acked-by: Lorenzo Pieralisi 
> 

Thanks, Lorenzo.  The suggested changes all seem fine; I'll include them
in a v5.

-- 
ciao,
al
---
Al Stone
Software Engineer
Linaro Enterprise Group
al.st...@linaro.org
---

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

On 04/19/2016 05:15 AM, Lorenzo Pieralisi wrote:
> On Mon, Apr 18, 2016 at 01:32:22PM -0600, Al Stone wrote:
>> The ACPI 6.1 specification was recently released at the end of January
>> 2016, but the arm64 kernel documentation for the use of ACPI was written
>> for the 5.1 version of the spec.  There were significant additions to the
>> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
>> added to make it easier to define processors and low power idle states,
>> as well as the 6.1 addition allowing regular interrupts (not just from
>> GPIO) be used to signal ACPI general purpose events.
>>
>> This patch reflects going back through and examining the specs in detail
>> and updating content appropriately.  Whilst there, a few odds and ends of
>> typos were caught as well.  This brings the documentation up to date with
>> ACPI 6.1 for arm64.
>>
[snip...]

>> @@ -185,9 +185,22 @@ tables (all section numbers refer to the ACPI 5.1 
>> specfication):
>>  -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
>> Table), section 5.2.6, specifically Table 5-31.
>>  
>> +-- If booting without a console= kernel parameter is
>> +   supported, the SPCR (Serial Port Console Redirection table),
>> +   section 5.2.6, specifically Table 5-31.
>> +
>> +-- If virtualization is supported, the IORT (Input Output Remapping
>> +   Table, section 5.2.6, specifically Table 5-31.
> 
> Why only "If virtualization is supported" ? Missing closing bracket.

Hrm.  I guess that is an unnecessary qualification.

> I still question sections of this document that IMHO do not belong
> in the kernel documentation (but in the ACPI specs - eg _PRx methods
> usage), anyway the information seems accurate so, pending changes above:
> 
> Acked-by: Lorenzo Pieralisi 
> 

Thanks, Lorenzo.  The suggested changes all seem fine; I'll include them
in a v5.

-- 
ciao,
al
---
Al Stone
Software Engineer
Linaro Enterprise Group
al.st...@linaro.org
---

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Alexey Klimov]

Hi Al,

I hope you don't mind if I put few minor questions here.

On Mon, Apr 18, 2016 at 8:32 PM, Al Stone  wrote:
> The ACPI 6.1 specification was recently released at the end of January
> 2016, but the arm64 kernel documentation for the use of ACPI was written
> for the 5.1 version of the spec.  There were significant additions to the
> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
> added to make it easier to define processors and low power idle states,
> as well as the 6.1 addition allowing regular interrupts (not just from
> GPIO) be used to signal ACPI general purpose events.
> 
> This patch reflects going back through and examining the specs in detail
> and updating content appropriately.  Whilst there, a few odds and ends of
> typos were caught as well.  This brings the documentation up to date with
> ACPI 6.1 for arm64.

Why linux-acpi is not in the destination list?
 
> Changes for v4:
>-- Clarify that IORT can sometimes be optional (Jon Masters).
>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>   no substantive information and doing so simplifies maintenance of
>   this document over time.  These have been replaced with a simpler
>   notice that states that unless otherwise noted, do what the APCI
>   specification says is needed.
>-- Corrected the _OSI object usage recommendation; it described kernel
>   behavior that does not exist (Al Stone).
> 
> Changes for v3:
>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>-- Whitespace cleanup as pointed out by checkpatch
> 
> Changes for v2:
>-- Clean up white space (Harb Abdulhahmid)
>-- Clarification on _CCA usage (Harb Abdulhamid)
>-- IORT moved to required from recommended (Hanjun Guo)
>-- Clarify IORT description (Hanjun Guo)
> 
> Signed-off-by: Al Stone 
> Cc: Catalin Marinas 
> Cc: Will Deacon 
> Cc: Jonathan Corbet 
> ---
>  Documentation/arm64/acpi_object_usage.txt | 347 
> --
>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>  2 files changed, 212 insertions(+), 163 deletions(-)
> 
> diff --git a/Documentation/arm64/acpi_object_usage.txt
> b/Documentation/arm64/acpi_object_usage.txt
> index a6e1a18..3891750 100644
> --- a/Documentation/arm64/acpi_object_usage.txt
> +++ b/Documentation/arm64/acpi_object_usage.txt
> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the
> following categories:

[..]

> == Memory-mapped ConFiGuration space ==
> @@ -176,14 +192,38 @@ MPST   Section 5.2.21 (signature == "MPST")
> == Memory Power State Table ==
> Optional, not currently supported.
> 
> +MSCT   Section 5.2.19 (signature == "MSCT")
> +   == Maximum System Characteristic Table ==
> +   Optional, not currently supported.
> +
>  MSDM   Signature Reserved (signature == "MSDM")
> == Microsoft Data Management table ==
> Microsoft only table, will not be supported.
> 
> -MSCT   Section 5.2.19 (signature == "MSCT")
> -   == Maximum System Characteristic Table ==
> +NFIT   Section 5.2.25 (signature == "NFIT")
> +   == NVDIMM Firmware Interface Table ==
> Optional, not currently supported.
> 
> +OEMx   Signature of "OEMx" only
> +   == OEM Specific Tables ==
> +   All tables starting with a signature of "OEM" are reserved for OEM
> +   use.  Since these are not meant to be of general use but are limited
> +   to very specific end users, they are not recommended for use and are
> +   not supported by the kernel for arm64.
> +
> +PCCT   Section 14.1 (signature == "PCCT)
> +   == Platform Communications Channel Table ==
> +   Recommend for use on arm64, and required when using CPPC to control
> +   power on the platform.

Could you please check corectness of this sentence?

If I remember correctly CPPC may operate via PCC interface but there is no
strict requirement to implement control mechanism via PCC.

> using CPPC to control power on the platform

Sorry, I think I need to disagree.
Main description of CPPC says that CPPC defines mechanism to manage performance
of logical processor.

What do you think about "to control performance on the platform"?
(or maybe "to control performance and power on the platform")

Thanks,
Alexey

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Alexey Klimov]

Hi Al,

I hope you don't mind if I put few minor questions here.

On Mon, Apr 18, 2016 at 8:32 PM, Al Stone  wrote:
> The ACPI 6.1 specification was recently released at the end of January
> 2016, but the arm64 kernel documentation for the use of ACPI was written
> for the 5.1 version of the spec.  There were significant additions to the
> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
> added to make it easier to define processors and low power idle states,
> as well as the 6.1 addition allowing regular interrupts (not just from
> GPIO) be used to signal ACPI general purpose events.
> 
> This patch reflects going back through and examining the specs in detail
> and updating content appropriately.  Whilst there, a few odds and ends of
> typos were caught as well.  This brings the documentation up to date with
> ACPI 6.1 for arm64.

Why linux-acpi is not in the destination list?
 
> Changes for v4:
>-- Clarify that IORT can sometimes be optional (Jon Masters).
>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>   no substantive information and doing so simplifies maintenance of
>   this document over time.  These have been replaced with a simpler
>   notice that states that unless otherwise noted, do what the APCI
>   specification says is needed.
>-- Corrected the _OSI object usage recommendation; it described kernel
>   behavior that does not exist (Al Stone).
> 
> Changes for v3:
>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>-- Whitespace cleanup as pointed out by checkpatch
> 
> Changes for v2:
>-- Clean up white space (Harb Abdulhahmid)
>-- Clarification on _CCA usage (Harb Abdulhamid)
>-- IORT moved to required from recommended (Hanjun Guo)
>-- Clarify IORT description (Hanjun Guo)
> 
> Signed-off-by: Al Stone 
> Cc: Catalin Marinas 
> Cc: Will Deacon 
> Cc: Jonathan Corbet 
> ---
>  Documentation/arm64/acpi_object_usage.txt | 347 
> --
>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>  2 files changed, 212 insertions(+), 163 deletions(-)
> 
> diff --git a/Documentation/arm64/acpi_object_usage.txt
> b/Documentation/arm64/acpi_object_usage.txt
> index a6e1a18..3891750 100644
> --- a/Documentation/arm64/acpi_object_usage.txt
> +++ b/Documentation/arm64/acpi_object_usage.txt
> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the
> following categories:

[..]

> == Memory-mapped ConFiGuration space ==
> @@ -176,14 +192,38 @@ MPST   Section 5.2.21 (signature == "MPST")
> == Memory Power State Table ==
> Optional, not currently supported.
> 
> +MSCT   Section 5.2.19 (signature == "MSCT")
> +   == Maximum System Characteristic Table ==
> +   Optional, not currently supported.
> +
>  MSDM   Signature Reserved (signature == "MSDM")
> == Microsoft Data Management table ==
> Microsoft only table, will not be supported.
> 
> -MSCT   Section 5.2.19 (signature == "MSCT")
> -   == Maximum System Characteristic Table ==
> +NFIT   Section 5.2.25 (signature == "NFIT")
> +   == NVDIMM Firmware Interface Table ==
> Optional, not currently supported.
> 
> +OEMx   Signature of "OEMx" only
> +   == OEM Specific Tables ==
> +   All tables starting with a signature of "OEM" are reserved for OEM
> +   use.  Since these are not meant to be of general use but are limited
> +   to very specific end users, they are not recommended for use and are
> +   not supported by the kernel for arm64.
> +
> +PCCT   Section 14.1 (signature == "PCCT)
> +   == Platform Communications Channel Table ==
> +   Recommend for use on arm64, and required when using CPPC to control
> +   power on the platform.

Could you please check corectness of this sentence?

If I remember correctly CPPC may operate via PCC interface but there is no
strict requirement to implement control mechanism via PCC.

> using CPPC to control power on the platform

Sorry, I think I need to disagree.
Main description of CPPC says that CPPC defines mechanism to manage performance
of logical processor.

What do you think about "to control performance on the platform"?
(or maybe "to control performance and power on the platform")

Thanks,
Alexey

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Lorenzo Pieralisi]

On Mon, Apr 18, 2016 at 01:32:22PM -0600, Al Stone wrote:
> The ACPI 6.1 specification was recently released at the end of January
> 2016, but the arm64 kernel documentation for the use of ACPI was written
> for the 5.1 version of the spec.  There were significant additions to the
> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
> added to make it easier to define processors and low power idle states,
> as well as the 6.1 addition allowing regular interrupts (not just from
> GPIO) be used to signal ACPI general purpose events.
> 
> This patch reflects going back through and examining the specs in detail
> and updating content appropriately.  Whilst there, a few odds and ends of
> typos were caught as well.  This brings the documentation up to date with
> ACPI 6.1 for arm64.
> 
> Changes for v4:
>-- Clarify that IORT can sometimes be optional (Jon Masters).
>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>   no substantive information and doing so simplifies maintenance of
>   this document over time.  These have been replaced with a simpler
>   notice that states that unless otherwise noted, do what the APCI

s/APCI/ACPI

>   specification says is needed.
>-- Corrected the _OSI object usage recommendation; it described kernel
>   behavior that does not exist (Al Stone).
> 
> Changes for v3:
>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>-- Whitespace cleanup as pointed out by checkpatch
> 
> Changes for v2:
>-- Clean up white space (Harb Abdulhahmid)
>-- Clarification on _CCA usage (Harb Abdulhamid)
>-- IORT moved to required from recommended (Hanjun Guo)
>-- Clarify IORT description (Hanjun Guo)

Changes summary does not belong in the commit log.

> Signed-off-by: Al Stone 
> Cc: Catalin Marinas 
> Cc: Will Deacon 
> Cc: Jonathan Corbet 
> ---
>  Documentation/arm64/acpi_object_usage.txt | 347 
> --
>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>  2 files changed, 212 insertions(+), 163 deletions(-)
> 
> diff --git a/Documentation/arm64/acpi_object_usage.txt 
> b/Documentation/arm64/acpi_object_usage.txt
> index a6e1a18..3891750 100644
> --- a/Documentation/arm64/acpi_object_usage.txt
> +++ b/Documentation/arm64/acpi_object_usage.txt
> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the following 
> categories:
>  
> -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
>  
> -   -- Recommended: BERT, EINJ, ERST, HEST, SSDT
> +   -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
>  
> -   -- Optional: BGRT, CPEP, CSRT, DRTM, ECDT, FACS, FPDT, MCHI, MPST,
> -  MSCT, RASF, SBST, SLIT, SPMI, SRAT, TCPA, TPM2, UEFI
> +   -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, MCHI,
> +  MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA,
> +  TPM2, UEFI, XENV
>  
> -   -- Not supported: BOOT, DBG2, DBGP, DMAR, ETDT, HPET, IBFT, IVRS,
> -  LPIT, MSDM, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
> +   -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
> +  MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
>  
> +   -- NB: the IORT is required on certain SBSA platforms (e.g., when
> +  using GICv3-ITS and an SMMU); it is optional on SBSA Level 0
> +   platforms.

Mark it as optional and refer to the specs in the IORT entry below.

[...]

> +PMTT   Section 5.2.21.12 (signature == "PMTT")
> +   == Platform Memory Topology Table ==
> +   Optional, but useful, but not currently supported.

"Optional, not supported".

[...]

>  SLIT   Section 5.2.17 (signature == "SLIT")
> == System Locality distance Information Table ==
> -   Optional in general, but required for NUMA systems.
> +   Optional in general, but required for arm64 NUMA systems.

We know it is arm64 related, it is an arm64 specific document.

[...]

> +_HRV   6.1.6   Use to clarify device behavior; in some cases, this 
> +may be easier to use than _DSD.

What does it mean ? Either we add a concrete example or "Use as needed".

[...]

> +Note too, that the processor Device objects defined and the entries in the
> +MADT for GICs are expected to be in sychronization.  The _UID of the Device

s/sychronization/synchronization

> +object must correspond to processor IDs used in the MADT.
> +
> +It is recommended that CPPC (8.4.5) be used as the primary model for 
> processor
> +performance control on arm64.  C-states and P-states may become available at
> +some point in the future, but most current design work appears to favor CPPC.
>  
>  Further, it is essential that the ARMv8 SoC provide a fully functional
>  implementation of PSCI; this will be the only mechanism supported by ACPI
> -to control CPU power state (including secondary CPU booting).
> -
> 

Re: [PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Lorenzo Pieralisi]

On Mon, Apr 18, 2016 at 01:32:22PM -0600, Al Stone wrote:
> The ACPI 6.1 specification was recently released at the end of January
> 2016, but the arm64 kernel documentation for the use of ACPI was written
> for the 5.1 version of the spec.  There were significant additions to the
> spec that had not yet been mentioned -- for example, the 6.0 mechanisms
> added to make it easier to define processors and low power idle states,
> as well as the 6.1 addition allowing regular interrupts (not just from
> GPIO) be used to signal ACPI general purpose events.
> 
> This patch reflects going back through and examining the specs in detail
> and updating content appropriately.  Whilst there, a few odds and ends of
> typos were caught as well.  This brings the documentation up to date with
> ACPI 6.1 for arm64.
> 
> Changes for v4:
>-- Clarify that IORT can sometimes be optional (Jon Masters).
>-- Remove "Use as needed" descriptions of ACPI objects; they provide
>   no substantive information and doing so simplifies maintenance of
>   this document over time.  These have been replaced with a simpler
>   notice that states that unless otherwise noted, do what the APCI

s/APCI/ACPI

>   specification says is needed.
>-- Corrected the _OSI object usage recommendation; it described kernel
>   behavior that does not exist (Al Stone).
> 
> Changes for v3:
>-- Clarify use of _LPI/_RDI (Vikas Sajjan)
>-- Whitespace cleanup as pointed out by checkpatch
> 
> Changes for v2:
>-- Clean up white space (Harb Abdulhahmid)
>-- Clarification on _CCA usage (Harb Abdulhamid)
>-- IORT moved to required from recommended (Hanjun Guo)
>-- Clarify IORT description (Hanjun Guo)

Changes summary does not belong in the commit log.

> Signed-off-by: Al Stone 
> Cc: Catalin Marinas 
> Cc: Will Deacon 
> Cc: Jonathan Corbet 
> ---
>  Documentation/arm64/acpi_object_usage.txt | 347 
> --
>  Documentation/arm64/arm-acpi.txt  |  28 ++-
>  2 files changed, 212 insertions(+), 163 deletions(-)
> 
> diff --git a/Documentation/arm64/acpi_object_usage.txt 
> b/Documentation/arm64/acpi_object_usage.txt
> index a6e1a18..3891750 100644
> --- a/Documentation/arm64/acpi_object_usage.txt
> +++ b/Documentation/arm64/acpi_object_usage.txt
> @@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the following 
> categories:
>  
> -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
>  
> -   -- Recommended: BERT, EINJ, ERST, HEST, SSDT
> +   -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
>  
> -   -- Optional: BGRT, CPEP, CSRT, DRTM, ECDT, FACS, FPDT, MCHI, MPST,
> -  MSCT, RASF, SBST, SLIT, SPMI, SRAT, TCPA, TPM2, UEFI
> +   -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, MCHI,
> +  MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA,
> +  TPM2, UEFI, XENV
>  
> -   -- Not supported: BOOT, DBG2, DBGP, DMAR, ETDT, HPET, IBFT, IVRS,
> -  LPIT, MSDM, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
> +   -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
> +  MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
>  
> +   -- NB: the IORT is required on certain SBSA platforms (e.g., when
> +  using GICv3-ITS and an SMMU); it is optional on SBSA Level 0
> +   platforms.

Mark it as optional and refer to the specs in the IORT entry below.

[...]

> +PMTT   Section 5.2.21.12 (signature == "PMTT")
> +   == Platform Memory Topology Table ==
> +   Optional, but useful, but not currently supported.

"Optional, not supported".

[...]

>  SLIT   Section 5.2.17 (signature == "SLIT")
> == System Locality distance Information Table ==
> -   Optional in general, but required for NUMA systems.
> +   Optional in general, but required for arm64 NUMA systems.

We know it is arm64 related, it is an arm64 specific document.

[...]

> +_HRV   6.1.6   Use to clarify device behavior; in some cases, this 
> +may be easier to use than _DSD.

What does it mean ? Either we add a concrete example or "Use as needed".

[...]

> +Note too, that the processor Device objects defined and the entries in the
> +MADT for GICs are expected to be in sychronization.  The _UID of the Device

s/sychronization/synchronization

> +object must correspond to processor IDs used in the MADT.
> +
> +It is recommended that CPPC (8.4.5) be used as the primary model for 
> processor
> +performance control on arm64.  C-states and P-states may become available at
> +some point in the future, but most current design work appears to favor CPPC.
>  
>  Further, it is essential that the ARMv8 SoC provide a fully functional
>  implementation of PSCI; this will be the only mechanism supported by ACPI
> -to control CPU power state (including secondary CPU booting).
> -
> -More details will be provided on the release of the ACPI 6.0 specification.
> +to 

[PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

The ACPI 6.1 specification was recently released at the end of January
2016, but the arm64 kernel documentation for the use of ACPI was written
for the 5.1 version of the spec.  There were significant additions to the
spec that had not yet been mentioned -- for example, the 6.0 mechanisms
added to make it easier to define processors and low power idle states,
as well as the 6.1 addition allowing regular interrupts (not just from
GPIO) be used to signal ACPI general purpose events.

This patch reflects going back through and examining the specs in detail
and updating content appropriately.  Whilst there, a few odds and ends of
typos were caught as well.  This brings the documentation up to date with
ACPI 6.1 for arm64.

Changes for v4:
   -- Clarify that IORT can sometimes be optional (Jon Masters).
   -- Remove "Use as needed" descriptions of ACPI objects; they provide
  no substantive information and doing so simplifies maintenance of
  this document over time.  These have been replaced with a simpler
  notice that states that unless otherwise noted, do what the APCI
  specification says is needed.
   -- Corrected the _OSI object usage recommendation; it described kernel
  behavior that does not exist (Al Stone).

Changes for v3:
   -- Clarify use of _LPI/_RDI (Vikas Sajjan)
   -- Whitespace cleanup as pointed out by checkpatch

Changes for v2:
   -- Clean up white space (Harb Abdulhahmid)
   -- Clarification on _CCA usage (Harb Abdulhamid)
   -- IORT moved to required from recommended (Hanjun Guo)
   -- Clarify IORT description (Hanjun Guo)

Signed-off-by: Al Stone 
Cc: Catalin Marinas 
Cc: Will Deacon 
Cc: Jonathan Corbet 
---
 Documentation/arm64/acpi_object_usage.txt | 347 --
 Documentation/arm64/arm-acpi.txt  |  28 ++-
 2 files changed, 212 insertions(+), 163 deletions(-)

diff --git a/Documentation/arm64/acpi_object_usage.txt 
b/Documentation/arm64/acpi_object_usage.txt
index a6e1a18..3891750 100644
--- a/Documentation/arm64/acpi_object_usage.txt
+++ b/Documentation/arm64/acpi_object_usage.txt
@@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the following 
categories:
 
-- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
 
-   -- Recommended: BERT, EINJ, ERST, HEST, SSDT
+   -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
 
-   -- Optional: BGRT, CPEP, CSRT, DRTM, ECDT, FACS, FPDT, MCHI, MPST,
-  MSCT, RASF, SBST, SLIT, SPMI, SRAT, TCPA, TPM2, UEFI
+   -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, MCHI,
+  MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA,
+  TPM2, UEFI, XENV
 
-   -- Not supported: BOOT, DBG2, DBGP, DMAR, ETDT, HPET, IBFT, IVRS,
-  LPIT, MSDM, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
+   -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+  MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
 
+   -- NB: the IORT is required on certain SBSA platforms (e.g., when
+  using GICv3-ITS and an SMMU); it is optional on SBSA Level 0
+ platforms.
 
 Table  Usage for ARMv8 Linux
 -  
@@ -50,7 +54,8 @@ CSRT   Signature Reserved (signature == "CSRT")
 
 DBG2   Signature Reserved (signature == "DBG2")
== DeBuG port table 2 ==
-   Microsoft only table, will not be supported.
+   License has changed and should be usable.  Optional if used instead
+   of earlycon= on the command line.
 
 DBGP   Signature Reserved (signature == "DBGP")
== DeBuG Port table ==
@@ -133,10 +138,11 @@ GTDT   Section 5.2.24 (signature == "GTDT")
 
 HEST   Section 18.3.2 (signature == "HEST")
== Hardware Error Source Table ==
-   Until further error source types are defined, use only types 6 (AER
-   Root Port), 7 (AER Endpoint), 8 (AER Bridge), or 9 (Generic Hardware
-   Error Source).  Firmware first error handling is possible if and only
-   if Trusted Firmware is being used on arm64.
+   ARM-specific error sources have been defined; please use those or the
+   PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
+   Bridge), or use type 9 (Generic Hardware Error Source).  Firmware first
+   error handling is possible if and only if Trusted Firmware is being
+   used on arm64.
 
Must be supplied if RAS support is provided by the platform.  It
is recommended this table be supplied.
@@ -149,20 +155,30 @@ IBFT   Signature Reserved (signature == "IBFT")
== iSCSI Boot Firmware Table ==
Microsoft defined table, support TBD.
 
+IORT   Signature Reserved (signature == "IORT")
+   == Input Output Remapping Table ==
+   arm64 only table, required in order to describe IO topology, SMMUs,
+   and GIC ITSs, and how those various components are 

[PATCH v4] ARM64: ACPI: Update documentation for latest specification version

[Al Stone]

The ACPI 6.1 specification was recently released at the end of January
2016, but the arm64 kernel documentation for the use of ACPI was written
for the 5.1 version of the spec.  There were significant additions to the
spec that had not yet been mentioned -- for example, the 6.0 mechanisms
added to make it easier to define processors and low power idle states,
as well as the 6.1 addition allowing regular interrupts (not just from
GPIO) be used to signal ACPI general purpose events.

This patch reflects going back through and examining the specs in detail
and updating content appropriately.  Whilst there, a few odds and ends of
typos were caught as well.  This brings the documentation up to date with
ACPI 6.1 for arm64.

Changes for v4:
   -- Clarify that IORT can sometimes be optional (Jon Masters).
   -- Remove "Use as needed" descriptions of ACPI objects; they provide
  no substantive information and doing so simplifies maintenance of
  this document over time.  These have been replaced with a simpler
  notice that states that unless otherwise noted, do what the APCI
  specification says is needed.
   -- Corrected the _OSI object usage recommendation; it described kernel
  behavior that does not exist (Al Stone).

Changes for v3:
   -- Clarify use of _LPI/_RDI (Vikas Sajjan)
   -- Whitespace cleanup as pointed out by checkpatch

Changes for v2:
   -- Clean up white space (Harb Abdulhahmid)
   -- Clarification on _CCA usage (Harb Abdulhamid)
   -- IORT moved to required from recommended (Hanjun Guo)
   -- Clarify IORT description (Hanjun Guo)

Signed-off-by: Al Stone 
Cc: Catalin Marinas 
Cc: Will Deacon 
Cc: Jonathan Corbet 
---
 Documentation/arm64/acpi_object_usage.txt | 347 --
 Documentation/arm64/arm-acpi.txt  |  28 ++-
 2 files changed, 212 insertions(+), 163 deletions(-)

diff --git a/Documentation/arm64/acpi_object_usage.txt 
b/Documentation/arm64/acpi_object_usage.txt
index a6e1a18..3891750 100644
--- a/Documentation/arm64/acpi_object_usage.txt
+++ b/Documentation/arm64/acpi_object_usage.txt
@@ -13,14 +13,18 @@ For ACPI on arm64, tables also fall into the following 
categories:
 
-- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
 
-   -- Recommended: BERT, EINJ, ERST, HEST, SSDT
+   -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
 
-   -- Optional: BGRT, CPEP, CSRT, DRTM, ECDT, FACS, FPDT, MCHI, MPST,
-  MSCT, RASF, SBST, SLIT, SPMI, SRAT, TCPA, TPM2, UEFI
+   -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, MCHI,
+  MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA,
+  TPM2, UEFI, XENV
 
-   -- Not supported: BOOT, DBG2, DBGP, DMAR, ETDT, HPET, IBFT, IVRS,
-  LPIT, MSDM, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
+   -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+  MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
 
+   -- NB: the IORT is required on certain SBSA platforms (e.g., when
+  using GICv3-ITS and an SMMU); it is optional on SBSA Level 0
+ platforms.
 
 Table  Usage for ARMv8 Linux
 -  
@@ -50,7 +54,8 @@ CSRT   Signature Reserved (signature == "CSRT")
 
 DBG2   Signature Reserved (signature == "DBG2")
== DeBuG port table 2 ==
-   Microsoft only table, will not be supported.
+   License has changed and should be usable.  Optional if used instead
+   of earlycon= on the command line.
 
 DBGP   Signature Reserved (signature == "DBGP")
== DeBuG Port table ==
@@ -133,10 +138,11 @@ GTDT   Section 5.2.24 (signature == "GTDT")
 
 HEST   Section 18.3.2 (signature == "HEST")
== Hardware Error Source Table ==
-   Until further error source types are defined, use only types 6 (AER
-   Root Port), 7 (AER Endpoint), 8 (AER Bridge), or 9 (Generic Hardware
-   Error Source).  Firmware first error handling is possible if and only
-   if Trusted Firmware is being used on arm64.
+   ARM-specific error sources have been defined; please use those or the
+   PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
+   Bridge), or use type 9 (Generic Hardware Error Source).  Firmware first
+   error handling is possible if and only if Trusted Firmware is being
+   used on arm64.
 
Must be supplied if RAS support is provided by the platform.  It
is recommended this table be supplied.
@@ -149,20 +155,30 @@ IBFT   Signature Reserved (signature == "IBFT")
== iSCSI Boot Firmware Table ==
Microsoft defined table, support TBD.
 
+IORT   Signature Reserved (signature == "IORT")
+   == Input Output Remapping Table ==
+   arm64 only table, required in order to describe IO topology, SMMUs,
+   and GIC ITSs, and how those various components are connected together,
+   such as identifying which components are behind which