| Message ID | 1410530416-30200-19-git-send-email-hanjun.guo@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > From: Graeme Gregory <graeme.gregory@linaro.org> > > Add documentation for the guidelines of how to use ACPI > on ARM64. > > Signed-off-by: Graeme Gregory <graeme.gregory@linaro.org> > Signed-off-by: Hanjun Guo <hanjun.guo@linaro.org> > --- > Documentation/arm64/arm-acpi.txt | 218 ++++++++++++++++++++++++++++++++++++++ > 1 file changed, 218 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..704a9e0 > --- /dev/null > +++ b/Documentation/arm64/arm-acpi.txt > @@ -0,0 +1,218 @@ > +ACPI on ARMv8 Servers > +--------------------- > + > +ACPI can 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 kernel will implement minimum ACPI version is 5.1 + errata as released by > +the UEFI Forum, which is available at <http://www.uefi.org/acpi/specs>. "implements", not "will implement" (assuming the rest of the patch set is merged at the same time as this patch). > +If the machine does not meet the requirements of the SBSA, or cannot be > +described in the required ACPI specifications 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 (including kernel bootargs). > + > +Regardless of whether DT or ACPI is used, the kernel must always be capable > +of booting with either scheme (in kernels with both schemes enabled at compile > +time). > + > +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 32-bit 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. This wording (DO NOT, MUST, etc) doesn't make sense in this doc. You're not instructing a firmware vendor how to implement their firmware here, you're documenting what the kernel expects from it. > + > +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 Recommendations" section. > + > +In non-driver code If the presence of ACPI needs to be detected at runtime, "code If" looks odd here. > +then check the value of acpi_disabled. If CONFIG_ACPI is not set, > +acpi_disabled will always be 1. > + > +Device Enumeration > +------------------ > + > +Device descriptions in ACPI should use standard recognized 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. s/simpler/contains less information/ This is a key point in this doc (use sensible defaults), and I expect it's one of the major ones that people will get wrong. A bit of elaboration would be good. > + > +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 represented with the appropriate _DSD (ACPI Section 6.2.5) > +structure. _DSM (ACPI Section 9.14.1) should only be used if _DSD cannot > +represent the data required. > + > +This data should be rare and not OS specific. For x86 ACPI has taken to > +identifying itself as Windows because it was found that only one path was > +routinely tested. For ARMv8 it would be preferable to have only one well > +tested path. > + > +_DSD covers more than the generic server case and care should be taken not to > +replicate highly specific embedded behaviour from DT into generic servers. > + > +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 > + > +If these bindings are mirrored from DT care should be taken to ensure they are > +reviewed as DT bindings before submission to limit divergance in bindings. Some of the above is again not suitable language for this document. And again, this is likely the wrong place to educate system firware developers on how to describe their hardware. > + > +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. > + > +The ACPI 5.1 specification does not contain any standard binding for these > +objects to enable programmable levels or rates so this should be avoided if > +possible and the resources set to appropriate levels 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 organize that it is allocated/enabled using the _PS0 method. Again, some of this seems like the wrong place to mandate how firmware works. If anything, it can be rephrased as "the kernel assumes that ASL will handle power resource management/enablement through the _PS0 method", etc. > +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. > + > +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 devices aren't affected by the lack of clock tree representation, but they are affected by a possibly variable input clock to their blocks. That's quite a big difference. > +The firmware (for example, UEFI) should initialize these clocks to fixed working > +values before the kernel is executed. Add: ", such that the driver can be hardcoded to assume those frequencies". :-( > + > +Driver Recommendations > +---------------------- > + > +DO NOT remove any FDT handling when adding ACPI support for a driver. Different > +systems may use the same device. s/FDT/DT/ > + > +DO try and keep complex sections of ACPI and DT functionality separate. 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. The above can be read as we're preferring to split the driver in two with as much code path divergence as possible. Instead, splitting probing in two but making the rest of the driver mostly execute off of data (i.e. setup internal per-device state in a struct based on defaults + what you discover at probe) is a much better approach, and it's what we have been pushing for in the platform code as well. > +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 Since docs go stale all the time, please refer to 5.1 instead of "current" here. > +Specification Working Group (ASWG) <http://www.uefi.org/workinggroups>. > +Participation in this group is open to all UEFI members. > + > + - ACPI based CPU topology > + - ACPI based Power management > + - CPU idle control based on PSCI > + - CPU performance control (CPPC) > + - ACPI based SMMU > + - ITS support for GIC in MADT > + > +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. Technically this is untrue and should at least be rephrased. We're likely to at some point need to deal with bad tables that need quirks and fixups, just like we've had to do on other systems. -Olof
On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > +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 How are individuals/companies who aren't UEFI members supposed to do this? Aren't there IP issues involved in taking submissions from non-members? > +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. Similar question here. Is the expectation that all ARM vendors will become UEFI contributors?
On Wed, Sep 17, 2014 at 02:44:10AM +0100, Matthew Garrett wrote: > On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > > +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. > > Similar question here. Is the expectation that all ARM vendors will > become UEFI contributors? I should also add that this is inconsistent with how we've managed things in the x86 world - there's a great deal of ACPI functionality implemented that's not covered in the spec.
On 09/16/2014 09:44 PM, Matthew Garrett wrote: > On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > >> +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 > > How are individuals/companies who aren't UEFI members supposed to do > this? Aren't there IP issues involved in taking submissions from > non-members? Obviously, I'm not a lawyer, but I would note that the _DSD bindings aren't going into the core ACPI document. I think the specifics for non members of the UEFI to potentially contribute bindings need to be addressed. That said, at this point, the population of the UEFI forum is very well aligned with initial players (that this is the case is not entirely an accident, I went around to a few folks a year or so ago and made sure that they had become members in anticipation of this issue). Jon.
On Wed, Sep 17, 2014 at 02:44:10AM +0100, Matthew Garrett wrote: > On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > > > +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 > > How are individuals/companies who aren't UEFI members supposed to do > this? Aren't there IP issues involved in taking submissions from > non-members? > This section needs to be changed anyway, it comes out of a misunderstanding I had of the _DSD spec. It sounds like from the discussions in other threads that ARM64 should be following x86 and re-using DT bindings here. In which case there is not need to submit things to UEFI organisation. What I got a little lost in has there been a formal decision about DT bindings in _DSD? Graeme
On Wed, Sep 17, 2014 at 04:58:10AM -0400, Jon Masters wrote: > On 09/16/2014 09:44 PM, Matthew Garrett wrote: > >> +http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel.htm > > How are individuals/companies who aren't UEFI members supposed to do > > this? Aren't there IP issues involved in taking submissions from > > non-members? > Obviously, I'm not a lawyer, but I would note that the _DSD bindings > aren't going into the core ACPI document. I think the specifics for non > members of the UEFI to potentially contribute bindings need to be > addressed. That said, at this point, the population of the UEFI forum is > very well aligned with initial players (that this is the case is not > entirely an accident, I went around to a few folks a year or so ago and > made sure that they had become members in anticipation of this issue). Are you sure you've covered all the vendors of off-SoC components who might be involved? That's certainly already an issue with people doing x86 machines (who aren't being bound by this spec but as a subsystem maintainer how am I supposed to tell if the target is an ARM or x86 system?).
On Wed, Sep 17, 2014 at 09:37:42PM +0200, Rafael J. Wysocki wrote: > There are no implied IP issues with using the information there I know of and > if there's any fine print anywhere that may suggest so, please let me know. Using the information should be fine, but my understanding of the UEFI forum rules is that any submissions to UEFI specs must be from UEFI forum members - there are concerns around accidentally including patented material. The easy way around this is just for the bindings to be managed outside UEFI.
On 09/17/2014 03:22 PM, Matthew Garrett wrote: > On Wed, Sep 17, 2014 at 09:37:42PM +0200, Rafael J. Wysocki wrote: > >> There are no implied IP issues with using the information there I know of and >> if there's any fine print anywhere that may suggest so, please let me know. > > Using the information should be fine, but my understanding of the UEFI > forum rules is that any submissions to UEFI specs must be from UEFI > forum members - there are concerns around accidentally including > patented material. The easy way around this is just for the bindings to > be managed outside UEFI. I've raised this with Dong in person this morning and I'll ask him to followup on UEFI policy. Jon.
On Wednesday, September 17, 2014 02:44:10 AM Matthew Garrett wrote: > On Fri, Sep 12, 2014 at 10:00:16PM +0800, Hanjun Guo wrote: > > > +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 Well, the intention here is different. The linked document is supposed to define the format of data to be returned by _DSD and the one at: http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf does it specifically for the UUID associated with the DT bindings format. There are no implied IP issues with using the information there I know of and if there's any fine print anywhere that may suggest so, please let me know. That said, those documents are not intended to be libraries of actual bindings. A common place for the binding and a process for submitting/accepting them is needed, but we are yet to agree on how to do that. Rafael
On Wed, Sep 17, 2014 at 10:11:13PM +0200, Rafael J. Wysocki wrote: > On Wednesday, September 17, 2014 08:22:59 PM Matthew Garrett wrote: > > Using the information should be fine, but my understanding of the UEFI > > forum rules is that any submissions to UEFI specs must be from UEFI > > forum members - there are concerns around accidentally including > > patented material. > > The documents in question are not regarded as UEFI specs, however. They > are just hosted by UEFI. There's arguably some precedent for that - the ACPI vendor IDs and EFI System Partition name repositories are hosted rather than specs. But it seems like there's some qualitative difference between that kind of raw data and something that actually defines behaviour. But if the UEFI people feel comfortable with this, it's not a problem.
On Wednesday, September 17, 2014 08:22:59 PM Matthew Garrett wrote: > On Wed, Sep 17, 2014 at 09:37:42PM +0200, Rafael J. Wysocki wrote: > > > There are no implied IP issues with using the information there I know of and > > if there's any fine print anywhere that may suggest so, please let me know. > > Using the information should be fine, but my understanding of the UEFI > forum rules is that any submissions to UEFI specs must be from UEFI > forum members - there are concerns around accidentally including > patented material. The documents in question are not regarded as UEFI specs, however. They are just hosted by UEFI. > The easy way around this is just for the bindings to > be managed outside UEFI. Again, there's a difference between UEFI material and the UEFI hosting something (but not maintaining it). In principle, the bindings could be hosted by UEFI, but maintained by community members. Rafael
On 2014?09?18? 04:11, Rafael J. Wysocki wrote: > On Wednesday, September 17, 2014 08:22:59 PM Matthew Garrett wrote: >> On Wed, Sep 17, 2014 at 09:37:42PM +0200, Rafael J. Wysocki wrote: >> >>> There are no implied IP issues with using the information there I know of and >>> if there's any fine print anywhere that may suggest so, please let me know. >> Using the information should be fine, but my understanding of the UEFI >> forum rules is that any submissions to UEFI specs must be from UEFI >> forum members - there are concerns around accidentally including >> patented material. > The documents in question are not regarded as UEFI specs, however. They > are just hosted by UEFI. > >> The easy way around this is just for the bindings to >> be managed outside UEFI. > Again, there's a difference between UEFI material and the UEFI hosting > something (but not maintaining it). > > In principle, the bindings could be hosted by UEFI, but maintained by > community members. Thanks for the clarify, I totally agree with you, that's how things work now for such doc hosted by UEFI. For now, _DSD will use the same binding as DT, is there any chance that _DSD will introduce new bindings? if yes, how can we handle it? Thanks Hanjun
On Wednesday 17 September 2014, Graeme Gregory wrote: > It sounds like from the discussions in other threads that ARM64 should > be following x86 and re-using DT bindings here. In which case there is > not need to submit things to UEFI organisation. > > What I got a little lost in has there been a formal decision about DT > bindings in _DSD? I think this is a discussion that still needs to happen: either we should recommend everyone to use _DSD in favor of the alternatives, or we should prohibit the use of _DSD. I have heard arguments both ways, but hopefully we can find an easy answer. Arnd
On Thu, Sep 18, 2014 at 01:22:10AM +0200, Arnd Bergmann wrote: > On Wednesday 17 September 2014, Graeme Gregory wrote: > > It sounds like from the discussions in other threads that ARM64 should > > be following x86 and re-using DT bindings here. In which case there is > > not need to submit things to UEFI organisation. > > > > What I got a little lost in has there been a formal decision about DT > > bindings in _DSD? > > I think this is a discussion that still needs to happen: either we should > recommend everyone to use _DSD in favor of the alternatives, or we > should prohibit the use of _DSD. I have heard arguments both ways, but > hopefully we can find an easy answer. > This discussion is just not going to happen until people at @redhat.com and people who have currently announced/released hardware are actually willing to start talking about it. Id love to be able to put my foot down and ban the use of _DSD for servers but I suspect that will not happen. Graeme
On Thu, Sep 18, 2014 at 12:40:36AM +0100, Graeme Gregory wrote: > On Thu, Sep 18, 2014 at 01:22:10AM +0200, Arnd Bergmann wrote: > > On Wednesday 17 September 2014, Graeme Gregory wrote: > > > It sounds like from the discussions in other threads that ARM64 should > > > be following x86 and re-using DT bindings here. In which case there is > > > not need to submit things to UEFI organisation. > > > > > > What I got a little lost in has there been a formal decision about DT > > > bindings in _DSD? > > > > I think this is a discussion that still needs to happen: either we should > > recommend everyone to use _DSD in favor of the alternatives, or we > > should prohibit the use of _DSD. I have heard arguments both ways, but > > hopefully we can find an easy answer. > > This discussion is just not going to happen until people at @redhat.com > and people who have currently announced/released hardware are actually > willing to start talking about it. OTOH, there doesn't seem to be any urgency for merging arm64 ACPI support, so this discussion can wait ;). > Id love to be able to put my foot down and ban the use of _DSD for > servers but I suspect that will not happen. And the alternative would be hard-coded platform specific configuration (or we assume that such configuration isn't needed)?
On Wednesday, September 17, 2014 04:40:36 PM Graeme Gregory wrote: > On Thu, Sep 18, 2014 at 01:22:10AM +0200, Arnd Bergmann wrote: > > On Wednesday 17 September 2014, Graeme Gregory wrote: > > > It sounds like from the discussions in other threads that ARM64 should > > > be following x86 and re-using DT bindings here. In which case there is > > > not need to submit things to UEFI organisation. > > > > > > What I got a little lost in has there been a formal decision about DT > > > bindings in _DSD? > > > > I think this is a discussion that still needs to happen: either we should > > recommend everyone to use _DSD in favor of the alternatives, or we > > should prohibit the use of _DSD. I have heard arguments both ways, but > > hopefully we can find an easy answer. > > > > This discussion is just not going to happen until people at @redhat.com > and people who have currently announced/released hardware are actually > willing to start talking about it. > > Id love to be able to put my foot down and ban the use of _DSD for > servers but I suspect that will not happen. I'll probably should stay away from this discussion, but I can't resist. :-) Please imagine the situation in which the same IP block is included in an ARM64 SoC and in an x86 SoC that ships with ACPI tables and a _DSD for that device in them. What benefit would be there from disallowing systems based on the ARM64 SoC in question to ship the same _DSD in their ACPI tables?
On 09/18/2014 07:20 PM, Rafael J. Wysocki wrote: > On Wednesday, September 17, 2014 04:40:36 PM Graeme Gregory wrote: >> On Thu, Sep 18, 2014 at 01:22:10AM +0200, Arnd Bergmann wrote: >>> On Wednesday 17 September 2014, Graeme Gregory wrote: >>>> It sounds like from the discussions in other threads that ARM64 should >>>> be following x86 and re-using DT bindings here. In which case there is >>>> not need to submit things to UEFI organisation. >>>> >>>> What I got a little lost in has there been a formal decision about DT >>>> bindings in _DSD? >>> >>> I think this is a discussion that still needs to happen: either we should >>> recommend everyone to use _DSD in favor of the alternatives, or we >>> should prohibit the use of _DSD. I have heard arguments both ways, but >>> hopefully we can find an easy answer. >>> >> >> This discussion is just not going to happen until people at @redhat.com >> and people who have currently announced/released hardware are actually >> willing to start talking about it. >> >> Id love to be able to put my foot down and ban the use of _DSD for >> servers but I suspect that will not happen. > > I'll probably should stay away from this discussion, but I can't resist. :-) > > Please imagine the situation in which the same IP block is included in an ARM64 > SoC and in an x86 SoC that ships with ACPI tables and a _DSD for that device in > them. What benefit would be there from disallowing systems based on the ARM64 > SoC in question to ship the same _DSD in their ACPI tables? "Disallowing" is a strong word in any case, because vendors own the platform and will ship _DSD properties to describe those devices. So the only "disallowing" Linux can do is to ignore entities present in ACPI tables that have already been shipped by vendors. Anyway. I think we all don't want a runaway frenzy with _DSD key/values (generally there ought to be as few as possible, and additions should only happen carefully). Broadly, there are three levels I see here: 0). Devices that are part of the core ACPI specification. None today need key/value pairs, and I want to avoid this from growing. 1). Devices containing _DSD key/value pairs for a specific device but of a common industry type, such as a network device. In this case, the 4-6 properties that might need to be specified (MAC address, PHY address, PHY type, etc.) should be as minimal as possible and then standardized into a common binding that vendors agree to support, and which is owned and controlled by a neutral group such as ASWG. 2). Devices containining a specific ACPI ID that is unique to a given vendor where that device implements value-add/offload/something non core that can be owned entirely within a driver for one device. In that case, maybe a vendor would define a minimal set of _DSD key/values and be on the hook to maintain compatibility themselves. I've chatted with a few people, and there will be a nice proposal presented to ASWG/UEFI on how to provide an official process for defining key/value pairs that are shared between common device types and managed by such a forum, as in the cases 0 and 1 above. In the meanwhile, there is only one _DSD use case in the early ACPI patches for ARM servers (in the network MAC, to pass in the mac address and a couple of PHY address/ID bits) and I've connected the vendors together asking them to come up with the initial first example covering that. None of this is core to ACPI enablement. It's specific to a few drivers where also on x86 there will be _DSD properties. Jon.
On Fri 2014-09-12 22:00:16, Hanjun Guo wrote: > From: Graeme Gregory <graeme.gregory@linaro.org> > > Add documentation for the guidelines of how to use ACPI > on ARM64. > +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. Surely this should be narrowed down somehow? Or is reading all the released standards from ASWG mandatory before patching the kernel now? Spelling out wtf ECR is would be nice, too. And if you expect all kernel contributors to comply with your favourite standards, you should put an URL where the standards can be downloaded here. Pavel
On Mon, Sep 22, 2014 at 09:48:41PM +0200, Pavel Machek wrote: > On Fri 2014-09-12 22:00:16, Hanjun Guo wrote: > > +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. > > Surely this should be narrowed down somehow? Or is reading all the > released standards from ASWG mandatory before patching the kernel now? > > Spelling out wtf ECR is would be nice, too. Explicit Change Request. These can only be filed by paid-up members of the UEFI Forum, so I suspect this requirement is going to be unworkable (there's plenty of ACPI support code for large x86 vendors which isn't part of any ACPI spec)
On Tue, Sep 23, 2014 at 12:46:24AM +0200, Rafael J. Wysocki wrote: > On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: > > Explicit Change Request. These can only be filed by paid-up members of > > the UEFI Forum, so I suspect this requirement is going to be unworkable > > (there's plenty of ACPI support code for large x86 vendors which isn't > > part of any ACPI spec). > > Why do you think so? The IP rules in the membership agreements. > Linux Foundation can do that on behalf of the community if no one else. Unfortunately not - any work contributed must be the work of the contributing member. There can't be any public discussion.
On Sep 23, 2014, 06:28AM, Matthew Garrett wrote: > On Tue, Sep 23, 2014 at 12:46:24AM +0200, Rafael J. Wysocki wrote: >> On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: >>> Explicit Change Request. These can only be filed by paid-up members of >>> the UEFI Forum, so I suspect this requirement is going to be unworkable >>> (there's plenty of ACPI support code for large x86 vendors which isn't >>> part of any ACPI spec). >> Why do you think so? > The IP rules in the membership agreements. If I'm not mistaken, I think there is no IP issues for the _DSD bindings, it just some key value pairs. Thanks Hanjun
On Tue, Sep 23, 2014 at 06:34:42AM +0800, Hanjun Guo wrote: > On Sep 23, 2014, 06:28AM, Matthew Garrett wrote: > > On Tue, Sep 23, 2014 at 12:46:24AM +0200, Rafael J. Wysocki wrote: > >> On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: > >>> Explicit Change Request. These can only be filed by paid-up members of > >>> the UEFI Forum, so I suspect this requirement is going to be unworkable > >>> (there's plenty of ACPI support code for large x86 vendors which isn't > >>> part of any ACPI spec). > >> Why do you think so? > > The IP rules in the membership agreements. > > If I'm not mistaken, I think there is no IP issues for the _DSD bindings, > it just some key value pairs. That paragraph is talking about ACPI support in general, not just the _DSD code.
On 09/22/2014 01:48 PM, Pavel Machek wrote: > On Fri 2014-09-12 22:00:16, Hanjun Guo wrote: >> From: Graeme Gregory <graeme.gregory@linaro.org> >> >> Add documentation for the guidelines of how to use ACPI >> on ARM64. > >> +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. > > Surely this should be narrowed down somehow? Or is reading all the > released standards from ASWG mandatory before patching the kernel now? Asking someone to read the ACPI standard when implementing ACPI functionality is no different than doing the same thing for PCI, SCSI, TCP/IP or any of a bazillion others that are used by the kernel. Yes, the wording of this sentence is awkward; that's a very different problem and easily fixed. > Spelling out wtf ECR is would be nice, too. ECR stands for "Engineering Change Request". It is simply a recommended document format for requesting changes to be made to the ACPI specification (and is also used by other UEFI working groups). The text can easily be fixed to make that clear. > And if you expect all kernel contributors to comply with your > favourite standards, you should put an URL where the standards can be > downloaded here. > Easily enough corrected; until the patch is updated, one can find the specs at the oh so very cleverly named URL: http://www.uefi.org/specifications
On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: > On Mon, Sep 22, 2014 at 09:48:41PM +0200, Pavel Machek wrote: > > On Fri 2014-09-12 22:00:16, Hanjun Guo wrote: > > > +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. > > > > Surely this should be narrowed down somehow? Or is reading all the > > released standards from ASWG mandatory before patching the kernel now? > > > > Spelling out wtf ECR is would be nice, too. > > Explicit Change Request. These can only be filed by paid-up members of > the UEFI Forum, so I suspect this requirement is going to be unworkable > (there's plenty of ACPI support code for large x86 vendors which isn't > part of any ACPI spec). Why do you think so? Linux Foundation can do that on behalf of the community if no one else.
On 09/22/2014 04:46 PM, Rafael J. Wysocki wrote: > On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: >> On Mon, Sep 22, 2014 at 09:48:41PM +0200, Pavel Machek wrote: >>> On Fri 2014-09-12 22:00:16, Hanjun Guo wrote: >>>> +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. >>> >>> Surely this should be narrowed down somehow? Or is reading all the >>> released standards from ASWG mandatory before patching the kernel now? >>> >>> Spelling out wtf ECR is would be nice, too. >> >> Explicit Change Request. Actually, it's "Engineering Change Request" -- a standard document format used by several of the UEFI working groups, including the ASWG. These can only be filed by paid-up members of >> the UEFI Forum, so I suspect this requirement is going to be unworkable >> (there's plenty of ACPI support code for large x86 vendors which isn't >> part of any ACPI spec). > > Why do you think so? > > Linux Foundation can do that on behalf of the community if no one else. > Exactly so. Or, collaborate with the hardware vendor, or a distro or anyone else that is a Promoter or Contributor as defined by UEFI [0]. The only thing to keep clear when doing so is who owns the intellectual property for any proposed change; this is one of the reasons the UEFI Forum has paid membership levels -- to pay for the legal assistance to make sure that the specs can be freely used. As someone who is part of the ASWG, I'd personally be glad to help out however I can in this regard. I'm also curious as to what's being referred to as ACPI support code for large x86 vendors which is not part of the spec; I *think* I know what's being described but a specific example would really help me understand better. Thanks. [0] http://www.uefi.org/join
On Mon, Sep 22, 2014 at 04:55:48PM -0600, Al Stone wrote: > Exactly so. Or, collaborate with the hardware vendor, or a distro > or anyone else that is a Promoter or Contributor as defined by UEFI > [0]. The only thing to keep clear when doing so is who owns the > intellectual property for any proposed change; this is one of the > reasons the UEFI Forum has paid membership levels -- to pay for the > legal assistance to make sure that the specs can be freely used. As > someone who is part of the ASWG, I'd personally be glad to help out > however I can in this regard. No, it's not about IP ownership, it's about whether those contributing the IP have waived patent rights. All contributors to a UEFI spec must be members - it's not acceptable for a member to contribute material on behalf of a non-member. > I'm also curious as to what's being referred to as ACPI support > code for large x86 vendors which is not part of the spec; I *think* > I know what's being described but a specific example would really > help me understand better. Almost everything in drivers/platform/x86, the ACPI support code under drivers/gpu, the PCC code for HP servers, some of the USB-ACPI glue (defined by a Microsoft spec), some of the ACPI/TPM integration (defined by TCG), some hwmon code, probably a few other bits and pieces.
On Tuesday, September 23, 2014 06:34:42 AM Hanjun Guo wrote: > On Sep 23, 2014, 06:28AM, Matthew Garrett wrote: > > On Tue, Sep 23, 2014 at 12:46:24AM +0200, Rafael J. Wysocki wrote: > >> On Monday, September 22, 2014 09:31:36 PM Matthew Garrett wrote: > >>> Explicit Change Request. These can only be filed by paid-up members of > >>> the UEFI Forum, so I suspect this requirement is going to be unworkable > >>> (there's plenty of ACPI support code for large x86 vendors which isn't > >>> part of any ACPI spec). > >> Why do you think so? > > The IP rules in the membership agreements. > > If I'm not mistaken, I think there is no IP issues for the _DSD bindings, > it just some key value pairs. Well, if we are talking about the bindings themselves only, then as I said previously that would be a hosted document rather than a UEFI specification anyway, so I don't see how the "IP rules in the membership agreements" would apply to that in any case.
diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.txt new file mode 100644 index 0000000..704a9e0 --- /dev/null +++ b/Documentation/arm64/arm-acpi.txt @@ -0,0 +1,218 @@ +ACPI on ARMv8 Servers +--------------------- + +ACPI can 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 kernel will implement minimum ACPI version is 5.1 + errata as released by +the UEFI Forum, which is available at <http://www.uefi.org/acpi/specs>. + +If the machine does not meet the requirements of the SBSA, or cannot be +described in the required ACPI specifications 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 (including kernel bootargs). + +Regardless of whether DT or ACPI is used, the kernel must always be capable +of booting with either scheme (in kernels with both schemes enabled at compile +time). + +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 32-bit 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 Recommendations" section. + +In non-driver code If the presence of ACPI needs to be detected at runtime, +then check the value of acpi_disabled. If CONFIG_ACPI is not set, +acpi_disabled will always be 1. + +Device Enumeration +------------------ + +Device descriptions in ACPI should use standard recognized 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 represented with the appropriate _DSD (ACPI Section 6.2.5) +structure. _DSM (ACPI Section 9.14.1) should only be used if _DSD cannot +represent the data required. + +This data should be rare and not OS specific. For x86 ACPI has taken to +identifying itself as Windows because it was found that only one path was +routinely tested. For ARMv8 it would be preferable to have only one well +tested path. + +_DSD covers more than the generic server case and care should be taken not to +replicate highly specific embedded behaviour from DT into generic servers. + +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 + +If these bindings are mirrored from DT care should be taken to ensure they are +reviewed as DT bindings before submission to limit divergance in bindings. + +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. + +The ACPI 5.1 specification does not contain any standard binding for these +objects to enable programmable levels or rates so this should be avoided if +possible and the resources set to appropriate levels 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 organize 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. + +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 initialize these clocks to fixed working +values before the kernel is executed. + +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 separate. 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() :- + +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) +{ + ... + struct device_node node = pdev->dev.of_node; + ... + + if (node) + ret = device_probe_dt(pdev); + else if (ACPI_HANDLE(&pdev->dev)) + ret = device_probe_acpi(pdev); + else + /* other initialization */ + ... + /* 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); + +ASWG +---- + +The following areas are not yet well defined for ARM in the current ACPI +specification and are expected to be worked through in the UEFI ACPI +Specification Working Group (ASWG) <http://www.uefi.org/workinggroups>. +Participation in this group is open to all UEFI members. + + - ACPI based CPU topology + - ACPI based Power management + - CPU idle control based on PSCI + - CPU performance control (CPPC) + - ACPI based SMMU + - ITS support for GIC in MADT + +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.