iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

There's been a fair amount of activity in Documentation/ this time around:

Browse Source 
- 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.
 -----BEGIN PGP SIGNATURE-----
 
 iQJDBAABCAAtFiEEUOvtSCFqLxY/7px3jc41VjAi5XoFAlrCPGYPHGNvcmJldEBs
 d24ubmV0AAoJEI3ONVYwIuV6izAP/1DpGfBdnrG4TZkCf+qQHT19ZluwGm+wOBF4
 +7qa6It4BL4PbSmSSZx79yZIpeSL96codCWMFSrud71WzOzfCtidyzOduuqvEluJ
 3Fhl+hxyDYDQGpPt4y7rPbjh23dliXHFzYycfsFn7H9Gj4MX74c6ktRlPUwIgR/D
 YFyE2jEKUU/2wblpZgcGdS49AUZAWiC9kS2Z9lSrIswcy+G2eZ1qUfbX60tge0op
 nLKWlWwv2hTO0KnYJebdHwQsRe5DkW9smPiG1fsCX5CUT1auZY9FVK3KS2AUVxia
 vilpUZrjEzuSa1EKWcflpmR/RuZ37a3fhc+cDoHrnCDp5FxOkdGp035Tx0/mgIDv
 I7TrUJzt+jawdVo7fMbsDcSmd12Dmsl16knVN4WXSfD1JUiTZNAIEnEH4fF5fsIF
 nvASedA9rsRRvMYEqqFIAPFJxdmfm3mWBKpOVhQyyAT3/T+vR1+rr6pGmThjHL09
 DZUCiPpdFqZZ8fhNZQxjQvbIkZFHLCrl1zNENlEPtvOXGZfNTdcag2mA87n4JVfp
 gCf1TuEvQ/aCMSL5V7aS3exXeaq1Xe+1P4+JOhY/Rv1SbI1JopChvO8z3ElHsKzN
 x+0UBYDjXSeD5LS0lCBytKo3IZLJAxabSLK4eMLdVr60kNi3c3cgtlUjNx+LTRVu
 tr7nWWLY
 =QQ/a
 -----END PGP SIGNATURE-----

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
  ...
This commit is contained in:
Linus Torvalds 2018-04-03 13:35:51 -07:00
commit bb2407a721
62 changed files with 6867 additions and 5419 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

358
COPYING
View File

@ -1,356 +1,18 @@
The Linux Kernel is provided under:
NOTE! This copyright does *not* cover user programs that use kernel
services by normal system calls - this is merely considered normal use
of the kernel, and does *not* fall under the heading of "derived work".
Also note that the GPL below is copyrighted by the Free Software
Foundation, but the instance of code that it refers to (the Linux
kernel) is copyrighted by me and others who actually wrote it.
SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
Also note that the only valid version of the GPL as far as the kernel
is concerned is _this_ particular version of the license (ie v2, not
v2.2 or v3.x or whatever), unless explicitly otherwise stated.
Being under the terms of the GNU General Public License version 2 only,
according with:
Linus Torvalds
LICENSES/preferred/GPL-2.0
----------------------------------------
With an explicit syscall exception, as stated at:
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
LICENSES/exceptions/Linux-syscall-note
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
In addition, other licenses may also apply. Please see:
Preamble
Documentation/process/license-rules.rst
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.
for more details.

818
Documentation/ABI/stable/sysfs-class-infiniband Normal file
View File

