| Message ID | 1413553034-20956-19-git-send-email-hanjun.guo@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 2014年12月19日 04:01, Suravee Suthikulanit wrote: > On 10/17/2014 8:37 AM, 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: Al Stone <al.stone@linaro.org> >> Signed-off-by: Hanjun Guo <hanjun.guo@linaro.org> >> --- >> Documentation/arm64/arm-acpi.txt | 323 >> ++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 323 insertions(+) >> create mode 100644 Documentation/arm64/arm-acpi.txt >> [...] > > AMD has reviewed this document, and currently implements ACPI table in > the firmware for AMD Seattle platform based on the documentation > published here: > > http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf > > > Reviewed-by: Suravee Suthikulpanit <Suravee.Suthikulpanit@amd.com> Thank you very much, Suravee. Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Timur, On 2014年12月19日 04:04, Timur Tabi wrote: > On Fri, Oct 17, 2014 at 8:37 AM, Hanjun Guo <hanjun.guo@linaro.org> wrote: > >> If acpi=force is used, the kernel >> +will ONLY use device configuration information contained in the ACPI tables. > > Based on this statement, ... > >> +In order for the kernel to load and use ACPI tables, the UEFI implementation >> +MUST set the ACPI_20_TABLE_GUID to point to the RSDP table (the table with >> +the ACPI signature "RSD PTR "). If this pointer is incorrect and acpi=force >> +is used, the kernel will disable ACPI and try to use DT to boot. > > wouldn't it be more correct to say "If this pointer is incorrect OR > acpi=force is used"? Good catch, some inconsistency here. Actually it means if the pointer to RSDP is incorrect, the ACPI code will catch that error, then ACPI will be disabled and tries to boot with DT even if acpi=force is passed, I think that makes sense. I will fix the inconsistency anyway in next version. > >> +Forum provides a mechanism for registering such bindings [URL TBD by ASWG] > > Did you intend to replace the text in []? Yes, it is TBD by ASWG, and we already agreed that the bindings will be reviewed by ASWG which proposed by Al. the URL will be ready when next version of ACPI spec is released. > >> +so that they may be used on any operating system supporting ACPI. Device >> +properties that have not been registered with the UEFI Forum should not be >> +used. > > Blech. I guess it's necessary, but the information needs to be documented here. > >> +Drivers should look for device properties in the _DSD object ONLY; the _DSD >> +object is described in the ACPI specification section 6.2.5, but more >> +specifically, use the _DSD Device Properties UUID: >> + >> + -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 >> + >> + -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf) > > Extra ) here. Good catch :) > >> +The kernel has an interface for looking up device properties in a manner >> +independent of whether DT or ACPI is being used and that interface should >> +be used; it can eliminate some duplication of code paths in driver probing >> +functions and discourage divergence between DT bindings and ACPI device >> +properties. > > How about a pointer to the documentation for this method? This is a patch set posted by Rafael and goes into 3.19: https://lkml.org/lkml/2014/10/21/762 No documentation as far as I know. > >> +Such code in _PS? methods will of course be very platform specific. But, > > I would use _PSx instead of _PS? here. I will update it. > >> +this allows the driver to abstract out the interface for operating the device >> +and avoid having to read special non-standard values from ACPI tables. Further, >> +abstracting the use of these resources allows the hardware to change over time >> +without requiring updates to the driver. >> + >> + >> +Clocks >> +------ >> +ACPI makes the assumption that clocks are initialized by the firmware -- >> +UEFI, in this case -- to some working value before control is handed over >> +to the kernel. This has implications for devices such as UARTs, or SoC >> +driven LCD displays, for example. > > SOC-driven should be hyphenated. > >> +When the kernel boots, the clock is assumed to be set to reasonable > > to A reasonable > >> +working value. If for some reason the frequency needs to change -- e.g., >> +throttling for power management -- the device driver should expect that >> +process to be abstracted out into some ACPI method that can be invoked >> +(please see the ACPI specification for further recommendations on standard >> +methods to be expected). If is not, there is no direct way for ACPI to > > If IT is not > >> +control the clocks. >> + >> + >> +Driver Recommendations >> +---------------------- >> +DO NOT remove any DT handling when adding ACPI support for a driver. The >> +same device may be used on many different systems. >> + >> +DO try to structure the driver so that it is data driven. That is, set up > > data-driven I will update them. Thanks a lot for your review! Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi, On 2014年12月25日 01:18, Catalin Marinas wrote: > Hi, > > Some thoughts before the end of the year. I won't be able to follow up > until around 5th of January though. > > On Fri, Oct 17, 2014 at 02:37:14PM +0100, Hanjun Guo wrote: >> --- /dev/null >> +++ b/Documentation/arm64/arm-acpi.txt >> @@ -0,0 +1,323 @@ >> +ACPI on ARMv8 Servers >> +--------------------- >> +ACPI can be used for ARMv8 general purpose servers designed to follow >> +the ARM SBSA (Server Base System Architecture) specification, currently >> +available to those with an ARM login at http://silver.arm.com. > > You should mention SBBR (Server Base Boot Requirements) here as well. > The arm-acpi.txt is complementary to arm-acpi.txt and longer term we > should aim to move parts of the Linux document into the more OS-agonstic > SBBR. ok, I will update the doc. and I agree that moving parts of this doc into SBBR, actually part of the content is coming from SBBR, especially section "Booting using ACPI tables" (not include the command line part). please refer to section 4.2 ACPI Tables in SBBR. > >> +The ARMv8 kernel implements the reduced hardware model of ACPI version >> +5.1 and its corresponding errata. > > I would say 5.1 or later to avoid updating this document every time we > get a new ACPI release. sure, will update it. > >> +If an ARMv8 system does not meet the requirements of the SBSA, or cannot >> +be described using the mechanisms defined in the required ACPI specifications, >> +then it is likely that Device Tree (DT) is more suitable than ACPI for the >> +hardware. > > Based on some private discussions, I think we could drop some of the > references to DT in this document. It should specify the requirements > for ACPI support and, if not met, the alternative SoC support is > automatically DT for Linux. That's just to make it easier to move parts > of this doc into SBBR. > >> +Relationship with Device Tree >> +----------------------------- > > This section is fine, Linux specific and it will stay in this document. > >> +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. > > I don't think this paragraph is needed. That's a kernel detail when how > the EFI_STUB passes the information to the rest of the kernel. We > mandate UEFI booting for ACPI support, so I wouldn't expect an > ACPI-aware U-Boot. Agree, we can boot kernel ok without passing the dtb to kernel in the command line if ACPI presents. > >> +Booting using ACPI tables >> +------------------------- >> +The only defined method for passing ACPI tables to the kernel on ARMv8 >> +is via the UEFI system configuration table. >> + >> +Processing of ACPI tables may be disabled by passing acpi=off on the kernel >> +command line; this is the default behavior. If acpi=force is used, the kernel >> +will ONLY use device configuration information contained in the ACPI tables. > > See my comments to Al around the defaults. I think if only ACPI tables > are present, we shouldn't panic the kernel if acpi=force is missing but > continue with ACPI. I think we need another patch to implement it, for this patch set,kernel will panic if no dtb and acpi=off. since passing no DT tables to OS but acpi=force is missing is a corner case, we can do a follow up patch to fix that, does it make sense? > If both DT and ACPI tables are present, DT will be > the default. You could say "this is the default behaviour if both ACPI > and DT tables are present". > >> +Device Enumeration >> +------------------ >> +Device descriptions in ACPI should use standard recognized ACPI interfaces. >> +These can contain less information than is typically provided via a Device > > s/can/may/ ? Not sure, it just sounds better to me (not a native English > speaker). > >> +Tree description for the same device. This is also one of the reasons that >> +ACPI can be useful -- the driver takes into account that it may have less >> +detailed information about the device and uses sensible defaults instead. >> +If done properly in the driver, the hardware can change and improve over >> +time without the driver having to change at all. >> + >> +Clocks provide an excellent example. In DT, clocks need to be specified >> +and the drivers need to take them into account. In ACPI, the assumption >> +is that UEFI will leave the device in a reasonable default state, including >> +any clock settings. If for some reason the driver needs to change a clock >> +value, this can be done in an ACPI method; all the driver needs to do is >> +invoke the method and not concern itself with what the method needs to do >> +to change the clock. Changing the hardware can then take place over time >> +by changing what the ACPI method does, and not the driver. >> + >> +ACPI drivers should only look at one specific ASL object -- the _DSD object >> +-- for device driver parameters (known in DT as "bindings", or "Device >> +Properties" in ACPI). Not all DT bindings will be recognized. > > This last sentence kind of implies that many of the DT bindings will be > recognised. While it is useful to have some commonalities, I think this > gives the wrong message that _DSD is a copy of DT. We should avoid this. > >> The UEFI >> +Forum provides a mechanism for registering such bindings [URL TBD by ASWG] > > s/bindings/properties/ if we talk in the ACPI context. > >> +so that they may be used on any operating system supporting ACPI. Device >> +properties that have not been registered with the UEFI Forum should not be >> +used. > > More about this further down. > >> +Drivers should look for device properties in the _DSD object ONLY; the _DSD >> +object is described in the ACPI specification section 6.2.5, but more >> +specifically, use the _DSD Device Properties UUID: >> + >> + -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 >> + >> + -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf) >> + >> +The kernel has an interface for looking up device properties in a manner >> +independent of whether DT or ACPI is being used and that interface should >> +be used; > > I haven't followed the _DSD kernel support but does it provide a common > API to be shared with DT? I'm not entirely convinced it's a good idea. > >> it can eliminate some duplication of code paths in driver probing >> +functions and discourage divergence between DT bindings and ACPI device >> +properties. > > Given the current different mechanism of reviewing/approving bindings > between DT and ACPI (kernel community vs UEFI forum), I don't see how we > encourage convergence (unless we state that _DSD are Linux-only, Windows > should use a different mechanism like .inf files). > >> +ACPI tables are described with a formal language called ASL, the ACPI >> +Source Language (section 19 of the specification). This means that there >> +are always multiple ways to describe the same thing -- including device >> +properties. For example, device properties could use an ASL construct >> +that looks like this: Name(KEY0, "value0"). An ACPI device driver would >> +then retrieve the value of the property by evaluating the KEY0 object. >> +However, using Name() this way has multiple problems: (1) ACPI limits >> +names ("KEY0") to four characters unlike DT; (2) there is no industry >> +wide registry that maintains a list of names, minimzing re-use; (3) >> +there is also no registry for the definition of property values ("value0"), >> +again making re-use difficult; and (4) how does one maintain backward >> +compatibility as new hardware comes out? The _DSD method was created >> +to solve precisely these sorts of problems; Linux drivers should ALWAYS >> +use the _DSD method for device properties and nothing else. >> + >> +The _DSM object (ACPI Section 9.14.1) could also be used for conveying >> +device properties to a driver. Linux drivers should only expect it to >> +be used if _DSD cannot represent the data required, and there is no way >> +to create a new UUID for the _DSD object. Note that there is even less >> +regulation of the use of _DSM than there is of _DSD. Drivers that depend >> +on the contents of _DSM objects will be more difficult to maintain over >> +time because of this. >> + >> +The _DSD object is a very flexible mechanism in ACPI, as are the registered >> +Device Properties. This flexibility allows _DSD to cover more than just the >> +generic server case and care should be taken in device drivers not to expect >> +it to replicate highly specific embedded behaviour from DT. > > While this is all good, we need to be more specific on what "embedded > behaviour" means. Maybe not for this document but the UEFI approval > process for new properties doesn't give any hint on what is and is not > sane (and I already disagree with some of the examples on uefi.org). > >> +Both DT bindings and ACPI device properties for device drivers have review >> +processes. Use them. And, before creating new device properties, check to >> +be sure that they have not been defined before and either registered in the >> +Linux kernel documentation or the UEFI Forum. If the device drivers supports >> +ACPI and DT, please make sure the device properties are consistent in both >> +places. > > In the interest of progress, I think we need to *temporarily* ban the > use of _DSD on ARM platforms aimed at ACPI and state it clearly in this > document. Once we are happy with the UEFI forum review process, we'll > adjust the document accordingly. > > My problems with _DSD: > > a) no clear guidance on what a good property means, whether it covers > just device specific information or it may include Linux behaviour > (like "linux,default-trigger", I don't think it should) > b) the Linux kernel community does not seem to be involved in the UEFI > forum _DSD review process. This means that we'll be faced with > patches against drivers to support UEFI-published _DSD properties. > I want to avoid such arguments, rejecting kernel code is too late > after _DSD properties have been published > > The alternative to _DSD would be to program the hardware to some sane > state. For example, I'm sure a MAC address can be written by firmware to > some register and the driver can read and store it locally (I'm not even > sure why we need MAC address in ACPI tables, this is not really a > property of the hardware but a configuration that could be done in > firmware). > >> +Clocks >> +------ >> +ACPI makes the assumption that clocks are initialized by the firmware -- >> +UEFI, in this case -- to some working value before control is handed over >> +to the kernel. This has implications for devices such as UARTs, or SoC >> +driven LCD displays, for example. >> + >> +When the kernel boots, the clock is assumed to be set to reasonable >> +working value. If for some reason the frequency needs to change -- e.g., >> +throttling for power management -- the device driver should expect that >> +process to be abstracted out into some ACPI method that can be invoked >> +(please see the ACPI specification for further recommendations on standard >> +methods to be expected). If is not, there is no direct way for ACPI to >> +control the clocks. > > I would emphasize that there is no way for _Linux_ to directly control the > clocks on an ACPI-enabled platform. > >> +ASWG >> +---- >> +The following areas are not yet fully defined for ARM in the 5.1 version >> +of the ACPI specification and are expected to be worked through in the >> +UEFI ACPI Specification Working Group (ASWG): >> + >> + -- 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 > > In addition to the above and _DSD requirements/banning, I would also add > some clear statements around: > > _OSC: only global/published capabilities are allowed. For > device-specific _OSC we need a process or maybe we can ban them entirely > and rely on _DSD once we clarify the process. > > _OSI: firmware must not check for certain _OSI strings. Here I'm not > sure what we would have to do for ARM Linux. Reporting "Windows" does > not make any sense but not reporting anything can, as Matthew Garrett > pointed out, can be interpreted by firmware as "Linux". In addition to > any statements in this document, I suggest you patch > drivers/acpi/acpica/utosi.c accordingly, maybe report "Linux" for ARM > and print a kernel warning so that we notice earlier. > > ACPI_OS_NAME: this is globally defined as "Microsoft Windows NT". It > doesn't make much sense in the ARM context. Could we change it to > "Linux" when CONFIG_ARM64? > > Compatibility with older kernels: ACPI firmware must work, even though > not fully optimal, with the earliest kernel version implementing the > targeted ACPI spec. There may be a need for new drivers but otherwise > adding things like CPU power management should not break older kernel > versions. In addition, the ACPI firmware must also work with the latest > kernel version. > > > I strongly consider that we need to be very strict with the Linux ACPI > firmware and hardware requirements to avoid the need for supporting > non-standard implementations as much as possible. This is, however, a > live document, so we can relax it as we see fit (e.g. _DSD process > clarified). > > In the meantime, Merry Christmas ;). I'll follow up in January. I will send another version of patches based on 3.19-rc2, and I will address some comments in that patch set, we can continue our discussion here about doc for ACPI on ARM64. Thanks Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On 2014年12月31日 04:13, ashwinc@codeaurora.org wrote: > Hi Hanjun, > > Overall the document looks good to us. Some minor clarifications below. > >> ---------- Forwarded message ---------- >> 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: Al Stone <al.stone@linaro.org> >> Signed-off-by: Hanjun Guo <hanjun.guo@linaro.org> >> --- >> Documentation/arm64/arm-acpi.txt | 323 >> ++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 323 insertions(+) >> create mode 100644 Documentation/arm64/arm-acpi.txt >> > > [..] > >> +Relationship with Device Tree >> +----------------------------- > > [..] > >> +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. > > Is this still true? No, we can booting the ACPI system in EFI stub without dtb. Catalin also pointed out this issue, I will remove this paragraph. > > >> +Programmable Power Control Resources >> +------------------------------------ >> +Programmable power control resources include such resources as >> voltage/current >> +providers (regulators) and clock sources. >> + >> +The kernel assumes that power control of these resources is represented >> with >> +Power Resource Objects (ACPI section 7.1). The ACPI core will then >> handle >> +correctly enabling and disabling resources as they are needed. In order >> to >> +get that to work, ACPI assumes each device has defined D-states and that >> these >> +can be controlled through the optional ACPI methods _PS0, _PS1, _PS2, and >> _PS3; >> +in ACPI, _PS0 is the method to invoke to turn a device full on, and _PS3 >> is for >> +turning a device full off. >> + >> +The kernel ACPI code will also assume that the _PS? methods follow the >> normal >> +ACPI rules for such methods: >> + >> + -- 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 or enabled in the _PS0 method should be >> disabled >> + or de-allocated in the _PS3 method. >> + >> + -- Firmware will leave the resources in a reasonable state before >> handing >> + over control to the kernel. >> + > > We found this section could be improved a bit by explicitly calling out > the options for handling device PM. Platform vendor has two choices. > Resources can be managed in _PSx routine which gets called on entry to Dx. > Or they can be declared separately as power resources with their own _ON > and _OFF methods. They are then tied back to D-states for a particular > device via _PRx which specifies which power resources a device needs to be > on while in Dx. Kernel then tracks number of devices using a power > resource and calls _ON/_OFF as needed. Good point, this exactly what ACPI spec says, we need to update this paragraph a little bit. > >> +Such code in _PS? methods will of course be very platform specific. But, >> +this allows the driver to abstract out the interface for operating the >> device >> +and avoid having to read special non-standard values from ACPI tables. >> Further, >> +abstracting the use of these resources allows the hardware to change over >> time >> +without requiring updates to the driver. >> + > > I think its been mentioned in the past and you planned to add it here: we > should explicitly state that with ACPI, the kernel clock/vreg framework > are not expected to be used at all. > >> + >> +Clocks >> +------ >> +ACPI makes the assumption that clocks are initialized by the firmware -- >> +UEFI, in this case -- to some working value before control is handed over >> +to the kernel. This has implications for devices such as UARTs, or SoC >> +driven LCD displays, for example. >> + >> +When the kernel boots, the clock is assumed to be set to reasonable >> +working value. If for some reason the frequency needs to change -- e.g., >> +throttling for power management -- the device driver should expect that >> +process to be abstracted out into some ACPI method that can be invoked > > Exception to this is CPU clocks where CPPC provides a much richer > interface than just blindly invoking some method. > >> +(please see the ACPI specification for further recommendations on >> standard >> +methods to be expected). If is not, there is no direct way for ACPI to >> +control the clocks. >> + >> + > > [..] > >> +ASWG >> +---- >> +The following areas are not yet fully defined for ARM in the 5.1 version >> +of the ACPI specification and are expected to be worked through in the >> +UEFI ACPI Specification Working Group (ASWG): >> + >> + -- ACPI based CPU topology >> + -- ACPI based Power management > > Should clarify this to idle management rather than generic power management. and I think it is CPU idle specific here, right? > >> + -- CPU idle control based on PSCI >> + -- CPU performance control (CPPC) > > There is no ongoing work on CPPC. Additional enhancements may be explored > in the future, but spec is viable as is. will remove it. Thanks for reviewing it! Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Graeme, On 2015年01月02日 04:04, Graeme Gregory wrote: > On Wed, Dec 31, 2014 at 04:34:46PM +0800, Hanjun Guo wrote: >> On 2014年12月31日 04:13, ashwinc@codeaurora.org wrote: >>> Hi Hanjun, >>> >>> Overall the document looks good to us. Some minor clarifications below. >>> >>>> ---------- Forwarded message ---------- >>>> 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: Al Stone <al.stone@linaro.org> >>>> Signed-off-by: Hanjun Guo <hanjun.guo@linaro.org> >>>> --- >>>> Documentation/arm64/arm-acpi.txt | 323 >>>> ++++++++++++++++++++++++++++++++++++++ >>>> 1 file changed, 323 insertions(+) >>>> create mode 100644 Documentation/arm64/arm-acpi.txt >>>> >>> >>> [..] >>> >>>> +Relationship with Device Tree >>>> +----------------------------- >>> >>> [..] >>> >>>> +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. >>> >>> Is this still true? >> >> No, we can booting the ACPI system in EFI stub without dtb. Catalin >> also pointed out this issue, I will remove this paragraph. >> > > The paragraph is still correct, the /chosen node is always present even > if nothing else is. Sorry for the confusing, I mean no dtb needed for the command line if ACPI tables are available. efi will create a empty dtb if no dtb found, and add the cmd line into the new created dtb, I'm just wondering, can we remove the limitation for passing the cmd line in /chosen node in the future? Thanks Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On 2014年12月25日 01:18, Catalin Marinas wrote: [...] > > In addition to the above and _DSD requirements/banning, I would also add > some clear statements around: > > _OSC: only global/published capabilities are allowed. For > device-specific _OSC we need a process or maybe we can ban them entirely > and rely on _DSD once we clarify the process. > > _OSI: firmware must not check for certain _OSI strings. Here I'm not > sure what we would have to do for ARM Linux. Reporting "Windows" does > not make any sense but not reporting anything can, as Matthew Garrett > pointed out, can be interpreted by firmware as "Linux". In addition to > any statements in this document, I suggest you patch > drivers/acpi/acpica/utosi.c accordingly, maybe report "Linux" for ARM > and print a kernel warning so that we notice earlier. > > ACPI_OS_NAME: this is globally defined as "Microsoft Windows NT". It > doesn't make much sense in the ARM context. Could we change it to > "Linux" when CONFIG_ARM64? We will work on this both on ASWG and linux ACPI driver side, as Dong and Charles pointed out, _OSI things can be solved in ACPI spec, when that is done, we can modify the kernel driver to fix the problems above. > > Compatibility with older kernels: ACPI firmware must work, even though > not fully optimal, with the earliest kernel version implementing the > targeted ACPI spec. There may be a need for new drivers but otherwise > adding things like CPU power management should not break older kernel > versions. In addition, the ACPI firmware must also work with the latest > kernel version. It should be, and I think that's why we need ACPI (or DT) here :) Thanks Hanjun -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.txt new file mode 100644 index 0000000..17cf96d --- /dev/null +++ b/Documentation/arm64/arm-acpi.txt @@ -0,0 +1,323 @@ +ACPI on ARMv8 Servers +--------------------- +ACPI can be used for ARMv8 general purpose servers designed to follow +the ARM SBSA (Server Base System Architecture) specification, currently +available to those with an ARM login at http://silver.arm.com. + +The ARMv8 kernel implements the reduced hardware model of ACPI version +5.1 and its corresponding errata. Links to the specification and all +external documents it refers to are managed by the UEFI Forum. The +specification is available at http://www.uefi.org/specifications and +external documents can be found via http://www.uefi.org/acpi. + +If an ARMv8 system does not meet the requirements of the SBSA, or cannot +be described using the mechanisms defined in the required ACPI specifications, +then it is likely that Device Tree (DT) is more suitable than ACPI 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 +------------------------- +The only defined method for passing ACPI tables to the kernel on ARMv8 +is via the UEFI system configuration table. + +Processing of ACPI tables may be disabled by passing acpi=off on the kernel +command line; this is the default behavior. If acpi=force is used, the kernel +will ONLY use device configuration information contained in the ACPI tables. + +In order for the kernel to load and use ACPI tables, the UEFI implementation +MUST set the ACPI_20_TABLE_GUID to point to the RSDP table (the table with +the ACPI signature "RSD PTR "). If this pointer is incorrect and acpi=force +is used, the kernel will disable ACPI and try to use DT to boot. + +If the pointer to the RSDP table is correct, the table will be mapped into +the kernel by the ACPI core, using the address provided by UEFI. + +The ACPI core will then locate and map in all other ACPI tables provided by +using the addresses in the RSDP table to find the XSDT (eXtended System +Description Table). The XSDT in turn provides the addresses to all other +ACPI tables provided by the system firmware; the ACPI core will then traverse +this table and map in the tables listed. + +The ACPI core will ignore any provided RSDT (Root System Description Table). +RSDTs have been deprecated and are ignored on arm64 since they only allow +for 32-bit addresses. + +Further, the ACPI core will only use the 64-bit address fields in the FADT +(Fixed ACPI Description Table). Any 32-bit address fields in the FADT will +be ignored on arm64. + +Hardware reduced mode (see Section 4.1 of the ACPI 5.1 specification) will +be enforced by the ACPI core on arm64. Doing so allows the ACPI core to +run less complex code since it no longer has to provide support for legacy +hardware from other architectures. + +For the ACPI core to operate properly, and in turn provide the information +the kernel needs to configure devices, it expects to find the following +tables (all section numbers refer to the ACPI 5.1 specfication): + + -- RSDP (Root System Description Pointer), section 5.2.5 + + -- XSDT (eXtended System Description Table), section 5.2.8 + + -- FACS (Firmware ACPI Control Structure), section 5.2.10 + + -- FADT (Fixed ACPI Description Table), section 5.2.9 + + -- DSDT (Differentiated System Description Table), section + 5.2.11.1 + + -- MADT (Multiple APIC Description Table), section 5.2.12 + + -- GTDT (Generic Timer Description Table), section 5.2.24 + + -- If PCI is supported, the MCFG (Memory mapped ConFiGuration + Table), section 5.2.6, specifically Table 5-31. + +If the above tables are not all present, the kernel may or may not be +able to boot properly since it may not be able to configure all of the +devices available. + + +ACPI Detection +-------------- +Drivers should determine their probe() type by checking for a null +value for ACPI_HANDLE, or checking .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 can contain less information than is typically provided via a Device +Tree description for the same device. This is also one of the reasons that +ACPI can be useful -- the driver takes into account that it may have less +detailed information about the device and uses sensible defaults instead. +If done properly in the driver, the hardware can change and improve over +time without the driver having to change at all. + +Clocks provide an excellent example. In DT, clocks need to be specified +and the drivers need to take them into account. In ACPI, the assumption +is that UEFI will leave the device in a reasonable default state, including +any clock settings. If for some reason the driver needs to change a clock +value, this can be done in an ACPI method; all the driver needs to do is +invoke the method and not concern itself with what the method needs to do +to change the clock. Changing the hardware can then take place over time +by changing what the ACPI method does, and not the driver. + +ACPI drivers should only look at one specific ASL object -- the _DSD object +-- for device driver parameters (known in DT as "bindings", or "Device +Properties" in ACPI). Not all DT bindings will be recognized. The UEFI +Forum provides a mechanism for registering such bindings [URL TBD by ASWG] +so that they may be used on any operating system supporting ACPI. Device +properties that have not been registered with the UEFI Forum should not be +used. + +Drivers should look for device properties in the _DSD object ONLY; the _DSD +object is described in the ACPI specification section 6.2.5, but more +specifically, use the _DSD Device Properties UUID: + + -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 + + -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf) + +The kernel has an interface for looking up device properties in a manner +independent of whether DT or ACPI is being used and that interface should +be used; it can eliminate some duplication of code paths in driver probing +functions and discourage divergence between DT bindings and ACPI device +properties. + +ACPI tables are described with a formal language called ASL, the ACPI +Source Language (section 19 of the specification). This means that there +are always multiple ways to describe the same thing -- including device +properties. For example, device properties could use an ASL construct +that looks like this: Name(KEY0, "value0"). An ACPI device driver would +then retrieve the value of the property by evaluating the KEY0 object. +However, using Name() this way has multiple problems: (1) ACPI limits +names ("KEY0") to four characters unlike DT; (2) there is no industry +wide registry that maintains a list of names, minimzing re-use; (3) +there is also no registry for the definition of property values ("value0"), +again making re-use difficult; and (4) how does one maintain backward +compatibility as new hardware comes out? The _DSD method was created +to solve precisely these sorts of problems; Linux drivers should ALWAYS +use the _DSD method for device properties and nothing else. + +The _DSM object (ACPI Section 9.14.1) could also be used for conveying +device properties to a driver. Linux drivers should only expect it to +be used if _DSD cannot represent the data required, and there is no way +to create a new UUID for the _DSD object. Note that there is even less +regulation of the use of _DSM than there is of _DSD. Drivers that depend +on the contents of _DSM objects will be more difficult to maintain over +time because of this. + +The _DSD object is a very flexible mechanism in ACPI, as are the registered +Device Properties. This flexibility allows _DSD to cover more than just the +generic server case and care should be taken in device drivers not to expect +it to replicate highly specific embedded behaviour from DT. + +Both DT bindings and ACPI device properties for device drivers have review +processes. Use them. And, before creating new device properties, check to +be sure that they have not been defined before and either registered in the +Linux kernel documentation or the UEFI Forum. If the device drivers supports +ACPI and DT, please make sure the device properties are consistent in both +places. + + +Programmable Power Control Resources +------------------------------------ +Programmable power control resources include such resources as voltage/current +providers (regulators) and clock sources. + +The kernel assumes that power control of these resources is represented with +Power Resource Objects (ACPI section 7.1). The ACPI core will then handle +correctly enabling and disabling resources as they are needed. In order to +get that to work, ACPI assumes each device has defined D-states and that these +can be controlled through the optional ACPI methods _PS0, _PS1, _PS2, and _PS3; +in ACPI, _PS0 is the method to invoke to turn a device full on, and _PS3 is for +turning a device full off. + +The kernel ACPI code will also assume that the _PS? methods follow the normal +ACPI rules for such methods: + + -- 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 or enabled in the _PS0 method should be disabled + or de-allocated in the _PS3 method. + + -- Firmware will leave the resources in a reasonable state before handing + over control to the kernel. + +Such code in _PS? methods will of course be very platform specific. But, +this allows the driver to abstract out the interface for operating the device +and avoid having to read special non-standard values from ACPI tables. Further, +abstracting the use of these resources allows the hardware to change over time +without requiring updates to the driver. + + +Clocks +------ +ACPI makes the assumption that clocks are initialized by the firmware -- +UEFI, in this case -- to some working value before control is handed over +to the kernel. This has implications for devices such as UARTs, or SoC +driven LCD displays, for example. + +When the kernel boots, the clock is assumed to be set to reasonable +working value. If for some reason the frequency needs to change -- e.g., +throttling for power management -- the device driver should expect that +process to be abstracted out into some ACPI method that can be invoked +(please see the ACPI specification for further recommendations on standard +methods to be expected). If is not, there is no direct way for ACPI to +control the clocks. + + +Driver Recommendations +---------------------- +DO NOT remove any DT handling when adding ACPI support for a driver. The +same device may be used on many different systems. + +DO try to structure the driver so that it is data driven. That is, set up +a struct containing internal per-device state based on defaults and whatever +else must be discovered by the driver probe function. Then, have the rest +of the driver operate off of the contents of that struct. Doing so should +allow most divergence between ACPI and DT functionality to be kept local to +the probe function instead of being scattered throughout the driver. For +example: + +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: + +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 fully defined for ARM in the 5.1 version +of the ACPI specification and are expected to be worked through in the +UEFI ACPI Specification Working Group (ASWG): + + -- 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 + +Participation in this group is open to all UEFI members. Please see +http://www.uefi.org/workinggroup for details on group membership. + +It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification +as closely as possible, and to only implement functionality that complies with +the released standards from UEFI ASWG. As a practical matter, there will be +vendors that provide bad ACPI tables or violate the standards in some way. +If this is because of errors, quirks and fixups may be necessary, but will +be avoided if possible. If there are features missing from ACPI that preclude +it from being used on a platform, ECRs (Engineering Change Requests) should be +submitted to ASWG and go through the normal approval process; for those that +are not UEFI members, many other members of the Linux community are and would +likely be willing to assist in submitting ECRs.