code:
What:		/sys/bus/platform/devices/MLNXBF04:00/lifecycle_state
Date:		Oct 2019
KernelVersion:	5.5
Contact:	"Liming Sun <lsun@mellanox.com>"
Description:
		The Life-cycle state of the SoC, which could be one of the
		following values.

		==============  =============================================
		Production      Production state and can be updated to secure
		GA Secured      Secure chip and not able to change state
		GA Non-Secured  Non-Secure chip and not able to change state
		RMA             Return Merchandise Authorization
		==============  =============================================

What:		/sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
Date:		Oct 2019
KernelVersion:	5.5
Contact:	"Liming Sun <lsun@mellanox.com>"
Description:
		The watchdog setting in seconds for the next booting. It's used
		to reboot the chip and recover it to the old state if the new
		boot partition fails.

What:		/sys/bus/platform/devices/MLNXBF04:00/reset_action
Date:		Oct 2019
KernelVersion:	5.5
Contact:	"Liming Sun <lsun@mellanox.com>"
Description:
		The source of the boot stream for the next reset. It could be
		one of the following values:

		===========  ===============================================
		external     boot from external source (USB or PCIe)
		emmc         boot from the onchip eMMC
		emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
		===========  ===============================================

What:		/sys/bus/platform/devices/MLNXBF04:00/second_reset_action
Date:		Oct 2019
KernelVersion:	5.5
Contact:	"Liming Sun <lsun@mellanox.com>"
Description:
		Update the source of the boot stream after next reset. It could
		be one of the following values and will be applied after next
		reset.

		===========  ===============================================
		external     boot from external source (USB or PCIe)
		emmc         boot from the onchip eMMC
		emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
		swap_emmc    swap the primary / secondary boot partition
		none         cancel the action
		===========  ===============================================

What:		/sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
Date:		Oct 2019
KernelVersion:	5.5
Contact:	"Liming Sun <lsun@mellanox.com>"
Description:
		The state of eFuse versions with the following values.

		=======  ===============================================
		InUse    burnt, valid and currently in use
		Used     burnt and valid
		Free     not burnt and free to use
		Skipped  not burnt but not free (skipped)
		Wasted   burnt and invalid
		Invalid  not burnt but marked as valid (error state).
		=======  ===============================================


code:
What:		/sys/devices/platform/msi-laptop-pf/lcd_level
Date:		Oct 2006
KernelVersion:	2.6.19
Contact:	"Lennart Poettering <mzxreary@0pointer.de>"
Description:
		Screen brightness: contains a single integer in the range 0..8.

What:		/sys/devices/platform/msi-laptop-pf/auto_brightness
Date:		Oct 2006
KernelVersion:	2.6.19
Contact:	"Lennart Poettering <mzxreary@0pointer.de>"
Description:
		Enable automatic brightness control: contains either 0 or 1. If
		set to 1 the hardware adjusts the screen brightness
		automatically when the power cord is plugged/unplugged.

What:		/sys/devices/platform/msi-laptop-pf/wlan
Date:		Oct 2006
KernelVersion:	2.6.19
Contact:	"Lennart Poettering <mzxreary@0pointer.de>"
Description:
		WLAN subsystem enabled: contains either 0 or 1.

What:		/sys/devices/platform/msi-laptop-pf/bluetooth
Date:		Oct 2006
KernelVersion:	2.6.19
Contact:	"Lennart Poettering <mzxreary@0pointer.de>"
Description:
		Bluetooth subsystem enabled: contains either 0 or 1. Please
		note that this file is constantly 0 if no Bluetooth hardware is
		available.

What:		/sys/devices/platform/msi-laptop-pf/touchpad
Date:		Nov 2012
KernelVersion:	3.8
Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
		Contains either 0 or 1 and indicates if touchpad is turned on.
		Touchpad state can only be toggled by pressing Fn+F3.

What:		/sys/devices/platform/msi-laptop-pf/turbo_mode
Date:		Nov 2012
KernelVersion:	3.8
Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
		Contains either 0 or 1 and indicates if turbo mode is turned
		on. In turbo mode power LED is orange and processor is
		overclocked. Turbo mode is available only if charging. It is
		only possible to toggle turbo mode state by pressing Fn+F10,
		and there is a few seconds cooldown between subsequent toggles.
		If user presses Fn+F10 too frequent, turbo mode state is not
		changed.

What:		/sys/devices/platform/msi-laptop-pf/eco_mode
Date:		Nov 2012
KernelVersion:	3.8
Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
		Contains either 0 or 1 and indicates if ECO mode is turned on.
		In ECO mode power LED is green and userspace should do some
		powersaving actions. ECO mode is available only on battery
		power. ECO mode can only be toggled by pressing Fn+F10.

What:		/sys/devices/platform/msi-laptop-pf/turbo_cooldown
Date:		Nov 2012
KernelVersion:	3.8
Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
		Contains value in range 0..3:
			* 0 -> Turbo mode is off
			* 1 -> Turbo mode is on, cannot be turned off yet
			* 2 -> Turbo mode is off, cannot be turned on yet
			* 3 -> Turbo mode is on

What:		/sys/devices/platform/msi-laptop-pf/auto_fan
Date:		Nov 2012
KernelVersion:	3.8
Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
		Contains either 0 or 1 and indicates if fan speed is controlled
		automatically (1) or fan runs at maximal speed (0). Can be
		toggled in software.

repo_name: angery/linux


code:
What:		/sys/devices/platform/<phy-name>/role
Date:		October 2016
KernelVersion:	4.10
Contact:	Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
Description:
		This file can be read and write.
		The file can show/change the phy mode for role swap of usb.

		Write the following strings to change the mode:

		 - "host" - switching mode from peripheral to host.
		 - "peripheral" - switching mode from host to peripheral.

		Read the file, then it shows the following strings:

		 - "host" - The mode is host now.
		 - "peripheral" - The mode is peripheral now.


code:
What:		/sys/devices/platform/<renesas_usb3's name>/role
Date:		March 2017
KernelVersion:	4.13
Contact:	Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
Description:
		This file can be read and write.
		The file can show/change the drd mode of usb.

		Write the following string to change the mode:

		- "host" - switching mode from peripheral to host.
		- "peripheral" - switching mode from host to peripheral.

		Read the file, then it shows the following strings:

		- "host" - The mode is host now.
		- "peripheral" - The mode is peripheral now.


code:
What:		/sys/devices/platform/8086<x>:00/firmware_version
Date:		November 2016
KernelVersion:	4.10
Contact:	"Sebastien Guiriec" <sebastien.guiriec@intel.com>
Description:
		LPE Firmware version for SST driver on all atom
		plaforms (BYT/CHT/Merrifield/BSW).
		If the FW has never been loaded it will display::

			"FW not yet loaded"

		If FW has been loaded it will display::

			"v01.aa.bb.cc"

		aa: Major version is reflecting SoC version:

			=== =============
			0d: BYT FW
			0b: BSW FW
			07: Merrifield FW
			=== =============

		bb: Minor version

		cc: Build version


code:
What:		/sys/bus/platform/devices/tahvo-usb/otg_mode
Date:		December 2013
Contact:	Aaro Koskinen <aaro.koskinen@iki.fi>
Description:
		Set or read the current OTG mode. Valid values are "host" and
		"peripheral".

		Reading: returns the current mode.

What:		/sys/bus/platform/devices/tahvo-usb/vbus
Date:		December 2013
Contact:	Aaro Koskinen <aaro.koskinen@iki.fi>
Description:
		Read the current VBUS state.

		Reading: returns "on" or "off".


code:
What:		/sys/devices/platform/ts5500/adc
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Indicates the presence of an A/D Converter. If it is present,
		it will display "1", otherwise "0".

What:		/sys/devices/platform/ts5500/ereset
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Indicates the presence of an external reset. If it is present,
		it will display "1", otherwise "0".

What:		/sys/devices/platform/ts5500/id
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Product ID of the TS board. TS-5500 ID is 0x60.

What:		/sys/devices/platform/ts5500/jumpers
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Bitfield showing the jumpers' state. If a jumper is present,
		the corresponding bit is set. For instance, 0x0e means jumpers
		2, 3 and 4 are set.

What:		/sys/devices/platform/ts5500/name
Date:		July 2014
KernelVersion:	3.16
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Model name of the TS board, e.g. "TS-5500".

What:		/sys/devices/platform/ts5500/rs485
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Indicates the presence of the RS485 option. If it is present,
		it will display "1", otherwise "0".

What:		/sys/devices/platform/ts5500/sram
Date:		January 2013
KernelVersion:	3.7
Contact:	"Savoir-faire Linux Inc." <kernel@savoirfairelinux.com>
Description:
		Indicates the presence of the SRAM option. If it is present,
		it will display "1", otherwise "0".