@ -0,0 +1,818 @@
sysfs interface common for all infiniband devices
-------------------------------------------------
What: /sys/class/infiniband/<device>/node_type
What: /sys/class/infiniband/<device>/node_guid
What: /sys/class/infiniband/<device>/sys_image_guid
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP,
switch or router)
node_guid: (RO) Node GUID
sys_image_guid: (RO) System image GUID
What: /sys/class/infiniband/<device>/node_desc
Date: Feb, 2006
KernelVersion: v2.6.17
Contact: linux-rdma@vger.kernel.org
Description:
(RW) Update the node description with information such as the
node's hostname, so that IB network management software can tie
its view to the real world.
What: /sys/class/infiniband/<device>/fw_ver
Date: Jun, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Display firmware version
What: /sys/class/infiniband/<device>/ports/<port-num>/lid
What: /sys/class/infiniband/<device>/ports/<port-num>/rate
What: /sys/class/infiniband/<device>/ports/<port-num>/lid_mask_count
What: /sys/class/infiniband/<device>/ports/<port-num>/sm_sl
What: /sys/class/infiniband/<device>/ports/<port-num>/sm_lid
What: /sys/class/infiniband/<device>/ports/<port-num>/state
What: /sys/class/infiniband/<device>/ports/<port-num>/phys_state
What: /sys/class/infiniband/<device>/ports/<port-num>/cap_mask
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
lid: (RO) Port LID
rate: (RO) Port data rate (active width * active
speed)
lid_mask_count: (RO) Port LID mask count
sm_sl: (RO) Subnet manager SL for port's subnet
sm_lid: (RO) Subnet manager LID for port's subnet
state: (RO) Port state (DOWN, INIT, ARMED, ACTIVE or
ACTIVE_DEFER)
phys_state: (RO) Port physical state (Sleep, Polling,
LinkUp, etc)
cap_mask: (RO) Port capability mask. 2 bits here are
settable- IsCommunicationManagementSupported
(set when CM module is loaded) and IsSM (set via
open of issmN file).
What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Link layer type information (Infiniband or Ethernet type)
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/symbol_error
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_remote_physical_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_switch_relay_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_error_recovery
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_constraint_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_contraint_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/local_link_integrity_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/excessive_buffer_overrun_errors
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_data
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_data
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_rcv_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_xmit_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_rcv_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_xmit_packets
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_downed
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_discards
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/VL15_dropped
What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_wait
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
Errors info:
-----------
symbol_error: (RO) Total number of minor link errors detected on
one or more physical lanes.
port_rcv_errors : (RO) Total number of packets containing an
error that were received on the port.
port_rcv_remote_physical_errors : (RO) Total number of packets
marked with the EBP delimiter received on the port.
port_rcv_switch_relay_errors : (RO) Total number of packets
received on the port that were discarded because they could not
be forwarded by the switch relay.
link_error_recovery: (RO) Total number of times the Port
Training state machine has successfully completed the link error
recovery process.
port_xmit_constraint_errors: (RO) Total number of packets not
transmitted from the switch physical port due to outbound raw
filtering or failing outbound partition or IP version check.
port_rcv_constraint_errors: (RO) Total number of packets
received on the switch physical port that are discarded due to
inbound raw filtering or failing inbound partition or IP version
check.
local_link_integrity_errors: (RO) The number of times that the
count of local physical errors exceeded the threshold specified
by LocalPhyErrors
excessive_buffer_overrun_errors: (RO) This counter, indicates an
input buffer overrun. It indicates possible misconfiguration of
a port, either by the Subnet Manager (SM) or by user
intervention. It can also indicate hardware issues or extremely
poor link signal integrity
Data info:
---------
port_xmit_data: (RO) Total number of data octets, divided by 4
(lanes), transmitted on all VLs. This is 64 bit counter
port_rcv_data: (RO) Total number of data octets, divided by 4
(lanes), received on all VLs. This is 64 bit counter.
port_xmit_packets: (RO) Total number of packets transmitted on
all VLs from this port. This may include packets with errors.
This is 64 bit counter.
port_rcv_packets: (RO) Total number of packets (this may include
packets containing Errors. This is 64 bit counter.
link_downed: (RO) Total number of times the Port Training state
machine has failed the link error recovery process and downed
the link.
unicast_rcv_packets: (RO) Total number of unicast packets,
including unicast packets containing errors.
unicast_xmit_packets: (RO) Total number of unicast packets
transmitted on all VLs from the port. This may include unicast
packets with errors.
multicast_rcv_packets: (RO) Total number of multicast packets,
including multicast packets containing errors.
multicast_xmit_packets: (RO) Total number of multicast packets
transmitted on all VLs from the port. This may include multicast
packets with errors.
Misc info:
---------
port_xmit_discards: (RO) Total number of outbound packets
discarded by the port because the port is down or congested.
VL15_dropped: (RO) Number of incoming VL15 packets dropped due
to resource limitations (e.g., lack of buffers) of the port.
port_xmit_wait: (RO) The number of ticks during which the port
had data to transmit but no data was sent during the entire tick
(either because of insufficient credits or because of lack of
arbitration).
Each of these files contains the corresponding value from the
port's Performance Management PortCounters attribute, as
described in the InfiniBand Architecture Specification.
What: /sys/class/infiniband/<device-name>/hw_counters/lifespan
What: /sys/class/infiniband/<device-name>/ports/<port-num>/hw_counters/lifespan
Date: May, 2016
KernelVersion: 4.6
Contact: linux-rdma@vger.kernel.org
Description:
The optional "hw_counters" subdirectory can 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 milliseconds 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.
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 GIDs
or "RoCE v2" for RoCE v2 based GIDs.
What: /sys/class/infiniband_mad/umadN/ibdev
What: /sys/class/infiniband_mad/umadN/port
What: /sys/class/infiniband_mad/issmN/ibdev
What: /sys/class/infiniband_mad/issmN/port
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
Each port of each InfiniBand device has a "umad" device and an
"issm" device attached. For example, a two-port HCA will have
two umad devices and two issm devices, while a switch will have
one device of each type (for switch port 0).
ibdev: (RO) Show Infiniband (IB) device name
port: (RO) Display port number
What: /sys/class/infiniband_mad/abi_version
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Value is incremented if any changes are made that break
userspace ABI compatibility of umad & issm devices.
What: /sys/class/infiniband_cm/ucmN/ibdev
Date: Oct, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Display Infiniband (IB) device name
What: /sys/class/infiniband_cm/abi_version
Date: Oct, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Value is incremented if any changes are made that break
userspace ABI compatibility of ucm devices.
What: /sys/class/infiniband_verbs/uverbsN/ibdev
What: /sys/class/infiniband_verbs/uverbsN/abi_version
Date: Sept, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
ibdev: (RO) Display Infiniband (IB) device name
abi_version: (RO) Show ABI version of IB device specific
interfaces.
What: /sys/class/infiniband_verbs/abi_version
Date: Sep, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
(RO) Value is incremented if any changes are made that break
userspace ABI compatibility of uverbs devices.
sysfs interface for Mellanox IB HCA low-level driver (mthca)
------------------------------------------------------------
What: /sys/class/infiniband/mthcaX/hw_rev
What: /sys/class/infiniband/mthcaX/hca_type
What: /sys/class/infiniband/mthcaX/board_id
Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type: MT23108, MT25208
(MT23108 compat mode), MT25208 or MT25204
board_id: (RO) Manufacturing board ID
sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
--------------------------------------------------
What: /sys/class/infiniband/cxgb3_X/hw_rev
What: /sys/class/infiniband/cxgb3_X/hca_type
What: /sys/class/infiniband/cxgb3_X/board_id
Date: Feb, 2007
KernelVersion: v2.6.21
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) HCA type. Here it is a driver short name.
It should normally match the name in its bus
driver structure (e.g. pci_driver::name).
board_id: (RO) Manufacturing board id
sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
----------------------------------------------------------
What: /sys/class/infiniband/mlx4_X/hw_rev
What: /sys/class/infiniband/mlx4_X/hca_type
What: /sys/class/infiniband/mlx4_X/board_id
Date: Sep, 2007
KernelVersion: v2.6.24
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Manufacturing board ID
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/admin_guids/<n>
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/pkeys/<n>
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/mcgs/
What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/gid_idx/0
What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/pkey_idx/<n>
Date: Aug, 2012
KernelVersion: v3.6.15
Contact: linux-rdma@vger.kernel.org
Description:
The sysfs iov directory is used to manage and examine the port
P_Key and guid paravirtualization. This directory is added only
for the master -- slaves do not have it.
Under iov/ports, the administrator may examine the gid and P_Key
tables as they are present in the device (and as are seen in the
"network view" presented to the SM).
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.
gids/<n>: (RO) The physical port gids n = 0..127
admin_guids/<n>: (RW) Allows examining or changing the
administrative state of a given GUID
n = 0..127
pkeys/<n>: (RO) Displays the contents of the physical
key table n = 0..126
mcgs/: (RO) Muticast group table
<m>/gid_idx/0: (RO) Display the GID mapping m = 1..2
<m>/pkey_idx/<n>: (RW) Writable except for RoCE pkeys.
m = 1..2, n = 0..126
Under the iov/<pci slot number>
directories, the admin may map the index
numbers in the physical tables (as under
iov/ports) to the paravirtualized index
numbers that guests see.
For example, if the administrator, for
port 1 on guest 2 maps physical pkey
index 10 to virtual index 1, then that
guest, whenever it uses its pkey index
1, will actually be using the real pkey
index 10.
What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/enable_smi_admin
Date: May, 2014
KernelVersion: v3.15.7
Contact: linux-rdma@vger.kernel.org
Description:
Enabling QP0 on VFs for selected VF/port. By default, no VFs are
enabled for QP0 operation.
smi_enabled: (RO) Indicates whether smi is currently enabled
for the indicated VF/port
enable_smi_admin:(RW) Used by the admin to request that smi
capability be enabled or disabled for the
indicated VF/port. 0 = disable, 1 = enable.
The requested enablement will occur at the next reset of the VF
(e.g. driver restart on the VM which owns the VF).
sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
---------------------------------------------------------------
What: /sys/class/infiniband/nesX/hw_rev
What: /sys/class/infiniband/nesX/hca_type
What: /sys/class/infiniband/nesX/board_id
Date: Feb, 2008
KernelVersion: v2.6.25
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type (NEX020)
board_id: (RO) Manufacturing board id
sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
-----------------------------------------------------
What: /sys/class/infiniband/cxgb4_X/hw_rev
What: /sys/class/infiniband/cxgb4_X/hca_type
What: /sys/class/infiniband/cxgb4_X/board_id
Date: Apr, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Driver short name. Should normally match
the name in its bus driver structure (e.g.
pci_driver::name)
board_id: (RO) Manufacturing board id. (Vendor + device
information)
sysfs interface for Intel IB driver qib
---------------------------------------
What: /sys/class/infiniband/qibX/version
What: /sys/class/infiniband/qibX/hw_rev
What: /sys/class/infiniband/qibX/hca_type
What: /sys/class/infiniband/qibX/board_id
What: /sys/class/infiniband/qibX/boardversion
What: /sys/class/infiniband/qibX/nctxts
What: /sys/class/infiniband/qibX/localbus_info
What: /sys/class/infiniband/qibX/tempsense
What: /sys/class/infiniband/qibX/serial
What: /sys/class/infiniband/qibX/nfreectxts
What: /sys/class/infiniband/qibX/chip_reset
Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
version: (RO) Display version information of installed software
and drivers.
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Manufacturing board id
boardversion: (RO) Current version of the chip architecture
nctxts: (RO) Return the number of user ports (contexts)
available
localbus_info: (RO) Human readable localbus info
tempsense: (RO) Display temp sense registers in decimal
serial: (RO) Serial number of the HCA
nfreectxts: (RO) The number of free user ports (contexts)
available.
chip_reset: (WO) Reset the chip if possible by writing
"reset" to this file. Only allowed if no user
contexts are open that use chip resources.
What: /sys/class/infiniband/qibX/ports/N/sl2vl/[0-15]
Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
(RO) The directory contains 16 files numbered 0-15 that specify
the Service Level (SL). Listing the SL files returns the Virtual
Lane (VL) as programmed by the SL.
What: /sys/class/infiniband/qibX/ports/N/CCMgtA/cc_settings_bin
What: /sys/class/infiniband/qibX/ports/N/CCMgtA/cc_table_bin
Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control. Both are binary attributes.
cc_table_bin: (RO) Congestion control table size followed by
table entries.
cc_settings_bin:(RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay.
What: /sys/class/infiniband/qibX/ports/N/linkstate/loopback
What: /sys/class/infiniband/qibX/ports/N/linkstate/led_override
What: /sys/class/infiniband/qibX/ports/N/linkstate/hrtbt_enable
What: /sys/class/infiniband/qibX/ports/N/linkstate/status
What: /sys/class/infiniband/qibX/ports/N/linkstate/status_str
Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
loopback: (WO)
led_override: (WO)
hrtbt_enable: (RW)
status: (RO)
status_str: (RO) Displays information about the link state,
possible cable/switch problems, and hardware
errors. Possible states are- "Initted",
"Present", "IB_link_up", "IB_configured" or
"Fatal_Hardware_Error".
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends
What: /sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rdma_seq
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rnr_naks
What: /sys/class/infiniband/qibX/ports/N/diag_counters/other_naks
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_timeouts
What: /sys/class/infiniband/qibX/ports/N/diag_counters/look_pkts
What: /sys/class/infiniband/qibX/ports/N/diag_counters/pkt_drops
What: /sys/class/infiniband/qibX/ports/N/diag_counters/dma_wait
What: /sys/class/infiniband/qibX/ports/N/diag_counters/unaligned
Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
sysfs interface for Mellanox Connect-IB HCA driver mlx5
-------------------------------------------------------
What: /sys/class/infiniband/mlx5_X/hw_rev
What: /sys/class/infiniband/mlx5_X/hca_type
What: /sys/class/infiniband/mlx5_X/reg_pages
What: /sys/class/infiniband/mlx5_X/fw_pages
Date: Jul, 2013
KernelVersion: v3.11
Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
sysfs interface for Cisco VIC (usNIC) Verbs Driver
--------------------------------------------------
What: /sys/class/infiniband/usnic_X/board_id
What: /sys/class/infiniband/usnic_X/config
What: /sys/class/infiniband/usnic_X/qp_per_vf
What: /sys/class/infiniband/usnic_X/max_vf
What: /sys/class/infiniband/usnic_X/cq_per_vf
What: /sys/class/infiniband/usnic_X/iface
Date: Sep, 2013
KernelVersion: v3.14
Contact: Christian Benvenuti <benve@cisco.com>,
Dave Goodell <dgoodell@cisco.com>,
linux-rdma@vger.kernel.org
Description:
board_id: (RO) Manufacturing board id
config: (RO) Report the configuration for this PF
qp_per_vf: (RO) Queue pairs per virtual function.
max_vf: (RO) Max virtual functions
cq_per_vf: (RO) Completion queue per virtual function
iface: (RO) Shows which network interface this usNIC
entry is associated to (visible with ifconfig).
What: /sys/class/infiniband/usnic_X/qpn/summary
What: /sys/class/infiniband/usnic_X/qpn/context
Date: Sep, 2013
KernelVersion: v3.14
Contact: Christian Benvenuti <benve@cisco.com>,
Dave Goodell <dgoodell@cisco.com>,
linux-rdma@vger.kernel.org
Description:
[to be documented]
sysfs interface for Emulex RoCE HCA Driver
------------------------------------------
What: /sys/class/infiniband/ocrdmaX/hw_rev
Date: Feb, 2014
KernelVersion: v3.14
Description:
hw_rev: (RO) Hardware revision number
What: /sys/class/infiniband/ocrdmaX/hca_type
Date: Jun, 2014
KernelVersion: v3.16
Contact: linux-rdma@vger.kernel.org
Description:
hca_type: (RO) Display FW version
sysfs interface for Intel Omni-Path driver (HFI1)
-------------------------------------------------
What: /sys/class/infiniband/hfi1_X/hw_rev
What: /sys/class/infiniband/hfi1_X/board_id
What: /sys/class/infiniband/hfi1_X/nctxts
What: /sys/class/infiniband/hfi1_X/serial
What: /sys/class/infiniband/hfi1_X/chip_reset
What: /sys/class/infiniband/hfi1_X/boardversion
What: /sys/class/infiniband/hfi1_X/nfreectxts
What: /sys/class/infiniband/hfi1_X/tempsense
Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
board_id: (RO) Manufacturing board id
nctxts: (RO) Total contexts available.
serial: (RO) Board serial number
chip_reset: (WO) Write "reset" to this file to reset the
chip if possible. Only allowed if no user
contexts are open that use chip resources.
boardversion: (RO) Human readable board info
nfreectxts: (RO) The number of free user ports (contexts)
available.
tempsense: (RO) Thermal sense information
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_table_bin
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_prescan
Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control.
cc_table_bin: (RO) CCA tables used by PSM2 Congestion control
table size followed by table entries. Binary
attribute.
cc_settings_bin:(RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay. Binary attribute.
cc_prescan: (RW) enable prescanning for faster BECN
response. Write "on" to enable and "off" to
disable.
What: /sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31]
What: /sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31]
What: /sys/class/infiniband/hfi1_X/ports/N/vl2mtu/[0-15]
Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl
sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc
vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl
What: /sys/class/infiniband/hfi1_X/sdma_N/cpu_list
What: /sys/class/infiniband/hfi1_X/sdma_N/vl
Date: Sept, 2016
KernelVersion: v4.8
Contact: linux-rdma@vger.kernel.org
Description:
sdma<N>/ contains one directory per sdma engine (0 - 15)
cpu_list: (RW) List of cpus for user-process to sdma
engine assignment.
vl: (RO) Displays the virtual lane (vl) the sdma
engine maps to.
This interface gives the user control on the affinity settings
for the 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.
sysfs interface for Intel(R) X722 iWARP i40iw driver
----------------------------------------------------
What: /sys/class/infiniband/i40iwX/hw_rev
What: /sys/class/infiniband/i40iwX/hca_type
What: /sys/class/infiniband/i40iwX/board_id
Date: Jan, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Show HCA type (I40IW)
board_id: (RO) I40IW board ID
sysfs interface for QLogic qedr NIC Driver
------------------------------------------
What: /sys/class/infiniband/qedrX/hw_rev
What: /sys/class/infiniband/qedrX/hca_type
Date: Oct, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Display HCA type
sysfs interface for VMware Paravirtual RDMA driver
--------------------------------------------------
What: /sys/class/infiniband/vmw_pvrdmaX/hw_rev
What: /sys/class/infiniband/vmw_pvrdmaX/hca_type
What: /sys/class/infiniband/vmw_pvrdmaX/board_id
Date: Oct, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Display PVRDMA manufacturing board ID
sysfs interface for Broadcom NetXtreme-E RoCE driver
----------------------------------------------------
What: /sys/class/infiniband/bnxt_reX/hw_rev
What: /sys/class/infiniband/bnxt_reX/hca_type
Date: Feb, 2017
KernelVersion: v4.11
Contact: linux-rdma@vger.kernel.org
Description:
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type

45
Documentation/ABI/testing/sysfs-block-aoe Normal file
View File

@ -0,0 +1,45 @@
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.

50
Documentation/ABI/testing/sysfs-block-loop Normal file
View File

@ -0,0 +1,50 @@
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").

233
Documentation/ABI/testing/sysfs-bus-nfit Normal file
View File

@ -0,0 +1,233 @@
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.

198
Documentation/ABI/testing/sysfs-bus-rapidio Normal file
View File

@ -0,0 +1,198 @@
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.

199
Documentation/ABI/testing/sysfs-bus-rbd
View File

