summaryrefslogtreecommitdiffstats
path: root/Documentation/ABI/testing/sysfs-firmware-acpi
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/ABI/testing/sysfs-firmware-acpi')
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-acpi250
1 files changed, 250 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
new file mode 100644
index 000000000..819939d85
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -0,0 +1,250 @@
+What: /sys/firmware/acpi/fpdt/
+Date: Jan 2021
+Contact: Zhang Rui <rui.zhang@intel.com>
+Description:
+ ACPI Firmware Performance Data Table (FPDT) provides
+ information for firmware performance data for system boot,
+ S3 suspend and S3 resume. This sysfs entry contains the
+ performance data retrieved from the FPDT.
+
+ boot:
+ firmware_start_ns: Timer value logged at the beginning
+ of firmware image execution. In nanoseconds.
+ bootloader_load_ns: Timer value logged just prior to
+ loading the OS boot loader into memory.
+ In nanoseconds.
+ bootloader_launch_ns: Timer value logged just prior to
+ launching the currently loaded OS boot loader
+ image. In nanoseconds.
+ exitbootservice_start_ns: Timer value logged at the
+ point when the OS loader calls the
+ ExitBootServices function for UEFI compatible
+ firmware. In nanoseconds.
+ exitbootservice_end_ns: Timer value logged at the point
+ just prior to the OS loader gaining control
+ back from the ExitBootServices function for
+ UEFI compatible firmware. In nanoseconds.
+ suspend:
+ suspend_start_ns: Timer value recorded at the previous
+ OS write to SLP_TYP upon entry to S3. In
+ nanoseconds.
+ suspend_end_ns: Timer value recorded at the previous
+ firmware write to SLP_TYP used to trigger
+ hardware entry to S3. In nanoseconds.
+ resume:
+ resume_count: A count of the number of S3 resume cycles
+ since the last full boot sequence.
+ resume_avg_ns: Average timer value of all resume cycles
+ logged since the last full boot sequence,
+ including the most recent resume. In nanoseconds.
+ resume_prev_ns: Timer recorded at the end of the previous
+ platform runtime firmware S3 resume, just prior to
+ handoff to the OS waking vector. In nanoseconds.
+
+What: /sys/firmware/acpi/bgrt/
+Date: January 2012
+Contact: Matthew Garrett <mjg@redhat.com>
+Description:
+ The BGRT is an ACPI 5.0 feature that allows the OS
+ to obtain a copy of the firmware boot splash and
+ some associated metadata. This is intended to be used
+ by boot splash applications in order to interact with
+ the firmware boot splash in order to avoid jarring
+ transitions.
+
+ image: The image bitmap. Currently a 32-bit BMP.
+ status: 1 if the image is valid, 0 if firmware invalidated it.
+ type: 0 indicates image is in BMP format.
+
+ ======== ===================================================
+ version: The version of the BGRT. Currently 1.
+ xoffset: The number of pixels between the left of the screen
+ and the left edge of the image.
+ yoffset: The number of pixels between the top of the screen
+ and the top edge of the image.
+ ======== ===================================================
+
+What: /sys/firmware/acpi/hotplug/
+Date: February 2013
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ There are separate hotplug profiles for different classes of
+ devices supported by ACPI, such as containers, memory modules,
+ processors, PCI root bridges etc. A hotplug profile for a given
+ class of devices is a collection of settings defining the way
+ that class of devices will be handled by the ACPI core hotplug
+ code. Those profiles are represented in sysfs as subdirectories
+ of /sys/firmware/acpi/hotplug/.
+
+ The following setting is available to user space for each
+ hotplug profile:
+
+ ======== =======================================================
+ enabled: If set, the ACPI core will handle notifications of
+ hotplug events associated with the given class of
+ devices and will allow those devices to be ejected with
+ the help of the _EJ0 control method. Unsetting it
+ effectively disables hotplug for the correspoinding
+ class of devices.
+ ======== =======================================================
+
+ The value of the above attribute is an integer number: 1 (set)
+ or 0 (unset). Attempts to write any other values to it will
+ cause -EINVAL to be returned.
+
+What: /sys/firmware/acpi/interrupts/
+Date: February 2008
+Contact: Len Brown <lenb@kernel.org>
+Description:
+ All ACPI interrupts are handled via a single IRQ,
+ the System Control Interrupt (SCI), which appears
+ as "acpi" in /proc/interrupts.
+
+ However, one of the main functions of ACPI is to make
+ the platform understand random hardware without
+ special driver support. So while the SCI handles a few
+ well known (fixed feature) interrupts sources, such
+ as the power button, it can also handle a variable
+ number of a "General Purpose Events" (GPE).
+
+ A GPE vectors to a specified handler in AML, which
+ can do a anything the BIOS writer wants from
+ OS context. GPE 0x12, for example, would vector
+ to a level or edge handler called _L12 or _E12.
+ The handler may do its business and return.
+ Or the handler may send send a Notify event
+ to a Linux device driver registered on an ACPI device,
+ such as a battery, or a processor.
+
+ To figure out where all the SCI's are coming from,
+ /sys/firmware/acpi/interrupts contains a file listing
+ every possible source, and the count of how many
+ times it has triggered::
+
+ $ cd /sys/firmware/acpi/interrupts
+ $ grep . *
+ error: 0
+ ff_gbl_lock: 0 enable
+ ff_pmtimer: 0 invalid
+ ff_pwr_btn: 0 enable
+ ff_rt_clk: 2 disable
+ ff_slp_btn: 0 invalid
+ gpe00: 0 invalid
+ gpe01: 0 enable
+ gpe02: 108 enable
+ gpe03: 0 invalid
+ gpe04: 0 invalid
+ gpe05: 0 invalid
+ gpe06: 0 enable
+ gpe07: 0 enable
+ gpe08: 0 invalid
+ gpe09: 0 invalid
+ gpe0A: 0 invalid
+ gpe0B: 0 invalid
+ gpe0C: 0 invalid
+ gpe0D: 0 invalid
+ gpe0E: 0 invalid
+ gpe0F: 0 invalid
+ gpe10: 0 invalid
+ gpe11: 0 invalid
+ gpe12: 0 invalid
+ gpe13: 0 invalid
+ gpe14: 0 invalid
+ gpe15: 0 invalid
+ gpe16: 0 invalid
+ gpe17: 1084 enable
+ gpe18: 0 enable
+ gpe19: 0 invalid
+ gpe1A: 0 invalid
+ gpe1B: 0 invalid
+ gpe1C: 0 invalid
+ gpe1D: 0 invalid
+ gpe1E: 0 invalid
+ gpe1F: 0 invalid
+ gpe_all: 1192
+ sci: 1194
+ sci_not: 0
+
+ =========== ==================================================
+ sci The number of times the ACPI SCI
+ has been called and claimed an interrupt.
+
+ sci_not The number of times the ACPI SCI
+ has been called and NOT claimed an interrupt.
+
+ gpe_all count of SCI caused by GPEs.
+
+ gpeXX count for individual GPE source
+
+ ff_gbl_lock Global Lock
+
+ ff_pmtimer PM Timer
+
+ ff_pwr_btn Power Button
+
+ ff_rt_clk Real Time Clock
+
+ ff_slp_btn Sleep Button
+
+ error an interrupt that can't be accounted for above.
+
+ invalid it's either a GPE or a Fixed Event that
+ doesn't have an event handler.
+
+ disable the GPE/Fixed Event is valid but disabled.
+
+ enable the GPE/Fixed Event is valid and enabled.
+ =========== ==================================================
+
+ Root has permission to clear any of these counters. Eg.::
+
+ # echo 0 > gpe11
+
+ All counters can be cleared by clearing the total "sci"::
+
+ # echo 0 > sci
+
+ None of these counters has an effect on the function
+ of the system, they are simply statistics.
+
+ Besides this, user can also write specific strings to these files
+ to enable/disable/clear ACPI interrupts in user space, which can be
+ used to debug some ACPI interrupt storm issues.
+
+ Note that only writing to VALID GPE/Fixed Event is allowed,
+ i.e. user can only change the status of runtime GPE and
+ Fixed Event with event handler installed.
+
+ Let's take power button fixed event for example, please kill acpid
+ and other user space applications so that the machine won't shutdown
+ when pressing the power button::
+
+ # cat ff_pwr_btn
+ 0 enabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 enabled
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 3 disabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 disabled
+ # echo enable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 4 enabled
+ /*
+ * this is because the status bit is set even if the enable
+ * bit is cleared, and it triggers an ACPI fixed event when
+ * the enable bit is set again
+ */
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 7 enabled
+ # echo disable > ff_pwr_btn
+ # press the power button for 3 times;
+ # echo clear > ff_pwr_btn /* clear the status bit */
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 7 enabled
+