[PATCH v3] ARM64: ACPI: Update documentation for latest specification version
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 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 | 446 ++ Documentation/arm64/arm-acpi.txt | 28 +- 2 files changed, 357 insertions(+), 117 deletions(-) diff --git a/Documentation/arm64/acpi_object_usage.txt b/Documentation/arm64/acpi_object_usage.txt index a6e1a18..756d2f8 100644 --- a/Documentation/arm64/acpi_object_usage.txt +++ b/Documentation/arm64/acpi_object_usage.txt @@ -11,15 +11,16 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification). For ACPI on arm64, tables also fall into the following categories: - -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT + -- Required: DSDT, FADT, GTDT, IORT, 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 Table Usage for ARMv8 Linux @@ -50,7 +51,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 +135,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 +152,27 @@ 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 SMMUs/ITSs. + IVRS Signature Reserved (signature == "IVRS") == I/O Virtualization Reporting Structure == x86_64 (AMD) only table, will not be supported. LPIT Signature Reserved (signature == "LPIT") == Low Power Idle Table == - x86 only table as of ACPI 5.1; future versions have been adapted for - use with ARM and will be recommended in order to support ACPI power - management. + x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor + descriptions and power states on ARM platforms should use the DSDT + and define processor container devices
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 03/28/2016 06:06 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. > > 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 | 446 > ++ > Documentation/arm64/arm-acpi.txt | 28 +- > 2 files changed, 357 insertions(+), 117 deletions(-) > [snip...] Ping? Any further comments or is this good to go? Thanks. -- ciao, al --- Al Stone Software Engineer Red Hat, Inc. a...@redhat.com --- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On Thu, Apr 07, 2016 at 03:50:55PM -0600, Al Stone wrote: > On 03/28/2016 06:06 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. > > > > 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 | 446 > > ++ > > Documentation/arm64/arm-acpi.txt | 28 +- > > 2 files changed, 357 insertions(+), 117 deletions(-) > > [snip...] > > Ping? Any further comments or is this good to go? It would be nice to see an ack from some other ACPI people, if that's possible. Which tree were you planning to merge this through? Will -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 04/08/2016 07:12 AM, Will Deacon wrote: > On Thu, Apr 07, 2016 at 03:50:55PM -0600, Al Stone wrote: >> On 03/28/2016 06:06 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. >>> >>> 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 | 446 >>> ++ >>> Documentation/arm64/arm-acpi.txt | 28 +- >>> 2 files changed, 357 insertions(+), 117 deletions(-) >>> [snip...] >> >> Ping? Any further comments or is this good to go? > > It would be nice to see an ack from some other ACPI people, if that's > possible. Which tree were you planning to merge this through? > > Will > Agreed. I was hoping the ping would elicit some of that. I assumed this would go through the arm64 tree since it's pretty specific to the architecture. -- ciao, al --- Al Stone Software Engineer Linaro Enterprise Group al.st...@linaro.org --- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 2016/3/29 8:06, 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 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 Acked-by: Hanjun Guo Thanks for the doc updating! Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
Hi Al,
On Mon, Mar 28, 2016 at 06:06:42PM -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 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 | 446
> ++
> Documentation/arm64/arm-acpi.txt | 28 +-
> 2 files changed, 357 insertions(+), 117 deletions(-)
I went through this patch twice and before posting my review comments
I have some questions to _ASK ;-):
- Do we really need acpi_object_usage.txt to list all possible ACPI
methods in the ACPI specs ("Use as needed") and update them as the
specs evolve ?
IMO that's what the ACPI specs are for and that's what AML developers
will refer to, I do not see the point in listing all methods in that
file (can't it become an ARM addendum to the ACPI specs at least to
deprecate methods/tables that are obsolete in ARM's world) ?
- How do we keep acpi_object_usage.txt in sync with ACPI specs from now
onwards ? Is that what we really want/need ?
- How do we keep arm-acpi.txt in sync with kernel supported ARM64 ACPI
features (if - given that this document is part of the Linux kernel docs -
its aim is to describe what bits of ACPI are supported on arm64 (?)) ?
So, agreed with fixing the typos, agreed with arm-acpi.txt (and with
updating it) which describes how the ARM64 kernel is using ACPI
methods/tables, but acpi_object_usage.txt and in particular describing
in there what methods are _useful_ and what are not, honestly I think we
should ask ourselves what that file is really meant to be.
Happy to send my review comments as a follow-up since overall the patch
is OK, I wanted to ask the basic questions above first.
Thanks,
Lorenzo
>
> diff --git a/Documentation/arm64/acpi_object_usage.txt
> b/Documentation/arm64/acpi_object_usage.txt
> index a6e1a18..756d2f8 100644
> --- a/Documentation/arm64/acpi_object_usage.txt
> +++ b/Documentation/arm64/acpi_object_usage.txt
> @@ -11,15 +11,16 @@ outside of the UEFI Forum (see Section 5.2.6 of the
> specification).
>
> For ACPI on arm64, tables also fall into the following categories:
>
> - -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
> + -- Required: DSDT, FADT, GTDT, IORT, 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
>
>
> Table Usage for ARMv8 Linux
> @@ -50,7 +51,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 +135,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
>
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 04/15/2016 08:37 AM, Lorenzo Pieralisi wrote:
> Hi Al,
>
> On Mon, Mar 28, 2016 at 06:06:42PM -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 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 | 446
>> ++
>> Documentation/arm64/arm-acpi.txt | 28 +-
>> 2 files changed, 357 insertions(+), 117 deletions(-)
>
> I went through this patch twice and before posting my review comments
> I have some questions to _ASK ;-):
>
> - Do we really need acpi_object_usage.txt to list all possible ACPI
>methods in the ACPI specs ("Use as needed") and update them as the
>specs evolve ?
>IMO that's what the ACPI specs are for and that's what AML developers
>will refer to, I do not see the point in listing all methods in that
>file (can't it become an ARM addendum to the ACPI specs at least to
>deprecate methods/tables that are obsolete in ARM's world) ?
The original intent was to provide guidance to those unfamiliar with ACPI,
and in particular provide some details on what usage makes sense on ARM.
In writing it, the objective was that arm-acpi.txt be primarily an overall
view, but that acpi_object_usage.txt answered specific questions about
specific objects, which we got asked about frequently since APCI was very
new on ARM at the time. That being said, however, it is possible that
acpi_object_usage.txt has outlived its usefulness, as those that need to
have become familiar with ACPI.
It doesn't help in the ACPI specs since the idea was to try to document
recommended Linux-specific usage, which may or may not be OS-agnostic, but
would at least be in the open to encourage common usage.
> - How do we keep acpi_object_usage.txt in sync with ACPI specs from now
>onwards ? Is that what we really want/need ?
>
> - How do we keep arm-acpi.txt in sync with kernel supported ARM64 ACPI
>features (if - given that this document is part of the Linux kernel docs -
>its aim is to describe what bits of ACPI are supported on arm64 (?)) ?
Well, maintenance will be necessary as new spec revisions come out, just like
any other part of the kernel code. I don't see anything unique about these
documents versus any other; is there something else in the question that I'm
not seeing?
I guess I just assumed that since I wrote these, I'd be responsible for keeping
them up to date. If you're volunteering to do so, I would not object :-).
> So, agreed with fixing the typos, agreed with arm-acpi.txt (and with
> updating it) which describes how the ARM64 kernel is using ACPI
> methods/tables, but acpi_object_usage.txt and in particular describing
> in there what methods are _useful_ and what are not, honestly I think we
> should ask ourselves what that file is really meant to be.
>
> Happy to send my review comments as a follow-up since overall the patch
> is OK, I wanted to ask the basic questions above first.
>
> Thanks,
> Lorenzo
> [snip...]
Does that help clarify?
--
ciao,
al
---
Al Stone
Software Engineer
Linaro Enterprise Group
al.st...@linaro.org
---
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On Fri, Apr 15, 2016 at 10:41:02AM -0600, Al Stone wrote:
> On 04/15/2016 08:37 AM, Lorenzo Pieralisi wrote:
> > Hi Al,
> >
> > On Mon, Mar 28, 2016 at 06:06:42PM -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 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 | 446
> >> ++
> >> Documentation/arm64/arm-acpi.txt | 28 +-
> >> 2 files changed, 357 insertions(+), 117 deletions(-)
> >
> > I went through this patch twice and before posting my review comments
> > I have some questions to _ASK ;-):
> >
> > - Do we really need acpi_object_usage.txt to list all possible ACPI
> >methods in the ACPI specs ("Use as needed") and update them as the
> >specs evolve ?
> >IMO that's what the ACPI specs are for and that's what AML developers
> >will refer to, I do not see the point in listing all methods in that
> >file (can't it become an ARM addendum to the ACPI specs at least to
> >deprecate methods/tables that are obsolete in ARM's world) ?
>
> The original intent was to provide guidance to those unfamiliar with ACPI,
> and in particular provide some details on what usage makes sense on ARM.
> In writing it, the objective was that arm-acpi.txt be primarily an overall
> view, but that acpi_object_usage.txt answered specific questions about
> specific objects, which we got asked about frequently since APCI was very
> new on ARM at the time. That being said, however, it is possible that
> acpi_object_usage.txt has outlived its usefulness, as those that need to
> have become familiar with ACPI.
>
> It doesn't help in the ACPI specs since the idea was to try to document
> recommended Linux-specific usage, which may or may not be OS-agnostic, but
> would at least be in the open to encourage common usage.
Understood, the point I wanted to make is that adding a list of methods
in acpi_object_usage.txt ("Use as needed") is not necessarily additional
information, you can add a pointer at ACPI specs (for that specific
purpose - as I said there are parts of the patch that add additional
information Linux related) for that purpose instead of having to list
all of them in acpi_object_usage.txt again.
> > - How do we keep acpi_object_usage.txt in sync with ACPI specs from now
> >onwards ? Is that what we really want/need ?
> >
> > - How do we keep arm-acpi.txt in sync with kernel supported ARM64 ACPI
> >features (if - given that this document is part of the Linux kernel docs
> > -
> >its aim is to describe what bits of ACPI are supported on arm64 (?)) ?
>
> Well, maintenance will be necessary as new spec revisions come out, just like
> any other part of the kernel code. I don't see anything unique about these
> documents versus any other; is there something else in the question that I'm
> not seeing?
No, see above.
> I guess I just assumed that since I wrote these, I'd be responsible
> for keeping them up to date. If you're volunteering to do so, I would
> not object :-).
I asked because it is kernel documentation and it has to be reviewed
as such, some updates I found them necessary, adding a list of new
ACPI methods that came up with ACPI 6.1, maybe, but that's already
in the specs, so I question why they should be listed in that file,
unless there is something kernel people really have to know, I will
comment on the specific methods.
> > So, agreed with fixing the typos, agreed with arm-acpi.txt (and with
> > updating it) which describes how the ARM64 kernel is using ACPI
> > methods/tables, but acpi_object_usage.txt and in particular describing
> > in there what methods are _useful_ and what are not, honestly I think we
> > should ask ourselves what that file is really meant to be.
> >
> > Happy to
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 04/15/2016 11:47 AM, Lorenzo Pieralisi wrote:
> On Fri, Apr 15, 2016 at 10:41:02AM -0600, Al Stone wrote:
>> On 04/15/2016 08:37 AM, Lorenzo Pieralisi wrote:
>>> Hi Al,
>>>
>>> On Mon, Mar 28, 2016 at 06:06:42PM -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 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 | 446
++
Documentation/arm64/arm-acpi.txt | 28 +-
2 files changed, 357 insertions(+), 117 deletions(-)
>>>
>>> I went through this patch twice and before posting my review comments
>>> I have some questions to _ASK ;-):
>>>
>>> - Do we really need acpi_object_usage.txt to list all possible ACPI
>>>methods in the ACPI specs ("Use as needed") and update them as the
>>>specs evolve ?
>>>IMO that's what the ACPI specs are for and that's what AML developers
>>>will refer to, I do not see the point in listing all methods in that
>>>file (can't it become an ARM addendum to the ACPI specs at least to
>>>deprecate methods/tables that are obsolete in ARM's world) ?
>>
>> The original intent was to provide guidance to those unfamiliar with ACPI,
>> and in particular provide some details on what usage makes sense on ARM.
>> In writing it, the objective was that arm-acpi.txt be primarily an overall
>> view, but that acpi_object_usage.txt answered specific questions about
>> specific objects, which we got asked about frequently since APCI was very
>> new on ARM at the time. That being said, however, it is possible that
>> acpi_object_usage.txt has outlived its usefulness, as those that need to
>> have become familiar with ACPI.
>>
>> It doesn't help in the ACPI specs since the idea was to try to document
>> recommended Linux-specific usage, which may or may not be OS-agnostic, but
>> would at least be in the open to encourage common usage.
>
> Understood, the point I wanted to make is that adding a list of methods
> in acpi_object_usage.txt ("Use as needed") is not necessarily additional
> information, you can add a pointer at ACPI specs (for that specific
> purpose - as I said there are parts of the patch that add additional
> information Linux related) for that purpose instead of having to list
> all of them in acpi_object_usage.txt again.
I see. That makes sense. How about I collapse those down with something
on the order of "unless otherwise noted, use as needed" and just remove the
ones that have no specific info?
>>> - How do we keep acpi_object_usage.txt in sync with ACPI specs from now
>>>onwards ? Is that what we really want/need ?
>>>
>>> - How do we keep arm-acpi.txt in sync with kernel supported ARM64 ACPI
>>>features (if - given that this document is part of the Linux kernel docs
>>> -
>>>its aim is to describe what bits of ACPI are supported on arm64 (?)) ?
>>
>> Well, maintenance will be necessary as new spec revisions come out, just like
>> any other part of the kernel code. I don't see anything unique about these
>> documents versus any other; is there something else in the question that I'm
>> not seeing?
>
> No, see above.
>
>> I guess I just assumed that since I wrote these, I'd be responsible
>> for keeping them up to date. If you're volunteering to do so, I would
>> not object :-).
>
> I asked because it is kernel documentation and it has to be reviewed
> as such, some updates I found them necessary, adding a list of new
> ACPI methods that came up with ACPI 6.1, maybe, but that's already
> in the specs, so I question why they should be listed in that file,
> unless there is something kernel people really have to know, I will
> comment on the specific methods.
Yup, good point; I can remove the fluff.
>>> So, agreed with fixing the typos, agreed wit
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On Mon, 28 Mar 2016 18:06:42 -0600 Al Stone wrote: > 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. So I'll happily pull this into the docs tree if that seems like the right place for it. I'd really like to see an ack or two first, though, since I'm not really in a position to review it properly myself. Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 04/15/2016 03:35 PM, Jonathan Corbet wrote: > On Mon, 28 Mar 2016 18:06:42 -0600 > Al Stone wrote: > >> 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. > > So I'll happily pull this into the docs tree if that seems like the right > place for it. I'd really like to see an ack or two first, though, since > I'm not really in a position to review it properly myself. > > Thanks, > > jon > Agreed; I'd like to see an ACK or two or three first. Thanks for the offer. Stay tuned, I reckon :). -- ciao, al --- Al Stone Software Engineer Linaro Enterprise Group al.st...@linaro.org --- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On 3/28/16 5:06 PM, Al Stone wrote: For ACPI on arm64, tables also fall into the following categories: - -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT + -- Required: DSDT, FADT, GTDT, IORT, MADT, MCFG, RSDP, SPCR, XSDT Nit: IORT will only be required on certain SBSA platforms using e.g. GICv3-ITS and an SMMU. On e.g. level 0 platforms, it remains optional. Sorry for late comment - just catching up on this thread. Jon. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version
On Fri, Apr 15, 2016 at 11:54:08AM -0600, Al Stone wrote:
[...]
> > Understood, the point I wanted to make is that adding a list of methods
> > in acpi_object_usage.txt ("Use as needed") is not necessarily additional
> > information, you can add a pointer at ACPI specs (for that specific
> > purpose - as I said there are parts of the patch that add additional
> > information Linux related) for that purpose instead of having to list
> > all of them in acpi_object_usage.txt again.
>
> I see. That makes sense. How about I collapse those down with something
> on the order of "unless otherwise noted, use as needed" and just remove the
> ones that have no specific info?
Agreed, that would also help you avoid keeping track of new specs
updates that do not necessarily require updates to these docs.
Lorenzo
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