@ -1,121 +1,162 @@
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.
$ echo 2 > /sys/bus/rbd/remove
Usage: <dev-id> [force]
$ 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
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.
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
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.
The ceph unique client id that was assigned for this specific session.
major: (RO) The block device major number.
cluster_fsid
client_id: (RO) The ceph unique client id that was assigned
for this specific session.
The ceph cluster UUID. (August 2016, since 4.9.)
pool: (RO) The name of the storage pool where this rbd
image resides. An rbd image name is unique
within its pool.
config_info
name: (RO) The name of the rbd image.
The string written into /sys/bus/rbd/add{,_single_major}. (August
2016, since 4.9.)
refresh: (WO) Writing to this file will reread the image
header data and set all relevant data structures
accordingly.
features
current_snap: (RO) The current snapshot for which the device
is mapped.
A hexadecimal encoding of the feature bits for this image.
major
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.
The block device major number.
minor
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.)
The block device minor number. (December 2013, since 3.14.)
features: (RO) A hexadecimal encoding of the feature bits
for this image.
name
The name of the rbd image.
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.
image_id
The unique id for the rbd image. (For rbd image format 1
this is empty.)
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.
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>/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.
pool_id
config_info: (RO) The string written into
/sys/bus/rbd/add{,_single_major}.
The unique identifier for the rbd image's pool. This is
a permanent attribute of the pool. A pool's id will never
change.
cluster_fsid: (RO) The ceph cluster UUID.
size
The size (in bytes) of the mapped block device.
refresh
Writing to this file will reread the image header data and set
all relevant datastructures accordingly.
current_snap
The current snapshot for which the device is mapped.
snap_id
The current snapshot's id. (August 2016, since 4.9.)
parent
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'.

31
Documentation/ABI/testing/sysfs-class-backlight-adp5520 Normal file
View File

@ -0,0 +1,31 @@
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.

54
Documentation/ABI/testing/sysfs-class-backlight-adp8860 Normal file
View File

@ -0,0 +1,54 @@
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.

11
Documentation/ABI/testing/sysfs-class-backlight-lm3639 Normal file
View File

@ -0,0 +1,11 @@
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).

25
Documentation/ABI/testing/sysfs-class-bsr Normal file
View File

@ -0,0 +1,25 @@
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.

16
Documentation/ABI/testing/sysfs-class-infiniband
View File

@ -1,16 +0,0 @@
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.

27
Documentation/ABI/testing/sysfs-class-lcd-s6e63m0 Normal file
View File

@ -0,0 +1,27 @@
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>/).

109
Documentation/ABI/testing/sysfs-class-pktcdvd
View File

@ -1,60 +1,81 @@
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)
The pktcdvd module (packet writing driver) creates
these files in the sysfs:
(<devid> is in 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:
/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.
add: (WO) 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.
remove: (WO) Write the pktcdvd device id (major:minor)
to remove the pktcdvd device.
device_map (0444) Shows the device mapping in format:
pktcdvd[0-7] <pktdevid> <blkdevid>
device_map: (RO) 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.
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
kb_written (0444) kBytes written.
kb_read (0444) kBytes read.
kb_read_gather (0444) kBytes read to fill write packets.
uevent: (WO) To send a uevent
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.
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.
congestion_off (0644) If bio write queue size is below
this mark, accept new bio requests
from the block layer.
packets_finished: (RO) Number of finished packets.
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.
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.
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:

55
Documentation/ABI/testing/sysfs-class-rapidio Normal file
View File

@ -0,0 +1,55 @@
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

115
Documentation/ABI/testing/sysfs-devices-platform-trackpoint Normal file
View File

@ -0,0 +1,115 @@
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.

7
Documentation/admin-guide/README.rst
View File

@ -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.

10
Documentation/admin-guide/module-signing.rst
View File

@ -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.
========================

24
Documentation/admin-guide/security-bugs.rst
View File

@ -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
------------

18
Documentation/admin-guide/tainted-kernels.rst
View File

@ -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.)

4
Documentation/core-api/printk-formats.rst
View File

@ -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
-------------------------

2
Documentation/dev-tools/sparse.rst
View File

@ -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

563
Documentation/doc-guide/kernel-doc.rst
View File

@ -1,201 +1,59 @@
Including kernel-doc comments
=============================
The Linux kernel source files may contain structured documentation comments, or
kernel-doc comments to describe the functions and types and design of the
code. The documentation comments may be included to any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.
The kernel-doc directive is of the format::
.. kernel-doc:: source
:option:
The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:
export: *[source-pattern ...]*
Include documentation for all functions in *source* that have been exported
using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
of the files specified by *source-pattern*.
The *source-pattern* is useful when the kernel-doc comments have been placed
in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
Examples::
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: *[source-pattern ...]*
Include documentation for all functions and types in *source* that have
**not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
in *source* or in any of the files specified by *source-pattern*.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
doc: *title*
Include documentation for the ``DOC:`` paragraph identified by *title* in
*source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
is only used as an identifier for the paragraph, and is not included in the
output. Please make sure to have an appropriate heading in the enclosing
reStructuredText document.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
functions: *function* *[...]*
Include documentation for each *function* in *source*.
Example::
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
Without options, the kernel-doc directive includes all documentation comments
from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
.. _kernel_doc:
Writing kernel-doc comments
===========================
In order to provide embedded, "C" friendly, easy to maintain, but consistent and
extractable overview, function and type documentation, the Linux kernel has
adopted a consistent style for documentation comments. The format for this
documentation is called the kernel-doc format, described below. This style
embeds the documentation within the source files, using a few simple conventions
for adding documentation paragraphs and documenting functions and their
parameters, structures and unions and their members, enumerations, and typedefs.
The Linux kernel source files may contain structured documentation
comments in the kernel-doc format to describe the functions, types
and design of the code. It is easier to keep documentation up-to-date
when it is embedded in source files.
.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen,
yet distinctively different, for historical reasons. The kernel source
contains tens of thousands of kernel-doc comments. Please stick to the style
described here.
.. note:: The kernel-doc format is deceptively similar to javadoc,
gtk-doc or Doxygen, yet distinctively different, for historical
reasons. The kernel source contains tens of thousands of kernel-doc
comments. Please stick to the style described here.
The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in
the documentation build to extract this embedded documentation into the various
HTML, PDF, and other format documents.
The kernel-doc structure is extracted from the comments, and proper
`Sphinx C Domain`_ function and type descriptions with anchors are
generated from them. The descriptions are filtered for special kernel-doc
highlights and cross-references. See below for details.
In order to provide good documentation of kernel functions and data structures,
please use the following conventions to format your kernel-doc comments in the
Linux kernel source.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
Every function that is exported to loadable modules using
``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
comment. Functions and data structures in header files which are intended
to be used by modules should also have kernel-doc comments.
It is good practice to also provide kernel-doc formatted documentation
for functions externally visible to other kernel files (not marked
``static``). We also recommend providing kernel-doc formatted
documentation for private (file ``static``) routines, for consistency of
kernel source code layout. This is lower priority and at the discretion
of the maintainer of that kernel source file.
How to format kernel-doc comments
---------------------------------
The opening comment mark ``/**`` is reserved for kernel-doc comments. Only
comments so marked will be considered by the ``kernel-doc`` tool. Use it only
for comment blocks that contain kernel-doc formatted comments. The usual ``*/``
should be used as the closing comment marker. The lines in between should be
prefixed by `` * `` (space star space).
The opening comment mark ``/**`` is used for kernel-doc comments. The
``kernel-doc`` tool will extract comments marked this way. The rest of
the comment is formatted like a normal multi-line comment with a column
of asterisks on the left side, closing with ``*/`` on a line by itself.
The function and type kernel-doc comments should be placed just before the
function or type being described. The overview kernel-doc comments may be freely
placed at the top indentation level.
The function and type kernel-doc comments should be placed just before
the function or type being described in order to maximise the chance
that somebody changing the code will also change the documentation. The
overview kernel-doc comments may be placed anywhere at the top indentation
level.
Example kernel-doc function comment::
Running the ``kernel-doc`` tool with increased verbosity and without actual
output generation may be used to verify proper formatting of the
documentation comments. For example::
/**
* foobar() - Brief description of foobar.
* @argument1: Description of parameter argument1 of foobar.
* @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
int foobar(int argument1, char *argument2)
scripts/kernel-doc -v -none drivers/foo/bar.c
The format is similar for documentation for structures, enums, paragraphs,
etc. See the sections below for specific details of each type.
The documentation format is verified by the kernel build when it is
requested to perform extra gcc checks::
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
descriptions are filtered for special kernel-doc highlights and
cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
Parameters and member arguments
-------------------------------
The kernel-doc function comments describe each parameter to the function and
function typedefs or each member of struct/union, in order, with the
``@argument:`` descriptions. For each non-private member argument, one
``@argument`` definition is needed.
The ``@argument:`` descriptions begin on the very next line following
the opening brief function description line, with no intervening blank
comment lines.
The ``@argument:`` descriptions may span multiple lines.
.. note::
If the ``@argument`` description has multiple lines, the continuation
of the description should be starting exactly at the same column as
the previous line, e. g.::
* @argument: some long description
* that continues on next lines
or::
* @argument:
* some long description
* that continues on next lines
If a function or typedef parameter argument is ``...`` (e. g. a variable
number of arguments), its description should be listed in kernel-doc
notation as::
* @...: description
Private members
~~~~~~~~~~~~~~~
Inside a struct or union description, you can use the ``private:`` and
``public:`` comment tags. Structure fields that are inside a ``private:``
area are not listed in the generated output documentation.
The ``private:`` and ``public:`` tags must begin immediately following a
``/*`` comment marker. They may optionally include comments between the
``:`` and the ending ``*/`` marker.
Example::
/**
* struct my_struct - short description
* @a: first member
* @b: second member
* @d: fourth member
*
* Longer description
*/
struct my_struct {
int a;
int b;
/* private: internal use only */
int c;
/* public: the next one is public */
int d;
};
make W=n
Function documentation
----------------------
@ -216,6 +74,9 @@ The general format of a function and function-like macro kernel-doc comment is::
*
* The longer description may have multiple paragraphs.
*
* Context: Describes whether the function can sleep, what locks it takes,
* releases, or expects to be held. It can extend over multiple
* lines.
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and should
@ -226,6 +87,52 @@ The brief description following the function name may span multiple lines, and
ends with an argument description, a blank comment line, or the end of the
comment block.
Function parameters
~~~~~~~~~~~~~~~~~~~
Each function argument should be described in order, immediately following
the short function description. Do not leave a blank line between the
function description and the arguments, nor between the arguments.
Each ``@argument:`` description may span multiple lines.
.. note::
If the ``@argument`` description has multiple lines, the continuation
of the description should start at the same column as the previous line::
* @argument: some long description
* that continues on next lines
or::
* @argument:
* some long description
* that continues on next lines
If a function has a variable number of arguments, its description should
be written in kernel-doc notation as::
* @...: description
Function context
~~~~~~~~~~~~~~~~
The context in which a function can be called should be described in a
section named ``Context``. This should include whether the function
sleeps or can be called from interrupt context, as well as what locks
it takes, releases and expects to be held by its caller.
Examples::
* Context: Any context.
* Context: Any context. Takes and releases the RCU lock.
* Context: Any context. Expects <lock> to be held by caller.
* Context: Process context. May sleep if @gfp flags permit.
* Context: Process context. Takes and releases <mutex>.
* Context: Softirq or process context. Takes and releases <lock>, BH-safe.
* Context: Interrupt context.
Return values
~~~~~~~~~~~~~
@ -255,7 +162,7 @@ named ``Return``.
#) If the descriptive text you provide has lines that begin with
some phrase followed by a colon, each of those phrases will be taken
as a new section heading, with probably won't produce the desired
as a new section heading, which probably won't produce the desired
effect.
Structure, union, and enumeration documentation
@ -265,69 +172,144 @@ The general format of a struct, union, and enum kernel-doc comment is::
/**
* struct struct_name - Brief description.
* @argument: Description of member member_name.
* @member1: Description of member1.
* @member2: Description of member2.
* One can provide multiple line descriptions
* for members.
*
* Description of the structure.
*/
On the above, ``struct`` is used to mean structs. You can also use ``union``
and ``enum`` to describe unions and enums. ``argument`` is used
to mean struct and union member names as well as enumerations in an enum.
You can replace the ``struct`` in the above example with ``union`` or
``enum`` to describe unions or enums. ``member`` is used to mean struct
and union member names as well as enumerations in an enum.
The brief description following the structure name may span multiple lines, and
ends with a member description, a blank comment line, or the end of the
comment block.
The brief description following the structure name may span multiple
lines, and ends with a member description, a blank comment line, or the
end of the comment block.
The kernel-doc data structure comments describe each member of the structure,
in order, with the member descriptions.
Members
~~~~~~~
Members of structs, unions and enums should be documented the same way
as function parameters; they immediately succeed the short description
and may be multi-line.
Inside a struct or union description, you can use the ``private:`` and
``public:`` comment tags. Structure fields that are inside a ``private:``
area are not listed in the generated output documentation.
The ``private:`` and ``public:`` tags must begin immediately following a
``/*`` comment marker. They may optionally include comments between the
``:`` and the ending ``*/`` marker.
Example::
/**
* struct my_struct - short description
* @a: first member
* @b: second member
* @d: fourth member
*
* Longer description
*/
struct my_struct {
int a;
int b;
/* private: internal use only */
int c;
/* public: the next one is public */
int d;
};
Nested structs/unions
~~~~~~~~~~~~~~~~~~~~~
It is possible to document nested structs unions, like::
It is possible to document nested structs and unions, like::
/**
* struct nested_foobar - a struct with nested unions and structs
* @arg1: - first argument of anonymous union/anonymous struct
* @arg2: - second argument of anonymous union/anonymous struct
* @arg3: - third argument of anonymous union/anonymous struct
* @arg4: - fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1 - first argument of struct st1 on union bar
* @bar.st1.arg2 - second argument of struct st1 on union bar
* @bar.st2.arg1 - first argument of struct st2 on union bar
* @bar.st2.arg2 - second argument of struct st2 on union bar
* @memb1: first member of anonymous union/anonymous struct
* @memb2: second member of anonymous union/anonymous struct
* @memb3: third member of anonymous union/anonymous struct
* @memb4: fourth member of anonymous union/anonymous struct
* @bar: non-anonymous union
* @bar.st1: struct st1 inside @bar
* @bar.st2: struct st2 inside @bar
* @bar.st1.memb1: first member of struct st1 on union bar
* @bar.st1.memb2: second member of struct st1 on union bar
* @bar.st2.memb1: first member of struct st2 on union bar
* @bar.st2.memb2: second member of struct st2 on union bar
*/
struct nested_foobar {
/* Anonymous union/struct*/
union {
struct {
int arg1;
int arg2;
}
int memb1;
int memb2;
}
struct {
void *arg3;
int arg4;
}
}
union {
void *memb3;
int memb4;
}
}
union {
struct {
int arg1;
int arg2;
} st1;
int memb1;
int memb2;
} st1;
struct {
void *arg1;
int arg2;
} st2;
} bar;
void *memb1;
int memb2;
} st2;
} bar;
};
.. note::
#) When documenting nested structs or unions, if the struct/union ``foo``
is named, the argument ``bar`` inside it should be documented as
is named, the member ``bar`` inside it should be documented as
``@foo.bar:``
#) When the nested struct/union is anonymous, the argument ``bar`` on it
#) When the nested struct/union is anonymous, the member ``bar`` in it
should be documented as ``@bar:``
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The structure members may also be documented in-line within the definition.
There are two styles, single-line comments where both the opening ``/**`` and
closing ``*/`` are on the same line, and multi-line comments where they are each
on a line of their own, like all other kernel-doc comments::
/**
* struct foo - Brief description.
* @foo: The Foo member.
*/
struct foo {
int foo;
/**
* @bar: The Bar member.
*/
int bar;
/**
* @baz: The Baz member.
*
* Here, the member description may contain several paragraphs.
*/
int baz;
union {
/** @foobar: Single line description. */
int foobar;
};
/** @bar2: Description for struct @bar2 inside @foo */
struct {
/**
* @bar2.barbar: Description for @barbar inside @foo.bar2
*/
int barbar;
} bar2;
};
Typedef documentation
---------------------
@ -347,10 +329,12 @@ Typedefs with function prototypes can also be documented::
* @arg2: description of arg2
*
* Description of the type.
*
* Context: Locking context.
* Return: Meaning of the return value.
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Highlights and cross-references
-------------------------------
@ -422,37 +406,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation.
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The structure members may also be documented in-line within the definition.
There are two styles, single-line comments where both the opening ``/**`` and
closing ``*/`` are on the same line, and multi-line comments where they are each
on a line of their own, like all other kernel-doc comments::
/**
* struct foo - Brief description.
* @foo: The Foo member.
*/
struct foo {
int foo;
/**
* @bar: The Bar member.
*/
int bar;
/**
* @baz: The Baz member.
*
* Here, the member description may contain several paragraphs.
*/
int baz;
/** @foobar: Single line description. */
int foobar;
}
Overview documentation comments
-------------------------------
@ -482,53 +435,81 @@ The title following ``DOC:`` acts as a heading within the source file, but also
as an identifier for extracting the documentation comment. Thus, the title must
be unique within the file.
Recommendations
---------------
Including kernel-doc comments
=============================
We definitely need kernel-doc formatted documentation for functions that are
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``.
The documentation comments may be included in any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.
We also look to provide kernel-doc formatted documentation for functions
externally visible to other kernel files (not marked "static").
The kernel-doc directive is of the format::
We also recommend providing kernel-doc formatted documentation for private (file
"static") routines, for consistency of kernel source code layout. But this is
lower priority and at the discretion of the MAINTAINER of that kernel source
file.
.. kernel-doc:: source
:option:
Data structures visible in kernel include files should also be documented using
kernel-doc formatted comments.
The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:
export: *[source-pattern ...]*
Include documentation for all functions in *source* that have been exported
using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
of the files specified by *source-pattern*.
The *source-pattern* is useful when the kernel-doc comments have been placed
in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
Examples::
.. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
internal: *[source-pattern ...]*
Include documentation for all functions and types in *source* that have
**not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
in *source* or in any of the files specified by *source-pattern*.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
doc: *title*
Include documentation for the ``DOC:`` paragraph identified by *title* in
*source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
is only used as an identifier for the paragraph, and is not included in the
output. Please make sure to have an appropriate heading in the enclosing
reStructuredText document.
Example::
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
functions: *function* *[...]*
Include documentation for each *function* in *source*.
Example::
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
Without options, the kernel-doc directive includes all documentation comments
from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
.. _kernel_doc:
How to use kernel-doc to generate man pages
-------------------------------------------
If you just want to use kernel-doc to generate man pages you can do this
from the Kernel git tree::
from the kernel git tree::
$ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man
Using the small ``split-man.pl`` script below::
#!/usr/bin/perl
if ($#ARGV < 0) {
die "where do I put the results?\n";
}
mkdir $ARGV[0],0777;
$state = 0;
while (<STDIN>) {
if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
if ($state == 1) { close OUT }
$state = 1;
$fn = "$ARGV[0]/$1.9";
print STDERR "Creating $fn\n";
open OUT, ">$fn" or die "can't open $fn: $!\n";
print OUT $_;
} elsif ($state != 0) {
print OUT $_;
}
}
close OUT;
$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man

40
Documentation/driver-api/dmaengine/dmatest.rst
View File

@ -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)

2
Documentation/driver-api/slimbus.rst
View File

@ -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:

2
Documentation/filesystems/xfs.txt
View File

@ -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.

1
Documentation/index.rst
View File

@ -64,6 +64,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
trace/index
maintainer/index
Kernel API documentation

129
Documentation/infiniband/sysfs.txt
View File

@ -1,129 +1,4 @@
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.

7
Documentation/input/devices/alps.rst
View File

@ -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
---------------------------------------

2
Documentation/process/5.Posting.rst
View File

@ -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.

2
Documentation/process/changes.rst
View File

@ -430,7 +430,7 @@ udev
FUSE
----
- <http://sourceforge.net/projects/fuse>
- <https://github.com/libfuse/libfuse/releases>
mcelog
------

9
Documentation/process/coding-style.rst
View File

@ -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
***********

15
Documentation/process/howto.rst
View File

@ -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

1
Documentation/process/kernel-driver-statement.rst
View File

@ -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

18
Documentation/process/license-rules.rst
View File

@ -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.
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.
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::
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

2
Documentation/process/magic-number.rst
View File

@ -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 {

9
Documentation/process/submitting-patches.rst
View File

@ -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:
--------------------------------------------------------------------------

161
Documentation/rapidio/sysfs.txt
View File

@ -1,158 +1,3 @@
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

50
Documentation/trace/events-kmem.txt → Documentation/trace/events-kmem.rst
View File

@ -1,22 +1,26 @@
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

40
Documentation/trace/events-msr.rst Normal file
View File

@ -0,0 +1,40 @@
================
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
at http://www.intel.com/sdm (Volume 3)
Available trace points:
/sys/kernel/debug/tracing/events/msr/
Trace MSR reads:
read_msr
- msr: MSR number
- val: Value written
- failed: 1 if the access failed, otherwise 0
Trace MSR writes:
write_msr
- msr: MSR number
- val: Value written
- failed: 1 if the access failed, otherwise 0
Trace RDPMC in kernel:
rdpmc
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
to add symbolic MSR names.

37
Documentation/trace/events-msr.txt
View File

@ -1,37 +0,0 @@
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
at http://www.intel.com/sdm (Volume 3)
Available trace points:
/sys/kernel/debug/tracing/events/msr/
Trace MSR reads
read_msr
msr: MSR number
val: Value written
failed: 1 if the access failed, otherwise 0
Trace MSR writes
write_msr
msr: MSR number
val: Value written
failed: 1 if the access failed, otherwise 0
Trace RDPMC in kernel
rdpmc
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
to add symbolic MSR names.

45
Documentation/trace/events-nmi.rst Normal file
View File

@ -0,0 +1,45 @@
================
NMI Trace Events
================
These events normally show up here:
/sys/kernel/debug/tracing/events/nmi
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::
INFO: NMI handler took too long to run: 9.207 msecs
and this tracepoint will allow you to drill down and get some
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::
$ grep perf_event_nmi_handler /proc/kallsyms
ffffffff81625600 t perf_event_nmi_handler
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'::
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::
$ 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

43
Documentation/trace/events-nmi.txt
View File

@ -1,43 +0,0 @@
NMI Trace Events
These events normally show up here:
/sys/kernel/debug/tracing/events/nmi
--
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:
INFO: NMI handler took too long to run: 9.207 msecs
and this tracepoint will allow you to drill down and get some
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:
$ grep perf_event_nmi_handler /proc/kallsyms
ffffffff81625600 t perf_event_nmi_handler
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':
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:
$ 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

52
Documentation/trace/events-power.txt → Documentation/trace/events-power.rst
View File

@ -1,13 +1,14 @@
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.

643
Documentation/trace/events.txt → Documentation/trace/events.rst
View File

File diff suppressed because it is too large Load Diff

242
Documentation/trace/ftrace-design.txt → Documentation/trace/ftrace-design.rst
View File

@ -1,6 +1,12 @@
function tracer guts
====================
By Mike Frysinger
======================
Function Tracer Design
======================
:Author: Mike Frysinger
.. caution::
This document is out of date. Some of the description below doesn't
match current implementation now.
Introduction
------------
@ -21,8 +27,8 @@ Prerequisites
-------------
Ftrace relies on these features being implemented:
STACKTRACE_SUPPORT - implement save_stack_trace()
TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
- STACKTRACE_SUPPORT - implement save_stack_trace()
- TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
HAVE_FUNCTION_TRACER
@ -32,9 +38,11 @@ You will need to implement the mcount and the ftrace_stub functions.
The exact mcount symbol name will depend on your toolchain. Some call it
"mcount", "_mcount", or even "__mcount". You can probably figure it out by
running something like:
running something like::
$ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount
call mcount
We'll make the assumption below that the symbol is "mcount" just to keep things
nice and simple in the examples.
@ -56,8 +64,9 @@ size of the mcount call that is embedded in the function).
For example, if the function foo() calls bar(), when the bar() function calls
mcount(), the arguments mcount() will pass to the tracer are:
"frompc" - the address bar() will use to return to foo()
"selfpc" - the address bar() (with mcount() size adjustment)
- "frompc" - the address bar() will use to return to foo()
- "selfpc" - the address bar() (with mcount() size adjustment)
Also keep in mind that this mcount function will be called *a lot*, so
optimizing for the default case of no tracer will help the smooth running of
@ -67,39 +76,41 @@ means the code flow should usually be kept linear (i.e. no branching in the nop
case). This is of course an optimization and not a hard requirement.
Here is some pseudo code that should help (these functions should actually be
implemented in assembly):
implemented in assembly)::
void ftrace_stub(void)
{
return;
}
void ftrace_stub(void)
{
return;
}
void mcount(void)
{
/* save any bare state needed in order to do initial checking */
void mcount(void)
{
/* save any bare state needed in order to do initial checking */
extern void (*ftrace_trace_function)(unsigned long, unsigned long);
if (ftrace_trace_function != ftrace_stub)
goto do_trace;
extern void (*ftrace_trace_function)(unsigned long, unsigned long);
if (ftrace_trace_function != ftrace_stub)
goto do_trace;
/* restore any bare state */
/* restore any bare state */
return;
return;
do_trace:
do_trace:
/* save all state needed by the ABI (see paragraph above) */
/* save all state needed by the ABI (see paragraph above) */
unsigned long frompc = ...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
ftrace_trace_function(frompc, selfpc);
unsigned long frompc = ...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
ftrace_trace_function(frompc, selfpc);
/* restore all state needed by the ABI */
}
/* restore all state needed by the ABI */
}
Don't forget to export mcount for modules !
extern void mcount(void);
EXPORT_SYMBOL(mcount);
::
extern void mcount(void);
EXPORT_SYMBOL(mcount);
HAVE_FUNCTION_GRAPH_TRACER
@ -127,38 +138,40 @@ That function will simply call the common ftrace_return_to_handler function and
that will return the original return address with which you can return to the
original call site.
Here is the updated mcount pseudo code:
void mcount(void)
{
...
if (ftrace_trace_function != ftrace_stub)
goto do_trace;
Here is the updated mcount pseudo code::
+#ifdef CONFIG_FUNCTION_GRAPH_TRACER
+ extern void (*ftrace_graph_return)(...);
+ extern void (*ftrace_graph_entry)(...);
+ if (ftrace_graph_return != ftrace_stub ||
+ ftrace_graph_entry != ftrace_graph_entry_stub)
+ ftrace_graph_caller();
+#endif
void mcount(void)
{
...
if (ftrace_trace_function != ftrace_stub)
goto do_trace;
/* restore any bare state */
...
+#ifdef CONFIG_FUNCTION_GRAPH_TRACER
+ extern void (*ftrace_graph_return)(...);
+ extern void (*ftrace_graph_entry)(...);
+ if (ftrace_graph_return != ftrace_stub ||
+ ftrace_graph_entry != ftrace_graph_entry_stub)
+ ftrace_graph_caller();
+#endif
Here is the pseudo code for the new ftrace_graph_caller assembly function:
#ifdef CONFIG_FUNCTION_GRAPH_TRACER
void ftrace_graph_caller(void)
{
/* save all state needed by the ABI */
/* restore any bare state */
...
unsigned long *frompc = &...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
/* passing frame pointer up is optional -- see below */
prepare_ftrace_return(frompc, selfpc, frame_pointer);
Here is the pseudo code for the new ftrace_graph_caller assembly function::
/* restore all state needed by the ABI */
}
#endif
#ifdef CONFIG_FUNCTION_GRAPH_TRACER
void ftrace_graph_caller(void)
{
/* save all state needed by the ABI */
unsigned long *frompc = &...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
/* passing frame pointer up is optional -- see below */
prepare_ftrace_return(frompc, selfpc, frame_pointer);
/* restore all state needed by the ABI */
}
#endif
For information on how to implement prepare_ftrace_return(), simply look at the
x86 version (the frame pointer passing is optional; see the next section for
@ -171,20 +184,21 @@ that the ABI that applies here is different from what applies to the mcount
code. Since you are returning from a function (after the epilogue), you might
be able to skimp on things saved/restored (usually just registers used to pass
return values).
::
#ifdef CONFIG_FUNCTION_GRAPH_TRACER
void return_to_handler(void)
{
/* save all state needed by the ABI (see paragraph above) */
#ifdef CONFIG_FUNCTION_GRAPH_TRACER
void return_to_handler(void)
{
/* save all state needed by the ABI (see paragraph above) */
void (*original_return_point)(void) = ftrace_return_to_handler();
void (*original_return_point)(void) = ftrace_return_to_handler();
/* restore all state needed by the ABI */
/* restore all state needed by the ABI */
/* this is usually either a return or a jump */
original_return_point();
}
#endif
/* this is usually either a return or a jump */
original_return_point();
}
#endif
HAVE_FUNCTION_GRAPH_FP_TEST
@ -228,20 +242,20 @@ HAVE_SYSCALL_TRACEPOINTS
You need very few things to get the syscalls tracing in an arch.
- Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig).
- Have a NR_syscalls variable in <asm/unistd.h> that provides the number
of syscalls supported by the arch.
- Support the TIF_SYSCALL_TRACEPOINT thread flags.
- Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace
in the ptrace syscalls tracing path.
- If the system call table on this arch is more complicated than a simple array
of addresses of the system calls, implement an arch_syscall_addr to return
the address of a given system call.
- If the symbol names of the system calls do not match the function names on
this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and
implement arch_syscall_match_sym_name with the appropriate logic to return
true if the function name corresponds with the symbol name.
- Tag this arch as HAVE_SYSCALL_TRACEPOINTS.
- Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig).
- Have a NR_syscalls variable in <asm/unistd.h> that provides the number
of syscalls supported by the arch.
- Support the TIF_SYSCALL_TRACEPOINT thread flags.
- Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace
in the ptrace syscalls tracing path.
- If the system call table on this arch is more complicated than a simple array
of addresses of the system calls, implement an arch_syscall_addr to return
the address of a given system call.
- If the symbol names of the system calls do not match the function names on
this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and
implement arch_syscall_match_sym_name with the appropriate logic to return
true if the function name corresponds with the symbol name.
- Tag this arch as HAVE_SYSCALL_TRACEPOINTS.
HAVE_FTRACE_MCOUNT_RECORD
@ -276,22 +290,28 @@ Once those are out of the way, you will need to implement:
First you will need to fill out some arch details in your asm/ftrace.h.
Define MCOUNT_ADDR as the address of your mcount symbol similar to:
Define MCOUNT_ADDR as the address of your mcount symbol similar to::
#define MCOUNT_ADDR ((unsigned long)mcount)
Since no one else will have a decl for that function, you will need to:
Since no one else will have a decl for that function, you will need to::
extern void mcount(void);
You will also need the helper function ftrace_call_adjust(). Most people
will be able to stub it out like so:
will be able to stub it out like so::
static inline unsigned long ftrace_call_adjust(unsigned long addr)
{
return addr;
}
<details to be filled>
Lastly you will need the custom dyn_arch_ftrace structure. If you need
some extra state when runtime patching arbitrary call sites, this is the
place. For now though, create an empty struct:
place. For now though, create an empty struct::
struct dyn_arch_ftrace {
/* No extra data needed */
};
@ -306,28 +326,28 @@ easier to have two separate definitions split up by #ifdefs. Same goes for
the ftrace_stub() as that will now be inlined in ftrace_caller().
Before we get confused anymore, let's check out some pseudo code so you can
implement your own stuff in assembly:
implement your own stuff in assembly::
void mcount(void)
{
return;
}
void mcount(void)
{
return;
}
void ftrace_caller(void)
{
/* save all state needed by the ABI (see paragraph above) */
void ftrace_caller(void)
{
/* save all state needed by the ABI (see paragraph above) */
unsigned long frompc = ...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
unsigned long frompc = ...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
ftrace_call:
ftrace_stub(frompc, selfpc);
ftrace_call:
ftrace_stub(frompc, selfpc);
/* restore all state needed by the ABI */
/* restore all state needed by the ABI */
ftrace_stub:
return;
}
ftrace_stub:
return;
}
This might look a little odd at first, but keep in mind that we will be runtime
patching multiple things. First, only functions that we actually want to trace
@ -341,21 +361,23 @@ order to make it through the next section.
Every arch has an init callback function. If you need to do something early on
to initialize some state, this is the time to do that. Otherwise, this simple
function below should be sufficient for most people:
function below should be sufficient for most people::
int __init ftrace_dyn_arch_init(void)
{
return 0;
}
int __init ftrace_dyn_arch_init(void)
{
return 0;
}
There are two functions that are used to do runtime patching of arbitrary
functions. The first is used to turn the mcount call site into a nop (which
is what helps us retain runtime performance when not tracing). The second is
used to turn the mcount call site into a call to an arbitrary location (but
typically that is ftracer_caller()). See the general function definition in
linux/ftrace.h for the functions:
linux/ftrace.h for the functions::
ftrace_make_nop()
ftrace_make_call()
The rec->ip value is the address of the mcount call site that was collected
by the scripts/recordmcount.pl during build time.
@ -364,7 +386,8 @@ will be modifying the assembly code at the location of the ftrace_call symbol
inside of the ftrace_caller() function. So you should have sufficient padding
at that location to support the new function calls you'll be inserting. Some
people will be using a "call" type instruction while others will be using a
"branch" type instruction. Specifically, the function is:
"branch" type instruction. Specifically, the function is::
ftrace_update_ftrace_func()
@ -373,6 +396,7 @@ HAVE_DYNAMIC_FTRACE + HAVE_FUNCTION_GRAPH_TRACER
The function grapher needs a few tweaks in order to work with dynamic ftrace.
Basically, you will need to:
- update:
- ftrace_caller()
- ftrace_graph_call()
@ -382,7 +406,9 @@ Basically, you will need to:
- ftrace_disable_ftrace_graph_caller()
<details to be filled>
Quick notes:
- add a nop stub after the ftrace_call location named ftrace_graph_call;
stub needs to be large enough to support a call to ftrace_graph_caller()
- update ftrace_graph_caller() to work with being called by the new

23
Documentation/trace/ftrace-uses.rst
View File

@ -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

3332
Documentation/trace/ftrace.rst Normal file
View File

File diff suppressed because it is too large Load Diff

3220
Documentation/trace/ftrace.txt
View File

File diff suppressed because it is too large Load Diff

26
Documentation/trace/hwlat_detector.txt → Documentation/trace/hwlat_detector.rst
View File

@ -1,4 +1,8 @@
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

23
Documentation/trace/index.rst Normal file
View File

@ -0,0 +1,23 @@
==========================
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

43
Documentation/trace/intel_th.txt → Documentation/trace/intel_th.rst
View File

@ -1,3 +1,4 @@
=======================
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

96
Documentation/trace/kprobetrace.txt → Documentation/trace/kprobetrace.rst
View File

@ -1,8 +1,8 @@
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
# 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
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).

