Merge branch 'acpi-doc' (e8b6cb39) · Commits · e / devices / android_kernel_oneplus_sm7250

Documentation/ABI/testing/sysfs-bus-acpi

0 → 100644

+58 −0

Original line number	Original line	Diff line number	Diff line
			What: /sys/bus/acpi/devices/.../path
			Date: December 2006
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute indicates the full path of ACPI namespace
			object associated with the device object. For example,
			\_SB_.PCI0.
			This file is not present for device objects representing
			fixed ACPI hardware features (like power and sleep
			buttons).

			What: /sys/bus/acpi/devices/.../modalias
			Date: July 2007
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute indicates the PNP IDs of the device object.
			That is acpi:HHHHHHHH:[CCCCCCC:]. Where each HHHHHHHH or
			CCCCCCCC contains device object's PNPID (_HID or _CID).

			What: /sys/bus/acpi/devices/.../hid
			Date: April 2005
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute indicates the hardware ID (_HID) of the
			device object. For example, PNP0103.
			This file is present for device objects having the _HID
			control method.

			What: /sys/bus/acpi/devices/.../description
			Date: October 2012
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute contains the output of the device object's
			_STR control method, if present.

			What: /sys/bus/acpi/devices/.../adr
			Date: October 2012
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute contains the output of the device object's
			_ADR control method, which is present for ACPI device
			objects representing devices having standard enumeration
			algorithms, such as PCI.

			What: /sys/bus/acpi/devices/.../uid
			Date: October 2012
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			This attribute contains the output of the device object's
			_UID control method, if present.

			What: /sys/bus/acpi/devices/.../eject
			Date: December 2006
			Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
			Description:
			Writing 1 to this attribute will trigger hot removal of
			this device object. This file exists for every device
			object that has _EJ0 method.

Documentation/ABI/testing/sysfs-devices-sun

+1 −1

Original line number	Original line	Diff line number	Diff line
	Whatt: /sys/devices/.../sun		What: /sys/devices/.../sun
	Date: October 2012		Date: October 2012
	Contact: Yasuaki Ishimatsu <isimatu.yasuaki@jp.fujitsu.com>		Contact: Yasuaki Ishimatsu <isimatu.yasuaki@jp.fujitsu.com>
	Description:		Description:

Documentation/acpi/namespace.txt

0 → 100644

+395 −0

Original line number	Original line	Diff line number	Diff line
			ACPI Device Tree - Representation of ACPI Namespace

			Copyright (C) 2013, Intel Corporation
			Author: Lv Zheng <lv.zheng@intel.com>


			Abstract:

			The Linux ACPI subsystem converts ACPI namespace objects into a Linux
			device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
			receiving ACPI hotplug notification events. For each device object in this
			hierarchy there is a corresponding symbolic link in the
			/sys/bus/acpi/devices.
			This document illustrates the structure of the ACPI device tree.


			Credit:

			Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
			Wysocki <rafael.j.wysocki@intel.com>.


			1. ACPI Definition Blocks

			The ACPI firmware sets up RSDP (Root System Description Pointer) in the
			system memory address space pointing to the XSDT (Extended System
			Description Table). The XSDT always points to the FADT (Fixed ACPI
			Description Table) using its first entry, the data within the FADT
			includes various fixed-length entries that describe fixed ACPI features
			of the hardware. The FADT contains a pointer to the DSDT
			(Differentiated System Descripition Table). The XSDT also contains
			entries pointing to possibly multiple SSDTs (Secondary System
			Description Table).

			The DSDT and SSDT data is organized in data structures called definition
			blocks that contain definitions of various objects, including ACPI
			control methods, encoded in AML (ACPI Machine Language). The data block
			of the DSDT along with the contents of SSDTs represents a hierarchical
			data structure called the ACPI namespace whose topology reflects the
			structure of the underlying hardware platform.

			The relationships between ACPI System Definition Tables described above
			are illustrated in the following diagram.

			+---------+ +-------+ +--------+ +------------------------+
			\| RSDP \| +->\| XSDT \| +->\| FADT \| \| +-------------------+ \|
			+---------+ \| +-------+ \| +--------+ +-\|->\| DSDT \| \|
			\| Pointer \| \| \| Entry \|-+ \| ...... \| \| \| +-------------------+ \|
			+---------+ \| +-------+ \| X_DSDT \|--+ \| \| Definition Blocks \| \|
			\| Pointer \|-+ \| ..... \| \| ...... \| \| +-------------------+ \|
			+---------+ +-------+ +--------+ \| +-------------------+ \|
			\| Entry \|------------------\|->\| SSDT \| \|
			+- - - -+ \| +-------------------\| \|
			\| Entry \| - - - - - - - -+ \| \| Definition Blocks \| \|
			+- - - -+ \| \| +-------------------+ \|
			\| \| +- - - - - - - - - -+ \|
			+-\|->\| SSDT \| \|
			\| +-------------------+ \|
			\| \| Definition Blocks \| \|
			\| +- - - - - - - - - -+ \|
			+------------------------+
			\|
			OSPM Loading \|
			\\|/
			+----------------+
			\| ACPI Namespace \|
			+----------------+

			Figure 1. ACPI Definition Blocks

			NOTE: RSDP can also contain a pointer to the RSDT (Root System
			Description Table). Platforms provide RSDT to enable
			compatibility with ACPI 1.0 operating systems. The OS is expected
			to use XSDT, if present.


			2. Example ACPI Namespace

			All definition blocks are loaded into a single namespace. The namespace
			is a hierarchy of objects identified by names and paths.
			The following naming conventions apply to object names in the ACPI
			namespace:
			1. All names are 32 bits long.
			2. The first byte of a name must be one of 'A' - 'Z', '_'.
			3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
			- '9', '_'.
			4. Names starting with '_' are reserved by the ACPI specification.
			5. The '\' symbol represents the root of the namespace (i.e. names
			prepended with '\' are relative to the namespace root).
			6. The '^' symbol represents the parent of the current namespace node
			(i.e. names prepended with '^' are relative to the parent of the
			current namespace node).

			The figure below shows an example ACPI namespace.

			+------+
			\| \ \| Root
			+------+
			\|
			\| +------+
			+-\| _PR \| Scope(_PR): the processor namespace
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| CPU0 \| Processor(CPU0): the first processor
			\| +------+
			\|
			\| +------+
			+-\| _SB \| Scope(_SB): the system bus namespace
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| LID0 \| Device(LID0); the lid device
			\| \| +------+
			\| \| \|
			\| \| \| +------+
			\| \| +-\| _HID \| Name(_HID, "PNP0C0D"): the hardware ID
			\| \| \| +------+
			\| \| \|
			\| \| \| +------+
			\| \| +-\| _STA \| Method(_STA): the status control method
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| PCI0 \| Device(PCI0); the PCI root bridge
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| _HID \| Name(_HID, "PNP0A08"): the hardware ID
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| _CID \| Name(_CID, "PNP0A03"): the compatible ID
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| RP03 \| Scope(RP03): the PCI0 power scope
			\| \| +------+
			\| \| \|
			\| \| \| +------+
			\| \| +-\| PXP3 \| PowerResource(PXP3): the PCI0 power resource
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| GFX0 \| Device(GFX0): the graphics adapter
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| _ADR \| Name(_ADR, 0x00020000): the PCI bus address
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| DD01 \| Device(DD01): the LCD output device
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| _BCL \| Method(_BCL): the backlight control method
			\| +------+
			\|
			\| +------+
			+-\| _TZ \| Scope(_TZ): the thermal zone namespace
			\| +------+
			\| \|
			\| \| +------+
			\| +-\| FN00 \| PowerResource(FN00): the FAN0 power resource
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| FAN0 \| Device(FAN0): the FAN0 cooling device
			\| \| +------+
			\| \| \|
			\| \| \| +------+
			\| \| +-\| _HID \| Name(_HID, "PNP0A0B"): the hardware ID
			\| \| +------+
			\| \|
			\| \| +------+
			\| +-\| TZ00 \| ThermalZone(TZ00); the FAN thermal zone
			\| +------+
			\|
			\| +------+
			+-\| _GPE \| Scope(_GPE): the GPE namespace
			+------+

			Figure 2. Example ACPI Namespace


			3. Linux ACPI Device Objects

			The Linux kernel's core ACPI subsystem creates struct acpi_device
			objects for ACPI namespace objects representing devices, power resources
			processors, thermal zones. Those objects are exported to user space via
			sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
			format of their names is <bus_id:instance>, where 'bus_id' refers to the
			ACPI namespace representation of the given object and 'instance' is used
			for distinguishing different object of the same 'bus_id' (it is
			two-digit decimal representation of an unsigned integer).

			The value of 'bus_id' depends on the type of the object whose name it is
			part of as listed in the table below.

			+---+-----------------+-------+----------+
			\| \| Object/Feature \| Table \| bus_id \|
			+---+-----------------+-------+----------+
			\| N \| Root \| xSDT \| LNXSYSTM \|
			+---+-----------------+-------+----------+
			\| N \| Device \| xSDT \| _HID \|
			+---+-----------------+-------+----------+
			\| N \| Processor \| xSDT \| LNXCPU \|
			+---+-----------------+-------+----------+
			\| N \| ThermalZone \| xSDT \| LNXTHERM \|
			+---+-----------------+-------+----------+
			\| N \| PowerResource \| xSDT \| LNXPOWER \|
			+---+-----------------+-------+----------+
			\| N \| Other Devices \| xSDT \| device \|
			+---+-----------------+-------+----------+
			\| F \| PWR_BUTTON \| FADT \| LNXPWRBN \|
			+---+-----------------+-------+----------+
			\| F \| SLP_BUTTON \| FADT \| LNXSLPBN \|
			+---+-----------------+-------+----------+
			\| M \| Video Extension \| xSDT \| LNXVIDEO \|
			+---+-----------------+-------+----------+
			\| M \| ATA Controller \| xSDT \| LNXIOBAY \|
			+---+-----------------+-------+----------+
			\| M \| Docking Station \| xSDT \| LNXDOCK \|
			+---+-----------------+-------+----------+

			Table 1. ACPI Namespace Objects Mapping

			The following rules apply when creating struct acpi_device objects on
			the basis of the contents of ACPI System Description Tables (as
			indicated by the letter in the first column and the notation in the
			second column of the table above):
			N:
			The object's source is an ACPI namespace node (as indicated by the
			named object's type in the second column). In that case the object's
			directory in sysfs will contain the 'path' attribute whose value is
			the full path to the node from the namespace root.
			struct acpi_device objects are created for the ACPI namespace nodes
			whose _STA control methods return PRESENT or FUNCTIONING. The power
			resource nodes or nodes without _STA are assumed to be both PRESENT
			and FUNCTIONING.
			F:
			The struct acpi_device object is created for a fixed hardware
			feature (as indicated by the fixed feature flag's name in the second
			column), so its sysfs directory will not contain the 'path'
			attribute.
			M:
			The struct acpi_device object is created for an ACPI namespace node
			with specific control methods (as indicated by the ACPI defined
			device's type in the second column). The 'path' attribute containing
			its namespace path will be present in its sysfs directory. For
			example, if the _BCL method is present for an ACPI namespace node, a
			struct acpi_device object with LNXVIDEO 'bus_id' will be created for
			it.

			The third column of the above table indicates which ACPI System
			Description Tables contain information used for the creation of the
			struct acpi_device objects represented by the given row (xSDT means DSDT
			or SSDT).

			The forth column of the above table indicates the 'bus_id' generation
			rule of the struct acpi_device object:
			_HID:
			_HID in the last column of the table means that the object's bus_id
			is derived from the _HID/_CID identification objects present under
			the corresponding ACPI namespace node. The object's sysfs directory
			will then contain the 'hid' and 'modalias' attributes that can be
			used to retrieve the _HID and _CIDs of that object.
			LNXxxxxx:
			The 'modalias' attribute is also present for struct acpi_device
			objects having bus_id of the "LNXxxxxx" form (pseudo devices), in
			which cases it contains the bus_id string itself.
			device:
			'device' in the last column of the table indicates that the object's
			bus_id cannot be determined from _HID/_CID of the corresponding
			ACPI namespace node, although that object represents a device (for
			example, it may be a PCI device with _ADR defined and without _HID
			or _CID). In that case the string 'device' will be used as the
			object's bus_id.


			4. Linux ACPI Physical Device Glue

			ACPI device (i.e. struct acpi_device) objects may be linked to other
			objects in the Linux' device hierarchy that represent "physical" devices
			(for example, devices on the PCI bus). If that happens, it means that
			the ACPI device object is a "companion" of a device otherwise
			represented in a different way and is used (1) to provide configuration
			information on that device which cannot be obtained by other means and
			(2) to do specific things to the device with the help of its ACPI
			control methods. One ACPI device object may be linked this way to
			multiple "physical" devices.

			If an ACPI device object is linked to a "physical" device, its sysfs
			directory contains the "physical_node" symbolic link to the sysfs
			directory of the target device object. In turn, the target device's
			sysfs directory will then contain the "firmware_node" symbolic link to
			the sysfs directory of the companion ACPI device object.
			The linking mechanism relies on device identification provided by the
			ACPI namespace. For example, if there's an ACPI namespace object
			representing a PCI device (i.e. a device object under an ACPI namespace
			object representing a PCI bridge) whose _ADR returns 0x00020000 and the
			bus number of the parent PCI bridge is 0, the sysfs directory
			representing the struct acpi_device object created for that ACPI
			namespace object will contain the 'physical_node' symbolic link to the
			/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
			corresponding PCI device.

			The linking mechanism is generally bus-specific. The core of its
			implementation is located in the drivers/acpi/glue.c file, but there are
			complementary parts depending on the bus types in question located
			elsewhere. For example, the PCI-specific part of it is located in
			drivers/pci/pci-acpi.c.


			5. Example Linux ACPI Device Tree

			The sysfs hierarchy of struct acpi_device objects corresponding to the
			example ACPI namespace illustrated in Figure 2 with the addition of
			fixed PWR_BUTTON/SLP_BUTTON devices is shown below.

			+--------------+---+-----------------+
			\| LNXSYSTEM:00 \| \ \| acpi:LNXSYSTEM: \|
			+--------------+---+-----------------+
			\|
			\| +-------------+-----+----------------+
			+-\| LNXPWRBN:00 \| N/A \| acpi:LNXPWRBN: \|
			\| +-------------+-----+----------------+
			\|
			\| +-------------+-----+----------------+
			+-\| LNXSLPBN:00 \| N/A \| acpi:LNXSLPBN: \|
			\| +-------------+-----+----------------+
			\|
			\| +-----------+------------+--------------+
			+-\| LNXCPU:00 \| \_PR_.CPU0 \| acpi:LNXCPU: \|
			\| +-----------+------------+--------------+
			\|
			\| +-------------+-------+----------------+
			+-\| LNXSYBUS:00 \| \_SB_ \| acpi:LNXSYBUS: \|
			\| +-------------+-------+----------------+
			\| \|
			\| \| +- - - - - - - +- - - - - - +- - - - - - - -+
			\| +-\| * PNP0C0D:00 \| \_SB_.LID0 \| acpi:PNP0C0D: \|
			\| \| +- - - - - - - +- - - - - - +- - - - - - - -+
			\| \|
			\| \| +------------+------------+-----------------------+
			\| +-\| PNP0A08:00 \| \_SB_.PCI0 \| acpi:PNP0A08:PNP0A03: \|
			\| +------------+------------+-----------------------+
			\| \|
			\| \| +-----------+-----------------+-----+
			\| +-\| device:00 \| \_SB_.PCI0.RP03 \| N/A \|
			\| \| +-----------+-----------------+-----+
			\| \| \|
			\| \| \| +-------------+----------------------+----------------+
			\| \| +-\| LNXPOWER:00 \| \_SB_.PCI0.RP03.PXP3 \| acpi:LNXPOWER: \|
			\| \| +-------------+----------------------+----------------+
			\| \|
			\| \| +-------------+-----------------+----------------+
			\| +-\| LNXVIDEO:00 \| \_SB_.PCI0.GFX0 \| acpi:LNXVIDEO: \|
			\| +-------------+-----------------+----------------+
			\| \|
			\| \| +-----------+-----------------+-----+
			\| +-\| device:01 \| \_SB_.PCI0.DD01 \| N/A \|
			\| +-----------+-----------------+-----+
			\|
			\| +-------------+-------+----------------+
			+-\| LNXSYBUS:01 \| \_TZ_ \| acpi:LNXSYBUS: \|
			+-------------+-------+----------------+
			\|
			\| +-------------+------------+----------------+
			+-\| LNXPOWER:0a \| \_TZ_.FN00 \| acpi:LNXPOWER: \|
			\| +-------------+------------+----------------+
			\|
			\| +------------+------------+---------------+
			+-\| PNP0C0B:00 \| \_TZ_.FAN0 \| acpi:PNP0C0B: \|
			\| +------------+------------+---------------+
			\|
			\| +-------------+------------+----------------+
			+-\| LNXTHERM:00 \| \_TZ_.TZ00 \| acpi:LNXTHERM: \|
			+-------------+------------+----------------+

			Figure 3. Example Linux ACPI Device Tree

			NOTE: Each node is represented as "object/path/modalias", where:
			1. 'object' is the name of the object's directory in sysfs.
			2. 'path' is the ACPI namespace path of the corresponding
			ACPI namespace object, as returned by the object's 'path'
			sysfs attribute.
			3. 'modalias' is the value of the object's 'modalias' sysfs
			attribute (as described earlier in this document).
			NOTE: N/A indicates the device object does not have the 'path' or the
			'modalias' attribute.
			NOTE: The PNP0C0D device listed above is highlighted (marked by "*")
			to indicate it will be created only when its _STA methods return
			PRESENT or FUNCTIONING.

Documentation/acpi/video_extension.txt

0 → 100644

+106 −0

Original line number	Original line	Diff line number	Diff line
			ACPI video extensions
			~~~~~~~~~~~~~~~~~~~~~

			This driver implement the ACPI Extensions For Display Adapters for
			integrated graphics devices on motherboard, as specified in ACPI 2.0
			Specification, Appendix B, allowing to perform some basic control like
			defining the video POST device, retrieving EDID information or to
			setup a video output, etc. Note that this is an ref. implementation
			only. It may or may not work for your integrated video device.

			The ACPI video driver does 3 things regarding backlight control:

			1 Export a sysfs interface for user space to control backlight level

			If the ACPI table has a video device, and acpi_backlight=vendor kernel
			command line is not present, the driver will register a backlight device
			and set the required backlight operation structure for it for the sysfs
			interface control. For every registered class device, there will be a
			directory named acpi_videoX under /sys/class/backlight.

			The backlight sysfs interface has a standard definition here:
			Documentation/ABI/stable/sysfs-class-backlight.

			And what ACPI video driver does is:
			actual_brightness: on read, control method _BQC will be evaluated to
			get the brightness level the firmware thinks it is at;
			bl_power: not implemented, will set the current brightness instead;
			brightness: on write, control method _BCM will run to set the requested
			brightness level;
			max_brightness: Derived from the _BCL package(see below);
			type: firmware

			Note that ACPI video backlight driver will always use index for
			brightness, actual_brightness and max_brightness. So if we have
			the following _BCL package:

			Method (_BCL, 0, NotSerialized)
			{
			Return (Package (0x0C)
			{
			0x64,
			0x32,
			0x0A,
			0x14,
			0x1E,
			0x28,
			0x32,
			0x3C,
			0x46,
			0x50,
			0x5A,
			0x64
			})
			}

			The first two levels are for when laptop are on AC or on battery and are
			not used by Linux currently. The remaining 10 levels are supported levels
			that we can choose from. The applicable index values are from 0 (that
			corresponds to the 0x0A brightness value) to 9 (that corresponds to the
			0x64 brightness value) inclusive. Each of those index values is regarded
			as a "brightness level" indicator. Thus from the user space perspective
			the range of available brightness levels is from 0 to 9 (max_brightness)
			inclusive.

			2 Notify user space about hotkey event

			There are generally two cases for hotkey event reporting:
			i) For some laptops, when user presses the hotkey, a scancode will be
			generated and sent to user space through the input device created by
			the keyboard driver as a key type input event, with proper remap, the
			following key code will appear to user space:

			EV_KEY, KEY_BRIGHTNESSUP
			EV_KEY, KEY_BRIGHTNESSDOWN
			etc.

			For this case, ACPI video driver does not need to do anything(actually,
			it doesn't even know this happened).

			ii) For some laptops, the press of the hotkey will not generate the
			scancode, instead, firmware will notify the video device ACPI node
			about the event. The event value is defined in the ACPI spec. ACPI
			video driver will generate an key type input event according to the
			notify value it received and send the event to user space through the
			input device it created:

			event keycode
			0x86 KEY_BRIGHTNESSUP
			0x87 KEY_BRIGHTNESSDOWN
			etc.

			so this would lead to the same effect as case i) now.

			Once user space tool receives this event, it can modify the backlight
			level through the sysfs interface.

			3 Change backlight level in the kernel

			This works for machines covered by case ii) in Section 2. Once the driver
			received a notification, it will set the backlight level accordingly. This does
			not affect the sending of event to user space, they are always sent to user
			space regardless of whether or not the video module controls the backlight level
			directly. This behaviour can be controlled through the brightness_switch_enabled
			module parameter as documented in kernel-parameters.txt. It is recommended to
			disable this behaviour once a GUI environment starts up and wants to have full
			control of the backlight level.

Documentation/cpu-hotplug.txt

+4 −2

Original line number	Original line	Diff line number	Diff line
	@@ -370,8 +370,10 @@ A: There is no clear spec defined way from ACPI that can give us that
	CPUs in MADT as hotpluggable CPUS. In the case there are no disabled CPUS		CPUs in MADT as hotpluggable CPUS. In the case there are no disabled CPUS
	we assume 1/2 the number of CPUs currently present can be hotplugged.		we assume 1/2 the number of CPUs currently present can be hotplugged.

	Caveat: Today's ACPI MADT can only provide 256 entries since the apicid field		Caveat: ACPI MADT can only provide 256 entries in systems with only ACPI 2.0c
	in MADT is only 8 bits.		or earlier ACPI version supported, because the apicid field in MADT is only
			8 bits. From ACPI 3.0, this limitation was removed since the apicid field
			was extended to 32 bits with x2APIC introduced.

	User Space Notification		User Space Notification