code:
What: /sys/bus/platform/devices/*twl4030-usb/vbus
Description:
	Read-only status reporting if VBUS (approx 5V)
	is being supplied by the USB bus.

	Possible values: "on", "off".

	Changes are notified via select/poll.


code:
What:		/sys/devices/platform/usbip-vudc.%d/dev_desc
Date:		April 2016
KernelVersion:	4.6
Contact:	Krzysztof Opasiak <k.opasiak@samsung.com>
Description:
		This file allows to read device descriptor of
		gadget driver which is currently bound to this
		controller. It is possible to read this file
		only if gadget driver is bound, otherwise error
		is returned.

What:		/sys/devices/platform/usbip-vudc.%d/usbip_status
Date:		April 2016
KernelVersion:	4.6
Contact:	Krzysztof Opasiak <k.opasiak@samsung.com>
Description:
		Current status of the device.
		Allowed values:

		==  ==========================================
		1   Device is available and can be exported
		2   Device is currently exported
		3   Fatal error occurred during communication
		    with peer
		==  ==========================================

What:		/sys/devices/platform/usbip-vudc.%d/usbip_sockfd
Date:		April 2016
KernelVersion:	4.6
Contact:	Krzysztof Opasiak <k.opasiak@samsung.com>
Description:
		This file allows to export usb device to
		connection peer. It is done by writing to this
		file socket fd (as a string for example "8")
		associated with a connection to remote peer who
		would like to use this device. It is possible to
		close the connection by writing -1 instead of
		socked fd.


code:
What:		/sys/bus/platform/devices/GOOG000C\:00/boot_on_ac
Date:		April 2019
KernelVersion:	5.3
Description:
		Boot on AC is a policy which makes the device boot from S5
		when AC power is connected. This is useful for users who
		want to run their device headless or with a dock.

		Input should be parseable by kstrtou8() to 0 or 1.

What:          /sys/bus/platform/devices/GOOG000C\:00/build_date
Date:          May 2019
KernelVersion: 5.3
Description:
               Display Wilco Embedded Controller firmware build date.
               Output will a MM/DD/YY string.

What:          /sys/bus/platform/devices/GOOG000C\:00/build_revision
Date:          May 2019
KernelVersion: 5.3
Description:
               Display Wilco Embedded Controller build revision.
               Output will a version string be similar to the example below:
               d2592cae0

What:          /sys/bus/platform/devices/GOOG000C\:00/model_number
Date:          May 2019
KernelVersion: 5.3
Description:
               Display Wilco Embedded Controller model number.
               Output will a version string be similar to the example below:
               08B6

What:          /sys/bus/platform/devices/GOOG000C\:00/usb_charge
Date:          October 2019
KernelVersion: 5.5
Description:
               Control the USB PowerShare Policy. USB PowerShare is a policy
               which affects charging via the special USB PowerShare port
               (marked with a small lightning bolt or battery icon) when in
               low power states:

               - In S0, the port will always provide power.
               - In S0ix, if usb_charge is enabled, then power will be
                 supplied to the port when on AC or if battery is > 50%.
                 Else no power is supplied.
               - In S5, if usb_charge is enabled, then power will be supplied
                 to the port when on AC. Else no power is supplied.

               Input should be either "0" or "1".

What:          /sys/bus/platform/devices/GOOG000C\:00/version
Date:          May 2019
KernelVersion: 5.3
Description:
               Display Wilco Embedded Controller firmware version.
               The format of the string is x.y.z. Where x is major, y is minor
               and z is the build number. For example: 95.00.06


code:
What:		/sys/firmware/acpi/platform_profile_choices
Date:		October 2020
Contact:	Hans de Goede <hdegoede@redhat.com>
Description:	This file contains a space-separated list of profiles supported for this device.

		Drivers must use the following standard profile-names:

		====================	========================================
		low-power		Low power consumption
		cool			Cooler operation
		quiet			Quieter operation
		balanced		Balance between low power consumption
					and performance
		balanced-performance	Balance between performance and low
					power consumption with a slight bias
					towards performance
		performance		High performance operation
		====================	========================================

		Userspace may expect drivers to offer more than one of these
		standard profile names.

What:		/sys/firmware/acpi/platform_profile
Date:		October 2020
Contact:	Hans de Goede <hdegoede@redhat.com>
Description:	Reading this file gives the current selected profile for this
		device. Writing this file with one of the strings from
		platform_profile_choices changes the profile to the new value.

		This file can be monitored for changes by polling for POLLPRI,
		POLLPRI will be signalled on any changes, independent of those
		changes coming from a userspace write; or coming from another
		source such as e.g. a hotkey triggered profile change handled
		either directly by the embedded-controller or fully handled
		inside the kernel.


code:
What:		/sys/power/
Date:		August 2006
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power directory will contain files that will
		provide a unified interface to the power management
		subsystem.

What:		/sys/power/state
Date:		November 2016
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/state file controls system sleep states.
		Reading from this file returns the available sleep state
		labels, which may be "mem" (suspend), "standby" (power-on
		suspend), "freeze" (suspend-to-idle) and "disk" (hibernation).

		Writing one of the above strings to this file causes the system
		to transition into the corresponding state, if available.

		See Documentation/admin-guide/pm/sleep-states.rst for more
		information.

What:		/sys/power/mem_sleep
Date:		November 2016
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/mem_sleep file controls the operating mode of
		system suspend.  Reading from it returns the available modes
		as "s2idle" (always present), "shallow" and "deep" (present if
		supported).  The mode that will be used on subsequent attempts
		to suspend the system (by writing "mem" to the /sys/power/state
		file described above) is enclosed in square brackets.

		Writing one of the above strings to this file causes the mode
		represented by it to be used on subsequent attempts to suspend
		the system.

		See Documentation/admin-guide/pm/sleep-states.rst for more
		information.

What:		/sys/power/disk
Date:		September 2006
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/disk file controls the operating mode of the
		suspend-to-disk mechanism.  Reading from this file returns
		the name of the method by which the system will be put to
		sleep on the next suspend.  There are four methods supported:

		'firmware' - means that the memory image will be saved to disk
		by some firmware, in which case we also assume that the
		firmware will handle the system suspend.

		'platform' - the memory image will be saved by the kernel and
		the system will be put to sleep by the platform driver (e.g.
		ACPI or other PM registers).

		'shutdown' - the memory image will be saved by the kernel and
		the system will be powered off.

		'reboot' - the memory image will be saved by the kernel and
		the system will be rebooted.

		Additionally, /sys/power/disk can be used to turn on one of the
		two testing modes of the suspend-to-disk mechanism: 'testproc'
		or 'test'.  If the suspend-to-disk mechanism is in the
		'testproc' mode, writing 'disk' to /sys/power/state will cause
		the kernel to disable nonboot CPUs and freeze tasks, wait for 5
		seconds, unfreeze tasks and enable nonboot CPUs.  If it is in
		the 'test' mode, writing 'disk' to /sys/power/state will cause
		the kernel to disable nonboot CPUs and freeze tasks, shrink
		memory, suspend devices, wait for 5 seconds, resume devices,
		unfreeze tasks and enable nonboot CPUs.  Then, we are able to
		look in the log messages and work out, for example, which code
		is being slow and which device drivers are misbehaving.

		The suspend-to-disk method may be chosen by writing to this
		file one of the accepted strings:

		- 'firmware'
		- 'platform'
		- 'shutdown'
		- 'reboot'
		- 'testproc'
		- 'test'

		It will only change to 'firmware' or 'platform' if the system
		supports that.

What:		/sys/power/image_size
Date:		August 2006
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/image_size file controls the size of the image
		created by the suspend-to-disk mechanism.  It can be written a
		string representing a non-negative integer that will be used
		as an upper limit of the image size, in bytes.  The kernel's
		suspend-to-disk code will do its best to ensure the image size
		will not exceed this number.  However, if it turns out to be
		impossible, the kernel will try to suspend anyway using the
		smallest image possible.  In particular, if "0" is written to
		this file, the suspend image will be as small as possible.

		Reading from this file will display the current image size
		limit, which is set to around 2/5 of available RAM by default.

What:		/sys/power/pm_trace
Date:		August 2006
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/pm_trace file controls the code which saves the
		last PM event point in the RTC across reboots, so that you can
		debug a machine that just hangs during suspend (or more
		commonly, during resume).  Namely, the RTC is only used to save
		the last PM event point if this file contains '1'.  Initially
		it contains '0' which may be changed to '1' by writing a
		string representing a nonzero integer into it.

		To use this debugging feature you should attempt to suspend
		the machine, then reboot it and run::

		  dmesg -s 1000000 | grep 'hash matches'

		If you do not get any matches (or they appear to be false
		positives), it is possible that the last PM event point
		referred to a device created by a loadable kernel module.  In
		this case cat /sys/power/pm_trace_dev_match (see below) after
		your system is started up and the kernel modules are loaded.

		CAUTION: Using it will cause your machine's real-time (CMOS)
		clock to be set to a random invalid time after a resume.

What;		/sys/power/pm_trace_dev_match
Date:		October 2010
Contact:	James Hogan <jhogan@kernel.org>
Description:
		The /sys/power/pm_trace_dev_match file contains the name of the
		device associated with the last PM event point saved in the RTC
		across reboots when pm_trace has been used.  More precisely it
		contains the list of current devices (including those
		registered by loadable kernel modules since boot) which match
		the device hash in the RTC at boot, with a newline after each
		one.

		The advantage of this file over the hash matches printed to the
		kernel log (see /sys/power/pm_trace), is that it includes
		devices created after boot by loadable kernel modules.

		Due to the small hash size necessary to fit in the RTC, it is
		possible that more than one device matches the hash, in which
		case further investigation is required to determine which
		device is causing the problem.  Note that genuine RTC clock
		values (such as when pm_trace has not been used), can still
		match a device and output its name here.

What:		/sys/power/pm_async
Date:		January 2009
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/pm_async file controls the switch allowing the
		user space to enable or disable asynchronous suspend and resume
		of devices.  If enabled, this feature will cause some device
		drivers' suspend and resume callbacks to be executed in parallel
		with each other and with the main suspend thread.  It is enabled
		if this file contains "1", which is the default.  It may be
		disabled by writing "0" to this file, in which case all devices
		will be suspended and resumed synchronously.

What:		/sys/power/wakeup_count
Date:		July 2010
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/wakeup_count file allows user space to put the
		system into a sleep state while taking into account the
		concurrent arrival of wakeup events.  Reading from it returns
		the current number of registered wakeup events and it blocks if
		some wakeup events are being processed at the time the file is
		read from.  Writing to it will only succeed if the current
		number of wakeup events is equal to the written value and, if
		successful, will make the kernel abort a subsequent transition
		to a sleep state if any wakeup events are reported after the
		write has returned.

What:		/sys/power/reserved_size
Date:		May 2011
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/reserved_size file allows user space to control
		the amount of memory reserved for allocations made by device
		drivers during the "device freeze" stage of hibernation.  It can
		be written a string representing a non-negative integer that
		will be used as the amount of memory to reserve for allocations
		made by device drivers' "freeze" callbacks, in bytes.

		Reading from this file will display the current value, which is
		set to 1 MB by default.

What:		/sys/power/autosleep
Date:		April 2012
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/autosleep file can be written one of the strings
		returned by reads from /sys/power/state.  If that happens, a
		work item attempting to trigger a transition of the system to
		the sleep state represented by that string is queued up.  This
		attempt will only succeed if there are no active wakeup sources
		in the system at that time.  After every execution, regardless
		of whether or not the attempt to put the system to sleep has
		succeeded, the work item requeues itself until user space
		writes "off" to /sys/power/autosleep.

		Reading from this file causes the last string successfully
		written to it to be returned.

What:		/sys/power/wake_lock
Date:		February 2012
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/wake_lock file allows user space to create
		wakeup source objects and activate them on demand (if one of
		those wakeup sources is active, reads from the
		/sys/power/wakeup_count file block or return false).  When a
		string without white space is written to /sys/power/wake_lock,
		it will be assumed to represent a wakeup source name.  If there
		is a wakeup source object with that name, it will be activated
		(unless active already).  Otherwise, a new wakeup source object
		will be registered, assigned the given name and activated.
		If a string written to /sys/power/wake_lock contains white
		space, the part of the string preceding the white space will be
		regarded as a wakeup source name and handled as descrived above.
		The other part of the string will be regarded as a timeout (in
		nanoseconds) such that the wakeup source will be automatically
		deactivated after it has expired.  The timeout, if present, is
		set regardless of the current state of the wakeup source object
		in question.

		Reads from this file return a string consisting of the names of
		wakeup sources created with the help of it that are active at
		the moment, separated with spaces.

What:		/sys/power/wake_unlock
Date:		February 2012
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/wake_unlock file allows user space to deactivate
		wakeup sources created with the help of /sys/power/wake_lock.
		When a string is written to /sys/power/wake_unlock, it will be
		assumed to represent the name of a wakeup source to deactivate.

		If a wakeup source object of that name exists and is active at
		the moment, it will be deactivated.

		Reads from this file return a string consisting of the names of
		wakeup sources created with the help of /sys/power/wake_lock
		that are inactive at the moment, separated with spaces.

What:		/sys/power/pm_print_times
Date:		May 2012
Contact:	Sameer Nanda <snanda@chromium.org>
Description:
		The /sys/power/pm_print_times file allows user space to
		control whether the time taken by devices to suspend and
		resume is printed.  These prints are useful for hunting down
		devices that take too long to suspend or resume.

		Writing a "1" enables this printing while writing a "0"
		disables it.  The default value is "0".  Reading from this file
		will display the current value.

What:		/sys/power/pm_wakeup_irq
Date:		April 2015
Contact:	Alexandra Yates <alexandra.yates@linux.intel.org>
Description:
		The /sys/power/pm_wakeup_irq file reports to user space the IRQ
		number of the first wakeup interrupt (that is, the first
		interrupt from an IRQ line armed for system wakeup) seen by the
		kernel during the most recent system suspend/resume cycle.

		This output is useful for system wakeup diagnostics of spurious
		wakeup interrupts.

What:		/sys/power/pm_debug_messages
Date:		July 2017
Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
		The /sys/power/pm_debug_messages file controls the printing
		of debug messages from the system suspend/hiberbation
		infrastructure to the kernel log.

		Writing a "1" to this file enables the debug messages and
		writing a "0" (default) to it disables them.  Reads from
		this file return the current value.

What:		/sys/power/resume_offset
Date:		April 2018
Contact:	Mario Limonciello <mario.limonciello@outlook.com>
Description:
		This file is used for telling the kernel an offset into a disk
		to use when hibernating the system such as with a swap file.

		Reads from this file will display the current offset
		the kernel will be using on the next hibernation
		attempt.

		Using this sysfs file will override any values that were
		set using the kernel command line for disk offset.

What:		/sys/power/suspend_stats
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats directory contains suspend related
		statistics.

What:		/sys/power/suspend_stats/success
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/success file contains the number
		of times entering system sleep state succeeded.

What:		/sys/power/suspend_stats/fail
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/fail file contains the number
		of times entering system sleep state failed.

What:		/sys/power/suspend_stats/failed_freeze
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_freeze file contains the
		number of times freezing processes failed.

What:		/sys/power/suspend_stats/failed_prepare
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_prepare file contains the
		number of times preparing all non-sysdev devices for
		a system PM transition failed.

What:		/sys/power/suspend_stats/failed_resume
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_resume file contains the
		number of times executing "resume" callbacks of
		non-sysdev devices failed.

What:		/sys/power/suspend_stats/failed_resume_early
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_resume_early file contains
		the number of times executing "early resume" callbacks
		of devices failed.

What:		/sys/power/suspend_stats/failed_resume_noirq
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_resume_noirq file contains
		the number of times executing "noirq resume" callbacks
		of devices failed.

What:		/sys/power/suspend_stats/failed_suspend
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_suspend file contains
		the number of times executing "suspend" callbacks
		of all non-sysdev devices failed.

What:		/sys/power/suspend_stats/failed_suspend_late
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_suspend_late file contains
		the number of times executing "late suspend" callbacks
		of all devices failed.

What:		/sys/power/suspend_stats/failed_suspend_noirq
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/failed_suspend_noirq file contains
		the number of times executing "noirq suspend" callbacks
		of all devices failed.

What:		/sys/power/suspend_stats/last_failed_dev
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/last_failed_dev file contains
		the last device for which a suspend/resume callback failed.

What:		/sys/power/suspend_stats/last_failed_errno
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/last_failed_errno file contains
		the errno of the last failed attempt at entering
		system sleep state.

What:		/sys/power/suspend_stats/last_failed_step
Date:		July 2019
Contact:	Kalesh Singh <kaleshsingh96@gmail.com>
Description:
		The /sys/power/suspend_stats/last_failed_step file contains
		the last failed step in the suspend/resume path.

What:		/sys/power/sync_on_suspend
Date:		October 2019
Contact:	Jonas Meurer <jonas@freesources.org>
Description:
		This file controls whether or not the kernel will sync()
		filesystems during system suspend (after freezing user space
		and before suspending devices).

		Writing a "1" to this file enables the sync() and writing a "0"
		disables it.  Reads from the file return the current value.
		The default is "1" if the build-time "SUSPEND_SKIP_SYNC" config
		flag is unset, or "0" otherwise.

path: Documentation/ABI/testing/sysfs-power


code:
What:		/sys/class/pps/
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ directory will contain files and
		directories that will provide a unified interface to
		the PPS sources.

What:		/sys/class/pps/ppsX/
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/ directory is related to X-th
		PPS source into the system. Each directory will
		contain files to manage and control its PPS source.

What:		/sys/class/pps/ppsX/assert
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/assert file reports the assert events
		and the assert sequence number of the X-th source in the form:

			<secs>.<nsec>#<sequence>

		If the source has no assert events the content of this file
		is empty.

What:		/sys/class/pps/ppsX/clear
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/clear file reports the clear events
		and the clear sequence number of the X-th source in the form:

			<secs>.<nsec>#<sequence>

		If the source has no clear events the content of this file
		is empty.

What:		/sys/class/pps/ppsX/mode
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/mode file reports the functioning
		mode of the X-th source in hexadecimal encoding.

		Please, refer to linux/include/linux/pps.h for further
		info.

What:		/sys/class/pps/ppsX/echo
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/echo file reports if the X-th does
		or does not support an "echo" function.

What:		/sys/class/pps/ppsX/name
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/name file reports the name of the
		X-th source.

What:		/sys/class/pps/ppsX/path
Date:		February 2008
Contact:	Rodolfo Giometti <giometti@linux.it>
Description:
		The /sys/class/pps/ppsX/path file reports the path name of
		the device connected with the X-th source.

		If the source is not connected with any device the content
		of this file is empty.

path: Documentation/ABI/testing/sysfs-pps


code:
What:		/sys/kernel/profiling
Date:		September 2008
Contact:	Dave Hansen <dave@linux.vnet.ibm.com>
Description:
		/sys/kernel/profiling is the runtime equivalent
		of the boot-time profile= option.

		You can get the same effect running::

			echo 2 > /sys/kernel/profiling

		as you would by issuing profile=2 on the boot
		command line.


code:
What:		/sys/class/ptp/
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This directory contains files and directories
		providing a standardized interface to the ancillary
		features of PTP hardware clocks.

What:		/sys/class/ptp/ptp<N>/
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This directory contains the attributes of the Nth PTP
		hardware clock registered into the PTP class driver
		subsystem.

What:		/sys/class/ptp/ptp<N>/clock_name
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the name of the PTP hardware clock
		as a human readable string. The purpose of this
		attribute is to provide the user with a "friendly
		name" and to help distinguish PHY based devices from
		MAC based ones. The string does not necessarily have
		to be any kind of unique id.

What:		/sys/class/ptp/ptp<N>/max_adjustment
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the PTP hardware clock's maximum
		frequency adjustment value (a positive integer) in
		parts per billion.

What:		/sys/class/ptp/ptp<N>/max_vclocks
Date:		May 2021
Contact:	Yangbo Lu <yangbo.lu@nxp.com>
Description:
		This file contains the maximum number of ptp vclocks.
		Write integer to re-configure it.

What:		/sys/class/ptp/ptp<N>/n_alarms
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the number of periodic or one shot
		alarms offer by the PTP hardware clock.

What:		/sys/class/ptp/ptp<N>/n_external_timestamps
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the number of external timestamp
		channels offered by the PTP hardware clock.

What:		/sys/class/ptp/ptp<N>/n_periodic_outputs
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the number of programmable periodic
		output channels offered by the PTP hardware clock.

What:		/sys/class/ptp/ptp<N>/n_pins
Date:		March 2014
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file contains the number of programmable pins
		offered by the PTP hardware clock.

What:		/sys/class/ptp/ptp<N>/n_vclocks
Date:		May 2021
Contact:	Yangbo Lu <yangbo.lu@nxp.com>
Description:
		This file contains the number of virtual PTP clocks in
		use.  By default, the value is 0 meaning that only the
		physical clock is in use.  Setting the value creates
		the corresponding number of virtual clocks and causes
		the physical clock to become free running.  Setting the
		value back to 0 deletes the virtual clocks and
		switches the physical clock back to normal, adjustable
		operation.

What:		/sys/class/ptp/ptp<N>/pins
Date:		March 2014
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This directory contains one file for each programmable
		pin offered by the PTP hardware clock. The file name
		is the hardware dependent pin name. Reading from this
		file produces two numbers, the assigned function (see
		the `PTP_PF_` enumeration values in linux/ptp_clock.h)
		and the channel number. The function and channel
		assignment may be changed by two writing numbers into
		the file.

What:		/sys/class/ptp/ptp<N>/pps_available
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file indicates whether the PTP hardware clock
		supports a Pulse Per Second to the host CPU. Reading
		"1" means that the PPS is supported, while "0" means
		not supported.

What:		/sys/class/ptp/ptp<N>/extts_enable
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This write-only file enables or disables external
		timestamps. To enable external timestamps, write the
		channel index followed by a "1" into the file.
		To disable external timestamps, write the channel
		index followed by a "0" into the file.

What:		/sys/class/ptp/ptp<N>/fifo
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This file provides timestamps on external events, in
		the form of three integers: channel index, seconds,
		and nanoseconds.

What:		/sys/class/ptp/ptp<N>/period
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This write-only file enables or disables periodic
		outputs. To enable a periodic output, write five
		integers into the file: channel index, start time
		seconds, start time nanoseconds, period seconds, and
		period nanoseconds. To disable a periodic output, set
		all the seconds and nanoseconds values to zero.

What:		/sys/class/ptp/ptp<N>/pps_enable
Date:		September 2010
Contact:	Richard Cochran <richardcochran@gmail.com>
Description:
		This write-only file enables or disables delivery of
		PPS events to the Linux PPS subsystem. To enable PPS
		events, write a "1" into the file. To disable events,
		write a "0" into the file.

path: Documentation/ABI/testing/sysfs-ptp


code:
What:		/sys/firmware/secvar
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	This directory is created if the POWER firmware supports OS
		secureboot, thereby secure variables. It exposes interface
		for reading/writing the secure variables

What:		/sys/firmware/secvar/vars
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	This directory lists all the secure variables that are supported
		by the firmware.

What:		/sys/firmware/secvar/format
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	A string indicating which backend is in use by the firmware.
		This determines the format of the variable and the accepted
		format of variable updates.

What:		/sys/firmware/secvar/vars/<variable name>
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	Each secure variable is represented as a directory named as
		<variable_name>. The variable name is unique and is in ASCII
		representation. The data and size can be determined by reading
		their respective attribute files.

What:		/sys/firmware/secvar/vars/<variable_name>/size
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	An integer representation of the size of the content of the
		variable. In other words, it represents the size of the data.

What:		/sys/firmware/secvar/vars/<variable_name>/data
Date:		August 2019
Contact:	Nayna Jain h<nayna@linux.ibm.com>
Description:	A read-only file containing the value of the variable. The size
		of the file represents the maximum size of the variable data.

What:		/sys/firmware/secvar/vars/<variable_name>/update
Date:		August 2019
Contact:	Nayna Jain <nayna@linux.ibm.com>
Description:	A write-only file that is used to submit the new value for the
		variable. The size of the file represents the maximum size of
		the variable data that can be written.

path: Documentation/ABI/testing/sysfs-secvar


code:
What:		/sys/class/timecard/
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This directory contains files and directories
		providing a standardized interface to the ancillary
		features of the OpenCompute timecard.

What:		/sys/class/timecard/ocpN/
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This directory contains the attributes of the Nth timecard
		registered.

What:		/sys/class/timecard/ocpN/available_clock_sources
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) The list of available time sources that the PHC
		uses for clock adjustments.

		====  =================================================
                NONE  no adjustments
                PPS   adjustments come from the PPS1 selector (default)
                TOD   adjustments from the GNSS/TOD module
                IRIG  adjustments from external IRIG-B signal
                DCF   adjustments from external DCF signal
                ====  =================================================

What:		/sys/class/timecard/ocpN/available_sma_inputs
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Set of available destinations (sinks) for a SMA
		input signal.

                =====  ================================================
                10Mhz  signal is used as the 10Mhz reference clock
                PPS1   signal is sent to the PPS1 selector
                PPS2   signal is sent to the PPS2 selector
                TS1    signal is sent to timestamper 1
                TS2    signal is sent to timestamper 2
                TS3    signal is sent to timestamper 3
                TS4    signal is sent to timestamper 4
                IRIG   signal is sent to the IRIG-B module
                DCF    signal is sent to the DCF module
                FREQ1  signal is sent to frequency counter 1
                FREQ2  signal is sent to frequency counter 2
                FREQ3  signal is sent to frequency counter 3
                FREQ4  signal is sent to frequency counter 4
                None   signal input is disabled
                =====  ================================================

What:		/sys/class/timecard/ocpN/available_sma_outputs
Date:		May 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Set of available sources for a SMA output signal.

                =====  ================================================
                10Mhz  output is from the 10Mhz reference clock
                PHC    output PPS is from the PHC clock
                MAC    output PPS is from the Miniature Atomic Clock
                GNSS1  output PPS is from the first GNSS module
                GNSS2  output PPS is from the second GNSS module
                IRIG   output is from the PHC, in IRIG-B format
                DCF    output is from the PHC, in DCF format
                GEN1   output is from frequency generator 1
                GEN2   output is from frequency generator 2
                GEN3   output is from frequency generator 3
                GEN4   output is from frequency generator 4
                GND    output is GND
                VCC    output is VCC
                =====  ================================================

What:		/sys/class/timecard/ocpN/clock_source
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) Contains the current synchronization source used by
		the PHC.  May be changed by writing one of the listed
		values from the available_clock_sources attribute set.

What:		/sys/class/timecard/ocpN/clock_status_drift
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Contains the current drift value used by the firmware
		for internal disciplining of the atomic clock.

What:		/sys/class/timecard/ocpN/clock_status_offset
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Contains the current offset value used by the firmware
		for internal disciplining of the atomic clock.

What:		/sys/class/timecard/ocpN/freqX
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Optional directory containing the sysfs nodes for
		frequency counter <X>.

What:		/sys/class/timecard/ocpN/freqX/frequency
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Contains the measured frequency over the specified
		measurement period.

What:		/sys/class/timecard/ocpN/freqX/seconds
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) Specifies the number of seconds from 0-255 that the
		frequency should be measured over.  Write 0 to disable.

What:		/sys/class/timecard/ocpN/genX
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Optional directory containing the sysfs nodes for
		frequency generator <X>.

What:		/sys/class/timecard/ocpN/genX/duty
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Specifies the signal duty cycle as a percentage from 1-99.

What:		/sys/class/timecard/ocpN/genX/period
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Specifies the signal period in nanoseconds.

What:		/sys/class/timecard/ocpN/genX/phase
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Specifies the signal phase offset in nanoseconds.

What:		/sys/class/timecard/ocpN/genX/polarity
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Specifies the signal polarity, either 1 or 0.

What:		/sys/class/timecard/ocpN/genX/running
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Either 0 or 1, showing if the signal generator is running.

What:		/sys/class/timecard/ocpN/genX/start
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Shows the time in <sec>.<nsec> that the signal generator
		started running.

What:		/sys/class/timecard/ocpN/genX/signal
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) Used to start the signal generator, and summarize
		the current status.

		The signal generator may be started by writing the signal
		period, followed by the optional signal values.  If the
		optional values are not provided, they default to the current
		settings, which may be obtained from the other sysfs nodes.

		    period [duty [phase [polarity]]]

		echo 500000000 > signal       # 1/2 second period
		echo 1000000 40 100 > signal
		echo 0 > signal               # turn off generator

		Period and phase are specified in nanoseconds.  Duty cycle is
		a percentage from 1-99.  Polarity is 1 or 0.

		Reading this node will return:

		    period duty phase polarity start_time

What:		/sys/class/timecard/ocpN/gnss_sync
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Indicates whether a valid GNSS signal is received,
		or when the signal was lost.

What:		/sys/class/timecard/ocpN/i2c
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This optional attribute links to the associated i2c device.

What:		/sys/class/timecard/ocpN/irig_b_mode
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) An integer from 0-7 indicating the timecode format
		of the IRIG-B output signal: B00<n>

What:		/sys/class/timecard/ocpN/pps
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This optional attribute links to the associated PPS device.

What:		/sys/class/timecard/ocpN/ptp
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This attribute links to the associated PTP device.

What:		/sys/class/timecard/ocpN/serialnum
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RO) Provides the serial number of the timecard.

What:		/sys/class/timecard/ocpN/sma1
What:		/sys/class/timecard/ocpN/sma2
What:		/sys/class/timecard/ocpN/sma3
What:		/sys/class/timecard/ocpN/sma4
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) These attributes specify the direction of the signal
		on the associated SMA connectors, and also the signal sink
		or source.

		The display format of the attribute is a space separated
		list of signals, prefixed by the input/output direction.

		The signal direction may be changed (if supported) by
		prefixing the signal list with either "in:" or "out:".
		If neither prefix is present, then the direction is unchanged.

		The output signal may be changed by writing one of the listed
		values from the available_sma_outputs attribute set.

		The input destinations may be changed by writing multiple
		values from the available_sma_inputs attribute set,
		separated by spaces.  If there are duplicated input
		destinations between connectors, the lowest numbered SMA
		connector is given priority.

		Note that not all input combinations may make sense.

		The 10Mhz reference clock input is currently only valid
		on SMA1 and may not be combined with other destination sinks.

What:		/sys/class/timecard/ocpN/tod_correction
Date:		March 2022
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) The incoming GNSS signal is in UTC time, and the NMEA
		format messages do not provide a TAI offset.  This sets the
		correction value for the incoming time.

		If UBX_LS is enabled, this should be 0, and the offset is
		taken from the UBX-NAV-TIMELS message.

What:		/sys/class/timecard/ocpN/ts_window_adjust
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) When retrieving the PHC with the PTP SYS_OFFSET_EXTENDED
		ioctl, a system timestamp is made before and after the PHC
		time is retrieved.  The midpoint between the two system
		timestamps is usually taken to be the SYS time associated
		with the PHC time.  This estimate may be wrong, as it depends
		on PCI latencies, and when the PHC time was latched

		The attribute value reduces the end timestamp by the given
		number of nanoseconds, so the computed midpoint matches the
		retrieved PHC time.

		The initial value is set based on measured PCI latency and
		the estimated point where the FPGA latches the PHC time.  This
		value may be changed by writing an unsigned integer.

What:		/sys/class/timecard/ocpN/ttyGNSS
What:		/sys/class/timecard/ocpN/ttyGNSS2
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	These optional attributes link to the TTY serial ports
		associated with the GNSS devices.

What:		/sys/class/timecard/ocpN/ttyMAC
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This optional attribute links to the TTY serial port
		associated with the Miniature Atomic Clock.

What:		/sys/class/timecard/ocpN/ttyNMEA
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	This optional attribute links to the TTY serial port
		which outputs the PHC time in NMEA ZDA format.

What:		/sys/class/timecard/ocpN/utc_tai_offset
Date:		September 2021
Contact:	Jonathan Lemon <jonathan.lemon@gmail.com>
Description:	(RW) The DCF and IRIG output signals are in UTC, while the
		TimeCard operates on TAI.  This attribute allows setting the
		offset in seconds, which is added to the TAI timebase for
		these formats.

		The offset may be changed by writing an unsigned integer.


code:
What:		/sys/class/tty/console/active
Date:		Nov 2010
Contact:	Kay Sievers <kay.sievers@vrfy.org>
Description:
		 Shows the list of currently configured
		 console devices, like 'tty1 ttyS0'.
		 The last entry in the file is the active
		 device connected to /dev/console.
		 The file supports poll() to detect virtual
		 console switches.

What:		/sys/class/tty/tty<x>/active
Date:		Nov 2010
Contact:	Kay Sievers <kay.sievers@vrfy.org>
Description:
		 Shows the currently active virtual console
		 device, like 'tty1'.
		 The file supports poll() to detect virtual
		 console switches.

What:		/sys/class/tty/ttyS<x>/uartclk
Date:		Sep 2012
Contact:	Tomas Hlavacek <tmshlvck@gmail.com>
Description:
		 Shows the current uartclk value associated with the
		 UART port in serial_core, that is bound to TTY like ttyS0.
		 uartclk = 16 * baud_base

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/type
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Shows the current tty type for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/line
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Shows the current tty line number for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/port
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Shows the current tty port I/O address for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/irq
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Shows the current primary interrupt for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/flags
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the tty port status flags for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/xmit_fifo_size
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the transmit FIFO size for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/close_delay
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the closing delay time for this port in ms.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/closing_wait
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the close wait time for this port in ms.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/custom_divisor
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the custom divisor if any that is set on this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/io_type
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the I/O type that is to be used with the iomem base
		 address.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/iomem_base
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 The I/O memory base for this port.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/iomem_reg_shift
Date:		October 2012
Contact:	Alan Cox <alan@linux.intel.com>
Description:
		 Show the register shift indicating the spacing to be used
		 for accesses on this iomem address.

		 These sysfs values expose the TIOCGSERIAL interface via
		 sysfs rather than via ioctls.

What:		/sys/class/tty/ttyS<x>/rx_trig_bytes
Date:		May 2014
Contact:	Yoshihiro YUNOMAE <yoshihiro.yunomae.ez@hitachi.com>
Description:
		 Shows current RX interrupt trigger bytes or sets the
		 user specified value to change it for the FIFO buffer.
		 Users can show or set this value regardless of opening the
		 serial device file or not.

		 The RX trigger can be set one of four kinds of values for UART
		 serials. When users input a meaning less value to this I/F,
		 the RX trigger is changed to the nearest lower value for the
		 device specification. For example, when user sets 7bytes on
		 16550A, which has 1/4/8/14 bytes trigger, the RX trigger is
		 automatically changed to 4 bytes.

What:		/sys/class/tty/ttyS<x>/console
Date:		February 2020
Contact:	Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Description:
		 Allows user to detach or attach back the given device as
		 kernel console. It shows and accepts a boolean variable.

path: Documentation/ABI/testing/sysfs-tty


code:
What:           /sys/.../uevent
Date:           May 2017
KernelVersion:  4.13
Contact:        Linux kernel mailing list <linux-kernel@vger.kernel.org>
Description:
                Enable passing additional variables for synthetic uevents that
                are generated by writing /sys/.../uevent file.

                Recognized extended format is::

			ACTION [UUID [KEY=VALUE ...]

                The ACTION is compulsory - it is the name of the uevent
                action (``add``, ``change``, ``remove``). There is no change
                compared to previous functionality here. The rest of the
                extended format is optional.

                You need to pass UUID first before any KEY=VALUE pairs.
                The UUID must be in ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
                format where 'x' is a hex digit. The UUID is considered to be
                a transaction identifier so it's possible to use the same UUID
                value for one or more synthetic uevents in which case we
                logically group these uevents together for any userspace
                listeners. The UUID value appears in uevent as
                ``SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` environment
                variable.

                If UUID is not passed in, the generated synthetic uevent gains
                ``SYNTH_UUID=0`` environment variable automatically.

                The KEY=VALUE pairs can contain alphanumeric characters only.

                It's possible to define zero or more pairs - each pair is then
                delimited by a space character ' '. Each pair appears in
                synthetic uevent as ``SYNTH_ARG_KEY=VALUE``. That means the KEY
                name gains ``SYNTH_ARG_`` prefix to avoid possible collisions
                with existing variables.

                Example of valid sequence written to the uevent file::

                    add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc

                This generates synthetic uevent including these variables::

                    ACTION=add
                    SYNTH_ARG_A=1
                    SYNTH_ARG_B=abc
                    SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed

Users:
                udev, userspace tools generating synthetic uevents

path: Documentation/ABI/testing/sysfs-uevent


code:
What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_*
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                Various files for managing Cable Based Association of
                (wireless) USB devices.

                The sequence of operations should be:

                1. Device is plugged in.

                2. The connection manager (CM) sees a device with CBA capability.
                   (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE).

                3. The CM writes the host name, supported band groups,
                   and the CHID (host ID) into the wusb_host_name,
                   wusb_host_band_groups and wusb_chid files. These
                   get sent to the device and the CDID (if any) for
                   this host is requested.

                4. The CM can verify that the device's supported band
                   groups (wusb_device_band_groups) are compatible
                   with the host.

                5. The CM reads the wusb_cdid file.

                6. The CM looks it up its database.

                   - If it has a matching CHID,CDID entry, the device
                     has been authorized before and nothing further
                     needs to be done.

                   - If the CDID is zero (or the CM doesn't find a
                     matching CDID in its database), the device is
                     assumed to be not known.  The CM may associate
                     the host with device by: writing a randomly
                     generated CDID to wusb_cdid and then a random CK
                     to wusb_ck (this uploads the new CC to the
                     device).

                     CMD may choose to prompt the user before
                     associating with a new device.

                7. Device is unplugged.

                References:
                  [WUSB-AM]
			    Association Models Supplement to the
                            Certified Wireless Universal Serial Bus
                            Specification, version 1.0.

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                The CHID of the host formatted as 16 space-separated
                hex octets.

                Writes fetches device's supported band groups and the
                the CDID for any existing association with this host.

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                A friendly name for the host as a UTF-8 encoded string.

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                The band groups supported by the host, in the format
                defined in [WUSB-AM].

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                The band groups supported by the device, in the format
                defined in [WUSB-AM].

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                The device's CDID formatted as 16 space-separated hex
                octets.

What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
Description:
                Write 16 space-separated random, hex octets to
                associate with the device.


code:
What:		Raise a uevent when a USB charger is inserted or removed
Date:		2020-01-14
KernelVersion:	5.6
Contact:	linux-usb@vger.kernel.org
Description:	There are two USB charger states:

		- USB_CHARGER_ABSENT
		- USB_CHARGER_PRESENT

		There are five USB charger types:

		========================  ==========================
		USB_CHARGER_UNKNOWN_TYPE  Charger type is unknown
		USB_CHARGER_SDP_TYPE      Standard Downstream Port
		USB_CHARGER_CDP_TYPE      Charging Downstream Port
		USB_CHARGER_DCP_TYPE      Dedicated Charging Port
		USB_CHARGER_ACA_TYPE      Accessory Charging Adapter
		========================  ==========================

		https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement

		Here are two examples taken using ``udevadm monitor -p`` when
		USB charger is online::

		    UDEV  change   /devices/soc0/usbphynop1 (platform)
		    ACTION=change
		    DEVPATH=/devices/soc0/usbphynop1
		    DRIVER=usb_phy_generic
		    MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
		    OF_COMPATIBLE_0=usb-nop-xceiv
		    OF_COMPATIBLE_N=1
		    OF_FULLNAME=/usbphynop1
		    OF_NAME=usbphynop1
		    SEQNUM=2493
		    SUBSYSTEM=platform
		    USB_CHARGER_STATE=USB_CHARGER_PRESENT
		    USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
		    USEC_INITIALIZED=227422826

		USB charger is offline::

		    KERNEL change   /devices/soc0/usbphynop1 (platform)
		    ACTION=change
		    DEVPATH=/devices/soc0/usbphynop1
		    DRIVER=usb_phy_generic
		    MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
		    OF_COMPATIBLE_0=usb-nop-xceiv
		    OF_COMPATIBLE_N=1
		    OF_FULLNAME=/usbphynop1
		    OF_NAME=usbphynop1
		    SEQNUM=2494
		    SUBSYSTEM=platform
		    USB_CHARGER_STATE=USB_CHARGER_ABSENT
		    USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE


code:
What:		Raise a uevent when a USB Host Controller has died
Date:		2019-04-17
KernelVersion:	5.2
Contact:	linux-usb@vger.kernel.org
Description:	When the USB Host Controller has entered a state where it is no
		longer functional a uevent will be raised. The uevent will
		contain ACTION=offline and ERROR=DEAD.

		Here is an example taken using udevadm monitor -p::

		    KERNEL[130.428945] offline  /devices/pci0000:00/0000:00:10.0/usb2 (usb)
		    ACTION=offline
		    BUSNUM=002
		    DEVNAME=/dev/bus/usb/002/001
		    DEVNUM=001
		    DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2
		    DEVTYPE=usb_device
		    DRIVER=usb
		    ERROR=DEAD
		    MAJOR=189
		    MINOR=128
		    PRODUCT=1d6b/2/414
		    SEQNUM=2168
		    SUBSYSTEM=usb
		    TYPE=9/0/1

Users:		chromium-os-dev@chromium.org

path: Documentation/ABI/testing/usb-uevent


code: This file has moved to process/coding-style.rst

path: Documentation/CodingStyle


code:
config WARN_MISSING_DOCUMENTS
	bool "Warn if there's a missing documentation file"
	depends on COMPILE_TEST
	help
	  It is not uncommon that a document gets renamed.
	  This option makes the Kernel to check for missing dependencies,
	  warning when something is missing. Works only if the Kernel
	  is built from a git tree.

	  If unsure, select 'N'.

config WARN_ABI_ERRORS
	bool "Warn if there are errors at ABI files"
	depends on COMPILE_TEST
	help
	  The files under Documentation/ABI should follow what's
	  described at Documentation/ABI/README. Yet, as they're manually
	  written, it would be possible that some of those files would
	  have errors that would break them for being parsed by
	  scripts/get_abi.pl. Add a check to verify them.

	  If unsure, select 'N'.

path: Documentation/Kconfig


code:
# -*- makefile -*-
# Makefile for Sphinx documentation
#

# for cleaning
subdir- := devicetree/bindings

# Check for broken documentation file references
ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
endif

# Check for broken ABI files
ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
endif

# You can set these variables from the command line.
SPHINXBUILD   = sphinx-build
SPHINXOPTS    =
SPHINXDIRS    = .
DOCS_THEME    =
DOCS_CSS      =
_SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
SPHINX_CONF   = conf.py
PAPER         =
BUILDDIR      = $(obj)/output
PDFLATEX      = xelatex
LATEXOPTS     = -interaction=batchmode -no-shell-escape

ifeq ($(KBUILD_VERBOSE),0)
SPHINXOPTS    += "-q"
endif

# User-friendly check for sphinx-build
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

ifeq ($(HAVE_SPHINX),0)

.DEFAULT:
	$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
	@echo
	@$(srctree)/scripts/sphinx-pre-install
	@echo "  SKIP    Sphinx $@ target."

else # HAVE_SPHINX

# User-friendly check for pdflatex and latexmk
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)

ifeq ($(HAVE_LATEXMK),1)
	PDFLATEX := latexmk -$(PDFLATEX)
endif #HAVE_LATEXMK

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC       = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;

# $2 sphinx builder e.g. "html"
# $3 name of the build subfolder / e.g. "userspace-api/media", used as:
#    * dest folder relative to $(BUILDDIR) and
#    * cache folder relative to $(BUILDDIR)/.doctrees
# $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man
# $5 reST source folder relative to $(srctree)/$(src),
#    e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media

quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
	PYTHONDONTWRITEBYTECODE=1 \
	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
	$(PYTHON3) $(srctree)/scripts/jobserver-exec \
	$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
	$(SPHINXBUILD) \
	-b $2 \
	-c $(abspath $(srctree)/$(src)) \
	-d $(abspath $(BUILDDIR)/.doctrees/$3) \
	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
	$(ALLSPHINXOPTS) \
	$(abspath $(srctree)/$(src)/$5) \
	$(abspath $(BUILDDIR)/$3/$4) && \
	if [ "x$(DOCS_CSS)" != "x" ]; then \
		cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
	fi

htmldocs:
	@$(srctree)/scripts/sphinx-pre-install --version-check
	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

texinfodocs:
	@$(srctree)/scripts/sphinx-pre-install --version-check
	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))

# Note: the 'info' Make target is generated by sphinx itself when
# running the texinfodocs target define above.
infodocs: texinfodocs
	$(MAKE) -C $(BUILDDIR)/texinfo info

linkcheckdocs:
	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))

latexdocs:
	@$(srctree)/scripts/sphinx-pre-install --version-check
	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))

ifeq ($(HAVE_PDFLATEX),0)

pdfdocs:
	$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
	@echo "  SKIP    Sphinx $@ target."

else # HAVE_PDFLATEX

pdfdocs: latexdocs
	@$(srctree)/scripts/sphinx-pre-install --version-check
	$(foreach var,$(SPHINXDIRS), \
	   $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \
	   mkdir -p $(BUILDDIR)/$(var)/pdf; \
	   mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
	)

endif # HAVE_PDFLATEX

epubdocs:
	@$(srctree)/scripts/sphinx-pre-install --version-check
	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))

xmldocs:
	@$(srctree)/scripts/sphinx-pre-install --version-check
	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))

endif # HAVE_SPHINX

# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.

refcheckdocs:
	$(Q)cd $(srctree);scripts/documentation-file-ref-check

cleandocs:
	$(Q)rm -rf $(BUILDDIR)
	$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean

dochelp:
	@echo  ' Linux kernel internal documentation in different formats from ReST:'
	@echo  '  htmldocs        - HTML'
	@echo  '  texinfodocs     - Texinfo'
	@echo  '  infodocs        - Info'
	@echo  '  latexdocs       - LaTeX'
	@echo  '  pdfdocs         - PDF'
	@echo  '  epubdocs        - EPUB'
	@echo  '  xmldocs         - XML'
	@echo  '  linkcheckdocs   - check for broken external links'
	@echo  '                    (will connect to external hosts)'
	@echo  '  refcheckdocs    - check for references to non-existing files under'
	@echo  '                    Documentation'
	@echo  '  cleandocs       - clean all generated files'
	@echo
	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
	@echo
	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
	@echo
	@echo  '  make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
	@echo
	@echo  '  make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
	@echo
	@echo  '  Default location for the generated documents is Documentation/output'

path: Documentation/Makefile


code:
.. SPDX-License-Identifier: GPL-2.0

========================================
ACPI considerations for PCI host bridges
========================================

The general rule is that the ACPI namespace should describe everything the
OS might use unless there's another way for the OS to find it [1, 2].

For example, there's no standard hardware mechanism for enumerating PCI
host bridges, so the ACPI namespace must describe each host bridge, the
method for accessing PCI config space below it, the address space windows
the host bridge forwards to PCI (using _CRS), and the routing of legacy
INTx interrupts (using _PRT).

PCI devices, which are below the host bridge, generally do not need to be
described via ACPI.  The OS can discover them via the standard PCI
enumeration mechanism, using config accesses to discover and identify
devices and read and size their BARs.  However, ACPI may describe PCI
devices if it provides power management or hotplug functionality for them
or if the device has INTx interrupts connected by platform interrupt
controllers and a _PRT is needed to describe those connections.

ACPI resource description is done via _CRS objects of devices in the ACPI
namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read
_CRS and figure out what resource is being consumed even if it doesn't have
a driver for the device [3].  That's important because it means an old OS
can work correctly even on a system with new devices unknown to the OS.
The new devices might not do anything, but the OS can at least make sure no
resources conflict with them.

Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
reserving address space.  The static tables are for things the OS needs to
know early in boot, before it can parse the ACPI namespace.  If a new table
is defined, an old OS needs to operate correctly even though it ignores the
table.  _CRS allows that because it is generic and understood by the old
OS; a static table does not.

If the OS is expected to manage a non-discoverable device described via
ACPI, that device will have a specific _HID/_CID that tells the OS what
driver to bind to it, and the _CRS tells the OS and the driver where the
device's registers are.

PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
describe all the address space they consume.  This includes all the windows
they forward down to the PCI bus, as well as registers of the host bridge
itself that are not forwarded to PCI.  The host bridge registers include
things like secondary/subordinate bus registers that determine the bus
range below the bridge, window registers that describe the apertures, etc.
These are all device-specific, non-architected things, so the only way a
PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
the device-specific details.  The host bridge registers also include ECAM
space, since it is consumed by the host bridge.

ACPI defines a Consumer/Producer bit to distinguish the bridge registers
("Consumer") from the bridge apertures ("Producer") [4, 5], but early
BIOSes didn't use that bit correctly.  The result is that the current ACPI
spec defines Consumer/Producer only for the Extended Address Space
descriptors; the bit should be ignored in the older QWord/DWord/Word
Address Space descriptors.  Consequently, OSes have to assume all
QWord/DWord/Word descriptors are windows.

Prior to the addition of Extended Address Space descriptors, the failure of
Consumer/Producer meant there was no way to describe bridge registers in
the PNP0A03/PNP0A08 device itself.  The workaround was to describe the
bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
With the exception of ECAM, the bridge register space is device-specific
anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
know about it.

New architectures should be able to use "Consumer" Extended Address Space
descriptors in the PNP0A03 device for bridge registers, including ECAM,
although a strict interpretation of [6] might prohibit this.  Old x86 and
ia64 kernels assume all address space descriptors, including "Consumer"
Extended Address Space ones, are windows, so it would not be safe to
describe bridge registers this way on those architectures.

PNP0C02 "motherboard" devices are basically a catch-all.  There's no
programming model for them other than "don't use these resources for
anything else."  So a PNP0C02 _CRS should claim any address space that is
(1) not claimed by _CRS under any other device object in the ACPI namespace
and (2) should not be assigned by the OS to something else.

The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
unless there's a standard firmware interface for config access, e.g., the
ia64 SAL interface [7].  A host bridge consumes ECAM memory address space
and converts memory accesses into PCI configuration accesses.  The spec
defines the ECAM address space layout and functionality; only the base of
the address space is device-specific.  An ACPI OS learns the base address
from either the static MCFG table or a _CBA method in the PNP0A03 device.

The MCFG table must describe the ECAM space of non-hot pluggable host
bridges [8].  Since MCFG is a static table and can't be updated by hotplug,
a _CBA method in the PNP0A03 device describes the ECAM space of a
hot-pluggable host bridge [9].  Note that for both MCFG and _CBA, the base
address always corresponds to bus 0, even if the bus range below the bridge
(which is reported via _CRS) doesn't start at 0.

[1] ACPI 6.2, sec 6.1:
    For any device that is on a non-enumerable type of bus (for example, an
    ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI
    system firmware must supply an _HID object ... for each device to
    enable OSPM to do that.

[2] ACPI 6.2, sec 3.7:
    The OS enumerates motherboard devices simply by reading through the
    ACPI Namespace looking for devices with hardware IDs.

    Each device enumerated by ACPI includes ACPI-defined objects in the
    ACPI Namespace that report the hardware resources the device could
    occupy [_PRS], an object that reports the resources that are currently
    used by the device [_CRS], and objects for configuring those resources
    [_SRS].  The information is used by the Plug and Play OS (OSPM) to
    configure the devices.

[3] ACPI 6.2, sec 6.2:
    OSPM uses device configuration objects to configure hardware resources
    for devices enumerated via ACPI.  Device configuration objects provide
    information about current and possible resource requirements, the
    relationship between shared resources, and methods for configuring
    hardware resources.

    When OSPM enumerates a device, it calls _PRS to determine the resource
    requirements of the device.  It may also call _CRS to find the current
    resource settings for the device.  Using this information, the Plug and
    Play system determines what resources the device should consume and
    sets those resources by calling the device’s _SRS control method.

    In ACPI, devices can consume resources (for example, legacy keyboards),
    provide resources (for example, a proprietary PCI bridge), or do both.
    Unless otherwise specified, resources for a device are assumed to be
    taken from the nearest matching resource above the device in the device
    hierarchy.

[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
    QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
      General Flags: Bit [0] Ignored

    Extended Address Space Descriptor (.4)
      General Flags: Bit [0] Consumer/Producer:

        * 1 – This device consumes this resource
        * 0 – This device produces and consumes this resource

[5] ACPI 6.2, sec 19.6.43:
    ResourceUsage specifies whether the Memory range is consumed by
    this device (ResourceConsumer) or passed on to child devices
    (ResourceProducer).  If nothing is specified, then
    ResourceConsumer is assumed.

[6] PCI Firmware 3.2, sec 4.1.2:
    If the operating system does not natively comprehend reserving the
    MMCFG region, the MMCFG region must be reserved by firmware.  The
    address range reported in the MCFG table or by _CBA method (see Section
    4.1.3) must be reserved by declaring a motherboard resource.  For most
    systems, the motherboard resource would appear at the root of the ACPI
    namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and
    the resources in this case should not be claimed in the root PCI bus’s
    _CRS.  The resources can optionally be returned in Int15 E820 or
    EFIGetMemoryMap as reserved memory but must always be reported through
    ACPI as a motherboard resource.

[7] PCI Express 4.0, sec 7.2.2:
    For systems that are PC-compatible, or that do not implement a
    processor-architecture-specific firmware interface standard that allows
    access to the Configuration Space, the ECAM is required as defined in
    this section.

[8] PCI Firmware 3.2, sec 4.1.2:
    The MCFG table is an ACPI table that is used to communicate the base
    addresses corresponding to the non-hot removable PCI Segment Groups
    range within a PCI Segment Group available to the operating system at
    boot. This is required for the PC-compatible systems.

    The MCFG table is only used to communicate the base addresses
    corresponding to the PCI Segment Groups available to the system at
    boot.

[9] PCI Firmware 3.2, sec 4.1.3:
    The _CBA (Memory mapped Configuration Base Address) control method is
    an optional ACPI object that returns the 64-bit memory mapped
    configuration base address for the hot plug capable host bridge. The
    base address returned by _CBA is processor-relative address. The _CBA
    control method evaluates to an Integer.

    This control method appears under a host bridge object. When the _CBA
    method appears under an active host bridge object, the operating system
    evaluates this structure to identify the memory mapped configuration
    base address corresponding to the PCI Segment Group for the bus number
    range specified in _CRS method. An ACPI name space object that contains
    the _CBA method must also contain a corresponding _SEG method.


code:
.. SPDX-License-Identifier: GPL-2.0

===============
Boot Interrupts
===============

:Author: - Sean V Kelley <sean.v.kelley@linux.intel.com>

Overview
========

On PCI Express, interrupts are represented with either MSI or inbound
interrupt messages (Assert_INTx/Deassert_INTx). The integrated IO-APIC in a
given Core IO converts the legacy interrupt messages from PCI Express to
MSI interrupts.  If the IO-APIC is disabled (via the mask bits in the
IO-APIC table entries), the messages are routed to the legacy PCH. This
in-band interrupt mechanism was traditionally necessary for systems that
did not support the IO-APIC and for boot. Intel in the past has used the
term "boot interrupts" to describe this mechanism. Further, the PCI Express
protocol describes this in-band legacy wire-interrupt INTx mechanism for
I/O devices to signal PCI-style level interrupts. The subsequent paragraphs
describe problems with the Core IO handling of INTx message routing to the
PCH and mitigation within BIOS and the OS.

Issue
=====

When in-band legacy INTx messages are forwarded to the PCH, they in turn
trigger a new interrupt for which the OS likely lacks a handler. When an
interrupt goes unhandled over time, they are tracked by the Linux kernel as
Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it
reaches a specific count with the error "nobody cared". This disabled IRQ
now prevents valid usage by an existing interrupt which may happen to share
the IRQ line::

  irq 19: nobody cared (try booting with the "irqpoll" option)
  CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1
  Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020
  Call Trace:

  <IRQ>
   ? dump_stack+0x46/0x5e
   ? __report_bad_irq+0x2e/0xb0
   ? note_interrupt+0x242/0x290
   ? nNIKAL100_memoryRead16+0x8/0x10 [nikal]
   ? handle_irq_event_percpu+0x55/0x70
   ? handle_irq_event+0x4f/0x80
   ? handle_fasteoi_irq+0x81/0x180
   ? handle_irq+0x1c/0x30
   ? do_IRQ+0x41/0xd0
   ? common_interrupt+0x84/0x84
  </IRQ>

  handlers:
  irq_default_primary_handler threaded usb_hcd_irq
  Disabling IRQ #19

Conditions
==========

The use of threaded interrupts is the most likely condition to trigger
this problem today. Threaded interrupts may not be reenabled after the IRQ
handler wakes. These "one shot" conditions mean that the threaded interrupt
needs to keep the interrupt line masked until the threaded handler has run.
Especially when dealing with high data rate interrupts, the thread needs to
run to completion; otherwise some handlers will end up in stack overflows
since the interrupt of the issuing device is still active.

Affected Chipsets
=================

The legacy interrupt forwarding mechanism exists today in a number of
devices including but not limited to chipsets from AMD/ATI, Broadcom, and
Intel. Changes made through the mitigations below have been applied to
drivers/pci/quirks.c

Starting with ICX there are no longer any IO-APICs in the Core IO's
devices.  IO-APIC is only in the PCH.  Devices connected to the Core IO's
PCIe Root Ports will use native MSI/MSI-X mechanisms.

Mitigations
===========

The mitigations take the form of PCI quirks. The preference has been to
first identify and make use of a means to disable the routing to the PCH.
In such a case a quirk to disable boot interrupt generation can be
added. [1]_

Intel® 6300ESB I/O Controller Hub
  Alternate Base Address Register:
   BIE: Boot Interrupt Enable

	  ==  ===========================
	  0   Boot interrupt is enabled.
	  1   Boot interrupt is disabled.
	  ==  ===========================

Intel® Sandy Bridge through Sky Lake based Xeon servers:
  Coherent Interface Protocol Interrupt Control
   dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2:
	  When this bit is set. Local INTx messages received from the
	  Intel® Quick Data DMA/PCI Express ports are not routed to legacy
	  PCH - they are either converted into MSI via the integrated IO-APIC
	  (if the IO-APIC mask bit is clear in the appropriate entries)
	  or cause no further action (when mask bit is set)

In the absence of a way to directly disable the routing, another approach
has been to make use of PCI Interrupt pin to INTx routing tables for
purposes of redirecting the interrupt handler to the rerouted interrupt
line by default.  Therefore, on chipsets where this INTx routing cannot be
disabled, the Linux kernel will reroute the valid interrupt to its legacy
interrupt. This redirection of the handler will prevent the occurrence of
the spurious interrupt detection which would ordinarily disable the IRQ
line due to excessive unhandled counts. [2]_

The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or
disable) the redirection of the interrupt handler to the PCH interrupt
line. The option can be overridden by either pci=ioapicreroute or
pci=noioapicreroute. [3]_

More Documentation
==================

There is an overview of the legacy interrupt handling in several datasheets
(6300ESB and 6700PXH below). While largely the same, it provides insight
into the evolution of its handling with chipsets.

Example of disabling of the boot interrupt
------------------------------------------

      - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
	5.7.3 Boot Interrupt
	https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf

      - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
	Datasheet - Volume 2: Registers (Document # 330784-003)
	6.6.41 cipintrc Coherent Interface Protocol Interrupt Control
	https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf

Example of handler rerouting
----------------------------

      - Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
	2.15.2 PCI Express Legacy INTx Support and Boot Interrupt
	https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf

If you have any legacy PCI interrupt questions that aren't answered, email me.

Cheers,
    Sean V Kelley
    sean.v.kelley@linux.intel.com

.. [1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
.. [2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
.. [3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/


code:
.. SPDX-License-Identifier: GPL-2.0

==========================
PCI NTB Endpoint Function
==========================

1) Create a subdirectory to pci_epf_ntb directory in configfs.

Standard EPF Configurable Fields:

================   ===========================================================
vendorid	   should be 0x104c
deviceid	   should be 0xb00d for TI's J721E SoC
revid		   don't care
progif_code	   don't care
subclass_code	   should be 0x00
baseclass_code	   should be 0x5
cache_line_size	   don't care
subsys_vendor_id   don't care
subsys_id	   don't care
interrupt_pin	   don't care
msi_interrupts	   don't care
msix_interrupts	   don't care
================   ===========================================================

2) Create a subdirectory to directory created in 1

NTB EPF specific configurable fields:

================   ===========================================================
db_count	   Number of doorbells; default = 4
mw1     	   size of memory window1
mw2     	   size of memory window2
mw3     	   size of memory window3
mw4     	   size of memory window4
num_mws     	   Number of memory windows; max = 4
spad_count     	   Number of scratchpad registers; default = 64
================   ===========================================================


code:
.. SPDX-License-Identifier: GPL-2.0

==========================
PCI Test Endpoint Function
==========================

name: Should be "pci_epf_test" to bind to the pci_epf_test driver.

Configurable Fields:

================   ===========================================================
vendorid	   should be 0x104c
deviceid	   should be 0xb500 for DRA74x and 0xb501 for DRA72x
revid		   don't care
progif_code	   don't care
subclass_code	   don't care
baseclass_code	   should be 0xff
cache_line_size	   don't care
subsys_vendor_id   don't care
subsys_id	   don't care
interrupt_pin	   Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
msi_interrupts	   Should be 1 to 32 depending on the number of MSI interrupts
		   to test
msix_interrupts	   Should be 1 to 2048 depending on the number of MSI-X
		   interrupts to test
================   ===========================================================


code:
.. SPDX-License-Identifier: GPL-2.0

======================
PCI Endpoint Framework
======================

.. toctree::
   :maxdepth: 2

   pci-endpoint
   pci-endpoint-cfs
   pci-test-function
   pci-test-howto
   pci-ntb-function
   pci-ntb-howto
   pci-vntb-function
   pci-vntb-howto

   function/binding/pci-test
   function/binding/pci-ntb


code:
.. SPDX-License-Identifier: GPL-2.0

=======================================
Configuring PCI Endpoint Using CONFIGFS
=======================================

:Author: Kishon Vijay Abraham I <kishon@ti.com>

The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
PCI endpoint function and to bind the endpoint function
with the endpoint controller. (For introducing other mechanisms to
configure the PCI Endpoint Function refer to [1]).

Mounting configfs
=================

The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
directory. configfs can be mounted using the following command::

	mount -t configfs none /sys/kernel/config

Directory Structure
===================

The pci_ep configfs has two directories at its root: controllers and
functions. Every EPC device present in the system will have an entry in
the *controllers* directory and every EPF driver present in the system
will have an entry in the *functions* directory.
::

	/sys/kernel/config/pci_ep/
		.. controllers/
		.. functions/

Creating EPF Device
===================

Every registered EPF driver will be listed in controllers directory. The
entries corresponding to EPF driver will be created by the EPF core.
::

	/sys/kernel/config/pci_ep/functions/
		.. <EPF Driver1>/
			... <EPF Device 11>/
			... <EPF Device 21>/
			... <EPF Device 31>/
		.. <EPF Driver2>/
			... <EPF Device 12>/
			... <EPF Device 22>/

In order to create a <EPF device> of the type probed by <EPF Driver>, the
user has to create a directory inside <EPF DriverN>.

Every <EPF device> directory consists of the following entries that can be
used to configure the standard configuration header of the endpoint function.
(These entries are created by the framework when any new <EPF Device> is
created)
::

		.. <EPF Driver1>/
			... <EPF Device 11>/
				... vendorid
				... deviceid
				... revid
				... progif_code
				... subclass_code
				... baseclass_code
				... cache_line_size
				... subsys_vendor_id
				... subsys_id
				... interrupt_pin
			        ... <Symlink EPF Device 31>/
                                ... primary/
			                ... <Symlink EPC Device1>/
                                ... secondary/
			                ... <Symlink EPC Device2>/

If an EPF device has to be associated with 2 EPCs (like in the case of
Non-transparent bridge), symlink of endpoint controller connected to primary
interface should be added in 'primary' directory and symlink of endpoint
controller connected to secondary interface should be added in 'secondary'
directory.

The <EPF Device> directory can have a list of symbolic links
(<Symlink EPF Device 31>) to other <EPF Device>. These symbolic links should
be created by the user to represent the virtual functions that are bound to
the physical function. In the above directory structure <EPF Device 11> is a
physical function and <EPF Device 31> is a virtual function. An EPF device once
it's linked to another EPF device, cannot be linked to a EPC device.

EPC Device
==========

Every registered EPC device will be listed in controllers directory. The
entries corresponding to EPC device will be created by the EPC core.
::

	/sys/kernel/config/pci_ep/controllers/
		.. <EPC Device1>/
			... <Symlink EPF Device11>/
			... <Symlink EPF Device12>/
			... start
		.. <EPC Device2>/
			... <Symlink EPF Device21>/
			... <Symlink EPF Device22>/
			... start

The <EPC Device> directory will have a list of symbolic links to
<EPF Device>. These symbolic links should be created by the user to
represent the functions present in the endpoint device. Only <EPF Device>
that represents a physical function can be linked to a EPC device.

The <EPC Device> directory will also have a *start* field. Once
"1" is written to this field, the endpoint device will be ready to
establish the link with the host. This is usually done after
all the EPF devices are created and linked with the EPC device.
::

			 | controllers/
				| <Directory: EPC name>/
					| <Symbolic Link: Function>
					| start
			 | functions/
				| <Directory: EPF driver>/
					| <Directory: EPF device>/
						| vendorid
						| deviceid
						| revid
						| progif_code
						| subclass_code
						| baseclass_code
						| cache_line_size
						| subsys_vendor_id
						| subsys_id
						| interrupt_pin
						| function

[1] Documentation/PCI/endpoint/pci-endpoint.rst