86
Documentation/trace/mmiotrace.txt → Documentation/trace/mmiotrace.rst
View File

@ -1,4 +1,6 @@
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

23
Documentation/trace/stm.txt → Documentation/trace/stm.rst
View File

@ -1,3 +1,4 @@
===================
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

41
Documentation/trace/tracepoint-analysis.txt → Documentation/trace/tracepoint-analysis.rst
View File

@ -1,7 +1,7 @@
Notes on Analysing Behaviour Using Events and Tracepoints
Documentation written by Mel Gorman
PCL information heavily based on email from Ingo Molnar
=========================================================
Notes on Analysing Behaviour Using Events and Tracepoints
=========================================================
:Author: Mel Gorman (PCL information heavily based on email from Ingo Molnar)
1. Introduction
===============
@ -27,18 +27,18 @@ assumed that the PCL tool tools/perf has been installed and is in your path.
----------------------
All possible events are visible from /sys/kernel/debug/tracing/events. Simply
calling
calling::
$ find /sys/kernel/debug/tracing/events -type d
will give a fair indication of the number of events available.
2.2 PCL (Performance Counters for Linux)
-------
----------------------------------------
Discovery and enumeration of all counters and events, including tracepoints,
are available with the perf tool. Getting a list of available events is a
simple case of:
simple case of::
$ perf list 2>&1 | grep Tracepoint
ext4:ext4_free_inode [Tracepoint event]
@ -57,7 +57,7 @@ simple case of:
See Documentation/trace/events.txt for a proper description on how events
can be enabled system-wide. A short example of enabling all events related
to page allocation would look something like:
to page allocation would look something like::
$ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done
@ -67,6 +67,7 @@ to page allocation would look something like:
In SystemTap, tracepoints are accessible using the kernel.trace() function
call. The following is an example that reports every 5 seconds what processes
were allocating the pages.
::
global page_allocs
@ -91,6 +92,7 @@ were allocating the pages.
By specifying the -a switch and analysing sleep, the system-wide events
for a duration of time can be examined.
::
$ perf stat -a \
-e kmem:mm_page_alloc -e kmem:mm_page_free \
@ -118,6 +120,7 @@ basis using set_ftrace_pid.
Events can be activated and tracked for the duration of a process on a local
basis using PCL such as follows.
::
$ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \
-e kmem:mm_page_free_batched ./hackbench 10
@ -145,6 +148,7 @@ Any workload can exhibit variances between runs and it can be important
to know what the standard deviation is. By and large, this is left to the
performance analyst to do it by hand. In the event that the discrete event
occurrences are useful to the performance analyst, then perf can be used.
::
$ perf stat --repeat 5 -e kmem:mm_page_alloc -e kmem:mm_page_free
-e kmem:mm_page_free_batched ./hackbench 10
@ -167,6 +171,7 @@ aggregation of discrete events, then a script would need to be developed.
Using --repeat, it is also possible to view how events are fluctuating over
time on a system-wide basis using -a and sleep.
::
$ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \
-e kmem:mm_page_free_batched \
@ -188,9 +193,9 @@ When events are enabled the events that are triggering can be read from
options exist as well. By post-processing the output, further information can
be gathered on-line as appropriate. Examples of post-processing might include
o Reading information from /proc for the PID that triggered the event
o Deriving a higher-level event from a series of lower-level events.
o Calculating latencies between two events
- Reading information from /proc for the PID that triggered the event
- Deriving a higher-level event from a series of lower-level events.
- Calculating latencies between two events
Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example
script that can read trace_pipe from STDIN or a copy of a trace. When used
@ -200,14 +205,14 @@ and twice to exit.
Simplistically, the script just reads STDIN and counts up events but it
also can do more such as
o Derive high-level events from many low-level events. If a number of pages
- Derive high-level events from many low-level events. If a number of pages
are freed to the main allocator from the per-CPU lists, it recognises
that as one per-CPU drain even though there is no specific tracepoint
for that event
o It can aggregate based on PID or individual process number
o In the event memory is getting externally fragmented, it reports
- It can aggregate based on PID or individual process number
- In the event memory is getting externally fragmented, it reports
on whether the fragmentation event was severe or moderate.
o When receiving an event about a PID, it can record who the parent was so
- When receiving an event about a PID, it can record who the parent was so
that if large numbers of events are coming from very short-lived
processes, the parent process responsible for creating all the helpers
can be identified
@ -218,6 +223,7 @@ also can do more such as
There may also be a requirement to identify what functions within a program
were generating events within the kernel. To begin this sort of analysis, the
data must be recorded. At the time of writing, this required root:
::
$ perf record -c 1 \
-e kmem:mm_page_alloc -e kmem:mm_page_free \
@ -232,6 +238,7 @@ very coarse as a result.
This record outputted a file called perf.data which can be analysed using
perf report.
::
$ perf report
# Samples: 30922
@ -258,6 +265,7 @@ within the VDSO. With simple binaries, this will often be the case so let's
take a slightly different example. In the course of writing this, it was
noticed that X was generating an insane amount of page allocations so let's look
at it:
::
$ perf record -c 1 -f \
-e kmem:mm_page_alloc -e kmem:mm_page_free \
@ -265,6 +273,7 @@ at it:
-p `pidof X`
This was interrupted after a few seconds and
::
$ perf report
# Samples: 27666
@ -282,6 +291,7 @@ This was interrupted after a few seconds and
So, almost half of the events are occurring in a library. To get an idea which
symbol:
::
$ perf report --sort comm,dso,symbol
# Samples: 27666
@ -298,6 +308,7 @@ symbol:
0.00% Xorg [kernel] [k] ftrace_trace_userstack
To see where within the function pixmanFillsse2 things are going wrong:
::
$ perf annotate pixmanFillsse2
[ ... ]

77
Documentation/trace/tracepoints.txt → Documentation/trace/tracepoints.rst
View File

@ -1,6 +1,8 @@
Using the Linux Kernel Tracepoints
==================================
Using the Linux Kernel Tracepoints
==================================
Mathieu Desnoyers
:Author: Mathieu Desnoyers
This document introduces Linux Kernel Tracepoints and their use. It
@ -9,8 +11,8 @@ connect probe functions to them and provides some examples of probe
functions.
* Purpose of tracepoints
Purpose of tracepoints
----------------------
A tracepoint placed in code provides a hook to call a function (probe)
that you can provide at runtime. A tracepoint can be "on" (a probe is
connected to it) or "off" (no probe is attached). When a tracepoint is
@ -31,8 +33,8 @@ header file.
They can be used for tracing and performance accounting.
* Usage
Usage
-----
Two elements are required for tracepoints :
- A tracepoint definition, placed in a header file.
@ -40,52 +42,53 @@ Two elements are required for tracepoints :
In order to use tracepoints, you should include linux/tracepoint.h.
In include/trace/events/subsys.h :
In include/trace/events/subsys.h::
#undef TRACE_SYSTEM
#define TRACE_SYSTEM subsys
#undef TRACE_SYSTEM
#define TRACE_SYSTEM subsys
#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
#define _TRACE_SUBSYS_H
#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
#define _TRACE_SUBSYS_H
#include <linux/tracepoint.h>
#include <linux/tracepoint.h>
DECLARE_TRACE(subsys_eventname,
TP_PROTO(int firstarg, struct task_struct *p),
TP_ARGS(firstarg, p));
DECLARE_TRACE(subsys_eventname,
TP_PROTO(int firstarg, struct task_struct *p),
TP_ARGS(firstarg, p));
#endif /* _TRACE_SUBSYS_H */
#endif /* _TRACE_SUBSYS_H */
/* This part must be outside protection */
#include <trace/define_trace.h>
/* This part must be outside protection */
#include <trace/define_trace.h>
In subsys/file.c (where the tracing statement must be added) :
In subsys/file.c (where the tracing statement must be added)::
#include <trace/events/subsys.h>
#include <trace/events/subsys.h>
#define CREATE_TRACE_POINTS
DEFINE_TRACE(subsys_eventname);
#define CREATE_TRACE_POINTS
DEFINE_TRACE(subsys_eventname);
void somefct(void)
{
...
trace_subsys_eventname(arg, task);
...
}
void somefct(void)
{
...
trace_subsys_eventname(arg, task);
...
}
Where :
- subsys_eventname is an identifier unique to your event
- subsys_eventname is an identifier unique to your event
- subsys is the name of your subsystem.
- eventname is the name of the event to trace.
- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the
function called by this tracepoint.
- `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the
function called by this tracepoint.
- TP_ARGS(firstarg, p) are the parameters names, same as found in the
prototype.
- `TP_ARGS(firstarg, p)` are the parameters names, same as found in the
prototype.
- if you use the header in multiple source files, #define CREATE_TRACE_POINTS
should appear only in one source file.
- if you use the header in multiple source files, `#define CREATE_TRACE_POINTS`
should appear only in one source file.
Connecting a function (probe) to a tracepoint is done by providing a
probe (function to call) for the specific tracepoint through
@ -117,7 +120,7 @@ used to export the defined tracepoints.
If you need to do a bit of work for a tracepoint parameter, and
that work is only used for the tracepoint, that work can be encapsulated
within an if statement with the following:
within an if statement with the following::
if (trace_foo_bar_enabled()) {
int i;
@ -139,7 +142,7 @@ The advantage of using the trace_<tracepoint>_enabled() is that it uses
the static_key of the tracepoint to allow the if statement to be implemented
with jump labels and avoid conditional branches.
Note: The convenience macro TRACE_EVENT provides an alternative way to
.. note:: The convenience macro TRACE_EVENT provides an alternative way to
define tracepoints. Check http://lwn.net/Articles/379903,
http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362
for a series of articles with more details.

44
Documentation/trace/uprobetracer.txt → Documentation/trace/uprobetracer.rst
View File

@ -1,7 +1,8 @@
Uprobe-tracer: Uprobe-based Event Tracing
=========================================
=========================================
Uprobe-tracer: Uprobe-based Event Tracing
=========================================
Documentation written by Srikar Dronamraju
:Author: Srikar Dronamraju
Overview
@ -19,6 +20,8 @@ user to calculate the offset of the probepoint in the object.
Synopsis of uprobe_tracer
-------------------------
::
p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe
r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe)
-:[GRP/]EVENT : Clear uprobe or uretprobe event
@ -57,7 +60,7 @@ x86-64 uses x64).
String type is a special type, which fetches a "null-terminated" string from
user space.
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>
@ -74,28 +77,28 @@ the third is the number of probe miss-hits.
Usage examples
--------------
* Add a probe as a new uprobe event, write a new definition to uprobe_events
as below: (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash)
as below (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash)::
echo 'p /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events
* Add a probe as a new uretprobe event:
* Add a probe as a new uretprobe event::
echo 'r /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events
* Unset registered event:
* Unset registered event::
echo '-:p_bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events
* Print out the events that are registered:
* Print out the events that are registered::
cat /sys/kernel/debug/tracing/uprobe_events
* Clear all events:
* Clear all events::
echo > /sys/kernel/debug/tracing/uprobe_events
Following example shows how to dump the instruction pointer and %ax register
at the probed text address. Probe zfree function in /bin/zsh:
at the probed text address. Probe zfree function in /bin/zsh::
# cd /sys/kernel/debug/tracing/
# cat /proc/`pgrep zsh`/maps | grep /bin/zsh | grep r-xp
@ -103,24 +106,27 @@ at the probed text address. Probe zfree function in /bin/zsh:
# objdump -T /bin/zsh | grep -w zfree
0000000000446420 g DF .text 0000000000000012 Base zfree
0x46420 is the offset of zfree in object /bin/zsh that is loaded at
0x00400000. Hence the command to uprobe would be:
0x46420 is the offset of zfree in object /bin/zsh that is loaded at
0x00400000. Hence the command to uprobe would be::
# echo 'p:zfree_entry /bin/zsh:0x46420 %ip %ax' > uprobe_events
And the same for the uretprobe would be:
And the same for the uretprobe would be::
# echo 'r:zfree_exit /bin/zsh:0x46420 %ip %ax' >> uprobe_events
Please note: User has to explicitly calculate the offset of the probe-point
in the object. We can see the events that are registered by looking at the
uprobe_events file.
.. note:: User has to explicitly calculate the offset of the probe-point
in the object.
We can see the events that are registered by looking at the uprobe_events file.
::
# cat uprobe_events
p:uprobes/zfree_entry /bin/zsh:0x00046420 arg1=%ip arg2=%ax
r:uprobes/zfree_exit /bin/zsh:0x00046420 arg1=%ip arg2=%ax
Format of events can be seen by viewing the file events/uprobes/zfree_entry/format
Format of events can be seen by viewing the file events/uprobes/zfree_entry/format.
::
# cat events/uprobes/zfree_entry/format
name: zfree_entry
@ -139,16 +145,18 @@ Format of events can be seen by viewing the file events/uprobes/zfree_entry/form
print fmt: "(%lx) arg1=%lx arg2=%lx", REC->__probe_ip, REC->arg1, REC->arg2
Right after definition, each event is disabled by default. For tracing these
events, you need to enable it by:
events, you need to enable it by::
# echo 1 > events/uprobes/enable
Lets disable the event after sleeping for some time.
::
# sleep 20
# echo 0 > events/uprobes/enable
And you can see the traced information via /sys/kernel/debug/tracing/trace.
::
# cat trace
# tracer: nop

