Commit bb2407a7 authored by Linus Torvalds's avatar Linus Torvalds

Merge tag 'docs-4.17' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "There's been a fair amount of activity in Documentation/ this time
  around:

   - Lots of work aligning Documentation/ABI with reality, done by
     Aishwarya Pant.

   - The trace documentation has been converted to RST by Changbin Du

   - I thrashed up kernel-doc to deal with a parsing issue and to try to
     make the code more readable. It's still a 20+-year-old Perl hack,
     though.

   - Lots of other updates, typo fixes, and more"

* tag 'docs-4.17' of git://git.lwn.net/linux: (82 commits)
  Documentation/process: update FUSE project website
  docs: kernel-doc: fix parsing of arrays
  dmaengine: Fix spelling for parenthesis in dmatest documentation
  dmaengine: Make dmatest.rst indeed reST compatible
  dmaengine: Add note to dmatest documentation about supported channels
  Documentation: magic-numbers: Fix typo
  Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands
  Input: alps - Update documentation for trackstick v3 format
  Documentation: Mention why %p prints ptrval
  COPYING: use the new text with points to the license files
  COPYING: create a new file with points to the Kernel license files
  Input: trackpoint: document sysfs interface
  xfs: Change URL for the project in xfs.txt
  char/bsr: add sysfs interface documentation
  acpi: nfit: document sysfs interface
  block: rbd: update sysfs interface
  Documentation/sparse: fix typo
  Documentation/CodingStyle: Add an example for braces
  docs/vm: update 00-INDEX
  kernel-doc: Remove __sched markings
  ...