18
Documentation/vm/00-INDEX
View File

@ -10,6 +10,8 @@ frontswap.txt
- Outline frontswap, part of the transcendent memory frontend.
highmem.txt
- Outline of highmem and common issues.
hmm.txt
- Documentation of heterogeneous memory management
hugetlbpage.txt
- a brief summary of hugetlbpage support in the Linux kernel.
hugetlbfs_reserv.txt
@ -20,25 +22,41 @@ idle_page_tracking.txt
- description of the idle page tracking feature.
ksm.txt
- how to use the Kernel Samepage Merging feature.
mmu_notifier.txt
- a note about clearing pte/pmd and mmu notifications
numa
- information about NUMA specific code in the Linux vm.
numa_memory_policy.txt
- documentation of concepts and APIs of the 2.6 memory policy support.
overcommit-accounting
- description of the Linux kernels overcommit handling modes.
page_frags
- description of page fragments allocator
page_migration
- description of page migration in NUMA systems.
pagemap.txt
- pagemap, from the userspace perspective
page_owner.txt
- tracking about who allocated each page
remap_file_pages.txt
- a note about remap_file_pages() system call
slub.txt
- a short users guide for SLUB.
soft-dirty.txt
- short explanation for soft-dirty PTEs
split_page_table_lock
- Separate per-table lock to improve scalability of the old page_table_lock.
swap_numa.txt
- automatic binding of swap device to numa node
transhuge.txt
- Transparent Hugepage Support, alternative way of using hugepages.
unevictable-lru.txt
- Unevictable LRU infrastructure
userfaultfd.txt
- description of userfaultfd system call
z3fold.txt
- outline of z3fold allocator for storing compressed pages
zsmalloc.txt
- outline of zsmalloc allocator for storing compressed pages
zswap.txt
- Intro to compressed cache for swap pages

11
README
View File

@ -1,13 +1,14 @@
Linux kernel
============
This file was moved to Documentation/admin-guide/README.rst
Please notice that there are several guides for kernel developers and users.
These guides can be rendered in a number of formats, like HTML and PDF.
There are several guides for kernel developers and users. These guides can
be rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.
In order to build the documentation, use ``make htmldocs`` or
``make pdfdocs``.
``make pdfdocs``. The formatted documentation can also be read online at:
https://www.kernel.org/doc/html/latest/
There are various text files in the Documentation/ subdirectory,
several of them using the Restructured Text markup notation.

671
scripts/kernel-doc
View File

@ -1,4 +1,5 @@
#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
use warnings;
use strict;
@ -328,13 +329,15 @@ my $lineprefix="";
use constant {
STATE_NORMAL => 0, # normal code
STATE_NAME => 1, # looking for function name
STATE_FIELD => 2, # scanning field start
STATE_PROTO => 3, # scanning prototype
STATE_DOCBLOCK => 4, # documentation block
STATE_INLINE => 5, # gathering documentation outside main block
STATE_BODY_MAYBE => 2, # body - or maybe more description
STATE_BODY => 3, # the body of the comment
STATE_PROTO => 4, # scanning prototype
STATE_DOCBLOCK => 5, # documentation block
STATE_INLINE => 6, # gathering documentation outside main block
};
my $state;
my $in_doc_sect;
my $leading_space;
# Inline documentation state
use constant {
@ -363,7 +366,7 @@ my $doc_sect = $doc_com .
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
my $doc_inline_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
@ -553,10 +556,9 @@ sub output_highlight {
}
if ($line eq ""){
if (! $output_preformatted) {
print $lineprefix, local_unescape($blankline);
print $lineprefix, $blankline;
}
} else {
$line =~ s/\\\\\\/\&/g;
if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
print "\\&$line";
} else {
@ -747,17 +749,73 @@ sub output_blockhead_rst(%) {
}
}
sub output_highlight_rst {
my $contents = join "\n",@_;
my $line;
# undo the evil effects of xml_escape() earlier
$contents = xml_unescape($contents);
#
# Apply the RST highlights to a sub-block of text.
#
sub highlight_block($) {
# The dohighlight kludge requires the text be called $contents
my $contents = shift;
eval $dohighlight;
die $@ if $@;
return $contents;
}
foreach $line (split "\n", $contents) {
#
# Regexes used only here.
#
my $sphinx_literal = '^[^.].*::$';
my $sphinx_cblock = '^\.\.\ +code-block::';
sub output_highlight_rst {
my $input = join "\n",@_;
my $output = "";
my $line;
my $in_literal = 0;
my $litprefix;
my $block = "";
foreach $line (split "\n",$input) {
#
# If we're in a literal block, see if we should drop out
# of it. Otherwise pass the line straight through unmunged.
#
if ($in_literal) {
if (! ($line =~ /^\s*$/)) {
#
# If this is the first non-blank line in a literal
# block we need to figure out what the proper indent is.
#
if ($litprefix eq "") {
$line =~ /^(\s*)/;
$litprefix = '^' . $1;
$output .= $line . "\n";
} elsif (! ($line =~ /$litprefix/)) {
$in_literal = 0;
} else {
$output .= $line . "\n";
}
} else {
$output .= $line . "\n";
}
}
#
# Not in a literal block (or just dropped out)
#
if (! $in_literal) {
$block .= $line . "\n";
if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($block);
$block = ""
}
}
}
if ($block) {
$output .= highlight_block($block);
}
foreach $line (split "\n", $output) {
print $lineprefix . $line . "\n";
}
}
@ -1062,7 +1120,7 @@ sub dump_struct($$) {
# Handle bitmaps
$arg =~ s/:\s*\d+\s*//g;
# Handle arrays
$arg =~ s/\[\S+\]//g;
$arg =~ s/\[.*\]//g;
# The type may have multiple words,
# and multiple IDs can be defined, like:
# const struct foo, *bar, foobar
@ -1422,8 +1480,6 @@ sub push_parameter($$$$) {
}
}
$param = xml_escape($param);
# strip spaces from $param so that it is one continuous string
# on @parameterlist;
# this fixes a problem where check_sections() cannot find
@ -1522,6 +1578,7 @@ sub dump_function($$) {
$prototype =~ s/__meminit +//;
$prototype =~ s/__must_check +//;
$prototype =~ s/__weak +//;
$prototype =~ s/__sched +//;
my $define = $prototype =~ s/^#\s*define\s+//; #ak added
$prototype =~ s/__attribute__\s*\(\(
(?:
@ -1748,47 +1805,6 @@ sub process_proto_type($$) {
}
}
# xml_escape: replace <, >, and & in the text stream;
#
# however, formatting controls that are generated internally/locally in the
# kernel-doc script are not escaped here; instead, they begin life like
# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
# just before actual output; (this is done by local_unescape())
sub xml_escape($) {
my $text = shift;
if ($output_mode eq "man") {
return $text;
}
$text =~ s/\&/\\\\\\amp;/g;
$text =~ s/\</\\\\\\lt;/g;
$text =~ s/\>/\\\\\\gt;/g;
return $text;
}
# xml_unescape: reverse the effects of xml_escape
sub xml_unescape($) {
my $text = shift;
if ($output_mode eq "man") {
return $text;
}
$text =~ s/\\\\\\amp;/\&/g;
$text =~ s/\\\\\\lt;/</g;
$text =~ s/\\\\\\gt;/>/g;
return $text;
}
# convert local escape strings to html
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
sub local_unescape($) {
my $text = shift;
if ($output_mode eq "man") {
return $text;
}
$text =~ s/\\\\\\\\lt:/</g;
$text =~ s/\\\\\\\\gt:/>/g;
return $text;
}
sub map_filename($) {
my $file;
@ -1826,15 +1842,291 @@ sub process_export_file($) {
close(IN);
}
#
# Parsers for the various processing states.
#
# STATE_NORMAL: looking for the /** to begin everything.
#
sub process_normal() {
if (/$doc_start/o) {
$state = STATE_NAME; # next line is always the function name
$in_doc_sect = 0;
$declaration_start_line = $. + 1;
}
}
#
# STATE_NAME: Looking for the "name - description" line
#
sub process_name($$) {
my $file = shift;
my $identifier;
my $descr;
if (/$doc_block/o) {
$state = STATE_DOCBLOCK;
$contents = "";
$new_start_line = $. + 1;
if ( $1 eq "" ) {
$section = $section_intro;
} else {
$section = $1;
}
}
elsif (/$doc_decl/o) {
$identifier = $1;
if (/\s*([\w\s]+?)(\(\))?\s*-/) {
$identifier = $1;
}
$state = STATE_BODY;
# if there's no @param blocks need to set up default section
# here
$contents = "";
$section = $section_default;
$new_start_line = $. + 1;
if (/-(.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
$descr =~ s/^\s*//;
$descr =~ s/\s*$//;
$descr =~ s/\s+/ /g;
$declaration_purpose = $descr;
$state = STATE_BODY_MAYBE;
} else {
$declaration_purpose = "";
}
if (($declaration_purpose eq "") && $verbose) {
print STDERR "${file}:$.: warning: missing initial short description on line:\n";
print STDERR $_;
++$warnings;
}
if ($identifier =~ m/^struct/) {
$decl_type = 'struct';
} elsif ($identifier =~ m/^union/) {
$decl_type = 'union';
} elsif ($identifier =~ m/^enum/) {
$decl_type = 'enum';
} elsif ($identifier =~ m/^typedef/) {
$decl_type = 'typedef';
} else {
$decl_type = 'function';
}
if ($verbose) {
print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
}
} else {
print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
" - I thought it was a doc line\n";
++$warnings;
$state = STATE_NORMAL;
}
}
#
# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
#
sub process_body($$) {
my $file = shift;
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
# map the supported section names to the canonical names
if ($newsection =~ m/^description$/i) {
$newsection = $section_default;
} elsif ($newsection =~ m/^context$/i) {
$newsection = $section_context;
} elsif ($newsection =~ m/^returns?$/i) {
$newsection = $section_return;
} elsif ($newsection =~ m/^\@return$/) {
# special: @return is a section, not a param description
$newsection = $section_return;
}
if (($contents ne "") && ($contents ne "\n")) {
if (!$in_doc_sect && $verbose) {
print STDERR "${file}:$.: warning: contents before sections\n";
++$warnings;
}
dump_section($file, $section, $contents);
$section = $section_default;
}
$in_doc_sect = 1;
$state = STATE_BODY;
$contents = $newcontents;
$new_start_line = $.;
while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
if ($contents ne "") {
$contents .= "\n";
}
$section = $newsection;
$leading_space = undef;
} elsif (/$doc_end/) {
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
}
# look for doc_com + <text> + doc_end:
if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
print STDERR "${file}:$.: warning: suspicious ending line: $_";
++$warnings;
}
$prototype = "";
$state = STATE_PROTO;
$brcount = 0;
} elsif (/$doc_content/) {
# miguel-style comment kludge, look for blank lines after
# @parameter line to signify start of description
if ($1 eq "") {
if ($section =~ m/^@/ || $section eq $section_context) {
dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
$new_start_line = $.;
} else {
$contents .= "\n";
}
$state = STATE_BODY;
} elsif ($state == STATE_BODY_MAYBE) {
# Continued declaration purpose
chomp($declaration_purpose);
$declaration_purpose .= " " . $1;
$declaration_purpose =~ s/\s+/ /g;
} else {
my $cont = $1;
if ($section =~ m/^@/ || $section eq $section_context) {
if (!defined $leading_space) {
if ($cont =~ m/^(\s+)/) {
$leading_space = $1;
} else {
$leading_space = "";
}
}
$cont =~ s/^$leading_space//;
}
$contents .= $cont . "\n";
}
} else {
# i dont know - bad line? ignore.
print STDERR "${file}:$.: warning: bad line: $_";
++$warnings;
}
}
#
# STATE_PROTO: reading a function/whatever prototype.
#
sub process_proto($$) {
my $file = shift;
if (/$doc_inline_oneline/) {
$section = $1;
$contents = $2;
if ($contents ne "") {
$contents .= "\n";
dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
}
} elsif (/$doc_inline_start/) {
$state = STATE_INLINE;
$inline_doc_state = STATE_INLINE_NAME;
} elsif ($decl_type eq 'function') {
process_proto_function($_, $file);
} else {
process_proto_type($_, $file);
}
}
#
# STATE_DOCBLOCK: within a DOC: block.
#
sub process_docblock($$) {
my $file = shift;
if (/$doc_end/) {
dump_doc_section($file, $section, $contents);
$section = $section_default;
$contents = "";
$function = "";
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
%sections = ();
@sectionlist = ();
$prototype = "";
$state = STATE_NORMAL;
} elsif (/$doc_content/) {
if ( $1 eq "" ) {
$contents .= $blankline;
} else {
$contents .= $1 . "\n";
}
}
}
#
# STATE_INLINE: docbook comments within a prototype.
#
sub process_inline($$) {
my $file = shift;
# First line (state 1) needs to be a @parameter
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
$section = $1;
$contents = $2;
$new_start_line = $.;
if ($contents ne "") {
while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
$contents .= "\n";
}
$inline_doc_state = STATE_INLINE_TEXT;
# Documentation block end */
} elsif (/$doc_inline_end/) {
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
}
$state = STATE_PROTO;
$inline_doc_state = STATE_INLINE_NA;
# Regular text
} elsif (/$doc_content/) {
if ($inline_doc_state == STATE_INLINE_TEXT) {
$contents .= $1 . "\n";
# nuke leading blank lines
if ($contents =~ /^\s*$/) {
$contents = "";
}
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
$inline_doc_state = STATE_INLINE_ERROR;
print STDERR "${file}:$.: warning: ";
print STDERR "Incorrect use of kernel-doc format: $_";
++$warnings;
}
}
}
sub process_file($) {
my $file;
my $identifier;
my $func;
my $descr;
my $in_purpose = 0;
my $initial_section_counter = $section_counter;
my ($orig_file) = @_;
my $leading_space;
$file = map_filename($orig_file);
@ -1853,250 +2145,23 @@ sub process_file($) {
}
# Replace tabs by spaces
while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
# Hand this line to the appropriate state handler
if ($state == STATE_NORMAL) {
if (/$doc_start/o) {
$state = STATE_NAME; # next line is always the function name
$in_doc_sect = 0;
$declaration_start_line = $. + 1;
}
} elsif ($state == STATE_NAME) {# this line is the function name (always)
if (/$doc_block/o) {
$state = STATE_DOCBLOCK;
$contents = "";
$new_start_line = $. + 1;
if ( $1 eq "" ) {
$section = $section_intro;
} else {
$section = $1;
}
}
elsif (/$doc_decl/o) {
$identifier = $1;
if (/\s*([\w\s]+?)\s*-/) {
$identifier = $1;
}
$state = STATE_FIELD;
# if there's no @param blocks need to set up default section
# here
$contents = "";
$section = $section_default;
$new_start_line = $. + 1;
if (/-(.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
$descr =~ s/^\s*//;
$descr =~ s/\s*$//;
$descr =~ s/\s+/ /g;
$declaration_purpose = xml_escape($descr);
$in_purpose = 1;
} else {
$declaration_purpose = "";
}
if (($declaration_purpose eq "") && $verbose) {
print STDERR "${file}:$.: warning: missing initial short description on line:\n";
print STDERR $_;
++$warnings;
}
if ($identifier =~ m/^struct/) {
$decl_type = 'struct';
} elsif ($identifier =~ m/^union/) {
$decl_type = 'union';
} elsif ($identifier =~ m/^enum/) {
$decl_type = 'enum';
} elsif ($identifier =~ m/^typedef/) {
$decl_type = 'typedef';
} else {
$decl_type = 'function';
}
if ($verbose) {
print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
}
} else {
print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
" - I thought it was a doc line\n";
++$warnings;
$state = STATE_NORMAL;
}
} elsif ($state == STATE_FIELD) { # look for head: lines, and include content
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
# map the supported section names to the canonical names
if ($newsection =~ m/^description$/i) {
$newsection = $section_default;
} elsif ($newsection =~ m/^context$/i) {
$newsection = $section_context;
} elsif ($newsection =~ m/^returns?$/i) {
$newsection = $section_return;
} elsif ($newsection =~ m/^\@return$/) {
# special: @return is a section, not a param description
$newsection = $section_return;
}
if (($contents ne "") && ($contents ne "\n")) {
if (!$in_doc_sect && $verbose) {
print STDERR "${file}:$.: warning: contents before sections\n";
++$warnings;
}
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
}
$in_doc_sect = 1;
$in_purpose = 0;
$contents = $newcontents;
$new_start_line = $.;
while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
if ($contents ne "") {
$contents .= "\n";
}
$section = $newsection;
$leading_space = undef;
} elsif (/$doc_end/) {
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
}
# look for doc_com + <text> + doc_end:
if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
print STDERR "${file}:$.: warning: suspicious ending line: $_";
++$warnings;
}
$prototype = "";
$state = STATE_PROTO;
$brcount = 0;
# print STDERR "end of doc comment, looking for prototype\n";
} elsif (/$doc_content/) {
# miguel-style comment kludge, look for blank lines after
# @parameter line to signify start of description
if ($1 eq "") {
if ($section =~ m/^@/ || $section eq $section_context) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
$new_start_line = $.;
} else {
$contents .= "\n";
}
$in_purpose = 0;
} elsif ($in_purpose == 1) {
# Continued declaration purpose
chomp($declaration_purpose);
$declaration_purpose .= " " . xml_escape($1);
$declaration_purpose =~ s/\s+/ /g;
} else {
my $cont = $1;
if ($section =~ m/^@/ || $section eq $section_context) {
if (!defined $leading_space) {
if ($cont =~ m/^(\s+)/) {
$leading_space = $1;
} else {
$leading_space = "";
}
}
$cont =~ s/^$leading_space//;
}
$contents .= $cont . "\n";
}
} else {
# i dont know - bad line? ignore.
print STDERR "${file}:$.: warning: bad line: $_";
++$warnings;
}
process_normal();
} elsif ($state == STATE_NAME) {
process_name($file, $_);
} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
process_body($file, $_);
} elsif ($state == STATE_INLINE) { # scanning for inline parameters
# First line (state 1) needs to be a @parameter
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
$section = $1;
$contents = $2;
$new_start_line = $.;
if ($contents ne "") {
while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
$contents .= "\n";
}
$inline_doc_state = STATE_INLINE_TEXT;
# Documentation block end */
} elsif (/$doc_inline_end/) {
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
}
$state = STATE_PROTO;
$inline_doc_state = STATE_INLINE_NA;
# Regular text
} elsif (/$doc_content/) {
if ($inline_doc_state == STATE_INLINE_TEXT) {
$contents .= $1 . "\n";
# nuke leading blank lines
if ($contents =~ /^\s*$/) {
$contents = "";
}
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
$inline_doc_state = STATE_INLINE_ERROR;
print STDERR "${file}:$.: warning: ";
print STDERR "Incorrect use of kernel-doc format: $_";
++$warnings;
}
}
} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
if (/$doc_inline_oneline/) {
$section = $1;
$contents = $2;
if ($contents ne "") {
$contents .= "\n";
dump_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
}
} elsif (/$doc_inline_start/) {
$state = STATE_INLINE;
$inline_doc_state = STATE_INLINE_NAME;
} elsif ($decl_type eq 'function') {
process_proto_function($_, $file);
} else {
process_proto_type($_, $file);
}
process_inline($file, $_);
} elsif ($state == STATE_PROTO) {
process_proto($file, $_);
} elsif ($state == STATE_DOCBLOCK) {
if (/$doc_end/)
{
dump_doc_section($file, $section, xml_escape($contents));
$section = $section_default;
$contents = "";
$function = "";
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
%sections = ();
@sectionlist = ();
$prototype = "";
$state = STATE_NORMAL;
}
elsif (/$doc_content/)
{
if ( $1 eq "" )
{
$contents .= $blankline;
}
else
{
$contents .= $1 . "\n";
}
}
process_docblock($file, $_);
}
}
# Make sure we got something interesting.
if ($initial_section_counter == $section_counter) {
if ($output_mode ne "none") {
print STDERR "${file}:1: warning: no structured comments found\n";

28
scripts/split-man.pl Executable file
View File

@ -0,0 +1,28 @@
#!/usr/bin/perl
# SPDX-License-Identifier: GPL-2.0
#
# Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
#
# Produce manpages from kernel-doc.
# See Documentation/doc-guide/kernel-doc.rst for instructions
if ($#ARGV < 0) {
die "where do I put the results?\n";
}
mkdir $ARGV[0],0777;
$state = 0;
while (<STDIN>) {
if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
if ($state == 1) { close OUT }
$state = 1;
$fn = "$ARGV[0]/$1.9";
print STDERR "Creating $fn\n";
open OUT, ">$fn" or die "can't open $fn: $!\n";
print OUT $_;
} elsif ($state != 0) {
print OUT $_;
}
}
close OUT;