parents e40dc662 86afad7d
This diff is collapsed.
This diff is collapsed.
What: /sys/block/etherd*/mac
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: Ed L. Cashin <ed.cashin@acm.org>
Description:
(RO) The ethernet address of the remote Ata over Ethernet (AoE)
device.
What: /sys/block/etherd*/netif
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: Ed L. Cashin <ed.cashin@acm.org>
Description:
(RO) The names of the network interfaces on the localhost (comma
separated) through which we are communicating with the remote
AoE device.
What: /sys/block/etherd*/state
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: Ed L. Cashin <ed.cashin@acm.org>
Description:
(RO) Device status. The state attribute is "up" when the device
is ready for I/O and "down" if detected but unusable. The
"down,closewait" state shows that the device is still open and
cannot come up again until it has been closed. The "up,kickme"
state means that the driver wants to send more commands to the
target but found out there were already the max number of
commands waiting for a response. It will retry again after being
kicked by the periodic timer handler routine.
What: /sys/block/etherd*/firmware-version
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: Ed L. Cashin <ed.cashin@acm.org>
Description:
(RO) Version of the firmware in the target.
What: /sys/block/etherd*/payload
Date: Dec, 2012
KernelVersion: v3.10
Contact: Ed L. Cashin <ed.cashin@acm.org>
Description:
(RO) The amount of user data transferred (in bytes) inside each AoE
command on the network, network headers excluded.
What: /sys/block/loopX/loop/autoclear
Date: Aug, 2010
KernelVersion: v2.6.37
Contact: linux-block@vger.kernel.org
Description:
(RO) Shows if the device is in autoclear mode or not ( "1" or
"0"). Autoclear (if set) indicates that the loopback device will
self-distruct after last close.
What: /sys/block/loopX/loop/backing_file
Date: Aug, 2010
KernelVersion: v2.6.37
Contact: linux-block@vger.kernel.org
Description:
(RO) The path of the backing file that the loop device maps its
data blocks to.
What: /sys/block/loopX/loop/offset
Date: Aug, 2010
KernelVersion: v2.6.37
Contact: linux-block@vger.kernel.org
Description:
(RO) Start offset (in bytes).
What: /sys/block/loopX/loop/sizelimit
Date: Aug, 2010
KernelVersion: v2.6.37
Contact: linux-block@vger.kernel.org
Description:
(RO) The size (in bytes) that the block device maps, starting
from the offset.
What: /sys/block/loopX/loop/partscan
Date: Aug, 2011
KernelVersion: v3.10
Contact: linux-block@vger.kernel.org
Description:
(RO) Shows if automatic partition scanning is enabled for the
device or not ("1" or "0"). This can be requested individually
per loop device during its setup by setting LO_FLAGS_PARTSCAN in
in the ioctl request. By default, no partition tables are
scanned.
What: /sys/block/loopX/loop/dio
Date: Aug, 2015
KernelVersion: v4.10
Contact: linux-block@vger.kernel.org
Description:
(RO) Shows if direct IO is being used to access backing file or
not ("1 or "0").
For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware
Interface Table (NFIT)' section in the ACPI specification
(http://www.uefi.org/specifications) for more details.
What: /sys/bus/nd/devices/nmemX/nfit/serial
Date: Jun, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Serial number of the NVDIMM (non-volatile dual in-line
memory module), assigned by the module vendor.
What: /sys/bus/nd/devices/nmemX/nfit/handle
Date: Apr, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) The address (given by the _ADR object) of the device on its
parent bus of the NVDIMM device containing the NVDIMM region.
What: /sys/bus/nd/devices/nmemX/nfit/device
Date: Apr, 2015
KernelVersion: v4.1
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Device id for the NVDIMM, assigned by the module vendor.
What: /sys/bus/nd/devices/nmemX/nfit/rev_id
Date: Jun, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Revision of the NVDIMM, assigned by the module vendor.
What: /sys/bus/nd/devices/nmemX/nfit/phys_id
Date: Apr, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Handle (i.e., instance number) for the SMBIOS (system
management BIOS) Memory Device structure describing the NVDIMM
containing the NVDIMM region.
What: /sys/bus/nd/devices/nmemX/nfit/flags
Date: Jun, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) The flags in the NFIT memory device sub-structure indicate
the state of the data on the nvdimm relative to its energy
source or last "flush to persistence".
The attribute is a translation of the 'NVDIMM State Flags' field
in section 5.2.25.3 'NVDIMM Region Mapping' Structure of the
ACPI specification 6.2.
The health states are "save_fail", "restore_fail", "flush_fail",
"not_armed", "smart_event", "map_fail" and "smart_notify".
What: /sys/bus/nd/devices/nmemX/nfit/format
What: /sys/bus/nd/devices/nmemX/nfit/format1
What: /sys/bus/nd/devices/nmemX/nfit/formats
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) The interface codes indicate support for persistent memory
mapped directly into system physical address space and / or a
block aperture access mechanism to the NVDIMM media.
The 'formats' attribute displays the number of supported
interfaces.
This layout is compatible with existing libndctl binaries that
only expect one code per-dimm as they will ignore
nmemX/nfit/formats and nmemX/nfit/formatN.
What: /sys/bus/nd/devices/nmemX/nfit/vendor
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Vendor id of the NVDIMM.
What: /sys/bus/nd/devices/nmemX/nfit/dsm_mask
Date: May, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) The bitmask indicates the supported device specific control
functions relative to the NVDIMM command family supported by the
device
What: /sys/bus/nd/devices/nmemX/nfit/family
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Displays the NVDIMM family command sets. Values
0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL,
NVDIMM_FAMILY_HPE1, NVDIMM_FAMILY_HPE2 and NVDIMM_FAMILY_MSFT
respectively.
See the specifications for these command families here:
http://pmem.io/documents/NVDIMM_DSM_Interface-V1.6.pdf
https://github.com/HewlettPackard/hpe-nvm/blob/master/Documentation/
https://msdn.microsoft.com/library/windows/hardware/mt604741"
What: /sys/bus/nd/devices/nmemX/nfit/id
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) ACPI specification 6.2 section 5.2.25.9, defines an
identifier for an NVDIMM, which refelects the id attribute.
What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Sub-system vendor id of the NVDIMM non-volatile memory
subsystem controller.
What: /sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem
controller, assigned by the non-volatile memory subsystem
controller vendor.
What: /sys/bus/nd/devices/nmemX/nfit/subsystem_device
Date: Apr, 2016
KernelVersion: v4.7
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Sub-system device id for the NVDIMM non-volatile memory
subsystem controller, assigned by the non-volatile memory
subsystem controller vendor.
What: /sys/bus/nd/devices/ndbusX/nfit/revision
Date: Jun, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) ACPI NFIT table revision number.
What: /sys/bus/nd/devices/ndbusX/nfit/scrub
Date: Sep, 2016
KernelVersion: v4.9
Contact: linux-nvdimm@lists.01.org
Description:
(RW) This shows the number of full Address Range Scrubs (ARS)
that have been completed since driver load time. Userspace can
wait on this using select/poll etc. A '+' at the end indicates
an ARS is in progress
Writing a value of 1 triggers an ARS scan.
What: /sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub
Date: Sep, 2016
KernelVersion: v4.9
Contact: linux-nvdimm@lists.01.org
Description:
(RW) Provides a way to toggle the behavior between just adding
the address (cache line) where the MCE happened to the poison
list and doing a full scrub. The former (selective insertion of
the address) is done unconditionally.
This attribute can have the following values written to it:
'0': Switch to the default mode where an exception will only
insert the address of the memory error into the poison and
badblocks lists.
'1': Enable a full scrub to happen if an exception for a memory
error is received.
What: /sys/bus/nd/devices/ndbusX/nfit/dsm_mask
Date: Jun, 2017
KernelVersion: v4.13
Contact: linux-nvdimm@lists.01.org
Description:
(RO) The bitmask indicates the supported bus specific control
functions. See the section named 'NVDIMM Root Device _DSMs' in
the ACPI specification.
What: /sys/bus/nd/devices/regionX/nfit/range_index
Date: Jun, 2015
KernelVersion: v4.2
Contact: linux-nvdimm@lists.01.org
Description:
(RO) A unique number provided by the BIOS to identify an address
range. Used by NVDIMM Region Mapping Structure to uniquely refer
to this structure. Value of 0 is reserved and not used as an
index.
What: /sys/bus/nd/devices/regionX/nfit/ecc_unit_size
Date: Aug, 2017
KernelVersion: v4.14
Contact: linux-nvdimm@lists.01.org
Description:
(RO) Size of a write request to a DIMM that will not incur a
read-modify-write cycle at the memory controller.
When the nfit driver initializes it runs an ARS (Address Range
Scrub) operation across every pmem range. Part of that process
involves determining the ARS capabilities of a given address
range. One of the capabilities that is reported is the 'Clear
Uncorrectable Error Range Length Unit Size' (see: ACPI 6.2
section 9.20.7.4 Function Index 1 - Query ARS Capabilities).
This property indicates the boundary at which the NVDIMM may
need to perform read-modify-write cycles to maintain ECC (Error
Correcting Code) blocks.
What: /sys/bus/rapidio/devices/nn:d:iiii
Description:
For each RapidIO device, the RapidIO subsystem creates files in
an individual subdirectory with the following name format of
device_name "nn:d:iiii", where:
nn - two-digit hexadecimal ID of RapidIO network where the
device resides
d - device type: 'e' - for endpoint or 's' - for switch
iiii - four-digit device destID for endpoints, or switchID for
switches
For example, below is a list of device directories that
represents a typical RapidIO network with one switch, one host,
and two agent endpoints, as it is seen by the enumerating host
(with destID = 1):
/sys/bus/rapidio/devices/00:e:0000
/sys/bus/rapidio/devices/00:e:0002
/sys/bus/rapidio/devices/00:s:0001
NOTE: An enumerating or discovering endpoint does not create a
sysfs entry for itself, this is why an endpoint with destID=1 is
not shown in the list.
Attributes Common for All RapidIO Devices
-----------------------------------------
What: /sys/bus/rapidio/devices/nn:d:iiii/did
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns the device identifier
What: /sys/bus/rapidio/devices/nn:d:iiii/vid
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns the device vendor identifier
What: /sys/bus/rapidio/devices/nn:d:iiii/device_rev
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns the device revision level
What: /sys/bus/rapidio/devices/nn:d:iiii/asm_did
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns identifier for the assembly containing the device
What: /sys/bus/rapidio/devices/nn:d:iiii/asm_rev
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns revision level of the assembly containing the
device
What: /sys/bus/rapidio/devices/nn:d:iiii/asm_vid
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns vendor identifier of the assembly containing the
device
What: /sys/bus/rapidio/devices/nn:d:iiii/destid
Date: Mar, 2011
KernelVersion: v2.6.3
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns device destination ID assigned by the enumeration
routine
What: /sys/bus/rapidio/devices/nn:d:iiii/lprev
Date: Mar, 2011
KernelVersion: v2.6.39
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns name of previous device (switch) on the path to the
device that that owns this attribute
What: /sys/bus/rapidio/devices/nn:d:iiii/modalias
Date: Jul, 2013
KernelVersion: v3.11
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns the device modalias
What: /sys/bus/rapidio/devices/nn:d:iiii/config
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RW) Binary attribute to read from and write to the device
configuration registers using the RapidIO maintenance
transactions. This attribute is similar in behaviour to the
"config" attribute of PCI devices and provides an access to the
RapidIO device registers using standard file read and write
operations.
RapidIO Switch Device Attributes
--------------------------------
RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports
common and device-specific sysfs attributes for switches. Because switches are
integrated into the RapidIO subsystem, it offers a method to create
device-specific sysfs attributes by specifying a callback function that may be
set by the switch initialization routine during enumeration or discovery
process.
What: /sys/bus/rapidio/devices/nn:s:iiii/routes
Date: Nov, 2005
KernelVersion: v2.6.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) reports switch routing information in "destID port" format.
This attribute reports only valid routing table entries, one
line for each entry.
What: /sys/bus/rapidio/devices/nn:s:iiii/destid
Date: Mar, 2011
KernelVersion: v2.6.3
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) device destination ID of the associated device that defines
a route to the switch
What: /sys/bus/rapidio/devices/nn:s:iiii/hopcount
Date: Mar, 2011
KernelVersion: v2.6.39
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) number of hops on the path to the switch
What: /sys/bus/rapidio/devices/nn:s:iiii/lnext
Date: Mar, 2011
KernelVersion: v2.6.39
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) returns names of devices linked to the switch except one of
a device linked to the ingress port (reported as "lprev"). This
is an array names with number of lines equal to number of ports
in switch. If a switch port has no attached device, returns
"null" instead of a device name.
Device-specific Switch Attributes
---------------------------------
IDT_GEN2-
What: /sys/bus/rapidio/devices/nn:s:iiii/errlog
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) reads contents of device error log until it is empty.
RapidIO Bus Attributes
----------------------
What: /sys/bus/rapidio/scan
Date: May, 2013
KernelVersion: v3.11
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(WO) Allows to trigger enumeration discovery process from user
space. To initiate an enumeration or discovery process on
specific mport device, a user needs to write mport_ID (not
RapidIO destination ID) into this file. The mport_ID is a
sequential number (0 ... RIO_MAX_MPORTS) assigned to the mport
device. For example, for a machine with a single RapidIO
controller, mport_ID for that controller always will be 0. To
initiate RapidIO enumeration/discovery on all available mports a
user must write '-1' (or RIO_MPORT_ANY) into this attribute
file.
What: /sys/bus/rbd/
Date: November 2010
Contact: Yehuda Sadeh <yehuda@newdream.net>,
Sage Weil <sage@newdream.net>
What: /sys/bus/rbd/add
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Sage Weil <sage@newdream.net>
Description:
(WO) Add rbd block device.
Being used for adding and removing rbd block devices.
Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
$ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
$ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
The snapshot name can be "-" or omitted to map the image
read/write. A <dev-id> will be assigned for any registered block
device. If snapshot is used, it will be mapped read-only.
The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>
will be assigned for any registered block device. If snapshot is used, it will
be mapped read-only.
Usage: <dev-id> [force]
What: /sys/bus/rbd/remove
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Sage Weil <sage@newdream.net>
Description:
(WO) Remove rbd block device.
Usage: <dev-id> [force]
$ echo 2 > /sys/bus/rbd/remove
$ echo 2 > /sys/bus/rbd/remove
Optional "force" argument which when passed will wait for
running requests and then unmap the image. Requests sent to the
driver after initiating the removal will be failed. (August
2016, since 4.9.)
Optional "force" argument which when passed will wait for running requests and
then unmap the image. Requests sent to the driver after initiating the removal
will be failed. (August 2016, since 4.9.)
What: /sys/bus/rbd/add_single_major
Date: December 2013
KernelVersion: 3.14
Contact: Sage Weil <sage@inktank.com>
Description: Available only if rbd module is inserted with single_major
Date: Dec, 2013
KernelVersion: v3.14
Contact: Sage Weil <sage@newdream.net>
Description:
(WO) Available only if rbd module is inserted with single_major
parameter set to true.
Usage is the same as for /sys/bus/rbd/add. If present,
Usage is the same as for /sys/bus/rbd/add. If present, this
should be used instead of the latter: any attempts to use
/sys/bus/rbd/add if /sys/bus/rbd/add_single_major is
available will fail for backwards compatibility reasons.
/sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
will fail for backwards compatibility reasons.
What: /sys/bus/rbd/remove_single_major
Date: December 2013
KernelVersion: 3.14
Contact: Sage Weil <sage@inktank.com>
Description: Available only if rbd module is inserted with single_major
Date: Dec, 2013
KernelVersion: v3.14
Contact: Sage Weil <sage@newdream.net>
Description:
(WO) Available only if rbd module is inserted with single_major
parameter set to true.
Usage is the same as for /sys/bus/rbd/remove. If present,
Usage is the same as for /sys/bus/rbd/remove. If present, this
should be used instead of the latter: any attempts to use
/sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
available will fail for backwards compatibility reasons.
Entries under /sys/bus/rbd/devices/<dev-id>/
--------------------------------------------
client_addr
The ceph unique client entity_addr_t (address + nonce).
The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
'[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.)
client_id
The ceph unique client id that was assigned for this specific session.
cluster_fsid
The ceph cluster UUID. (August 2016, since 4.9.)
config_info
The string written into /sys/bus/rbd/add{,_single_major}. (August
2016, since 4.9.)
features
A hexadecimal encoding of the feature bits for this image.
major
The block device major number.
What: /sys/bus/rbd/supported_features
Date: Mar, 2017
KernelVersion: v4.11
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) Displays the features supported by the rbd module so that
userspace can generate meaningful error messages and spell out
unsupported features that need to be disabled.
What: /sys/bus/rbd/devices/<dev-id>/size
What: /sys/bus/rbd/devices/<dev-id>/major
What: /sys/bus/rbd/devices/<dev-id>/client_id
What: /sys/bus/rbd/devices/<dev-id>/pool
What: /sys/bus/rbd/devices/<dev-id>/name
What: /sys/bus/rbd/devices/<dev-id>/refresh
What: /sys/bus/rbd/devices/<dev-id>/current_snap
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Sage Weil <sage@newdream.net>
Description:
size: (RO) The size (in bytes) of the mapped block
device.
minor
major: (RO) The block device major number.
The block device minor number. (December 2013, since 3.14.)
client_id: (RO) The ceph unique client id that was assigned
for this specific session.
name
pool: (RO) The name of the storage pool where this rbd
image resides. An rbd image name is unique
within its pool.
The name of the rbd image.
name: (RO) The name of the rbd image.
image_id
refresh: (WO) Writing to this file will reread the image
header data and set all relevant data structures
accordingly.
The unique id for the rbd image. (For rbd image format 1
this is empty.)
current_snap: (RO) The current snapshot for which the device
is mapped.
pool
The name of the storage pool where this rbd image resides.
An rbd image name is unique within its pool.
What: /sys/bus/rbd/devices/<dev-id>/pool_id
Date: Jul, 2012
KernelVersion: v3.6
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) The unique identifier for the rbd image's pool. This is a
permanent attribute of the pool. A pool's id will never change.
pool_id
The unique identifier for the rbd image's pool. This is
a permanent attribute of the pool. A pool's id will never
change.
What: /sys/bus/rbd/devices/<dev-id>/image_id
What: /sys/bus/rbd/devices/<dev-id>/features
Date: Oct, 2012
KernelVersion: v3.7
Contact: Sage Weil <sage@newdream.net>
Description:
image_id: (RO) The unique id for the rbd image. (For rbd
image format 1 this is empty.)
size
features: (RO) A hexadecimal encoding of the feature bits
for this image.
The size (in bytes) of the mapped block device.
refresh
What: /sys/bus/rbd/devices/<dev-id>/parent
Date: Nov, 2012
KernelVersion: v3.8
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) Information identifying the chain of parent images in a
layered rbd image. Entries are separated by empty lines.
Writing to this file will reread the image header data and set
all relevant datastructures accordingly.
current_snap
What: /sys/bus/rbd/devices/<dev-id>/minor
Date: Dec, 2013
KernelVersion: v3.14
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) The block device minor number.
The current snapshot for which the device is mapped.
snap_id
What: /sys/bus/rbd/devices/<dev-id>/snap_id
What: /sys/bus/rbd/devices/<dev-id>/config_info
What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid
What: /sys/bus/rbd/devices/<dev-id>/client_addr
Date: Aug, 2016
KernelVersion: v4.9
Contact: Sage Weil <sage@newdream.net>
Description:
snap_id: (RO) The current snapshot's id.
The current snapshot's id. (August 2016, since 4.9.)
config_info: (RO) The string written into
/sys/bus/rbd/add{,_single_major}.
parent
cluster_fsid: (RO) The ceph cluster UUID.
Information identifying the chain of parent images in a layered rbd
image. Entries are separated by empty lines.
client_addr: (RO) The ceph unique client
entity_addr_t (address + nonce). The format is
<address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
'[1:2:3:4:5:6:7:8]:1234/5678'.
sysfs interface for analog devices adp5520(01) backlight driver
---------------------------------------------------------------
The backlight brightness control operates at three different levels for the
adp5520 and adp5501 devices: daylight (level 1), office (level 2) and dark
(level 3). By default the brightness operates at the daylight brightness level.
What: /sys/class/backlight/<backlight>/daylight_max
What: /sys/class/backlight/<backlight>/office_max
What: /sys/class/backlight/<backlight>/dark_max
Date: Sep, 2009
KernelVersion: v2.6.32
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RW) Maximum current setting for the backlight when brightness
is at one of the three levels (daylight, office or dark). This
is an input code between 0 and 127, which is transformed to a
value between 0 mA and 30 mA using linear or non-linear
algorithms.
What: /sys/class/backlight/<backlight>/daylight_dim
What: /sys/class/backlight/<backlight>/office_dim
What: /sys/class/backlight/<backlight>/dark_dim
Date: Sep, 2009
KernelVersion: v2.6.32
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RW) Dim current setting for the backlight when brightness is at
one of the three levels (daylight, office or dark). This is an
input code between 0 and 127, which is transformed to a value
between 0 mA and 30 mA using linear or non-linear algorithms.
sysfs interface for analog devices adp8860 backlight driver
-----------------------------------------------------------
The backlight brightness control operates at three different levels for the
adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and
dark (level 3). By default the brightness operates at the daylight brightness
level.
What: /sys/class/backlight/<backlight>/ambient_light_level
Date: Apr, 2010
KernelVersion: v2.6.35
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RO) 13-bit conversion value for the first light sensor—high
byte (Bit 12 to Bit 8). The value is updated every 80 ms (when
the light sensor is enabled).
What: /sys/class/backlight/<backlight>/ambient_light_zone
Date: Apr, 2010
KernelVersion: v2.6.35
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RW) Read or write the specific level at which the backlight
operates. Value "0" enables automatic ambient light sensing, and
values "1", "2" or "3" set the control to daylight, office or
dark respectively.
What: /sys/class/backlight/<backlight>/l1_daylight_max
What: /sys/class/backlight/<backlight>/l2_office_max
What: /sys/class/backlight/<backlight>/l3_dark_max
Date: Apr, 2010
KernelVersion: v2.6.35
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RW) Maximum current setting for the backlight when brightness
is at one of the three levels (daylight, office or dark). This
is an input code between 0 and 127, which is transformed to a
value between 0 mA and 30 mA using linear or non-linear
algorithms.
What: /sys/class/backlight/<backlight>/l1_daylight_dim
What: /sys/class/backlight/<backlight>/l2_office_dim
What: /sys/class/backlight/<backlight>/l3_dark_dim
Date: Apr, 2010
KernelVersion: v2.6.35
Contact: Michael Hennerich <michael.hennerich@analog.com>
Description:
(RW) Dim current setting for the backlight when brightness is at
one of the three levels (daylight, office or dark). This is an
input code between 0 and 127, which is transformed to a value
between 0 mA and 30 mA using linear or non-linear algorithms.
sysfs interface for Texas Instruments lm3639 backlight + flash led driver chip
------------------------------------------------------------------------------
What: /sys/class/backlight/<backlight>/bled_mode
Date: Oct, 2012
KernelVersion: v3.10
Contact: dri-devel@lists.freedesktop.org
Description:
(WO) Write to the backlight mapping mode. The backlight current
can be mapped for either exponential (value "0") or linear
mapping modes (default).
What: /sys/class/bsr/bsr*/bsr_size
Date: Jul, 2008
KernelVersion: 2.6.27
Contact: Arnd Bergmann <arnd@arndb.de>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Description:
(RO) Size of the barrier-synchronization register (BSR)
register in bytes.
What: /sys/class/bsr/bsr*/bsr_length
Date: Jul, 2008
KernelVersion: 2.6.27
Contact: Arnd Bergmann <arnd@arndb.de>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Description:
(RO) The length of memory region that can be mapped in bytes.
What: /sys/class/bsr/bsr*/bsr_stride
Date: Jul, 2008
KernelVersion: 2.6.27
Contact: Arnd Bergmann <arnd@arndb.de>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Description:
(RO) The stride or the interval at which the allocated BSR bytes
repeat within the mapping.
What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index>
Date: November 29, 2015
KernelVersion: 4.4.0
Contact: linux-rdma@vger.kernel.org
Description: The net-device's name associated with the GID resides
at index <gid-index>.
What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index>
Date: November 29, 2015
KernelVersion: 4.4.0
Contact: linux-rdma@vger.kernel.org
Description: The RoCE type of the associated GID resides at index <gid-index>.
This could either be "IB/RoCE v1" for IB and RoCE v1 based GODs
or "RoCE v2" for RoCE v2 based GIDs.
sysfs interface for the S6E63M0 AMOLED LCD panel driver
-------------------------------------------------------
What: /sys/class/lcd/<lcd>/gamma_mode
Date: May, 2010
KernelVersion: v2.6.35
Contact: dri-devel@lists.freedesktop.org
Description:
(RW) Read or write the gamma mode. Following three modes are
supported:
0 - gamma value 2.2,
1 - gamma value 1.9 and
2 - gamma value 1.7.
What: /sys/class/lcd/<lcd>/gamma_table
Date: May, 2010
KernelVersion: v2.6.35
Contact: dri-devel@lists.freedesktop.org
Description:
(RO) Displays the size of the gamma table i.e. the number of
gamma modes available.
This is a backlight lcd driver. These interfaces are an extension to the API
documented in Documentation/ABI/testing/sysfs-class-lcd and in
Documentation/ABI/stable/sysfs-class-backlight (under
/sys/class/backlight/<backlight>/).
What: /sys/class/pktcdvd/
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
sysfs interface
---------------
The pktcdvd module (packet writing driver) creates the following files in the
sysfs: (<devid> is in the format major:minor)
What: /sys/class/pktcdvd/add
What: /sys/class/pktcdvd/remove
What: /sys/class/pktcdvd/device_map
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
add: (WO) Write a block device id (major:minor) to
create a new pktcdvd device and map it to the
block device.
remove: (WO) Write the pktcdvd device id (major:minor)
to remove the pktcdvd device.
device_map: (RO) Shows the device mapping in format:
pktcdvd[0-7] <pktdevid> <blkdevid>
What: /sys/class/pktcdvd/pktcdvd[0-7]/dev
What: /sys/class/pktcdvd/pktcdvd[0-7]/uevent
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
dev: (RO) Device id
uevent: (WO) To send a uevent
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_started
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_finished
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_written
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read_gather
What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/reset
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
packets_started: (RO) Number of started packets.
packets_finished: (RO) Number of finished packets.
kb_written: (RO) kBytes written.
kb_read: (RO) kBytes read.
kb_read_gather: (RO) kBytes read to fill write packets.
reset: (WO) Write any value to it to reset
pktcdvd device statistic values, like
bytes read/written.
What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/size
What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_off
What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_on
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
size: (RO) Contains the size of the bio write queue.
congestion_off: (RW) If bio write queue size is below this mark,
accept new bio requests from the block layer.
The pktcdvd module (packet writing driver) creates
these files in the sysfs:
(<devid> is in format major:minor )
/sys/class/pktcdvd/
add (0200) Write a block device id (major:minor)
to create a new pktcdvd device and map
it to the block device.
remove (0200) Write the pktcdvd device id (major:minor)
to it to remove the pktcdvd device.
device_map (0444) Shows the device mapping in format:
pktcdvd[0-7] <pktdevid> <blkdevid>
/sys/class/pktcdvd/pktcdvd[0-7]/
dev (0444) Device id
uevent (0200) To send an uevent.
/sys/class/pktcdvd/pktcdvd[0-7]/stat/
packets_started (0444) Number of started packets.
packets_finished (0444) Number of finished packets.
kb_written (0444) kBytes written.
kb_read (0444) kBytes read.
kb_read_gather (0444) kBytes read to fill write packets.
reset (0200) Write any value to it to reset
pktcdvd device statistic values, like
bytes read/written.
/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/
size (0444) Contains the size of the bio write
queue.
congestion_off (0644) If bio write queue size is below
this mark, accept new bio requests
from the block layer.
congestion_on (0644) If bio write queue size is higher
as this mark, do no longer accept
bio write requests from the block
layer and wait till the pktcdvd
device has processed enough bio's
so that bio write queue size is
below congestion off mark.
A value of <= 0 disables congestion
control.
congestion_on: (RW) If bio write queue size is higher as this
mark, do no longer accept bio write requests
from the block layer and wait till the pktcdvd
device has processed enough bio's so that bio
write queue size is below congestion off mark.
A value of <= 0 disables congestion control.
Example:
......
What: /sys/class/rapidio_port
Description:
On-chip RapidIO controllers and PCIe-to-RapidIO bridges
(referenced as "Master Port" or "mport") are presented in sysfs
as the special class of devices: "rapidio_port".
The /sys/class/rapidio_port subdirectory contains individual
subdirectories named as "rapidioN" where N = mport ID registered
with RapidIO subsystem.
NOTE: An mport ID is not a RapidIO destination ID assigned to a
given local mport device.
What: /sys/class/rapidio_port/rapidioN/sys_size
Date: Apr, 2014
KernelVersion: v3.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) reports RapidIO common transport system size:
0 = small (8-bit destination ID, max. 256 devices),
1 = large (16-bit destination ID, max. 65536 devices).
What: /sys/class/rapidio_port/rapidioN/port_destid
Date: Apr, 2014
KernelVersion: v3.15
Contact: Matt Porter <mporter@kernel.crashing.org>,
Alexandre Bounine <alexandre.bounine@idt.com>
Description:
(RO) reports RapidIO destination ID assigned to the given
RapidIO mport device. If value 0xFFFFFFFF is returned this means
that no valid destination ID have been assigned to the mport
(yet). Normally, before enumeration/discovery have been executed
only fabric enumerating mports have a valid destination ID
assigned to them using "hdid=..." rapidio module parameter.
After enumeration or discovery was performed for a given mport device,
the corresponding subdirectory will also contain subdirectories for each
child RapidIO device connected to the mport.
The example below shows mport device subdirectory with several child RapidIO
devices attached to it.
[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
total 0
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005
lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0
-r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
drwxr-xr-x 2 root root 0 Feb 11 15:11 power
lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
-r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
-rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
What: /sys/devices/platform/i8042/.../sensitivity
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Trackpoint sensitivity.
What: /sys/devices/platform/i8042/.../intertia
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Negative inertia factor. High values cause the cursor to
snap backward when the trackpoint is released.
What: /sys/devices/platform/i8042/.../reach
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Backup range for z-axis press.
What: /sys/devices/platform/i8042/.../draghys
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) The drag hysteresis controls how hard it is to drag with
z-axis pressed.
What: /sys/devices/platform/i8042/.../mindrag
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Minimum amount of force needed to trigger dragging.
What: /sys/devices/platform/i8042/.../speed
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Speed of the trackpoint cursor.
What: /sys/devices/platform/i8042/.../thresh
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Minimum value for z-axis force required to trigger a press
or release, relative to the running average.
What: /sys/devices/platform/i8042/.../upthresh
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) The offset from the running average required to generate a
select (click) on z-axis on release.
What: /sys/devices/platform/i8042/.../ztime
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) This attribute determines how sharp a press has to be in
order to be recognized.
What: /sys/devices/platform/i8042/.../jenks
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Minimum curvature in degrees required to generate a double
click without a release.
What: /sys/devices/platform/i8042/.../skipback
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) When the skipback bit is set, backup cursor movement during
releases from drags will be suppressed. The default value for
this bit is 0.
What: /sys/devices/platform/i8042/.../ext_dev
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Disable (0) or enable (1) external pointing device.
What: /sys/devices/platform/i8042/.../press_to_select
Date: Aug, 2005
KernelVersion: 2.6.14
Contact: linux-input@vger.kernel.org
Description:
(RW) Writing a value of 1 to this file will enable the Press to
Select functions like tapping the control stick to simulate a
left click, and writing 0 will disable it.
What: /sys/devices/platform/i8042/.../drift_time
Date: Dec, 2014
KernelVersion: 3.19
Contact: linux-input@vger.kernel.org
Description:
(RW) This parameter controls the period of time to test for a
‘hands off’ condition (i.e. when no force is applied) before a
drift (noise) calibration occurs.
IBM Trackpoints have a feature to compensate for drift by
recalibrating themselves periodically. By default, if for 0.5
seconds there is no change in position, it's used as the new
zero. This duration is too low. Often, the calibration happens
when the trackpoint is in fact being used.
......@@ -218,6 +218,13 @@ Configuring the kernel
"make localyesconfig" Similar to localmodconfig, except it will convert
all module options to built in (=y) options.
"make kvmconfig" Enable additional options for kvm guest kernel support.
"make xenconfig" Enable additional options for xen dom0 guest kernel
support.
"make tinyconfig" Configure the tiniest possible kernel.
You can find more information on using the Linux kernel config tools
in Documentation/kbuild/kconfig.txt.
......
......@@ -180,11 +180,11 @@ Public keys in the kernel
=========================
The kernel contains a ring of public keys that can be viewed by root. They're
in a keyring called ".system_keyring" that can be seen by::
in a keyring called ".builtin_trusted_keys" that can be seen by::
[root@deneb ~]# cat /proc/keys
...
223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1
223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1
302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 []
...
......@@ -197,15 +197,15 @@ add those in also (e.g. from the UEFI key database).
Finally, it is possible to add additional public keys by doing::
keyctl padd asymmetric "" [.system_keyring-ID] <[key-file]
keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file]
e.g.::
keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
Note, however, that the kernel will only permit keys to be added to
``.system_keyring _if_`` the new key's X.509 wrapper is validly signed by a key
that is already resident in the .system_keyring at the time the key was added.
``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key
that is already resident in the ``.builtin_trusted_keys`` at the time the key was added.
========================
......
......@@ -29,18 +29,20 @@ made public.
Disclosure
----------
The goal of the Linux kernel security team is to work with the
bug submitter to bug resolution as well as disclosure. We prefer
to fully disclose the bug as soon as possible. It is reasonable to
delay disclosure when the bug or the fix is not yet fully understood,
the solution is not well-tested or for vendor coordination. However, we
expect these delays to be short, measurable in days, not weeks or months.
A disclosure date is negotiated by the security team working with the
bug submitter as well as vendors. However, the kernel security team
holds the final say when setting a disclosure date. The timeframe for
disclosure is from immediate (esp. if it's already publicly known)
The goal of the Linux kernel security team is to work with the bug
submitter to understand and fix the bug. We prefer to publish the fix as
soon as possible, but try to avoid public discussion of the bug itself
and leave that to others.
Publishing the fix may be delayed when the bug or the fix is not yet
fully understood, the solution is not well-tested or for vendor
coordination. However, we expect these delays to be short, measurable in
days, not weeks or months. A release date is negotiated by the security
team working with the bug submitter as well as vendors. However, the
kernel security team holds the final say when setting a timeframe. The
timeframe varies from immediate (esp. if it's already publicly known bug)
to a few weeks. As a basic default policy, we expect report date to
disclosure date to be on the order of 7 days.
release date to be on the order of 7 days.
Coordination
------------
......
......@@ -6,34 +6,34 @@ counter. This indicates that the kernel has been tainted by some
mechanism. The string is followed by a series of position-sensitive
characters, each representing a particular tainted value.
1) 'G' if all modules loaded have a GPL or compatible license, 'P' if
1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
any proprietary module has been loaded. Modules without a
MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
insmod as GPL compatible are assumed to be proprietary.
2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
modules were loaded normally.
3) ``S`` if the oops occurred on an SMP kernel running on hardware that
3) ``S`` if the oops occurred on an SMP kernel running on hardware that
hasn't been certified as safe to run multiprocessor.
Currently this occurs only on various Athlons that are not
SMP capable.
4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
modules were unloaded normally.
5) ``M`` if any processor has reported a Machine Check Exception,
5) ``M`` if any processor has reported a Machine Check Exception,
``' '`` if no Machine Check Exceptions have occurred.
6) ``B`` if a page-release function has found a bad page reference or
6) ``B`` if a page-release function has found a bad page reference or
some unexpected page flags.
7) ``U`` if a user or user application specifically requested that the
7) ``U`` if a user or user application specifically requested that the
Tainted flag be set, ``' '`` otherwise.
8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
9) ``A`` if the ACPI table has been overridden.
9) ``A`` if the ACPI table has been overridden.
10) ``W`` if a warning has previously been issued by the kernel.
(Though some warnings may set more specific taint flags.)
......
......@@ -60,8 +60,8 @@ Plain Pointers
Pointers printed without a specifier extension (i.e unadorned %p) are
hashed to prevent leaking information about the kernel memory layout. This
has the added benefit of providing a unique identifier. On 64-bit machines
the first 32 bits are zeroed. If you *really* want the address see %px
below.
the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
gathers enough entropy. If you *really* want the address see %px below.
Symbols/Function Pointers
-------------------------
......
......@@ -67,7 +67,7 @@ __releases - The specified lock is held on function entry, but not exit.
If the function enters and exits without the lock held, acquiring and
releasing the lock inside the function in a balanced way, no
annotation is needed. The tree annotations above are for cases where
annotation is needed. The three annotations above are for cases where
sparse would otherwise report a context imbalance.
Getting sparse
......
This diff is collapsed.
......@@ -6,10 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com>
This small document introduces how to test DMA drivers using dmatest module.
.. note::
The test suite works only on the channels that have at least one
capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET
(const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ.
Part 1 - How to build the test module
=====================================
The menuconfig contains an option that could be found by following path:
Device Drivers -> DMA Engine support -> DMA Test client
In the configuration file the option called CONFIG_DMATEST. The dmatest could
......@@ -18,11 +24,11 @@ be built as module or inside kernel. Let's consider those cases.
Part 2 - When dmatest is built as a module
==========================================
Example of usage: ::
Example of usage::
% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
...or: ::
...or::
% modprobe dmatest
% echo dma0chan0 > /sys/module/dmatest/parameters/channel
......@@ -30,14 +36,12 @@ Example of usage: ::
% echo 1 > /sys/module/dmatest/parameters/iterations
% echo 1 > /sys/module/dmatest/parameters/run
...or on the kernel command line: ::
...or on the kernel command line::
dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
..hint:: available channel list could be extracted by running the following
command:
::
.. hint::
available channel list could be extracted by running the following command::
% ls -1 /sys/class/dma/
......@@ -59,12 +63,12 @@ before returning. For example, the following scripts wait for 42 tests
to complete before exiting. Note that if 'iterations' is set to 'infinite' then
waiting is disabled.
Example: ::
Example::
% modprobe dmatest run=1 iterations=42 wait=1
% modprobe -r dmatest
...or: ::
...or::
% modprobe dmatest run=1 iterations=42
% cat /sys/module/dmatest/parameters/wait
......@@ -76,7 +80,7 @@ Part 3 - When built-in in the kernel
The module parameters that is supplied to the kernel command line will be used
for the first performed test. After user gets a control, the test could be
re-run with the same or different parameters. For the details see the above
section "Part 2 - When dmatest is built as a module..."
section `Part 2 - When dmatest is built as a module`_.
In both cases the module parameters are used as the actual values for the test
case. You always could check them at run-time by running ::
......@@ -86,22 +90,22 @@ case. You always could check them at run-time by running ::
Part 4 - Gathering the test results
===================================
Test results are printed to the kernel log buffer with the format: ::
Test results are printed to the kernel log buffer with the format::
"dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
Example of output: ::
Example of output::
% dmesg | tail -n 1
dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
The message format is unified across the different types of errors. A number in
the parens represents additional information, e.g. error code, error counter,
or status. A test thread also emits a summary line at completion listing the
number of tests executed, number that failed, and a result code.
The message format is unified across the different types of errors. A
number in the parentheses represents additional information, e.g. error
code, error counter, or status. A test thread also emits a summary line at
completion listing the number of tests executed, number that failed, and a
result code.
Example: ::
Example::
% dmesg | tail -n 1
dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
......
......@@ -90,7 +90,7 @@ controller resets the bus. This notification allows the driver to take necessary
steps to boot the device so that it's functional after the bus has been reset.
Driver and Controller APIs:
--------------------------
---------------------------
.. kernel-doc:: include/linux/slimbus.h
:internal:
......
......@@ -9,7 +9,7 @@ variable block sizes, is extent based, and makes extensive use of
Btrees (directories, extents, free space) to aid both performance
and scalability.
Refer to the documentation at http://oss.sgi.com/projects/xfs/
Refer to the documentation at https://xfs.wiki.kernel.org/
for further details. This implementation is on-disk compatible
with the IRIX version of XFS.
......
......@@ -64,6 +64,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
trace/index
maintainer/index
Kernel API documentation
......
SYSFS FILES
For each InfiniBand device, the InfiniBand drivers create the
following files under /sys/class/infiniband/<device name>:
node_type - Node type (CA, switch or router)
node_guid - Node GUID
sys_image_guid - System image GUID
In addition, there is a "ports" subdirectory, with one subdirectory
for each port. For example, if mthca0 is a 2-port HCA, there will
be two directories:
/sys/class/infiniband/mthca0/ports/1
/sys/class/infiniband/mthca0/ports/2
(A switch will only have a single "0" subdirectory for switch port
0; no subdirectory is created for normal switch ports)
In each port subdirectory, the following files are created:
cap_mask - Port capability mask
lid - Port LID
lid_mask_count - Port LID mask count
rate - Port data rate (active width * active speed)
sm_lid - Subnet manager LID for port's subnet
sm_sl - Subnet manager SL for port's subnet
state - Port state (DOWN, INIT, ARMED, ACTIVE or ACTIVE_DEFER)
phys_state - Port physical state (Sleep, Polling, LinkUp, etc)
There is also a "counters" subdirectory, with files
VL15_dropped
excessive_buffer_overrun_errors
link_downed
link_error_recovery
local_link_integrity_errors
port_rcv_constraint_errors
port_rcv_data
port_rcv_errors
port_rcv_packets
port_rcv_remote_physical_errors
port_rcv_switch_relay_errors
port_xmit_constraint_errors
port_xmit_data
port_xmit_discards
port_xmit_packets
symbol_error
Each of these files contains the corresponding value from the port's
Performance Management PortCounters attribute, as described in
section 16.1.3.5 of the InfiniBand Architecture Specification.
The "pkeys" and "gids" subdirectories contain one file for each
entry in the port's P_Key or GID table respectively. For example,
ports/1/pkeys/10 contains the value at index 10 in port 1's P_Key
table.
There is an optional "hw_counters" subdirectory that may be under either
the parent device or the port subdirectories or both. If present,
there are a list of counters provided by the hardware. They may match
some of the counters in the counters directory, but they often include
many other counters. In addition to the various counters, there will
be a file named "lifespan" that configures how frequently the core
should update the counters when they are being accessed (counters are
not updated if they are not being accessed). The lifespan is in milli-
seconds and defaults to 10 unless set to something else by the driver.
Users may echo a value between 0 - 10000 to the lifespan file to set
the length of time between updates in milliseconds.
MTHCA
The Mellanox HCA driver also creates the files:
hw_rev - Hardware revision number
fw_ver - Firmware version
hca_type - HCA type: "MT23108", "MT25208 (MT23108 compat mode)",
or "MT25208"
HFI1
The hfi1 driver also creates these additional files:
hw_rev - hardware revision
board_id - manufacturing board id
tempsense - thermal sense information
serial - board serial number
nfreectxts - number of free user contexts
nctxts - number of allowed contexts (PSM2)
chip_reset - diagnostic (root only)
boardversion - board version
sdma<N>/ - one directory per sdma engine (0 - 15)
sdma<N>/cpu_list - read-write, list of cpus for user-process to sdma
engine assignment.
sdma<N>/vl - read-only, vl the sdma engine maps to.
The new interface will give the user control on the affinity settings
for the hfi1 device.
As an example, to set an sdma engine irq affinity and thread affinity
of a user processes to use the sdma engine, which is "near" in terms
of NUMA configuration, or physical cpu location, the user will do:
echo "3" > /proc/irq/<N>/smp_affinity_list
echo "4-7" > /sys/devices/.../sdma3/cpu_list
cat /sys/devices/.../sdma3/vl
0
echo "8" > /proc/irq/<M>/smp_affinity_list
echo "9-12" > /sys/devices/.../sdma4/cpu_list
cat /sys/devices/.../sdma4/vl
1
to make sure that when a process runs on cpus 4,5,6, or 7,
and uses vl=0, then sdma engine 3 is selected by the driver,
and also the interrupt of the sdma engine 3 is steered to cpu 3.
Similarly, when a process runs on cpus 9,10,11, or 12 and sets vl=1,
then engine 4 will be selected and the irq of the sdma engine 4 is
steered to cpu 8.
This assumes that in the above N is the irq number of "sdma3",
and M is irq number of "sdma4" in the /proc/interrupts file.
ports/1/
CCMgtA/
cc_settings_bin - CCA tables used by PSM2
cc_table_bin
cc_prescan - enable prescaning for faster BECN response
sc2v/ - 32 files (0 - 31) used to translate sl->vl
sl2sc/ - 32 files (0 - 31) used to translate sl->sc
vl2mtu/ - 16 (0 - 15) files used to determine MTU for vl
The sysfs interface has moved to
Documentation/ABI/stable/sysfs-class-infiniband.
......@@ -192,10 +192,13 @@ The final v3 packet type is the trackstick packet::
byte 0: 1 1 x7 y7 1 1 1 1
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
byte 2: 0 y6 y5 y4 y3 y2 y1 y0
byte 3: 0 1 0 0 1 0 0 0
byte 4: 0 z4 z3 z2 z1 z0 ? ?
byte 3: 0 1 TP SW 1 M R L
byte 4: 0 z6 z5 z4 z3 z2 z1 z0
byte 5: 0 0 1 1 1 1 1 1
TP means Tap SW status when tap processing is enabled or Press status when press
processing is enabled. SW means scroll up when 4 buttons are available.
ALPS Absolute Mode - Protocol Version 4
---------------------------------------
......
......@@ -213,7 +213,7 @@ The tags in common use are:
which can be found in Documentation/process/submitting-patches.rst. Code without a
proper signoff cannot be merged into the mainline.
- Co-Developed-by: states that the patch was also created by another developer
- Co-developed-by: states that the patch was also created by another developer
along with the original author. This is useful at times when multiple
people work on a single patch. Note, this person also needs to have a
Signed-off-by: line in the patch as well.
......
......@@ -430,7 +430,7 @@ udev
FUSE
----
- <http://sourceforge.net/projects/fuse>
- <https://github.com/libfuse/libfuse/releases>
mcelog
------
......
......@@ -200,6 +200,15 @@ statement; in the latter case use braces in both branches:
otherwise();
}
Also, use braces when a loop contains more than a single simple statement:
.. code-block:: c
while (condition) {
if (test)
do_something();
}
3.1) Spaces
***********
......
......@@ -213,13 +213,6 @@ will learn the basics of getting your patch into the Linux kernel tree,
and possibly be pointed in the direction of what to go work on next, if
you do not already have an idea.
If you already have a chunk of code that you want to put into the kernel
tree, but need some help getting it in the proper form, the
kernel-mentors project was created to help you out with this. It is a
mailing list, and can be found at:
https://selenic.com/mailman/listinfo/kernel-mentors
Before making any actual modifications to the Linux kernel code, it is
imperative to understand how the code in question works. For this
purpose, nothing is better than reading through it directly (most tricky
......@@ -381,14 +374,6 @@ bugs is one of the best ways to get merits among other developers, because
not many people like wasting time fixing other people's bugs.
To work in the already reported bug reports, go to https://bugzilla.kernel.org.
If you want to be advised of the future bug reports, you can subscribe to the
bugme-new mailing list (only new bug reports are mailed here) or to the
bugme-janitor mailing list (every change in the bugzilla is mailed here)
https://lists.linux-foundation.org/mailman/listinfo/bugme-new
https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
Mailing lists
......
......@@ -103,6 +103,7 @@ today, have in the past, or will in the future.
- Auke Kok
- Peter Korsgaard
- Jiri Kosina
- Aaro Koskinen
- Mariusz Kozlowski
- Greg Kroah-Hartman
- Michael Krufky
......
......@@ -4,15 +4,17 @@ Linux kernel licensing rules
============================
The Linux Kernel is provided under the terms of the GNU General Public
License version 2 only (GPL-2.0), as published by the Free Software
Foundation, and provided in the COPYING file. This documentation file is
not meant to replace the COPYING file, but provides a description of how
each source file should be annotated to make the licensing it is governed
under clear and unambiguous.
The license in the COPYING file applies to the kernel source as a whole,
though individual source files can have a different license which is
required to be compatible with the GPL-2.0::
License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0,
with an explicit syscall exception described in
LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.
This documentation file provides a description of how each source file
should be annotated to make its license clear and unambiguous.
It doesn't replace the Kernel's license.
The license described in the COPYING file applies to the kernel source
as a whole, though individual source files can have a different license
which is required to be compatible with the GPL-2.0::
GPL-1.0+ : GNU General Public License v1.0 or later
GPL-2.0+ : GNU General Public License v2.0 or later
......
......@@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer. The tty code,
for example, does this frequently to pass driver-specific and line
discipline-specific structures back and forth.
The way to use magic numbers is to declare then at the beginning of
The way to use magic numbers is to declare them at the beginning of
the structure, like so::
struct tty_ldisc {
......
......@@ -510,8 +510,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your
tree.
12) When to use Acked-by: and Cc:
---------------------------------
12) When to use Acked-by:, Cc:, and Co-Developed-by:
-------------------------------------------------------
The Signed-off-by: tag indicates that the signer was involved in the
development of the patch, or that he/she was in the patch's delivery path.
......@@ -543,6 +543,11 @@ person it names - but it should indicate that this person was copied on the
patch. This tag documents that potentially interested parties
have been included in the discussion.
A Co-Developed-by: states that the patch was also created by another developer
along with the original author. This is useful at times when multiple people
work on a single patch. Note, this person also needs to have a Signed-off-by:
line in the patch as well.
13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
--------------------------------------------------------------------------
......
RapidIO sysfs Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. RapidIO Device Subdirectories
--------------------------------
For each RapidIO device, the RapidIO subsystem creates files in an individual
subdirectory with the following name, /sys/bus/rapidio/devices/<device_name>.
The format of device_name is "nn:d:iiii", where:
nn - two-digit hexadecimal ID of RapidIO network where the device resides
d - device typr: 'e' - for endpoint or 's' - for switch
iiii - four-digit device destID for endpoints, or switchID for switches
For example, below is a list of device directories that represents a typical
RapidIO network with one switch, one host, and two agent endpoints, as it is
seen by the enumerating host (destID = 1):
/sys/bus/rapidio/devices/00:e:0000
/sys/bus/rapidio/devices/00:e:0002
/sys/bus/rapidio/devices/00:s:0001
NOTE: An enumerating or discovering endpoint does not create a sysfs entry for
itself, this is why an endpoint with destID=1 is not shown in the list.
2. Attributes Common for All RapidIO Devices
--------------------------------------------
Each device subdirectory contains the following informational read-only files:
did - returns the device identifier
vid - returns the device vendor identifier
device_rev - returns the device revision level
asm_did - returns identifier for the assembly containing the device
asm_rev - returns revision level of the assembly containing the device
asm_vid - returns vendor identifier of the assembly containing the device
destid - returns device destination ID assigned by the enumeration routine
(see 4.1 for switch specific details)
lprev - returns name of previous device (switch) on the path to the device
that that owns this attribute
modalias - returns the device modalias
In addition to the files listed above, each device has a binary attribute file
that allows read/write access to the device configuration registers using
the RapidIO maintenance transactions:
config - reads from and writes to the device configuration registers.
This attribute is similar in behavior to the "config" attribute of PCI devices
and provides an access to the RapidIO device registers using standard file read
and write operations.
3. RapidIO Endpoint Device Attributes
-------------------------------------
Currently Linux RapidIO subsystem does not create any endpoint specific sysfs
attributes. It is possible that RapidIO master port drivers and endpoint device
drivers will add their device-specific sysfs attributes but such attributes are
outside the scope of this document.
4. RapidIO Switch Device Attributes
-----------------------------------
RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports
common and device-specific sysfs attributes for switches. Because switches are
integrated into the RapidIO subsystem, it offers a method to create
device-specific sysfs attributes by specifying a callback function that may be
set by the switch initialization routine during enumeration or discovery process.
4.1 Common Switch Attributes
routes - reports switch routing information in "destID port" format. This
attribute reports only valid routing table entries, one line for
each entry.
destid - device destination ID that defines a route to the switch
hopcount - number of hops on the path to the switch
lnext - returns names of devices linked to the switch except one of a device
linked to the ingress port (reported as "lprev"). This is an array
names with number of lines equal to number of ports in switch. If
a switch port has no attached device, returns "null" instead of
a device name.
4.2 Device-specific Switch Attributes
Device-specific switch attributes are listed for each RapidIO switch driver
that exports additional attributes.
IDT_GEN2:
errlog - reads contents of device error log until it is empty.
5. RapidIO Bus Attributes
-------------------------
RapidIO bus subdirectory /sys/bus/rapidio implements the following bus-specific
attribute:
scan - allows to trigger enumeration discovery process from user space. This
is a write-only attribute. To initiate an enumeration or discovery
process on specific mport device, a user needs to write mport_ID (not
RapidIO destination ID) into this file. The mport_ID is a sequential
number (0 ... RIO_MAX_MPORTS) assigned to the mport device.
For example, for a machine with a single RapidIO controller, mport_ID
for that controller always will be 0.
To initiate RapidIO enumeration/discovery on all available mports
a user must write '-1' (or RIO_MPORT_ANY) into this attribute file.
6. RapidIO Bus Controllers/Ports
--------------------------------
On-chip RapidIO controllers and PCIe-to-RapidIO bridges (referenced as
"Master Port" or "mport") are presented in sysfs as the special class of
devices: "rapidio_port".
The /sys/class/rapidio_port subdirectory contains individual subdirectories
named as "rapidioN" where N = mport ID registered with RapidIO subsystem.
NOTE: An mport ID is not a RapidIO destination ID assigned to a given local
mport device.
Each mport device subdirectory in addition to standard entries contains the
following device-specific attributes:
port_destid - reports RapidIO destination ID assigned to the given RapidIO
mport device. If value 0xFFFFFFFF is returned this means that
no valid destination ID have been assigned to the mport (yet).
Normally, before enumeration/discovery have been executed only
fabric enumerating mports have a valid destination ID assigned
to them using "hdid=..." rapidio module parameter.
sys_size - reports RapidIO common transport system size:
0 = small (8-bit destination ID, max. 256 devices),
1 = large (16-bit destination ID, max. 65536 devices).
After enumeration or discovery was performed for a given mport device,
the corresponding subdirectory will also contain subdirectories for each
child RapidIO device connected to the mport. Naming conventions for RapidIO
devices are described in Section 1 above.
The example below shows mport device subdirectory with several child RapidIO
devices attached to it.
[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
total 0
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003
drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005
lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0
-r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
drwxr-xr-x 2 root root 0 Feb 11 15:11 power
lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
-r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
-rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
Documentation/ABI/testing/sysfs-class-rapidio
Subsystem Trace Points: kmem
============================
Subsystem Trace Points: kmem
============================
The kmem tracing system captures events related to object and page allocation
within the kernel. Broadly speaking there are five major subheadings.
o Slab allocation of small objects of unknown type (kmalloc)
o Slab allocation of small objects of known type
o Page allocation
o Per-CPU Allocator Activity
o External Fragmentation
- Slab allocation of small objects of unknown type (kmalloc)
- Slab allocation of small objects of known type
- Page allocation
- Per-CPU Allocator Activity
- External Fragmentation
This document describes what each of the tracepoints is and why they
might be useful.
1. Slab allocation of small objects of unknown type
===================================================
kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
kfree call_site=%lx ptr=%p
::
kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
kfree call_site=%lx ptr=%p
Heavy activity for these events may indicate that a specific cache is
justified, particularly if kmalloc slab pages are getting significantly
......@@ -27,9 +31,11 @@ the allocation sites were.
2. Slab allocation of small objects of known type
=================================================
kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
kmem_cache_free call_site=%lx ptr=%p
::
kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
kmem_cache_free call_site=%lx ptr=%p
These events are similar in usage to the kmalloc-related events except that
it is likely easier to pin the event down to a specific cache. At the time
......@@ -38,10 +44,12 @@ but the call_site can usually be used to extrapolate that information.
3. Page allocation
==================
mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
mm_page_free page=%p pfn=%lu order=%d
mm_page_free_batched page=%p pfn=%lu order=%d cold=%d
::
mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
mm_page_free page=%p pfn=%lu order=%d
mm_page_free_batched page=%p pfn=%lu order=%d cold=%d
These four events deal with page allocation and freeing. mm_page_alloc is
a simple indicator of page allocator activity. Pages may be allocated from
......@@ -65,8 +73,10 @@ contention on the zone->lru_lock.
4. Per-CPU Allocator Activity
=============================
mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d
::
mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d
In front of the page allocator is a per-cpu page allocator. It exists only
for order-0 pages, reduces contention on the zone->lock and reduces the
......@@ -92,7 +102,9 @@ can be allocated and freed on the same CPU through some algorithm change.
5. External Fragmentation
=========================
mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d
::
mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d
External fragmentation affects whether a high-order allocation will be
successful or not. For some types of hardware, this is important although
......
================
MSR Trace Events
================
The x86 kernel supports tracing most MSR (Model Specific Register) accesses.
To see the definition of the MSRs on Intel systems please see the SDM
......@@ -7,31 +10,31 @@ Available trace points:
/sys/kernel/debug/tracing/events/msr/
Trace MSR reads
Trace MSR reads:
read_msr
msr: MSR number
val: Value written
failed: 1 if the access failed, otherwise 0
- msr: MSR number
- val: Value written
- failed: 1 if the access failed, otherwise 0
Trace MSR writes
Trace MSR writes:
write_msr
msr: MSR number
val: Value written
failed: 1 if the access failed, otherwise 0
- msr: MSR number
- val: Value written
- failed: 1 if the access failed, otherwise 0
Trace RDPMC in kernel
Trace RDPMC in kernel:
rdpmc
The trace data can be post processed with the postprocess/decode_msr.py script
The trace data can be post processed with the postprocess/decode_msr.py script::
cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h
cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h
to add symbolic MSR names.
================
NMI Trace Events
================
These events normally show up here:
/sys/kernel/debug/tracing/events/nmi
--
nmi_handler:
nmi_handler
-----------
You might want to use this tracepoint if you suspect that your
NMI handlers are hogging large amounts of CPU time. The kernel
will warn if it sees long-running handlers:
will warn if it sees long-running handlers::
INFO: NMI handler took too long to run: 9.207 msecs
......@@ -19,7 +21,7 @@ more details.
Let's say you suspect that perf_event_nmi_handler() is causing
you some problems and you only want to trace that handler
specifically. You need to find its address:
specifically. You need to find its address::
$ grep perf_event_nmi_handler /proc/kallsyms
ffffffff81625600 t perf_event_nmi_handler
......@@ -27,17 +29,17 @@ specifically. You need to find its address:
Let's also say you are only interested in when that function is
really hogging a lot of CPU time, like a millisecond at a time.
Note that the kernel's output is in milliseconds, but the input
to the filter is in nanoseconds! You can filter on 'delta_ns':
to the filter is in nanoseconds! You can filter on 'delta_ns'::
cd /sys/kernel/debug/tracing/events/nmi/nmi_handler
echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter
echo 1 > enable
cd /sys/kernel/debug/tracing/events/nmi/nmi_handler
echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter
echo 1 > enable
Your output would then look like:
Your output would then look like::
$ cat /sys/kernel/debug/tracing/trace_pipe
<idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1
<idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1
<idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1
<idle>-0 [000] d.h3 506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1
$ cat /sys/kernel/debug/tracing/trace_pipe
<idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1
<idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1
<idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1
<idle>-0 [000] d.h3 506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1
Subsystem Trace Points: power
=============================
Subsystem Trace Points: power
=============================
The power tracing system captures events related to power transitions
within the kernel. Broadly speaking there are three major subheadings:
o Power state switch which reports events related to suspend (S-states),
cpuidle (C-states) and cpufreq (P-states)
o System clock related changes
o Power domains related changes and transitions
- Power state switch which reports events related to suspend (S-states),
cpuidle (C-states) and cpufreq (P-states)
- System clock related changes
- Power domains related changes and transitions
This document describes what each of the tracepoints is and why they
might be useful.
......@@ -22,14 +23,16 @@ Cf. include/trace/events/power.h for the events definitions.
A 'cpu' event class gathers the CPU-related events: cpuidle and
cpufreq.
::
cpu_idle "state=%lu cpu_id=%lu"
cpu_frequency "state=%lu cpu_id=%lu"
cpu_idle "state=%lu cpu_id=%lu"
cpu_frequency "state=%lu cpu_id=%lu"
A suspend event is used to indicate the system going in and out of the
suspend mode:
::
machine_suspend "state=%lu"
machine_suspend "state=%lu"
Note: the value of '-1' or '4294967295' for state means an exit from the current state,
......@@ -45,10 +48,11 @@ correctly draw the states diagrams and to calculate accurate statistics etc.
================
The clock events are used for clock enable/disable and for
clock rate change.
::
clock_enable "%s state=%lu cpu_id=%lu"
clock_disable "%s state=%lu cpu_id=%lu"
clock_set_rate "%s state=%lu cpu_id=%lu"
clock_enable "%s state=%lu cpu_id=%lu"
clock_disable "%s state=%lu cpu_id=%lu"
clock_set_rate "%s state=%lu cpu_id=%lu"
The first parameter gives the clock name (e.g. "gpio1_iclk").
The second parameter is '1' for enable, '0' for disable, the target
......@@ -57,8 +61,9 @@ clock rate for set_rate.
3. Power domains events
=======================
The power domain events are used for power domains transitions
::
power_domain_target "%s state=%lu cpu_id=%lu"
power_domain_target "%s state=%lu cpu_id=%lu"
The first parameter gives the power domain name (e.g. "mpu_pwrdm").
The second parameter is the power domain target state.
......@@ -67,28 +72,31 @@ The second parameter is the power domain target state.
================
The PM QoS events are used for QoS add/update/remove request and for
target/flags update.
::
pm_qos_add_request "pm_qos_class=%s value=%d"
pm_qos_update_request "pm_qos_class=%s value=%d"
pm_qos_remove_request "pm_qos_class=%s value=%d"
pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld"
pm_qos_add_request "pm_qos_class=%s value=%d"
pm_qos_update_request "pm_qos_class=%s value=%d"
pm_qos_remove_request "pm_qos_class=%s value=%d"
pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld"
The first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY").
The second parameter is value to be added/updated/removed.
The third parameter is timeout value in usec.
::
pm_qos_update_target "action=%s prev_value=%d curr_value=%d"
pm_qos_update_flags "action=%s prev_value=0x%x curr_value=0x%x"
pm_qos_update_target "action=%s prev_value=%d curr_value=%d"
pm_qos_update_flags "action=%s prev_value=0x%x curr_value=0x%x"
The first parameter gives the QoS action name (e.g. "ADD_REQ").
The second parameter is the previous QoS value.
The third parameter is the current QoS value to update.
And, there are also events used for device PM QoS add/update/remove request.
::
dev_pm_qos_add_request "device=%s type=%s new_value=%d"
dev_pm_qos_update_request "device=%s type=%s new_value=%d"
dev_pm_qos_remove_request "device=%s type=%s new_value=%d"
dev_pm_qos_add_request "device=%s type=%s new_value=%d"
dev_pm_qos_update_request "device=%s type=%s new_value=%d"
dev_pm_qos_remove_request "device=%s type=%s new_value=%d"
The first parameter gives the device name which tries to add/update/remove
QoS requests.
......
......@@ -21,13 +21,14 @@ how to use ftrace to implement your own function callbacks.
The ftrace context
==================
.. warning::
WARNING: The ability to add a callback to almost any function within the
kernel comes with risks. A callback can be called from any context
(normal, softirq, irq, and NMI). Callbacks can also be called just before
going to idle, during CPU bring up and takedown, or going to user space.
This requires extra care to what can be done inside a callback. A callback
can be called outside the protective scope of RCU.
The ability to add a callback to almost any function within the
kernel comes with risks. A callback can be called from any context
(normal, softirq, irq, and NMI). Callbacks can also be called just before
going to idle, during CPU bring up and takedown, or going to user space.
This requires extra care to what can be done inside a callback. A callback
can be called outside the protective scope of RCU.
The ftrace infrastructure has some protections agains recursions and RCU
but one must still be very careful how they use the callbacks.
......@@ -54,15 +55,15 @@ an ftrace_ops with ftrace:
Both .flags and .private are optional. Only .func is required.
To enable tracing call::
To enable tracing call:
.. c:function:: register_ftrace_function(&ops);
To disable tracing call::
To disable tracing call:
.. c:function:: unregister_ftrace_function(&ops);
The above is defined by including the header::
The above is defined by including the header:
.. c:function:: #include <linux/ftrace.h>
......@@ -200,7 +201,7 @@ match a specific pattern.
See Filter Commands in :file:`Documentation/trace/ftrace.txt`.
To just trace the schedule function::
To just trace the schedule function:
.. code-block:: c
......@@ -210,7 +211,7 @@ To add more functions, call the ftrace_set_filter() more than once with the
@reset parameter set to zero. To remove the current filter set and replace it
with new functions defined by @buf, have @reset be non-zero.
To remove all the filtered functions and trace all functions::
To remove all the filtered functions and trace all functions:
.. code-block:: c
......
Introduction:
=========================
Hardware Latency Detector
=========================
Introduction
-------------
The tracer hwlat_detector is a special purpose tracer that is used to
......@@ -28,7 +32,7 @@ Note that the hwlat detector should *NEVER* be used in a production environment.
It is intended to be run manually to determine if the hardware platform has a
problem with long system firmware service routines.
Usage:
Usage
------
Write the ASCII text "hwlat" into the current_tracer file of the tracing system
......@@ -36,16 +40,16 @@ Write the ASCII text "hwlat" into the current_tracer file of the tracing system
redefine the threshold in microseconds (us) above which latency spikes will
be taken into account.
Example:
Example::
# echo hwlat > /sys/kernel/tracing/current_tracer
# echo 100 > /sys/kernel/tracing/tracing_thresh
The /sys/kernel/tracing/hwlat_detector interface contains the following files:
width - time period to sample with CPUs held (usecs)
must be less than the total window size (enforced)
window - total period of sampling, width being inside (usecs)
- width - time period to sample with CPUs held (usecs)
must be less than the total window size (enforced)
- window - total period of sampling, width being inside (usecs)
By default the width is set to 500,000 and window to 1,000,000, meaning that
for every 1,000,000 usecs (1s) the hwlat detector will spin for 500,000 usecs
......@@ -67,11 +71,11 @@ The following tracing directory files are used by the hwlat_detector:
in /sys/kernel/tracing:
tracing_threshold - minimum latency value to be considered (usecs)
tracing_max_latency - maximum hardware latency actually observed (usecs)
tracing_cpumask - the CPUs to move the hwlat thread across
hwlat_detector/width - specified amount of time to spin within window (usecs)
hwlat_detector/window - amount of time between (width) runs (usecs)
- tracing_threshold - minimum latency value to be considered (usecs)
- tracing_max_latency - maximum hardware latency actually observed (usecs)
- tracing_cpumask - the CPUs to move the hwlat thread across
- hwlat_detector/width - specified amount of time to spin within window (usecs)
- hwlat_detector/window - amount of time between (width) runs (usecs)
The hwlat detector's kernel thread will migrate across each CPU specified in
tracing_cpumask between each window. To limit the migration, either modify
......
==========================
Linux Tracing Technologies
==========================
.. toctree::
:maxdepth: 2
ftrace-design
tracepoint-analysis
ftrace
ftrace-uses
kprobetrace
uprobetracer
tracepoints
events
events-kmem
events-power
events-nmi
events-msr
mmiotrace
hwlat_detector
intel_th
stm
=======================
Intel(R) Trace Hub (TH)
=======================
......@@ -18,13 +19,13 @@ via sysfs attributes.
Currently, the following Intel TH subdevices (blocks) are supported:
- Software Trace Hub (STH), trace source, which is a System Trace
Module (STM) device,
Module (STM) device,
- Memory Storage Unit (MSU), trace output, which allows storing
trace hub output in system memory,
trace hub output in system memory,
- Parallel Trace Interface output (PTI), trace output to an external
debug host via a PTI port,
debug host via a PTI port,
- Global Trace Hub (GTH), which is a switch and a central component
of Intel(R) Trace Hub architecture.
of Intel(R) Trace Hub architecture.
Common attributes for output devices are described in
Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most
......@@ -65,41 +66,41 @@ allocated, are accessible via /dev/intel_th0/msc{0,1}.
Quick example
-------------
# figure out which GTH port is the first memory controller:
# figure out which GTH port is the first memory controller::
$ cat /sys/bus/intel_th/devices/0-msc0/port
0
$ cat /sys/bus/intel_th/devices/0-msc0/port
0
# looks like it's port 0, configure master 33 to send data to port 0:
# looks like it's port 0, configure master 33 to send data to port 0::
$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
# allocate a 2-windowed multiblock buffer on the first memory
# controller, each with 64 pages:
# controller, each with 64 pages::
$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
# enable wrapping for this controller, too:
# enable wrapping for this controller, too::
$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
# and enable tracing into this port:
# and enable tracing into this port::
$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
# .. send data to master 33, see stm.txt for more details ..
# .. wait for traces to pile up ..
# .. and stop the trace:
# .. and stop the trace::
$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
# and now you can collect the trace from the device node:
# and now you can collect the trace from the device node::
$ cat /dev/intel_th0/msc0 > my_stp_trace
$ cat /dev/intel_th0/msc0 > my_stp_trace
Host Debugger Mode
==================
------------------
It is possible to configure the Trace Hub and control its trace
capture from a remote debug host, which should be connected via one of
......
Kprobe-based Event Tracing
==========================
Documentation is written by Masami Hiramatsu
==========================
Kprobe-based Event Tracing
==========================
:Author: Masami Hiramatsu
Overview
--------
......@@ -23,6 +23,8 @@ current_tracer. Instead of that, add probe points via
Synopsis of kprobe_events
-------------------------
::
p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe
r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe
-:[GRP/]EVENT : Clear a probe
......@@ -66,7 +68,7 @@ String type is a special type, which fetches a "null-terminated" string from
kernel space. This means it will fail and store NULL if the string container
has been paged out.
Bitfield is another special type, which takes 3 parameters, bit-width, bit-
offset, and container-size (usually 32). The syntax is;
offset, and container-size (usually 32). The syntax is::
b<bit-width>@<bit-offset>/<container-size>
......@@ -75,7 +77,7 @@ For $comm, the default type is "string"; any other type is invalid.
Per-Probe Event Filtering
-------------------------
Per-probe event filtering feature allows you to set different filter on each
Per-probe event filtering feature allows you to set different filter on each
probe and gives you what arguments will be shown in trace buffer. If an event
name is specified right after 'p:' or 'r:' in kprobe_events, it adds an event
under tracing/events/kprobes/<EVENT>, at the directory you can see 'id',
......@@ -96,87 +98,93 @@ id:
Event Profiling
---------------
You can check the total number of probe hits and probe miss-hits via
You can check the total number of probe hits and probe miss-hits via
/sys/kernel/debug/tracing/kprobe_profile.
The first column is event name, the second is the number of probe hits,
The first column is event name, the second is the number of probe hits,
the third is the number of probe miss-hits.
Usage examples
--------------
To add a probe as a new event, write a new definition to kprobe_events
as below.
as below::
echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events
This sets a kprobe on the top of do_sys_open() function with recording
This sets a kprobe on the top of do_sys_open() function with recording
1st to 4th arguments as "myprobe" event. Note, which register/stack entry is
assigned to each function argument depends on arch-specific ABI. If you unsure
the ABI, please try to use probe subcommand of perf-tools (you can find it
under tools/perf/).
As this example shows, users can choose more familiar names for each arguments.
::
echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events
This sets a kretprobe on the return point of do_sys_open() function with
This sets a kretprobe on the return point of do_sys_open() function with
recording return value as "myretprobe" event.
You can see the format of these events via
You can see the format of these events via
/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
::
cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
name: myprobe
ID: 780
format:
field:unsigned short common_type; offset:0; size:2; signed:0;
field:unsigned char common_flags; offset:2; size:1; signed:0;
field:unsigned char common_preempt_count; offset:3; size:1;signed:0;
field:int common_pid; offset:4; size:4; signed:1;
name: myprobe
ID: 780
format:
field:unsigned short common_type; offset:0; size:2; signed:0;
field:unsigned char common_flags; offset:2; size:1; signed:0;
field:unsigned char common_preempt_count; offset:3; size:1;signed:0;
field:int common_pid; offset:4; size:4; signed:1;
field:unsigned long __probe_ip; offset:12; size:4; signed:0;
field:int __probe_nargs; offset:16; size:4; signed:1;
field:unsigned long dfd; offset:20; size:4; signed:0;
field:unsigned long filename; offset:24; size:4; signed:0;
field:unsigned long flags; offset:28; size:4; signed:0;
field:unsigned long mode; offset:32; size:4; signed:0;
field:unsigned long __probe_ip; offset:12; size:4; signed:0;
field:int __probe_nargs; offset:16; size:4; signed:1;
field:unsigned long dfd; offset:20; size:4; signed:0;
field:unsigned long filename; offset:24; size:4; signed:0;
field:unsigned long flags; offset:28; size:4; signed:0;
field:unsigned long mode; offset:32; size:4; signed:0;
print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
REC->dfd, REC->filename, REC->flags, REC->mode
print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
REC->dfd, REC->filename, REC->flags, REC->mode
You can see that the event has 4 arguments as in the expressions you specified.
You can see that the event has 4 arguments as in the expressions you specified.
::
echo > /sys/kernel/debug/tracing/kprobe_events
This clears all probe points.
This clears all probe points.
Or,
Or,
::
echo -:myprobe >> kprobe_events
This clears probe points selectively.
This clears probe points selectively.
Right after definition, each event is disabled by default. For tracing these
Right after definition, each event is disabled by default. For tracing these
events, you need to enable it.
::
echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable
And you can see the traced information via /sys/kernel/debug/tracing/trace.
And you can see the traced information via /sys/kernel/debug/tracing/trace.
::
cat /sys/kernel/debug/tracing/trace
# tracer: nop
#
# TASK-PID CPU# TIMESTAMP FUNCTION
# | | | | |
<...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0
<...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
<...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6
<...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
<...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10
<...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Each line shows when the kernel hits an event, and <- SYMBOL means kernel
# tracer: nop
#
# TASK-PID CPU# TIMESTAMP FUNCTION
# | | | | |
<...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0
<...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe
<...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6
<...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
<...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10
<...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
Each line shows when the kernel hits an event, and <- SYMBOL means kernel
returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
returns from do_sys_open to sys_open+0x1b).
In-kernel memory-mapped I/O tracing
===================================
In-kernel memory-mapped I/O tracing
===================================
Home page and links to optional user space tools:
......@@ -31,30 +33,35 @@ is no way to automatically detect if you are losing events due to CPUs racing.
Usage Quick Reference
---------------------
::
$ mount -t debugfs debugfs /sys/kernel/debug
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt &
Start X or whatever.
$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker
$ echo nop > /sys/kernel/debug/tracing/current_tracer
Check for lost events.
$ mount -t debugfs debugfs /sys/kernel/debug
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt &
Start X or whatever.
$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker
$ echo nop > /sys/kernel/debug/tracing/current_tracer
Check for lost events.
Usage
-----
Make sure debugfs is mounted to /sys/kernel/debug.
If not (requires root privileges):
$ mount -t debugfs debugfs /sys/kernel/debug
If not (requires root privileges)::
$ mount -t debugfs debugfs /sys/kernel/debug
Check that the driver you are about to trace is not loaded.
Activate mmiotrace (requires root privileges):
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
Activate mmiotrace (requires root privileges)::
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
Start storing the trace::
$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt &
Start storing the trace:
$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt &
The 'cat' process should stay running (sleeping) in the background.
Load the driver you want to trace and use it. Mmiotrace will only catch MMIO
......@@ -66,30 +73,42 @@ This makes it easier to see which part of the (huge) trace corresponds to
which action. It is recommended to place descriptive markers about what you
do.
Shut down mmiotrace (requires root privileges):
$ echo nop > /sys/kernel/debug/tracing/current_tracer
Shut down mmiotrace (requires root privileges)::
$ echo nop > /sys/kernel/debug/tracing/current_tracer
The 'cat' process exits. If it does not, kill it by issuing 'fg' command and
pressing ctrl+c.
Check that mmiotrace did not lose events due to a buffer filling up. Either
$ grep -i lost mydump.txt
which tells you exactly how many events were lost, or use
$ dmesg
Check that mmiotrace did not lose events due to a buffer filling up. Either::
$ grep -i lost mydump.txt
which tells you exactly how many events were lost, or use::
$ dmesg
to view your kernel log and look for "mmiotrace has lost events" warning. If
events were lost, the trace is incomplete. You should enlarge the buffers and
try again. Buffers are enlarged by first seeing how large the current buffers
are:
$ cat /sys/kernel/debug/tracing/buffer_size_kb
are::
$ cat /sys/kernel/debug/tracing/buffer_size_kb
gives you a number. Approximately double this number and write it back, for
instance:
$ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb
instance::
$ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb
Then start again from the top.
If you are doing a trace for a driver project, e.g. Nouveau, you should also
do the following before sending your results:
$ lspci -vvv > lspci.txt
$ dmesg > dmesg.txt
$ tar zcf pciid-nick-mmiotrace.tar.gz mydump.txt lspci.txt dmesg.txt
do the following before sending your results::
$ lspci -vvv > lspci.txt
$ dmesg > dmesg.txt
$ tar zcf pciid-nick-mmiotrace.tar.gz mydump.txt lspci.txt dmesg.txt
and then send the .tar.gz file. The trace compresses considerably. Replace
"pciid" and "nick" with the PCI ID or model name of your piece of hardware
under investigation and your nickname.
......@@ -148,17 +167,18 @@ zero if it is not recorded. PID is always zero as tracing MMIO accesses
originating in user space memory is not yet supported.
For instance, the following awk filter will pass all 32-bit writes that target
physical addresses in the range [0xfb73ce40, 0xfb800000[
physical addresses in the range [0xfb73ce40, 0xfb800000]
::
$ awk '/W 4 / { adr=strtonum($5); if (adr >= 0xfb73ce40 &&
adr < 0xfb800000) print; }'
$ awk '/W 4 / { adr=strtonum($5); if (adr >= 0xfb73ce40 &&
adr < 0xfb800000) print; }'
Tools for Developers
--------------------
The user space tools include utilities for:
- replacing numeric addresses and values with hardware register names
- replaying MMIO logs, i.e., re-executing the recorded writes
- replacing numeric addresses and values with hardware register names
- replaying MMIO logs, i.e., re-executing the recorded writes
===================
System Trace Module
===================
......@@ -32,14 +33,14 @@ associated with it, located in "stp-policy" subsystem directory in
configfs. The topmost directory's name (the policy) is formatted as
the STM device name to which this policy applies and and arbitrary
string identifier separated by a stop. From the examle above, a rule
may look like this:
may look like this::
$ ls /config/stp-policy/dummy_stm.my-policy/user
channels masters
$ cat /config/stp-policy/dummy_stm.my-policy/user/masters
48 63
$ cat /config/stp-policy/dummy_stm.my-policy/user/channels
0 127
$ ls /config/stp-policy/dummy_stm.my-policy/user
channels masters
$ cat /config/stp-policy/dummy_stm.my-policy/user/masters
48 63
$ cat /config/stp-policy/dummy_stm.my-policy/user/channels
0 127
which means that the master allocation pool for this rule consists of
masters 48 through 63 and channel allocation pool has channels 0
......@@ -78,9 +79,9 @@ stm_source
For kernel-based trace sources, there is "stm_source" device
class. Devices of this class can be connected and disconnected to/from
stm devices at runtime via a sysfs attribute called "stm_source_link"
by writing the name of the desired stm device there, for example:
by writing the name of the desired stm device there, for example::
$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link
$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link
For examples on how to use stm_source interface in the kernel, refer
to stm_console, stm_heartbeat or stm_ftrace drivers.
......@@ -118,5 +119,5 @@ the same time.
Currently only Ftrace "function" tracer is supported.
[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
[2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
* [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
* [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment