Skip to content

L
linux
Commit bb2407a7 authored by Linus Torvalds's avatar Linus Torvalds
Browse files
Options

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

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

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

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

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

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

* tag 'docs-4.17' of git://git.lwn.net/linux: (82 commits)
  Documentation/process: update FUSE project website
  docs: kernel-doc: fix parsing of arrays
  dmaengine: Fix spelling for parenthesis in dmatest documentation
  dmaengine: Make dmatest.rst indeed reST compatible
  dmaengine: Add note to dmatest documentation about supported channels
  Documentation: magic-numbers: Fix typo
  Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands
  Input: alps - Update documentation for trackstick v3 format
  Documentation: Mention why %p prints ptrval
  COPYING: use the new text with points to the license files
  COPYING: create a new file with points to the Kernel license files
  Input: trackpoint: document sysfs interface
  xfs: Change URL for the project in xfs.txt
  char/bsr: add sysfs interface documentation
  acpi: nfit: document sysfs interface
  block: rbd: update sysfs interface
  Documentation/sparse: fix typo
  Documentation/CodingStyle: Add an example for braces
  docs/vm: update 00-INDEX
  kernel-doc: Remove __sched markings
  ...
parents e40dc662 86afad7d
Show whitespace changes
Inline Side-by-side
Showing with 6900 additions and 2152 deletions
COPYING
View file @ bb2407a7
The Linux Kernel is provided under:
NOTE! This copyright does *not* cover user programs that use kernel SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
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.
Also note that the only valid version of the GPL as far as the kernel Being under the terms of the GNU General Public License version 2 only,
is concerned is _this_ particular version of the license (ie v2, not according with:
v2.2 or v3.x or whatever), unless explicitly otherwise stated.
Linus Torvalds LICENSES/preferred/GPL-2.0
---------------------------------------- With an explicit syscall exception, as stated at:
GNU GENERAL PUBLIC LICENSE LICENSES/exceptions/Linux-syscall-note
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc. In addition, other licenses may also apply. Please see:
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.
Preamble Documentation/process/license-rules.rst
The licenses for most software are designed to take away your for more details.
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.
Documentation/ABI/stable/sysfs-class-infiniband 0 → 100644
View file @ bb2407a7
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
Documentation/ABI/testing/sysfs-block-aoe 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-block-loop 0 → 100644
View file @ bb2407a7
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").
Documentation/ABI/testing/sysfs-bus-nfit 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-bus-rapidio 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-bus-rbd
View file @ bb2407a7
What: /sys/bus/rbd/ What: /sys/bus/rbd/add
Date: November 2010 Date: Oct, 2010
Contact: Yehuda Sadeh <yehuda@newdream.net>, KernelVersion: v2.6.37
Sage Weil <sage@newdream.net> Contact: Sage Weil <sage@newdream.net>
Description: 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> The snapshot name can be "-" or omitted to map the image
will be assigned for any registered block device. If snapshot is used, it will read/write. A <dev-id> will be assigned for any registered block
be mapped read-only. device. If snapshot is used, it will be mapped read-only.
What: /sys/bus/rbd/remove
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Sage Weil <sage@newdream.net>
Description:
(WO) Remove rbd block device.
Usage: <dev-id> [force] Usage: <dev-id> [force]
$ echo 2 > /sys/bus/rbd/remove $ echo 2 > /sys/bus/rbd/remove
Optional "force" argument which when passed will wait for running requests and Optional "force" argument which when passed will wait for
then unmap the image. Requests sent to the driver after initiating the removal running requests and then unmap the image. Requests sent to the
will be failed. (August 2016, since 4.9.) driver after initiating the removal will be failed. (August
2016, since 4.9.)
What: /sys/bus/rbd/add_single_major What: /sys/bus/rbd/add_single_major
Date: December 2013 Date: Dec, 2013
KernelVersion: 3.14 KernelVersion: v3.14
Contact: Sage Weil <sage@inktank.com> Contact: Sage Weil <sage@newdream.net>
Description: Available only if rbd module is inserted with single_major Description:
(WO) Available only if rbd module is inserted with single_major
parameter set to true. 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 should be used instead of the latter: any attempts to use
/sys/bus/rbd/add if /sys/bus/rbd/add_single_major is /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
available will fail for backwards compatibility reasons. will fail for backwards compatibility reasons.
What: /sys/bus/rbd/remove_single_major What: /sys/bus/rbd/remove_single_major
Date: December 2013 Date: Dec, 2013
KernelVersion: 3.14 KernelVersion: v3.14
Contact: Sage Weil <sage@inktank.com> Contact: Sage Weil <sage@newdream.net>
Description: Available only if rbd module is inserted with single_major Description:
(WO) Available only if rbd module is inserted with single_major
parameter set to true. 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 should be used instead of the latter: any attempts to use
/sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is /sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
available will fail for backwards compatibility reasons. available will fail for backwards compatibility reasons.
Entries under /sys/bus/rbd/devices/<dev-id>/
--------------------------------------------
client_addr
The ceph unique client entity_addr_t (address + nonce).
The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
'[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.)
client_id
The ceph unique client id that was assigned for this specific session.
cluster_fsid What: /sys/bus/rbd/supported_features
Date: Mar, 2017
The ceph cluster UUID. (August 2016, since 4.9.) KernelVersion: v4.11
Contact: Sage Weil <sage@newdream.net>
config_info Description:
(RO) Displays the features supported by the rbd module so that
The string written into /sys/bus/rbd/add{,_single_major}. (August userspace can generate meaningful error messages and spell out
2016, since 4.9.) unsupported features that need to be disabled.
features
What: /sys/bus/rbd/devices/<dev-id>/size
A hexadecimal encoding of the feature bits for this image. What: /sys/bus/rbd/devices/<dev-id>/major
What: /sys/bus/rbd/devices/<dev-id>/client_id
major What: /sys/bus/rbd/devices/<dev-id>/pool
What: /sys/bus/rbd/devices/<dev-id>/name
The block device major number. What: /sys/bus/rbd/devices/<dev-id>/refresh
What: /sys/bus/rbd/devices/<dev-id>/current_snap
Date: Oct, 2010
KernelVersion: v2.6.37
Contact: Sage Weil <sage@newdream.net>
Description:
size: (RO) The size (in bytes) of the mapped block
device.
minor major: (RO) The block device major number.
The block device minor number. (December 2013, since 3.14.) client_id: (RO) The ceph unique client id that was assigned
for this specific session.
name pool: (RO) The name of the storage pool where this rbd
image resides. An rbd image name is unique
within its pool.
The name of the rbd image. name: (RO) The name of the rbd image.
image_id refresh: (WO) Writing to this file will reread the image
header data and set all relevant data structures
accordingly.
The unique id for the rbd image. (For rbd image format 1 current_snap: (RO) The current snapshot for which the device
this is empty.) is mapped.
pool
The name of the storage pool where this rbd image resides. What: /sys/bus/rbd/devices/<dev-id>/pool_id
An rbd image name is unique within its pool. Date: Jul, 2012
KernelVersion: v3.6
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) The unique identifier for the rbd image's pool. This is a
permanent attribute of the pool. A pool's id will never change.
pool_id
The unique identifier for the rbd image's pool. This is What: /sys/bus/rbd/devices/<dev-id>/image_id
a permanent attribute of the pool. A pool's id will never What: /sys/bus/rbd/devices/<dev-id>/features
change. Date: Oct, 2012
KernelVersion: v3.7
Contact: Sage Weil <sage@newdream.net>
Description:
image_id: (RO) The unique id for the rbd image. (For rbd
image format 1 this is empty.)
size features: (RO) A hexadecimal encoding of the feature bits
for this image.
The size (in bytes) of the mapped block device.
refresh What: /sys/bus/rbd/devices/<dev-id>/parent
Date: Nov, 2012
KernelVersion: v3.8
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) Information identifying the chain of parent images in a
layered rbd image. Entries are separated by empty lines.
Writing to this file will reread the image header data and set
all relevant datastructures accordingly.
current_snap What: /sys/bus/rbd/devices/<dev-id>/minor
Date: Dec, 2013
KernelVersion: v3.14
Contact: Sage Weil <sage@newdream.net>
Description:
(RO) The block device minor number.
The current snapshot for which the device is mapped.
snap_id What: /sys/bus/rbd/devices/<dev-id>/snap_id
What: /sys/bus/rbd/devices/<dev-id>/config_info
What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid
What: /sys/bus/rbd/devices/<dev-id>/client_addr
Date: Aug, 2016
KernelVersion: v4.9
Contact: Sage Weil <sage@newdream.net>
Description:
snap_id: (RO) The current snapshot's id.
The current snapshot's id. (August 2016, since 4.9.) config_info: (RO) The string written into
/sys/bus/rbd/add{,_single_major}.
parent cluster_fsid: (RO) The ceph cluster UUID.
Information identifying the chain of parent images in a layered rbd client_addr: (RO) The ceph unique client
image. Entries are separated by empty lines. 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'.
Documentation/ABI/testing/sysfs-class-backlight-adp5520 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-class-backlight-adp8860 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-class-backlight-lm3639 0 → 100644
View file @ bb2407a7
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).
Documentation/ABI/testing/sysfs-class-bsr 0 → 100644
View file @ bb2407a7
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.
Documentation/ABI/testing/sysfs-class-infiniband deleted 100644 → 0
View file @ e40dc662
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.
Documentation/ABI/testing/sysfs-class-lcd-s6e63m0 0 → 100644
View file @ bb2407a7
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>/).
Documentation/ABI/testing/sysfs-class-pktcdvd
View file @ bb2407a7
What: /sys/class/pktcdvd/ sysfs interface
---------------
The pktcdvd module (packet writing driver) creates the following files in the
sysfs: (<devid> is in the format major:minor)
What: /sys/class/pktcdvd/add
What: /sys/class/pktcdvd/remove
What: /sys/class/pktcdvd/device_map
Date: Oct. 2006 Date: Oct. 2006
KernelVersion: 2.6.20 KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de> Contact: Thomas Maier <balagi@justmail.de>
Description: Description:
sysfs interface add: (WO) Write a block device id (major:minor) to
--------------- create a new pktcdvd device and map it to the
block device.
The pktcdvd module (packet writing driver) creates remove: (WO) Write the pktcdvd device id (major:minor)
these files in the sysfs: to remove the pktcdvd device.
(<devid> is in format major:minor )
/sys/class/pktcdvd/ device_map: (RO) Shows the device mapping in format:
add (0200) Write a block device id (major:minor) pktcdvd[0-7] <pktdevid> <blkdevid>
to create a new pktcdvd device and map
it to the block device.
remove (0200) Write the pktcdvd device id (major:minor)
to it to remove the pktcdvd device.
device_map (0444) Shows the device mapping in format: What: /sys/class/pktcdvd/pktcdvd[0-7]/dev
pktcdvd[0-7] <pktdevid> <blkdevid> What: /sys/class/pktcdvd/pktcdvd[0-7]/uevent
Date: Oct. 2006
KernelVersion: 2.6.20
Contact: Thomas Maier <balagi@justmail.de>
Description:
dev: (RO) Device id
uevent: (WO) To send a uevent
/sys/class/pktcdvd/pktcdvd[0-7]/ What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_started
dev (0444) Device id What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_finished
uevent (0200) To send an uevent. 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.
/sys/class/pktcdvd/pktcdvd[0-7]/stat/ packets_finished: (RO) Number of finished packets.
packets_started (0444) Number of started packets.
packets_finished (0444) Number of finished packets.
kb_written (0444) kBytes written. kb_written: (RO) kBytes written.
kb_read (0444) kBytes read.
kb_read_gather (0444) kBytes read to fill write packets.
reset (0200) Write any value to it to reset 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 pktcdvd device statistic values, like
bytes read/written. bytes read/written.
/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/
size (0444) Contains the size of the bio write What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/size
queue. What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_off
What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_on
congestion_off (0644) If bio write queue size is below Date: Oct. 2006
this mark, accept new bio requests KernelVersion: 2.6.20
from the block layer. Contact: Thomas Maier <balagi@justmail.de>
Description:
congestion_on (0644) If bio write queue size is higher size: (RO) Contains the size of the bio write queue.
as this mark, do no longer accept
bio write requests from the block congestion_off: (RW) If bio write queue size is below this mark,
layer and wait till the pktcdvd accept new bio requests from the block layer.
device has processed enough bio's
so that bio write queue size is congestion_on: (RW) If bio write queue size is higher as this
below congestion off mark. mark, do no longer accept bio write requests
A value of <= 0 disables congestion from the block layer and wait till the pktcdvd
control. 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: Example:
......
Documentation/ABI/testing/sysfs-class-rapidio 0 → 100644
View file @ bb2407a7
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
Documentation/ABI/testing/sysfs-devices-platform-trackpoint 0 → 100644
View file @ bb2407a7
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.
Documentation/admin-guide/README.rst
View file @ bb2407a7
...@@ -218,6 +218,13 @@ Configuring the kernel ...@@ -218,6 +218,13 @@ Configuring the kernel
"make localyesconfig" Similar to localmodconfig, except it will convert "make localyesconfig" Similar to localmodconfig, except it will convert
all module options to built in (=y) options. 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 You can find more information on using the Linux kernel config tools
in Documentation/kbuild/kconfig.txt. in Documentation/kbuild/kconfig.txt.
......
Documentation/admin-guide/module-signing.rst
View file @ bb2407a7
...@@ -180,11 +180,11 @@ Public keys in the kernel ...@@ -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 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 [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 [] 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). ...@@ -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:: 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.:: e.g.::
keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
Note, however, that the kernel will only permit keys to be added to 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 ``.builtin_trusted_keys`` **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. that is already resident in the ``.builtin_trusted_keys`` at the time the key was added.
======================== ========================
......
Documentation/admin-guide/security-bugs.rst
View file @ bb2407a7
...@@ -29,18 +29,20 @@ made public. ...@@ -29,18 +29,20 @@ made public.
Disclosure Disclosure
---------- ----------
The goal of the Linux kernel security team is to work with the The goal of the Linux kernel security team is to work with the bug
bug submitter to bug resolution as well as disclosure. We prefer submitter to understand and fix the bug. We prefer to publish the fix as
to fully disclose the bug as soon as possible. It is reasonable to soon as possible, but try to avoid public discussion of the bug itself
delay disclosure when the bug or the fix is not yet fully understood, and leave that to others.
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. Publishing the fix may be delayed when the bug or the fix is not yet
A disclosure date is negotiated by the security team working with the fully understood, the solution is not well-tested or for vendor
bug submitter as well as vendors. However, the kernel security team coordination. However, we expect these delays to be short, measurable in
holds the final say when setting a disclosure date. The timeframe for days, not weeks or months. A release date is negotiated by the security
disclosure is from immediate (esp. if it's already publicly known) 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 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 Coordination
------------ ------------
......
Documentation/admin-guide/tainted-kernels.rst
View file @ bb2407a7
...@@ -6,7 +6,7 @@ counter. This indicates that the kernel has been tainted by some ...@@ -6,7 +6,7 @@ counter. This indicates that the kernel has been tainted by some
mechanism. The string is followed by a series of position-sensitive mechanism. The string is followed by a series of position-sensitive
characters, each representing a particular tainted value. 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 any proprietary module has been loaded. Modules without a
MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
insmod as GPL compatible are assumed to be proprietary. insmod as GPL compatible are assumed to be proprietary.
......
Documentation/core-api/printk-formats.rst
View file @ bb2407a7
...@@ -60,8 +60,8 @@ Plain Pointers ...@@ -60,8 +60,8 @@ Plain Pointers
Pointers printed without a specifier extension (i.e unadorned %p) are Pointers printed without a specifier extension (i.e unadorned %p) are
hashed to prevent leaking information about the kernel memory layout. This hashed to prevent leaking information about the kernel memory layout. This
has the added benefit of providing a unique identifier. On 64-bit machines 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 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
below. gathers enough entropy. If you *really* want the address see %px below.
Symbols/Function Pointers Symbols/Function Pointers
------------------------- -------------------------
......
Documentation/dev-tools/sparse.rst
View file @ bb2407a7
...@@ -67,7 +67,7 @@ __releases - The specified lock is held on function entry, but not exit. ...@@ -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 If the function enters and exits without the lock held, acquiring and
releasing the lock inside the function in a balanced way, no 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. sparse would otherwise report a context imbalance.
Getting sparse Getting sparse
......
Documentation/doc-guide/kernel-doc.rst
View file @ bb2407a7
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 Writing kernel-doc comments
=========================== ===========================
In order to provide embedded, "C" friendly, easy to maintain, but consistent and The Linux kernel source files may contain structured documentation
extractable overview, function and type documentation, the Linux kernel has comments in the kernel-doc format to describe the functions, types
adopted a consistent style for documentation comments. The format for this and design of the code. It is easier to keep documentation up-to-date
documentation is called the kernel-doc format, described below. This style when it is embedded in source files.
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.
.. 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.
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.
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.
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 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.
Example kernel-doc function comment::
/** .. note:: The kernel-doc format is deceptively similar to javadoc,
* foobar() - Brief description of foobar. gtk-doc or Doxygen, yet distinctively different, for historical
* @argument1: Description of parameter argument1 of foobar. reasons. The kernel source contains tens of thousands of kernel-doc
* @argument2: Description of parameter argument2 of foobar. comments. Please stick to the style described here.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
int foobar(int argument1, char *argument2)
The format is similar for documentation for structures, enums, paragraphs,
etc. See the sections below for specific details of each type.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C The kernel-doc structure is extracted from the comments, and proper
Domain`_ function and type descriptions with anchors are generated for them. The `Sphinx C Domain`_ function and type descriptions with anchors are
descriptions are filtered for special kernel-doc highlights and generated from them. The descriptions are filtered for special kernel-doc
cross-references. See below for details. highlights and cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html .. _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.
Parameters and member arguments 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
The kernel-doc function comments describe each parameter to the function and documentation for private (file ``static``) routines, for consistency of
function typedefs or each member of struct/union, in order, with the kernel source code layout. This is lower priority and at the discretion
``@argument:`` descriptions. For each non-private member argument, one of the maintainer of that kernel source file.
``@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: How to format kernel-doc comments
* some long description ---------------------------------
* that continues on next lines
If a function or typedef parameter argument is ``...`` (e. g. a variable The opening comment mark ``/**`` is used for kernel-doc comments. The
number of arguments), its description should be listed in kernel-doc ``kernel-doc`` tool will extract comments marked this way. The rest of
notation as:: 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.
* @...: description 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.
Private members 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::
Inside a struct or union description, you can use the ``private:`` and scripts/kernel-doc -v -none drivers/foo/bar.c
``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 The documentation format is verified by the kernel build when it is
``/*`` comment marker. They may optionally include comments between the requested to perform extra gcc checks::
``:`` and the ending ``*/`` marker.
Example:: make W=n
/**
* 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;
};
Function documentation Function documentation
---------------------- ----------------------
...@@ -216,6 +74,9 @@ The general format of a function and function-like macro kernel-doc comment is:: ...@@ -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. * 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. * Return: Describe the return value of foobar.
* *
* The return value description can also have multiple paragraphs, and should * 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 ...@@ -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 ends with an argument description, a blank comment line, or the end of the
comment block. 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 Return values
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
...@@ -255,7 +162,7 @@ named ``Return``. ...@@ -255,7 +162,7 @@ named ``Return``.
#) If the descriptive text you provide has lines that begin with #) If the descriptive text you provide has lines that begin with
some phrase followed by a colon, each of those phrases will be taken 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. effect.
Structure, union, and enumeration documentation Structure, union, and enumeration documentation
...@@ -265,57 +172,95 @@ The general format of a struct, union, and enum kernel-doc comment is:: ...@@ -265,57 +172,95 @@ The general format of a struct, union, and enum kernel-doc comment is::
/** /**
* struct struct_name - Brief description. * 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. * Description of the structure.
*/ */
On the above, ``struct`` is used to mean structs. You can also use ``union`` You can replace the ``struct`` in the above example with ``union`` or
and ``enum`` to describe unions and enums. ``argument`` is used ``enum`` to describe unions or enums. ``member`` is used to mean struct
to mean struct and union member names as well as enumerations in an enum. and union member names as well as enumerations in an enum.
The brief description following the structure name may span multiple lines, and The brief description following the structure name may span multiple
ends with a member description, a blank comment line, or the end of the lines, and ends with a member description, a blank comment line, or the
comment block. end of the comment block.
The kernel-doc data structure comments describe each member of the structure, Members
in order, with the member descriptions. ~~~~~~~
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 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 * struct nested_foobar - a struct with nested unions and structs
* @arg1: - first argument of anonymous union/anonymous struct * @memb1: first member of anonymous union/anonymous struct
* @arg2: - second argument of anonymous union/anonymous struct * @memb2: second member of anonymous union/anonymous struct
* @arg3: - third argument of anonymous union/anonymous struct * @memb3: third member of anonymous union/anonymous struct
* @arg4: - fourth argument of anonymous union/anonymous struct * @memb4: fourth member of anonymous union/anonymous struct
* @bar.st1.arg1 - first argument of struct st1 on union bar * @bar: non-anonymous union
* @bar.st1.arg2 - second argument of struct st1 on union bar * @bar.st1: struct st1 inside @bar
* @bar.st2.arg1 - first argument of struct st2 on union bar * @bar.st2: struct st2 inside @bar
* @bar.st2.arg2 - second argument of struct st2 on union 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 { struct nested_foobar {
/* Anonymous union/struct*/ /* Anonymous union/struct*/
union { union {
struct { struct {
int arg1; int memb1;
int arg2; int memb2;
} }
struct { struct {
void *arg3; void *memb3;
int arg4; int memb4;
} }
} }
union { union {
struct { struct {
int arg1; int memb1;
int arg2; int memb2;
} st1; } st1;
struct { struct {
void *arg1; void *memb1;
int arg2; int memb2;
} st2; } st2;
} bar; } bar;
}; };
...@@ -323,11 +268,48 @@ It is possible to document nested structs unions, like:: ...@@ -323,11 +268,48 @@ It is possible to document nested structs unions, like::
.. note:: .. note::
#) When documenting nested structs or unions, if the struct/union ``foo`` #) 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:`` ``@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:`` 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 Typedef documentation
--------------------- ---------------------
...@@ -347,10 +329,12 @@ Typedefs with function prototypes can also be documented:: ...@@ -347,10 +329,12 @@ Typedefs with function prototypes can also be documented::
* @arg2: description of arg2 * @arg2: description of arg2
* *
* Description of the type. * Description of the type.
*
* Context: Locking context.
* Return: Meaning of the return value.
*/ */
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Highlights and cross-references Highlights and cross-references
------------------------------- -------------------------------
...@@ -422,37 +406,6 @@ cross-references. ...@@ -422,37 +406,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation. 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 Overview documentation comments
------------------------------- -------------------------------
...@@ -482,53 +435,81 @@ The title following ``DOC:`` acts as a heading within the source file, but also ...@@ -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 as an identifier for extracting the documentation comment. Thus, the title must
be unique within the file. be unique within the file.
Recommendations Including kernel-doc comments
--------------- =============================
We definitely need kernel-doc formatted documentation for functions that are The documentation comments may be included in any of the reStructuredText
exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. documents using a dedicated kernel-doc Sphinx directive extension.
We also look to provide kernel-doc formatted documentation for functions The kernel-doc directive is of the format::
externally visible to other kernel files (not marked "static").
We also recommend providing kernel-doc formatted documentation for private (file .. kernel-doc:: source
"static") routines, for consistency of kernel source code layout. But this is :option:
lower priority and at the discretion of the MAINTAINER of that kernel source
file.
Data structures visible in kernel include files should also be documented using The *source* is the path to a source file, relative to the kernel source
kernel-doc formatted comments. tree. The following directive options are supported:
How to use kernel-doc to generate man pages 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*.
If you just want to use kernel-doc to generate man pages you can do this The *source-pattern* is useful when the kernel-doc comments have been placed
from the Kernel git tree:: in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
the function definitions.
$ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man Examples::
Using the small ``split-man.pl`` script below:: .. kernel-doc:: lib/bitmap.c
:export:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
#!/usr/bin/perl 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*.
if ($#ARGV < 0) { Example::
die "where do I put the results?\n";
}
mkdir $ARGV[0],0777; .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
$state = 0; :internal:
while (<STDIN>) {
if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { doc: *title*
if ($state == 1) { close OUT } Include documentation for the ``DOC:`` paragraph identified by *title* in
$state = 1; *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
$fn = "$ARGV[0]/$1.9"; is only used as an identifier for the paragraph, and is not included in the
print STDERR "Creating $fn\n"; output. Please make sure to have an appropriate heading in the enclosing
open OUT, ">$fn" or die "can't open $fn: $!\n"; reStructuredText document.
print OUT $_;
} elsif ($state != 0) { Example::
print OUT $_;
} .. 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::
close OUT; $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
Documentation/driver-api/dmaengine/dmatest.rst
View file @ bb2407a7
...@@ -6,10 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com> ...@@ -6,10 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com>
This small document introduces how to test DMA drivers using dmatest module. 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 Part 1 - How to build the test module
===================================== =====================================
The menuconfig contains an option that could be found by following path: The menuconfig contains an option that could be found by following path:
Device Drivers -> DMA Engine support -> DMA Test client Device Drivers -> DMA Engine support -> DMA Test client
In the configuration file the option called CONFIG_DMATEST. The dmatest could 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. ...@@ -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 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 % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
...or: :: ...or::
% modprobe dmatest % modprobe dmatest
% echo dma0chan0 > /sys/module/dmatest/parameters/channel % echo dma0chan0 > /sys/module/dmatest/parameters/channel
...@@ -30,14 +36,12 @@ Example of usage: :: ...@@ -30,14 +36,12 @@ Example of usage: ::
% echo 1 > /sys/module/dmatest/parameters/iterations % echo 1 > /sys/module/dmatest/parameters/iterations
% echo 1 > /sys/module/dmatest/parameters/run % 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 dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
..hint:: available channel list could be extracted by running the following .. hint::
command: available channel list could be extracted by running the following command::
::
% ls -1 /sys/class/dma/ % ls -1 /sys/class/dma/
...@@ -59,12 +63,12 @@ before returning. For example, the following scripts wait for 42 tests ...@@ -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 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
waiting is disabled. waiting is disabled.
Example: :: Example::
% modprobe dmatest run=1 iterations=42 wait=1 % modprobe dmatest run=1 iterations=42 wait=1
% modprobe -r dmatest % modprobe -r dmatest
...or: :: ...or::
% modprobe dmatest run=1 iterations=42 % modprobe dmatest run=1 iterations=42
% cat /sys/module/dmatest/parameters/wait % cat /sys/module/dmatest/parameters/wait
...@@ -76,7 +80,7 @@ Part 3 - When built-in in the kernel ...@@ -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 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 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 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 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 :: 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 :: ...@@ -86,22 +90,22 @@ case. You always could check them at run-time by running ::
Part 4 - Gathering the test results 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>)" "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 % dmesg | tail -n 1
dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0) 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 message format is unified across the different types of errors. A
the parens represents additional information, e.g. error code, error counter, number in the parentheses represents additional information, e.g. error
or status. A test thread also emits a summary line at completion listing the code, error counter, or status. A test thread also emits a summary line at
number of tests executed, number that failed, and a result code. completion listing the number of tests executed, number that failed, and a
result code.
Example: :: Example::
% dmesg | tail -n 1 % dmesg | tail -n 1
dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0) dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
......
Documentation/driver-api/slimbus.rst
View file @ bb2407a7
...@@ -90,7 +90,7 @@ controller resets the bus. This notification allows the driver to take necessary ...@@ -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. steps to boot the device so that it's functional after the bus has been reset.
Driver and Controller APIs: Driver and Controller APIs:
-------------------------- ---------------------------
.. kernel-doc:: include/linux/slimbus.h .. kernel-doc:: include/linux/slimbus.h
:internal: :internal:
......
Documentation/filesystems/xfs.txt
View file @ bb2407a7
...@@ -9,7 +9,7 @@ variable block sizes, is extent based, and makes extensive use of ...@@ -9,7 +9,7 @@ variable block sizes, is extent based, and makes extensive use of
Btrees (directories, extents, free space) to aid both performance Btrees (directories, extents, free space) to aid both performance
and scalability. 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 for further details. This implementation is on-disk compatible
with the IRIX version of XFS. with the IRIX version of XFS.
......
Documentation/index.rst
View file @ bb2407a7
...@@ -64,6 +64,7 @@ merged much easier. ...@@ -64,6 +64,7 @@ merged much easier.
dev-tools/index dev-tools/index
doc-guide/index doc-guide/index
kernel-hacking/index kernel-hacking/index
trace/index
maintainer/index maintainer/index
Kernel API documentation Kernel API documentation
......
Documentation/infiniband/sysfs.txt
View file @ bb2407a7
SYSFS FILES SYSFS FILES
For each InfiniBand device, the InfiniBand drivers create the The sysfs interface has moved to
following files under /sys/class/infiniband/<device name>: Documentation/ABI/stable/sysfs-class-infiniband.
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
Documentation/input/devices/alps.rst
View file @ bb2407a7
...@@ -192,10 +192,13 @@ The final v3 packet type is the trackstick packet:: ...@@ -192,10 +192,13 @@ The final v3 packet type is the trackstick packet::
byte 0: 1 1 x7 y7 1 1 1 1 byte 0: 1 1 x7 y7 1 1 1 1
byte 1: 0 x6 x5 x4 x3 x2 x1 x0 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
byte 2: 0 y6 y5 y4 y3 y2 y1 y0 byte 2: 0 y6 y5 y4 y3 y2 y1 y0
byte 3: 0 1 0 0 1 0 0 0 byte 3: 0 1 TP SW 1 M R L
byte 4: 0 z4 z3 z2 z1 z0 ? ? byte 4: 0 z6 z5 z4 z3 z2 z1 z0
byte 5: 0 0 1 1 1 1 1 1 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 ALPS Absolute Mode - Protocol Version 4
--------------------------------------- ---------------------------------------
......
Documentation/process/5.Posting.rst
View file @ bb2407a7
...@@ -213,7 +213,7 @@ The tags in common use are: ...@@ -213,7 +213,7 @@ The tags in common use are:
which can be found in Documentation/process/submitting-patches.rst. Code without a which can be found in Documentation/process/submitting-patches.rst. Code without a
proper signoff cannot be merged into the mainline. 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 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 people work on a single patch. Note, this person also needs to have a
Signed-off-by: line in the patch as well. Signed-off-by: line in the patch as well.
......
Documentation/process/changes.rst
View file @ bb2407a7
...@@ -430,7 +430,7 @@ udev ...@@ -430,7 +430,7 @@ udev
FUSE FUSE
---- ----
- <http://sourceforge.net/projects/fuse> - <https://github.com/libfuse/libfuse/releases>
mcelog mcelog
------ ------
......
Documentation/process/coding-style.rst
View file @ bb2407a7
...@@ -200,6 +200,15 @@ statement; in the latter case use braces in both branches: ...@@ -200,6 +200,15 @@ statement; in the latter case use braces in both branches:
otherwise(); 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 3.1) Spaces
*********** ***********
......
Documentation/process/howto.rst
View file @ bb2407a7
...@@ -213,13 +213,6 @@ will learn the basics of getting your patch into the Linux kernel tree, ...@@ -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 and possibly be pointed in the direction of what to go work on next, if
you do not already have an idea. 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 Before making any actual modifications to the Linux kernel code, it is
imperative to understand how the code in question works. For this imperative to understand how the code in question works. For this
purpose, nothing is better than reading through it directly (most tricky 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 ...@@ -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. 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. 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 Mailing lists
......
Documentation/process/kernel-driver-statement.rst
View file @ bb2407a7
...@@ -103,6 +103,7 @@ today, have in the past, or will in the future. ...@@ -103,6 +103,7 @@ today, have in the past, or will in the future.
- Auke Kok - Auke Kok
- Peter Korsgaard - Peter Korsgaard
- Jiri Kosina - Jiri Kosina
- Aaro Koskinen
- Mariusz Kozlowski - Mariusz Kozlowski
- Greg Kroah-Hartman - Greg Kroah-Hartman
- Michael Krufky - Michael Krufky
......
Documentation/process/license-rules.rst
View file @ bb2407a7
...@@ -4,15 +4,17 @@ Linux kernel licensing rules ...@@ -4,15 +4,17 @@ Linux kernel licensing rules
============================ ============================
The Linux Kernel is provided under the terms of the GNU General Public 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 License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0,
Foundation, and provided in the COPYING file. This documentation file is with an explicit syscall exception described in
not meant to replace the COPYING file, but provides a description of how LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.
each source file should be annotated to make the licensing it is governed
under clear and unambiguous. This documentation file provides a description of how each source file
should be annotated to make its license clear and unambiguous.
The license in the COPYING file applies to the kernel source as a whole, It doesn't replace the Kernel's license.
though individual source files can have a different license which is
required to be compatible with the GPL-2.0:: 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-1.0+ : GNU General Public License v1.0 or later
GPL-2.0+ : GNU General Public License v2.0 or later GPL-2.0+ : GNU General Public License v2.0 or later
......
Documentation/process/magic-number.rst
View file @ bb2407a7
...@@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer. The tty code, ...@@ -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 for example, does this frequently to pass driver-specific and line
discipline-specific structures back and forth. 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:: the structure, like so::
struct tty_ldisc { struct tty_ldisc {
......
Documentation/process/submitting-patches.rst
View file @ bb2407a7
...@@ -510,8 +510,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your ...@@ -510,8 +510,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your
tree. 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 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. 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 ...@@ -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 patch. This tag documents that potentially interested parties
have been included in the discussion. 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: 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
-------------------------------------------------------------------------- --------------------------------------------------------------------------
......
Documentation/rapidio/sysfs.txt
View file @ bb2407a7
RapidIO sysfs Files The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Documentation/ABI/testing/sysfs-class-rapidio
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
Documentation/trace/events-kmem.txt → Documentation/trace/events-kmem.rst
View file @ bb2407a7
Subsystem Trace Points: kmem ============================
Subsystem Trace Points: kmem
============================
The kmem tracing system captures events related to object and page allocation The kmem tracing system captures events related to object and page allocation
within the kernel. Broadly speaking there are five major subheadings. within the kernel. Broadly speaking there are five major subheadings.
o Slab allocation of small objects of unknown type (kmalloc) - Slab allocation of small objects of unknown type (kmalloc)
o Slab allocation of small objects of known type - Slab allocation of small objects of known type
o Page allocation - Page allocation
o Per-CPU Allocator Activity - Per-CPU Allocator Activity
o External Fragmentation - External Fragmentation
This document describes what each of the tracepoints is and why they This document describes what each of the tracepoints is and why they
might be useful. might be useful.
1. Slab allocation of small objects of unknown type 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 Heavy activity for these events may indicate that a specific cache is
justified, particularly if kmalloc slab pages are getting significantly justified, particularly if kmalloc slab pages are getting significantly
...@@ -27,9 +31,11 @@ the allocation sites were. ...@@ -27,9 +31,11 @@ the allocation sites were.
2. Slab allocation of small objects of known type 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 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 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. ...@@ -38,10 +44,12 @@ but the call_site can usually be used to extrapolate that information.
3. Page allocation 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_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
mm_page_free_batched page=%p pfn=%lu order=%d cold=%d 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 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 a simple indicator of page allocator activity. Pages may be allocated from
...@@ -65,8 +73,10 @@ contention on the zone->lru_lock. ...@@ -65,8 +73,10 @@ contention on the zone->lru_lock.
4. Per-CPU Allocator Activity 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 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 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. ...@@ -92,7 +102,9 @@ can be allocated and freed on the same CPU through some algorithm change.
5. External Fragmentation 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 External fragmentation affects whether a high-order allocation will be
successful or not. For some types of hardware, this is important although successful or not. For some types of hardware, this is important although
......
Documentation/trace/events-msr.txt → Documentation/trace/events-msr.rst
View file @ bb2407a7
================
MSR Trace Events
================
The x86 kernel supports tracing most MSR (Model Specific Register) accesses. 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 To see the definition of the MSRs on Intel systems please see the SDM
...@@ -7,31 +10,31 @@ Available trace points: ...@@ -7,31 +10,31 @@ Available trace points:
/sys/kernel/debug/tracing/events/msr/ /sys/kernel/debug/tracing/events/msr/
Trace MSR reads Trace MSR reads:
read_msr read_msr
msr: MSR number - msr: MSR number
val: Value written - val: Value written
failed: 1 if the access failed, otherwise 0 - failed: 1 if the access failed, otherwise 0
Trace MSR writes Trace MSR writes:
write_msr write_msr
msr: MSR number - msr: MSR number
val: Value written - val: Value written
failed: 1 if the access failed, otherwise 0 - failed: 1 if the access failed, otherwise 0
Trace RDPMC in kernel Trace RDPMC in kernel:
rdpmc rdpmc
The trace data can be post processed with the postprocess/decode_msr.py script The trace data can be post processed with the postprocess/decode_msr.py script::
cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h
to add symbolic MSR names. to add symbolic MSR names.
Documentation/trace/events-nmi.txt → Documentation/trace/events-nmi.rst
View file @ bb2407a7
================
NMI Trace Events NMI Trace Events
================
These events normally show up here: These events normally show up here:
/sys/kernel/debug/tracing/events/nmi /sys/kernel/debug/tracing/events/nmi
--
nmi_handler: nmi_handler
-----------
You might want to use this tracepoint if you suspect that your You might want to use this tracepoint if you suspect that your
NMI handlers are hogging large amounts of CPU time. The kernel NMI handlers are hogging large amounts of CPU time. The kernel
will warn if it sees long-running handlers: will warn if it sees long-running handlers::
INFO: NMI handler took too long to run: 9.207 msecs INFO: NMI handler took too long to run: 9.207 msecs
...@@ -19,7 +21,7 @@ more details. ...@@ -19,7 +21,7 @@ more details.
Let's say you suspect that perf_event_nmi_handler() is causing Let's say you suspect that perf_event_nmi_handler() is causing
you some problems and you only want to trace that handler you some problems and you only want to trace that handler
specifically. You need to find its address: specifically. You need to find its address::
$ grep perf_event_nmi_handler /proc/kallsyms $ grep perf_event_nmi_handler /proc/kallsyms
ffffffff81625600 t perf_event_nmi_handler ffffffff81625600 t perf_event_nmi_handler
...@@ -27,17 +29,17 @@ specifically. You need to find its address: ...@@ -27,17 +29,17 @@ specifically. You need to find its address:
Let's also say you are only interested in when that function is 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. 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 Note that the kernel's output is in milliseconds, but the input
to the filter is in nanoseconds! You can filter on 'delta_ns': to the filter is in nanoseconds! You can filter on 'delta_ns'::
cd /sys/kernel/debug/tracing/events/nmi/nmi_handler cd /sys/kernel/debug/tracing/events/nmi/nmi_handler
echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter
echo 1 > enable echo 1 > enable
Your output would then look like: Your output would then look like::
$ cat /sys/kernel/debug/tracing/trace_pipe $ 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.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 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.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 <idle>-0 [000] d.h3 506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1
Documentation/trace/events-power.txt → Documentation/trace/events-power.rst
View file @ bb2407a7
=============================
Subsystem Trace Points: power Subsystem Trace Points: power
=============================
The power tracing system captures events related to power transitions The power tracing system captures events related to power transitions
within the kernel. Broadly speaking there are three major subheadings: within the kernel. Broadly speaking there are three major subheadings:
o Power state switch which reports events related to suspend (S-states), - Power state switch which reports events related to suspend (S-states),
cpuidle (C-states) and cpufreq (P-states) cpuidle (C-states) and cpufreq (P-states)
o System clock related changes - System clock related changes
o Power domains related changes and transitions - Power domains related changes and transitions
This document describes what each of the tracepoints is and why they This document describes what each of the tracepoints is and why they
might be useful. might be useful.
...@@ -22,14 +23,16 @@ Cf. include/trace/events/power.h for the events definitions. ...@@ -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 A 'cpu' event class gathers the CPU-related events: cpuidle and
cpufreq. cpufreq.
::
cpu_idle "state=%lu cpu_id=%lu" cpu_idle "state=%lu cpu_id=%lu"
cpu_frequency "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 A suspend event is used to indicate the system going in and out of the
suspend mode: 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, 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. ...@@ -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 The clock events are used for clock enable/disable and for
clock rate change. clock rate change.
::
clock_enable "%s state=%lu cpu_id=%lu" clock_enable "%s state=%lu cpu_id=%lu"
clock_disable "%s state=%lu cpu_id=%lu" clock_disable "%s state=%lu cpu_id=%lu"
clock_set_rate "%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 first parameter gives the clock name (e.g. "gpio1_iclk").
The second parameter is '1' for enable, '0' for disable, the target The second parameter is '1' for enable, '0' for disable, the target
...@@ -57,8 +61,9 @@ clock rate for set_rate. ...@@ -57,8 +61,9 @@ clock rate for set_rate.
3. Power domains events 3. Power domains events
======================= =======================
The power domain events are used for power domains transitions 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 first parameter gives the power domain name (e.g. "mpu_pwrdm").
The second parameter is the power domain target state. The second parameter is the power domain target state.
...@@ -67,28 +72,31 @@ 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 The PM QoS events are used for QoS add/update/remove request and for
target/flags update. target/flags update.
::
pm_qos_add_request "pm_qos_class=%s value=%d" pm_qos_add_request "pm_qos_class=%s value=%d"
pm_qos_update_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_remove_request "pm_qos_class=%s value=%d"
pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld" 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 first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY").
The second parameter is value to be added/updated/removed. The second parameter is value to be added/updated/removed.
The third parameter is timeout value in usec. The third parameter is timeout value in usec.
::
pm_qos_update_target "action=%s prev_value=%d curr_value=%d" 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_flags "action=%s prev_value=0x%x curr_value=0x%x"
The first parameter gives the QoS action name (e.g. "ADD_REQ"). The first parameter gives the QoS action name (e.g. "ADD_REQ").
The second parameter is the previous QoS value. The second parameter is the previous QoS value.
The third parameter is the current QoS value to update. The third parameter is the current QoS value to update.
And, there are also events used for device PM QoS add/update/remove request. 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_add_request "device=%s type=%s new_value=%d"
dev_pm_qos_update_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_remove_request "device=%s type=%s new_value=%d"
The first parameter gives the device name which tries to add/update/remove The first parameter gives the device name which tries to add/update/remove
QoS requests. QoS requests.
......
Documentation/trace/events.txt → Documentation/trace/events.rst
View file @ bb2407a7
Event Tracing =============
Event Tracing
=============
Documentation written by Theodore Ts'o :Author: Theodore Ts'o
Updated by Li Zefan and Tom Zanussi :Updated: Li Zefan and Tom Zanussi
1. Introduction 1. Introduction
=============== ===============
...@@ -25,23 +27,22 @@ The events which are available for tracing can be found in the file ...@@ -25,23 +27,22 @@ The events which are available for tracing can be found in the file
/sys/kernel/debug/tracing/available_events. /sys/kernel/debug/tracing/available_events.
To enable a particular event, such as 'sched_wakeup', simply echo it To enable a particular event, such as 'sched_wakeup', simply echo it
to /sys/kernel/debug/tracing/set_event. For example: to /sys/kernel/debug/tracing/set_event. For example::
# echo sched_wakeup >> /sys/kernel/debug/tracing/set_event # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event
[ Note: '>>' is necessary, otherwise it will firstly disable .. Note:: '>>' is necessary, otherwise it will firstly disable all the events.
all the events. ]
To disable an event, echo the event name to the set_event file prefixed To disable an event, echo the event name to the set_event file prefixed
with an exclamation point: with an exclamation point::
# echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event
To disable all events, echo an empty line to the set_event file: To disable all events, echo an empty line to the set_event file::
# echo > /sys/kernel/debug/tracing/set_event # echo > /sys/kernel/debug/tracing/set_event
To enable all events, echo '*:*' or '*:' to the set_event file: To enable all events, echo ``*:*`` or ``*:`` to the set_event file::
# echo *:* > /sys/kernel/debug/tracing/set_event # echo *:* > /sys/kernel/debug/tracing/set_event
...@@ -49,8 +50,8 @@ The events are organized into subsystems, such as ext4, irq, sched, ...@@ -49,8 +50,8 @@ The events are organized into subsystems, such as ext4, irq, sched,
etc., and a full event name looks like this: <subsystem>:<event>. The etc., and a full event name looks like this: <subsystem>:<event>. The
subsystem name is optional, but it is displayed in the available_events subsystem name is optional, but it is displayed in the available_events
file. All of the events in a subsystem can be specified via the syntax file. All of the events in a subsystem can be specified via the syntax
"<subsystem>:*"; for example, to enable all irq events, you can use the ``<subsystem>:*``; for example, to enable all irq events, you can use the
command: command::
# echo 'irq:*' > /sys/kernel/debug/tracing/set_event # echo 'irq:*' > /sys/kernel/debug/tracing/set_event
...@@ -60,33 +61,33 @@ command: ...@@ -60,33 +61,33 @@ command:
The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy
of directories. of directories.
To enable event 'sched_wakeup': To enable event 'sched_wakeup'::
# echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
To disable it: To disable it::
# echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
To enable all events in sched subsystem: To enable all events in sched subsystem::
# echo 1 > /sys/kernel/debug/tracing/events/sched/enable # echo 1 > /sys/kernel/debug/tracing/events/sched/enable
To enable all events: To enable all events::
# echo 1 > /sys/kernel/debug/tracing/events/enable # echo 1 > /sys/kernel/debug/tracing/events/enable
When reading one of these enable files, there are four results: When reading one of these enable files, there are four results:
0 - all events this file affects are disabled - 0 - all events this file affects are disabled
1 - all events this file affects are enabled - 1 - all events this file affects are enabled
X - there is a mixture of events enabled and disabled - X - there is a mixture of events enabled and disabled
? - this file does not affect any event - ? - this file does not affect any event
2.3 Boot option 2.3 Boot option
--------------- ---------------
In order to facilitate early boot debugging, use boot option: In order to facilitate early boot debugging, use boot option::
trace_event=[event-list] trace_event=[event-list]
...@@ -110,12 +111,12 @@ It also displays the format string that will be used to print the ...@@ -110,12 +111,12 @@ It also displays the format string that will be used to print the
event in text mode, along with the event name and ID used for event in text mode, along with the event name and ID used for
profiling. profiling.
Every event has a set of 'common' fields associated with it; these are Every event has a set of ``common`` fields associated with it; these are
the fields prefixed with 'common_'. The other fields vary between the fields prefixed with ``common_``. The other fields vary between
events and correspond to the fields defined in the TRACE_EVENT events and correspond to the fields defined in the TRACE_EVENT
definition for that event. definition for that event.
Each field in the format has the form: Each field in the format has the form::
field:field-type field-name; offset:N; size:N; field:field-type field-name; offset:N; size:N;
...@@ -123,13 +124,13 @@ where offset is the offset of the field in the trace record and size ...@@ -123,13 +124,13 @@ where offset is the offset of the field in the trace record and size
is the size of the data item, in bytes. is the size of the data item, in bytes.
For example, here's the information displayed for the 'sched_wakeup' For example, here's the information displayed for the 'sched_wakeup'
event: event::
# cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format # cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format
name: sched_wakeup name: sched_wakeup
ID: 60 ID: 60
format: format:
field:unsigned short common_type; offset:0; size:2; field:unsigned short common_type; offset:0; size:2;
field:unsigned char common_flags; offset:2; size:1; field:unsigned char common_flags; offset:2; size:1;
field:unsigned char common_preempt_count; offset:3; size:1; field:unsigned char common_preempt_count; offset:3; size:1;
...@@ -142,7 +143,7 @@ format: ...@@ -142,7 +143,7 @@ format:
field:int success; offset:36; size:4; field:int success; offset:36; size:4;
field:int cpu; offset:40; size:4; field:int cpu; offset:40; size:4;
print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid, print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
REC->prio, REC->success, REC->cpu REC->prio, REC->success, REC->cpu
This event contains 10 fields, the first 5 common and the remaining 5 This event contains 10 fields, the first 5 common and the remaining 5
...@@ -168,7 +169,7 @@ A filter expression consists of one or more 'predicates' that can be ...@@ -168,7 +169,7 @@ A filter expression consists of one or more 'predicates' that can be
combined using the logical operators '&&' and '||'. A predicate is combined using the logical operators '&&' and '||'. A predicate is
simply a clause that compares the value of a field contained within a simply a clause that compares the value of a field contained within a
logged event with a constant value and returns either 0 or 1 depending logged event with a constant value and returns either 0 or 1 depending
on whether the field value matched (1) or didn't match (0): on whether the field value matched (1) or didn't match (0)::
field-name relational-operator value field-name relational-operator value
...@@ -189,8 +190,8 @@ And for string fields they are: ...@@ -189,8 +190,8 @@ And for string fields they are:
==, !=, ~ ==, !=, ~
The glob (~) accepts a wild card character (*,?) and character classes The glob (~) accepts a wild card character (\*,?) and character classes
([). For example: ([). For example::
prev_comm ~ "*sh" prev_comm ~ "*sh"
prev_comm ~ "sh*" prev_comm ~ "sh*"
...@@ -203,27 +204,27 @@ The glob (~) accepts a wild card character (*,?) and character classes ...@@ -203,27 +204,27 @@ The glob (~) accepts a wild card character (*,?) and character classes
A filter for an individual event is set by writing a filter expression A filter for an individual event is set by writing a filter expression
to the 'filter' file for the given event. to the 'filter' file for the given event.
For example: For example::
# cd /sys/kernel/debug/tracing/events/sched/sched_wakeup # cd /sys/kernel/debug/tracing/events/sched/sched_wakeup
# echo "common_preempt_count > 4" > filter # echo "common_preempt_count > 4" > filter
A slightly more involved example: A slightly more involved example::
# cd /sys/kernel/debug/tracing/events/signal/signal_generate # cd /sys/kernel/debug/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter
If there is an error in the expression, you'll get an 'Invalid If there is an error in the expression, you'll get an 'Invalid
argument' error when setting it, and the erroneous string along with argument' error when setting it, and the erroneous string along with
an error message can be seen by looking at the filter e.g.: an error message can be seen by looking at the filter e.g.::
# cd /sys/kernel/debug/tracing/events/signal/signal_generate # cd /sys/kernel/debug/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter
-bash: echo: write error: Invalid argument -bash: echo: write error: Invalid argument
# cat filter # cat filter
((sig >= 10 && sig < 15) || dsig == 17) && comm != bash ((sig >= 10 && sig < 15) || dsig == 17) && comm != bash
^ ^
parse_error: Field not found parse_error: Field not found
Currently the caret ('^') for an error always appears at the beginning of Currently the caret ('^') for an error always appears at the beginning of
the filter string; the error message should still be useful though the filter string; the error message should still be useful though
...@@ -255,35 +256,35 @@ fields can be guaranteed to propagate successfully to all events. ...@@ -255,35 +256,35 @@ fields can be guaranteed to propagate successfully to all events.
Here are a few subsystem filter examples that also illustrate the Here are a few subsystem filter examples that also illustrate the
above points: above points:
Clear the filters on all events in the sched subsystem: Clear the filters on all events in the sched subsystem::
# cd /sys/kernel/debug/tracing/events/sched # cd /sys/kernel/debug/tracing/events/sched
# echo 0 > filter # echo 0 > filter
# cat sched_switch/filter # cat sched_switch/filter
none none
# cat sched_wakeup/filter # cat sched_wakeup/filter
none none
Set a filter using only common fields for all events in the sched Set a filter using only common fields for all events in the sched
subsystem (all events end up with the same filter): subsystem (all events end up with the same filter)::
# cd /sys/kernel/debug/tracing/events/sched # cd /sys/kernel/debug/tracing/events/sched
# echo common_pid == 0 > filter # echo common_pid == 0 > filter
# cat sched_switch/filter # cat sched_switch/filter
common_pid == 0 common_pid == 0
# cat sched_wakeup/filter # cat sched_wakeup/filter
common_pid == 0 common_pid == 0
Attempt to set a filter using a non-common field for all events in the Attempt to set a filter using a non-common field for all events in the
sched subsystem (all events but those that have a prev_pid field retain sched subsystem (all events but those that have a prev_pid field retain
their old filters): their old filters)::
# cd /sys/kernel/debug/tracing/events/sched # cd /sys/kernel/debug/tracing/events/sched
# echo prev_pid == 0 > filter # echo prev_pid == 0 > filter
# cat sched_switch/filter # cat sched_switch/filter
prev_pid == 0 prev_pid == 0
# cat sched_wakeup/filter # cat sched_wakeup/filter
common_pid == 0 common_pid == 0
5.4 PID filtering 5.4 PID filtering
----------------- -----------------
...@@ -291,16 +292,18 @@ common_pid == 0 ...@@ -291,16 +292,18 @@ common_pid == 0
The set_event_pid file in the same directory as the top events directory The set_event_pid file in the same directory as the top events directory
exists, will filter all events from tracing any task that does not have the exists, will filter all events from tracing any task that does not have the
PID listed in the set_event_pid file. PID listed in the set_event_pid file.
::
# cd /sys/kernel/debug/tracing # cd /sys/kernel/debug/tracing
# echo $$ > set_event_pid # echo $$ > set_event_pid
# echo 1 > events/enabled # echo 1 > events/enable
Will only trace events for the current task. Will only trace events for the current task.
To add more PIDs without losing the PIDs already included, use '>>'. To add more PIDs without losing the PIDs already included, use '>>'.
::
# echo 123 244 1 >> set_event_pid # echo 123 244 1 >> set_event_pid
6. Event triggers 6. Event triggers
...@@ -342,12 +345,12 @@ way, so beware about making generalizations between the two. ...@@ -342,12 +345,12 @@ way, so beware about making generalizations between the two.
6.1 Expression syntax 6.1 Expression syntax
--------------------- ---------------------
Triggers are added by echoing the command to the 'trigger' file: Triggers are added by echoing the command to the 'trigger' file::
# echo 'command[:count] [if filter]' > trigger # echo 'command[:count] [if filter]' > trigger
Triggers are removed by echoing the same command but starting with '!' Triggers are removed by echoing the same command but starting with '!'
to the 'trigger' file: to the 'trigger' file::
# echo '!command[:count] [if filter]' > trigger # echo '!command[:count] [if filter]' > trigger
...@@ -379,24 +382,24 @@ The following commands are supported: ...@@ -379,24 +382,24 @@ The following commands are supported:
For example, the following trigger causes kmalloc events to be For example, the following trigger causes kmalloc events to be
traced when a read system call is entered, and the :1 at the end traced when a read system call is entered, and the :1 at the end
specifies that this enablement happens only once: specifies that this enablement happens only once::
# echo 'enable_event:kmem:kmalloc:1' > \ # echo 'enable_event:kmem:kmalloc:1' > \
/sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
The following trigger causes kmalloc events to stop being traced The following trigger causes kmalloc events to stop being traced
when a read system call exits. This disablement happens on every when a read system call exits. This disablement happens on every
read system call exit: read system call exit::
# echo 'disable_event:kmem:kmalloc' > \ # echo 'disable_event:kmem:kmalloc' > \
/sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger
The format is: The format is::
enable_event:<system>:<event>[:count] enable_event:<system>:<event>[:count]
disable_event:<system>:<event>[:count] disable_event:<system>:<event>[:count]
To remove the above commands: To remove the above commands::
# echo '!enable_event:kmem:kmalloc:1' > \ # echo '!enable_event:kmem:kmalloc:1' > \
/sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
...@@ -418,22 +421,22 @@ The following commands are supported: ...@@ -418,22 +421,22 @@ The following commands are supported:
triggering event occurs. triggering event occurs.
For example, the following trigger dumps a stacktrace every time the For example, the following trigger dumps a stacktrace every time the
kmalloc tracepoint is hit: kmalloc tracepoint is hit::
# echo 'stacktrace' > \ # echo 'stacktrace' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
The following trigger dumps a stacktrace the first 5 times a kmalloc The following trigger dumps a stacktrace the first 5 times a kmalloc
request happens with a size >= 64K request happens with a size >= 64K::
# echo 'stacktrace:5 if bytes_req >= 65536' > \ # echo 'stacktrace:5 if bytes_req >= 65536' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
The format is: The format is::
stacktrace[:count] stacktrace[:count]
To remove the above commands: To remove the above commands::
# echo '!stacktrace' > \ # echo '!stacktrace' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -442,7 +445,7 @@ The following commands are supported: ...@@ -442,7 +445,7 @@ The following commands are supported:
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
The latter can also be removed more simply by the following (without The latter can also be removed more simply by the following (without
the filter): the filter)::
# echo '!stacktrace:5' > \ # echo '!stacktrace:5' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -458,17 +461,17 @@ The following commands are supported: ...@@ -458,17 +461,17 @@ The following commands are supported:
The following command creates a snapshot every time a block request The following command creates a snapshot every time a block request
queue is unplugged with a depth > 1. If you were tracing a set of queue is unplugged with a depth > 1. If you were tracing a set of
events or functions at the time, the snapshot trace buffer would events or functions at the time, the snapshot trace buffer would
capture those events when the trigger event occurred: capture those events when the trigger event occurred::
# echo 'snapshot if nr_rq > 1' > \ # echo 'snapshot if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
To only snapshot once: To only snapshot once::
# echo 'snapshot:1 if nr_rq > 1' > \ # echo 'snapshot:1 if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
To remove the above commands: To remove the above commands::
# echo '!snapshot if nr_rq > 1' > \ # echo '!snapshot if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
...@@ -489,17 +492,17 @@ The following commands are supported: ...@@ -489,17 +492,17 @@ The following commands are supported:
request queue is unplugged with a depth > 1. If you were tracing a request queue is unplugged with a depth > 1. If you were tracing a
set of events or functions at the time, you could then examine the set of events or functions at the time, you could then examine the
trace buffer to see the sequence of events that led up to the trace buffer to see the sequence of events that led up to the
trigger event: trigger event::
# echo 'traceoff:1 if nr_rq > 1' > \ # echo 'traceoff:1 if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
To always disable tracing when nr_rq > 1 : To always disable tracing when nr_rq > 1::
# echo 'traceoff if nr_rq > 1' > \ # echo 'traceoff if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
To remove the above commands: To remove the above commands::
# echo '!traceoff:1 if nr_rq > 1' > \ # echo '!traceoff:1 if nr_rq > 1' > \
/sys/kernel/debug/tracing/events/block/block_unplug/trigger /sys/kernel/debug/tracing/events/block/block_unplug/trigger
...@@ -517,7 +520,7 @@ The following commands are supported: ...@@ -517,7 +520,7 @@ The following commands are supported:
totals derived from one or more trace event format fields and/or totals derived from one or more trace event format fields and/or
event counts (hitcount). event counts (hitcount).
The format of a hist trigger is as follows: The format of a hist trigger is as follows::
hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>] hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>]
[:sort=<field1[,field2,...]>][:size=#entries][:pause][:continue] [:sort=<field1[,field2,...]>][:size=#entries][:pause][:continue]
...@@ -566,11 +569,11 @@ The following commands are supported: ...@@ -566,11 +569,11 @@ The following commands are supported:
modified by appending any of the following modifiers to the field modified by appending any of the following modifiers to the field
name: name:
.hex display a number as a hex value - .hex display a number as a hex value
.sym display an address as a symbol - .sym display an address as a symbol
.sym-offset display an address as a symbol and offset - .sym-offset display an address as a symbol and offset
.syscall display a syscall id as a system call name - .syscall display a syscall id as a system call name
.execname display a common_pid as a program name - .execname display a common_pid as a program name
Note that in general the semantics of a given field aren't Note that in general the semantics of a given field aren't
interpreted when applying a modifier to it, but there are some interpreted when applying a modifier to it, but there are some
...@@ -588,7 +591,7 @@ The following commands are supported: ...@@ -588,7 +591,7 @@ The following commands are supported:
pid-specific comm fields in the event itself. pid-specific comm fields in the event itself.
A typical usage scenario would be the following to enable a hist A typical usage scenario would be the following to enable a hist
trigger, read its current contents, and then turn it off: trigger, read its current contents, and then turn it off::
# echo 'hist:keys=skbaddr.hex:vals=len' > \ # echo 'hist:keys=skbaddr.hex:vals=len' > \
/sys/kernel/debug/tracing/events/net/netif_rx/trigger /sys/kernel/debug/tracing/events/net/netif_rx/trigger
...@@ -636,7 +639,7 @@ The following commands are supported: ...@@ -636,7 +639,7 @@ The following commands are supported:
can be attached to a given event, allowing that event to kick off can be attached to a given event, allowing that event to kick off
and stop aggregations on a host of other events. and stop aggregations on a host of other events.
The format is very similar to the enable/disable_event triggers: The format is very similar to the enable/disable_event triggers::
enable_hist:<system>:<event>[:count] enable_hist:<system>:<event>[:count]
disable_hist:<system>:<event>[:count] disable_hist:<system>:<event>[:count]
...@@ -649,7 +652,7 @@ The following commands are supported: ...@@ -649,7 +652,7 @@ The following commands are supported:
A typical usage scenario for the enable_hist/disable_hist triggers A typical usage scenario for the enable_hist/disable_hist triggers
would be to first set up a paused hist trigger on some event, would be to first set up a paused hist trigger on some event,
followed by an enable_hist/disable_hist pair that turns the hist followed by an enable_hist/disable_hist pair that turns the hist
aggregation on and off when conditions of interest are hit: aggregation on and off when conditions of interest are hit::
# echo 'hist:keys=skbaddr.hex:vals=len:pause' > \ # echo 'hist:keys=skbaddr.hex:vals=len:pause' > \
/sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
...@@ -674,7 +677,7 @@ The following commands are supported: ...@@ -674,7 +677,7 @@ The following commands are supported:
The first set of examples creates aggregations using the kmalloc The first set of examples creates aggregations using the kmalloc
event. The fields that can be used for the hist trigger are listed event. The fields that can be used for the hist trigger are listed
in the kmalloc event's format file: in the kmalloc event's format file::
# cat /sys/kernel/debug/tracing/events/kmem/kmalloc/format # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/format
name: kmalloc name: kmalloc
...@@ -693,7 +696,7 @@ The following commands are supported: ...@@ -693,7 +696,7 @@ The following commands are supported:
We'll start by creating a hist trigger that generates a simple table We'll start by creating a hist trigger that generates a simple table
that lists the total number of bytes requested for each function in that lists the total number of bytes requested for each function in
the kernel that made one or more calls to kmalloc: the kernel that made one or more calls to kmalloc::
# echo 'hist:key=call_site:val=bytes_req' > \ # echo 'hist:key=call_site:val=bytes_req' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -708,7 +711,7 @@ The following commands are supported: ...@@ -708,7 +711,7 @@ The following commands are supported:
We'll let it run for awhile and then dump the contents of the 'hist' We'll let it run for awhile and then dump the contents of the 'hist'
file in the kmalloc event's subdirectory (for readability, a number file in the kmalloc event's subdirectory (for readability, a number
of entries have been omitted): of entries have been omitted)::
# cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
# trigger info: hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] # trigger info: hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active]
...@@ -748,7 +751,7 @@ The following commands are supported: ...@@ -748,7 +751,7 @@ The following commands are supported:
specified in the trigger, followed by the value(s) also specified in specified in the trigger, followed by the value(s) also specified in
the trigger. At the beginning of the output is a line that displays the trigger. At the beginning of the output is a line that displays
the trigger info, which can also be displayed by reading the the trigger info, which can also be displayed by reading the
'trigger' file: 'trigger' file::
# cat /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active]
...@@ -778,7 +781,7 @@ The following commands are supported: ...@@ -778,7 +781,7 @@ The following commands are supported:
frequencies. frequencies.
To turn the hist trigger off, simply call up the trigger in the To turn the hist trigger off, simply call up the trigger in the
command history and re-execute it with a '!' prepended: command history and re-execute it with a '!' prepended::
# echo '!hist:key=call_site:val=bytes_req' > \ # echo '!hist:key=call_site:val=bytes_req' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -786,7 +789,7 @@ The following commands are supported: ...@@ -786,7 +789,7 @@ The following commands are supported:
Finally, notice that the call_site as displayed in the output above Finally, notice that the call_site as displayed in the output above
isn't really very useful. It's an address, but normally addresses isn't really very useful. It's an address, but normally addresses
are displayed in hex. To have a numeric field displayed as a hex are displayed in hex. To have a numeric field displayed as a hex
value, simply append '.hex' to the field name in the trigger: value, simply append '.hex' to the field name in the trigger::
# echo 'hist:key=call_site.hex:val=bytes_req' > \ # echo 'hist:key=call_site.hex:val=bytes_req' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -831,7 +834,7 @@ The following commands are supported: ...@@ -831,7 +834,7 @@ The following commands are supported:
when looking at text addresses are the corresponding symbols when looking at text addresses are the corresponding symbols
instead. To have an address displayed as symbolic value instead, instead. To have an address displayed as symbolic value instead,
simply append '.sym' or '.sym-offset' to the field name in the simply append '.sym' or '.sym-offset' to the field name in the
trigger: trigger::
# echo 'hist:key=call_site.sym:val=bytes_req' > \ # echo 'hist:key=call_site.sym:val=bytes_req' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -881,7 +884,7 @@ The following commands are supported: ...@@ -881,7 +884,7 @@ The following commands are supported:
run. If instead we we wanted to see the top kmalloc callers in run. If instead we we wanted to see the top kmalloc callers in
terms of the number of bytes requested rather than the number of terms of the number of bytes requested rather than the number of
calls, and we wanted the top caller to appear at the top, we can use calls, and we wanted the top caller to appear at the top, we can use
the 'sort' parameter, along with the 'descending' modifier: the 'sort' parameter, along with the 'descending' modifier::
# echo 'hist:key=call_site.sym:val=bytes_req:sort=bytes_req.descending' > \ # echo 'hist:key=call_site.sym:val=bytes_req:sort=bytes_req.descending' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -922,7 +925,7 @@ The following commands are supported: ...@@ -922,7 +925,7 @@ The following commands are supported:
Dropped: 0 Dropped: 0
To display the offset and size information in addition to the symbol To display the offset and size information in addition to the symbol
name, just use 'sym-offset' instead: name, just use 'sym-offset' instead::
# echo 'hist:key=call_site.sym-offset:val=bytes_req:sort=bytes_req.descending' > \ # echo 'hist:key=call_site.sym-offset:val=bytes_req:sort=bytes_req.descending' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -961,7 +964,7 @@ The following commands are supported: ...@@ -961,7 +964,7 @@ The following commands are supported:
We can also add multiple fields to the 'values' parameter. For We can also add multiple fields to the 'values' parameter. For
example, we might want to see the total number of bytes allocated example, we might want to see the total number of bytes allocated
alongside bytes requested, and display the result sorted by bytes alongside bytes requested, and display the result sorted by bytes
allocated in a descending order: allocated in a descending order::
# echo 'hist:keys=call_site.sym:values=bytes_req,bytes_alloc:sort=bytes_alloc.descending' > \ # echo 'hist:keys=call_site.sym:values=bytes_req,bytes_alloc:sort=bytes_alloc.descending' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -1004,7 +1007,7 @@ The following commands are supported: ...@@ -1004,7 +1007,7 @@ The following commands are supported:
the hist trigger display symbolic call_sites, we can have the hist the hist trigger display symbolic call_sites, we can have the hist
trigger additionally display the complete set of kernel stack traces trigger additionally display the complete set of kernel stack traces
that led to each call_site. To do that, we simply use the special that led to each call_site. To do that, we simply use the special
value 'stacktrace' for the key parameter: value 'stacktrace' for the key parameter::
# echo 'hist:keys=stacktrace:values=bytes_req,bytes_alloc:sort=bytes_alloc' > \ # echo 'hist:keys=stacktrace:values=bytes_req,bytes_alloc:sort=bytes_alloc' > \
/sys/kernel/debug/tracing/events/kmem/kmalloc/trigger /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
...@@ -1015,7 +1018,7 @@ The following commands are supported: ...@@ -1015,7 +1018,7 @@ The following commands are supported:
event, along with a running total of any of the event fields for event, along with a running total of any of the event fields for
that event. Here we tally bytes requested and bytes allocated for that event. Here we tally bytes requested and bytes allocated for
every callpath in the system that led up to a kmalloc (in this case every callpath in the system that led up to a kmalloc (in this case
every callpath to a kmalloc for a kernel compile): every callpath to a kmalloc for a kernel compile)::
# cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
# trigger info: hist:keys=stacktrace:vals=bytes_req,bytes_alloc:sort=bytes_alloc:size=2048 [active] # trigger info: hist:keys=stacktrace:vals=bytes_req,bytes_alloc:sort=bytes_alloc:size=2048 [active]
...@@ -1113,7 +1116,7 @@ The following commands are supported: ...@@ -1113,7 +1116,7 @@ The following commands are supported:
gather and display sorted totals for each process, you can use the gather and display sorted totals for each process, you can use the
special .execname modifier to display the executable names for the special .execname modifier to display the executable names for the
processes in the table rather than raw pids. The example below processes in the table rather than raw pids. The example below
keeps a per-process sum of total bytes read: keeps a per-process sum of total bytes read::
# echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \ # echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \
/sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
...@@ -1154,7 +1157,7 @@ The following commands are supported: ...@@ -1154,7 +1157,7 @@ The following commands are supported:
gather and display a list of systemwide syscall hits, you can use gather and display a list of systemwide syscall hits, you can use
the special .syscall modifier to display the syscall names rather the special .syscall modifier to display the syscall names rather
than raw ids. The example below keeps a running total of syscall than raw ids. The example below keeps a running total of syscall
counts for the system during the run: counts for the system during the run::
# echo 'hist:key=id.syscall:val=hitcount' > \ # echo 'hist:key=id.syscall:val=hitcount' > \
/sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
...@@ -1208,7 +1211,7 @@ The following commands are supported: ...@@ -1208,7 +1211,7 @@ The following commands are supported:
system call id and pid - the end result is essentially a table system call id and pid - the end result is essentially a table
that keeps a per-pid sum of system call hits. The results are that keeps a per-pid sum of system call hits. The results are
sorted using the system call id as the primary key, and the sorted using the system call id as the primary key, and the
hitcount sum as the secondary key: hitcount sum as the secondary key::
# echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount' > \ # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount' > \
/sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
...@@ -1258,7 +1261,7 @@ The following commands are supported: ...@@ -1258,7 +1261,7 @@ The following commands are supported:
pid, but it also gives us quite a bit more than that, which we pid, but it also gives us quite a bit more than that, which we
don't really care about at the moment. Since we know the syscall don't really care about at the moment. Since we know the syscall
id for sys_ioctl (16, displayed next to the sys_ioctl name), we id for sys_ioctl (16, displayed next to the sys_ioctl name), we
can use that to filter out all the other syscalls: can use that to filter out all the other syscalls::
# echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount if id == 16' > \ # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount if id == 16' > \
/sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
...@@ -1301,7 +1304,7 @@ The following commands are supported: ...@@ -1301,7 +1304,7 @@ The following commands are supported:
common_pid and size event fields. Sorting with pid as the primary common_pid and size event fields. Sorting with pid as the primary
key and 'size' as the secondary key allows us to display an key and 'size' as the secondary key allows us to display an
ordered summary of the recvfrom sizes, with counts, received by ordered summary of the recvfrom sizes, with counts, received by
each process: each process::
# echo 'hist:key=common_pid.execname,size:val=hitcount:sort=common_pid,size' > \ # echo 'hist:key=common_pid.execname,size:val=hitcount:sort=common_pid,size' > \
/sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/trigger /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/trigger
...@@ -1354,7 +1357,7 @@ The following commands are supported: ...@@ -1354,7 +1357,7 @@ The following commands are supported:
demonstrates how you can manually pause and continue a hist trigger. demonstrates how you can manually pause and continue a hist trigger.
In this example, we'll aggregate fork counts and don't expect a In this example, we'll aggregate fork counts and don't expect a
large number of entries in the hash table, so we'll drop it to a large number of entries in the hash table, so we'll drop it to a
much smaller number, say 256: much smaller number, say 256::
# echo 'hist:key=child_comm:val=hitcount:size=256' > \ # echo 'hist:key=child_comm:val=hitcount:size=256' > \
/sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
...@@ -1390,7 +1393,7 @@ The following commands are supported: ...@@ -1390,7 +1393,7 @@ The following commands are supported:
If we want to pause the hist trigger, we can simply append :pause to If we want to pause the hist trigger, we can simply append :pause to
the command that started the trigger. Notice that the trigger info the command that started the trigger. Notice that the trigger info
displays as [paused]: displays as [paused]::
# echo 'hist:key=child_comm:val=hitcount:size=256:pause' >> \ # echo 'hist:key=child_comm:val=hitcount:size=256:pause' >> \
/sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
...@@ -1427,7 +1430,7 @@ The following commands are supported: ...@@ -1427,7 +1430,7 @@ The following commands are supported:
To manually continue having the trigger aggregate events, append To manually continue having the trigger aggregate events, append
:cont instead. Notice that the trigger info displays as [active] :cont instead. Notice that the trigger info displays as [active]
again, and the data has changed: again, and the data has changed::
# echo 'hist:key=child_comm:val=hitcount:size=256:cont' >> \ # echo 'hist:key=child_comm:val=hitcount:size=256:cont' >> \
/sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
...@@ -1481,7 +1484,7 @@ The following commands are supported: ...@@ -1481,7 +1484,7 @@ The following commands are supported:
wget. wget.
First we set up an initially paused stacktrace trigger on the First we set up an initially paused stacktrace trigger on the
netif_receive_skb event: netif_receive_skb event::
# echo 'hist:key=stacktrace:vals=len:pause' > \ # echo 'hist:key=stacktrace:vals=len:pause' > \
/sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
...@@ -1492,7 +1495,7 @@ The following commands are supported: ...@@ -1492,7 +1495,7 @@ The following commands are supported:
set up on netif_receive_skb if and only if it sees a set up on netif_receive_skb if and only if it sees a
sched_process_exec event with a filename of '/usr/bin/wget'. When sched_process_exec event with a filename of '/usr/bin/wget'. When
that happens, all netif_receive_skb events are aggregated into a that happens, all netif_receive_skb events are aggregated into a
hash table keyed on stacktrace: hash table keyed on stacktrace::
# echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \ # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \
/sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
...@@ -1500,7 +1503,7 @@ The following commands are supported: ...@@ -1500,7 +1503,7 @@ The following commands are supported:
The aggregation continues until the netif_receive_skb is paused The aggregation continues until the netif_receive_skb is paused
again, which is what the following disable_hist event does by again, which is what the following disable_hist event does by
creating a similar setup on the sched_process_exit event, using the creating a similar setup on the sched_process_exit event, using the
filter 'comm==wget': filter 'comm==wget'::
# echo 'disable_hist:net:netif_receive_skb if comm==wget' > \ # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \
/sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger
...@@ -1512,7 +1515,7 @@ The following commands are supported: ...@@ -1512,7 +1515,7 @@ The following commands are supported:
The overall effect is that netif_receive_skb events are aggregated The overall effect is that netif_receive_skb events are aggregated
into the hash table for only the duration of the wget. Executing a into the hash table for only the duration of the wget. Executing a
wget command and then listing the 'hist' file will display the wget command and then listing the 'hist' file will display the
output generated by the wget command: output generated by the wget command::
$ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz
...@@ -1597,13 +1600,13 @@ The following commands are supported: ...@@ -1597,13 +1600,13 @@ The following commands are supported:
Suppose we wanted to try another run of the previous example but Suppose we wanted to try another run of the previous example but
this time also wanted to see the complete list of events that went this time also wanted to see the complete list of events that went
into the histogram. In order to avoid having to set everything up into the histogram. In order to avoid having to set everything up
again, we can just clear the histogram first: again, we can just clear the histogram first::
# echo 'hist:key=stacktrace:vals=len:clear' >> \ # echo 'hist:key=stacktrace:vals=len:clear' >> \
/sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
Just to verify that it is in fact cleared, here's what we now see in Just to verify that it is in fact cleared, here's what we now see in
the hist file: the hist file::
# cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist
# trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused] # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused]
...@@ -1617,7 +1620,7 @@ The following commands are supported: ...@@ -1617,7 +1620,7 @@ The following commands are supported:
event occurring during the new run, which are in fact the same event occurring during the new run, which are in fact the same
events being aggregated into the hash table, we add some additional events being aggregated into the hash table, we add some additional
'enable_event' events to the triggering sched_process_exec and 'enable_event' events to the triggering sched_process_exec and
sched_process_exit events as such: sched_process_exit events as such::
# echo 'enable_event:net:netif_receive_skb if filename==/usr/bin/wget' > \ # echo 'enable_event:net:netif_receive_skb if filename==/usr/bin/wget' > \
/sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
...@@ -1628,7 +1631,7 @@ The following commands are supported: ...@@ -1628,7 +1631,7 @@ The following commands are supported:
If you read the trigger files for the sched_process_exec and If you read the trigger files for the sched_process_exec and
sched_process_exit triggers, you should see two triggers for each: sched_process_exit triggers, you should see two triggers for each:
one enabling/disabling the hist aggregation and the other one enabling/disabling the hist aggregation and the other
enabling/disabling the logging of events: enabling/disabling the logging of events::
# cat /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger # cat /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
enable_event:net:netif_receive_skb:unlimited if filename==/usr/bin/wget enable_event:net:netif_receive_skb:unlimited if filename==/usr/bin/wget
...@@ -1642,13 +1645,13 @@ The following commands are supported: ...@@ -1642,13 +1645,13 @@ The following commands are supported:
sched_process_exit events is hit and matches 'wget', it enables or sched_process_exit events is hit and matches 'wget', it enables or
disables both the histogram and the event log, and what you end up disables both the histogram and the event log, and what you end up
with is a hash table and set of events just covering the specified with is a hash table and set of events just covering the specified
duration. Run the wget command again: duration. Run the wget command again::
$ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz
Displaying the 'hist' file should show something similar to what you Displaying the 'hist' file should show something similar to what you
saw in the last run, but this time you should also see the saw in the last run, but this time you should also see the
individual events in the trace file: individual events in the trace file::
# cat /sys/kernel/debug/tracing/trace # cat /sys/kernel/debug/tracing/trace
...@@ -1673,15 +1676,15 @@ The following commands are supported: ...@@ -1673,15 +1676,15 @@ The following commands are supported:
irq/29-iwlwifi-559 [002] ..s. 31772.032196: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433100 len=2948 irq/29-iwlwifi-559 [002] ..s. 31772.032196: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433100 len=2948
irq/29-iwlwifi-559 [002] ..s. 31772.032761: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433000 len=2948 irq/29-iwlwifi-559 [002] ..s. 31772.032761: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433000 len=2948
irq/29-iwlwifi-559 [002] ..s. 31772.033220: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d432e00 len=1500 irq/29-iwlwifi-559 [002] ..s. 31772.033220: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d432e00 len=1500
. ....
.
.
The following example demonstrates how multiple hist triggers can be The following example demonstrates how multiple hist triggers can be
attached to a given event. This capability can be useful for attached to a given event. This capability can be useful for
creating a set of different summaries derived from the same set of creating a set of different summaries derived from the same set of
events, or for comparing the effects of different filters, among events, or for comparing the effects of different filters, among
other things. other things.
::
# echo 'hist:keys=skbaddr.hex:vals=len if len < 0' >> \ # echo 'hist:keys=skbaddr.hex:vals=len if len < 0' >> \
/sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
...@@ -1702,7 +1705,7 @@ The following commands are supported: ...@@ -1702,7 +1705,7 @@ The following commands are supported:
any existing hist triggers beforehand). any existing hist triggers beforehand).
Displaying the contents of the 'hist' file for the event shows the Displaying the contents of the 'hist' file for the event shows the
contents of all five histograms: contents of all five histograms::
# cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist
...@@ -1822,7 +1825,7 @@ The following commands are supported: ...@@ -1822,7 +1825,7 @@ The following commands are supported:
output of events generated by tracepoints contained inside inline output of events generated by tracepoints contained inside inline
functions, but names can be used in a hist trigger on any event. functions, but names can be used in a hist trigger on any event.
For example, these two triggers when hit will update the same 'len' For example, these two triggers when hit will update the same 'len'
field in the shared 'foo' histogram data: field in the shared 'foo' histogram data::
# echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \ # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \
/sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
...@@ -1830,7 +1833,7 @@ The following commands are supported: ...@@ -1830,7 +1833,7 @@ The following commands are supported:
/sys/kernel/debug/tracing/events/net/netif_rx/trigger /sys/kernel/debug/tracing/events/net/netif_rx/trigger
You can see that they're updating common histogram data by reading You can see that they're updating common histogram data by reading
each event's hist files at the same time: each event's hist files at the same time::
# cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist; # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist;
cat /sys/kernel/debug/tracing/events/net/netif_rx/hist cat /sys/kernel/debug/tracing/events/net/netif_rx/hist
...@@ -1943,7 +1946,7 @@ The following commands are supported: ...@@ -1943,7 +1946,7 @@ The following commands are supported:
And here's an example that shows how to combine histogram data from And here's an example that shows how to combine histogram data from
any two events even if they don't share any 'compatible' fields any two events even if they don't share any 'compatible' fields
other than 'hitcount' and 'stacktrace'. These commands create a other than 'hitcount' and 'stacktrace'. These commands create a
couple of triggers named 'bar' using those fields: couple of triggers named 'bar' using those fields::
# echo 'hist:name=bar:key=stacktrace:val=hitcount' > \ # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \
/sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
...@@ -1951,7 +1954,7 @@ The following commands are supported: ...@@ -1951,7 +1954,7 @@ The following commands are supported:
/sys/kernel/debug/tracing/events/net/netif_rx/trigger /sys/kernel/debug/tracing/events/net/netif_rx/trigger
And displaying the output of either shows some interesting if And displaying the output of either shows some interesting if
somewhat confusing output: somewhat confusing output::
# cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist
# cat /sys/kernel/debug/tracing/events/net/netif_rx/hist # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist
......
Documentation/trace/ftrace-design.txt → Documentation/trace/ftrace-design.rst
View file @ bb2407a7
function tracer guts ======================
==================== Function Tracer Design
By Mike Frysinger ======================
:Author: Mike Frysinger
.. caution::
This document is out of date. Some of the description below doesn't
match current implementation now.
Introduction Introduction
------------ ------------
...@@ -21,8 +27,8 @@ Prerequisites ...@@ -21,8 +27,8 @@ Prerequisites
------------- -------------
Ftrace relies on these features being implemented: Ftrace relies on these features being implemented:
STACKTRACE_SUPPORT - implement save_stack_trace() - STACKTRACE_SUPPORT - implement save_stack_trace()
TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h - TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
HAVE_FUNCTION_TRACER HAVE_FUNCTION_TRACER
...@@ -32,9 +38,11 @@ You will need to implement the mcount and the ftrace_stub functions. ...@@ -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 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 "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 $ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount
call mcount call mcount
We'll make the assumption below that the symbol is "mcount" just to keep things We'll make the assumption below that the symbol is "mcount" just to keep things
nice and simple in the examples. nice and simple in the examples.
...@@ -56,8 +64,9 @@ size of the mcount call that is embedded in the function). ...@@ -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 For example, if the function foo() calls bar(), when the bar() function calls
mcount(), the arguments mcount() will pass to the tracer are: 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 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 optimizing for the default case of no tracer will help the smooth running of
...@@ -67,15 +76,15 @@ means the code flow should usually be kept linear (i.e. no branching in the nop ...@@ -67,15 +76,15 @@ 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. 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 Here is some pseudo code that should help (these functions should actually be
implemented in assembly): implemented in assembly)::
void ftrace_stub(void) void ftrace_stub(void)
{ {
return; return;
} }
void mcount(void) void mcount(void)
{ {
/* save any bare state needed in order to do initial checking */ /* save any bare state needed in order to do initial checking */
extern void (*ftrace_trace_function)(unsigned long, unsigned long); extern void (*ftrace_trace_function)(unsigned long, unsigned long);
...@@ -86,7 +95,7 @@ void mcount(void) ...@@ -86,7 +95,7 @@ void mcount(void)
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) */
...@@ -95,11 +104,13 @@ do_trace: ...@@ -95,11 +104,13 @@ do_trace:
ftrace_trace_function(frompc, selfpc); 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 ! 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 HAVE_FUNCTION_GRAPH_TRACER
...@@ -127,28 +138,30 @@ That function will simply call the common ftrace_return_to_handler function and ...@@ -127,28 +138,30 @@ 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 that will return the original return address with which you can return to the
original call site. original call site.
Here is the updated mcount pseudo code: Here is the updated mcount pseudo code::
void mcount(void)
{ void mcount(void)
... {
...
if (ftrace_trace_function != ftrace_stub) if (ftrace_trace_function != ftrace_stub)
goto do_trace; goto do_trace;
+#ifdef CONFIG_FUNCTION_GRAPH_TRACER +#ifdef CONFIG_FUNCTION_GRAPH_TRACER
+ extern void (*ftrace_graph_return)(...); + extern void (*ftrace_graph_return)(...);
+ extern void (*ftrace_graph_entry)(...); + extern void (*ftrace_graph_entry)(...);
+ if (ftrace_graph_return != ftrace_stub || + if (ftrace_graph_return != ftrace_stub ||
+ ftrace_graph_entry != ftrace_graph_entry_stub) + ftrace_graph_entry != ftrace_graph_entry_stub)
+ ftrace_graph_caller(); + ftrace_graph_caller();
+#endif +#endif
/* restore any bare state */ /* restore any bare state */
... ...
Here is the pseudo code for the new ftrace_graph_caller assembly function::
Here is the pseudo code for the new ftrace_graph_caller assembly function: #ifdef CONFIG_FUNCTION_GRAPH_TRACER
#ifdef CONFIG_FUNCTION_GRAPH_TRACER void ftrace_graph_caller(void)
void ftrace_graph_caller(void) {
{
/* save all state needed by the ABI */ /* save all state needed by the ABI */
unsigned long *frompc = &...; unsigned long *frompc = &...;
...@@ -157,8 +170,8 @@ void ftrace_graph_caller(void) ...@@ -157,8 +170,8 @@ void ftrace_graph_caller(void)
prepare_ftrace_return(frompc, selfpc, frame_pointer); prepare_ftrace_return(frompc, selfpc, frame_pointer);
/* restore all state needed by the ABI */ /* restore all state needed by the ABI */
} }
#endif #endif
For information on how to implement prepare_ftrace_return(), simply look at the 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 x86 version (the frame pointer passing is optional; see the next section for
...@@ -171,10 +184,11 @@ that the ABI that applies here is different from what applies to the mcount ...@@ -171,10 +184,11 @@ 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 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 be able to skimp on things saved/restored (usually just registers used to pass
return values). return values).
::
#ifdef CONFIG_FUNCTION_GRAPH_TRACER #ifdef CONFIG_FUNCTION_GRAPH_TRACER
void return_to_handler(void) void return_to_handler(void)
{ {
/* save all state needed by the ABI (see paragraph above) */ /* 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();
...@@ -183,8 +197,8 @@ void return_to_handler(void) ...@@ -183,8 +197,8 @@ void return_to_handler(void)
/* this is usually either a return or a jump */ /* this is usually either a return or a jump */
original_return_point(); original_return_point();
} }
#endif #endif
HAVE_FUNCTION_GRAPH_FP_TEST HAVE_FUNCTION_GRAPH_FP_TEST
...@@ -228,20 +242,20 @@ HAVE_SYSCALL_TRACEPOINTS ...@@ -228,20 +242,20 @@ HAVE_SYSCALL_TRACEPOINTS
You need very few things to get the syscalls tracing in an arch. You need very few things to get the syscalls tracing in an arch.
- Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig). - Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig).
- Have a NR_syscalls variable in <asm/unistd.h> that provides the number - Have a NR_syscalls variable in <asm/unistd.h> that provides the number
of syscalls supported by the arch. of syscalls supported by the arch.
- Support the TIF_SYSCALL_TRACEPOINT thread flags. - Support the TIF_SYSCALL_TRACEPOINT thread flags.
- Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace - Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace
in the ptrace syscalls tracing path. in the ptrace syscalls tracing path.
- If the system call table on this arch is more complicated than a simple array - 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 of addresses of the system calls, implement an arch_syscall_addr to return
the address of a given system call. the address of a given system call.
- If the symbol names of the system calls do not match the function names on - 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 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 implement arch_syscall_match_sym_name with the appropriate logic to return
true if the function name corresponds with the symbol name. true if the function name corresponds with the symbol name.
- Tag this arch as HAVE_SYSCALL_TRACEPOINTS. - Tag this arch as HAVE_SYSCALL_TRACEPOINTS.
HAVE_FTRACE_MCOUNT_RECORD HAVE_FTRACE_MCOUNT_RECORD
...@@ -276,22 +290,28 @@ Once those are out of the way, you will need to implement: ...@@ -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. 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) #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); extern void mcount(void);
You will also need the helper function ftrace_call_adjust(). Most people 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) static inline unsigned long ftrace_call_adjust(unsigned long addr)
{ {
return addr; return addr;
} }
<details to be filled> <details to be filled>
Lastly you will need the custom dyn_arch_ftrace structure. If you need 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 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 { struct dyn_arch_ftrace {
/* No extra data needed */ /* No extra data needed */
}; };
...@@ -306,28 +326,28 @@ easier to have two separate definitions split up by #ifdefs. Same goes for ...@@ -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(). 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 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) void mcount(void)
{ {
return; return;
} }
void ftrace_caller(void) void ftrace_caller(void)
{ {
/* 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 frompc = ...;
unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;
ftrace_call: ftrace_call:
ftrace_stub(frompc, selfpc); ftrace_stub(frompc, selfpc);
/* restore all state needed by the ABI */ /* restore all state needed by the ABI */
ftrace_stub: ftrace_stub:
return; return;
} }
This might look a little odd at first, but keep in mind that we will be runtime 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 patching multiple things. First, only functions that we actually want to trace
...@@ -341,21 +361,23 @@ order to make it through the next section. ...@@ -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 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 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) int __init ftrace_dyn_arch_init(void)
{ {
return 0; return 0;
} }
There are two functions that are used to do runtime patching of arbitrary 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 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 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 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 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_nop()
ftrace_make_call() ftrace_make_call()
The rec->ip value is the address of the mcount call site that was collected The rec->ip value is the address of the mcount call site that was collected
by the scripts/recordmcount.pl during build time. 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 ...@@ -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 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 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 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() ftrace_update_ftrace_func()
...@@ -373,6 +396,7 @@ HAVE_DYNAMIC_FTRACE + HAVE_FUNCTION_GRAPH_TRACER ...@@ -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. The function grapher needs a few tweaks in order to work with dynamic ftrace.
Basically, you will need to: Basically, you will need to:
- update: - update:
- ftrace_caller() - ftrace_caller()
- ftrace_graph_call() - ftrace_graph_call()
...@@ -382,7 +406,9 @@ Basically, you will need to: ...@@ -382,7 +406,9 @@ Basically, you will need to:
- ftrace_disable_ftrace_graph_caller() - ftrace_disable_ftrace_graph_caller()
<details to be filled> <details to be filled>
Quick notes: Quick notes:
- add a nop stub after the ftrace_call location named ftrace_graph_call; - 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() 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 - update ftrace_graph_caller() to work with being called by the new
......
Documentation/trace/ftrace-uses.rst
View file @ bb2407a7
...@@ -21,13 +21,14 @@ how to use ftrace to implement your own function callbacks. ...@@ -21,13 +21,14 @@ how to use ftrace to implement your own function callbacks.
The ftrace context The ftrace context
================== ==================
.. warning::
WARNING: The ability to add a callback to almost any function within the The ability to add a callback to almost any function within the
kernel comes with risks. A callback can be called from any context kernel comes with risks. A callback can be called from any context
(normal, softirq, irq, and NMI). Callbacks can also be called just before (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. 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 This requires extra care to what can be done inside a callback. A callback
can be called outside the protective scope of RCU. can be called outside the protective scope of RCU.
The ftrace infrastructure has some protections agains recursions and RCU The ftrace infrastructure has some protections agains recursions and RCU
but one must still be very careful how they use the callbacks. but one must still be very careful how they use the callbacks.
...@@ -54,15 +55,15 @@ an ftrace_ops with ftrace: ...@@ -54,15 +55,15 @@ an ftrace_ops with ftrace:
Both .flags and .private are optional. Only .func is required. Both .flags and .private are optional. Only .func is required.
To enable tracing call:: To enable tracing call:
.. c:function:: register_ftrace_function(&ops); .. c:function:: register_ftrace_function(&ops);
To disable tracing call:: To disable tracing call:
.. c:function:: unregister_ftrace_function(&ops); .. 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> .. c:function:: #include <linux/ftrace.h>
...@@ -200,7 +201,7 @@ match a specific pattern. ...@@ -200,7 +201,7 @@ match a specific pattern.
See Filter Commands in :file:`Documentation/trace/ftrace.txt`. See Filter Commands in :file:`Documentation/trace/ftrace.txt`.
To just trace the schedule function:: To just trace the schedule function:
.. code-block:: c .. code-block:: c
...@@ -210,7 +211,7 @@ To add more functions, call the ftrace_set_filter() more than once with the ...@@ -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 @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. 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 .. code-block:: c
......
Documentation/trace/ftrace.txt → Documentation/trace/ftrace.rst
View file @ bb2407a7
ftrace - Function Tracer ========================
======================== ftrace - Function Tracer
========================
Copyright 2008 Red Hat Inc. Copyright 2008 Red Hat Inc.
Author: Steven Rostedt <srostedt@redhat.com>
License: The GNU Free Documentation License, Version 1.2 :Author: Steven Rostedt <srostedt@redhat.com>
:License: The GNU Free Documentation License, Version 1.2
(dual licensed under the GPL v2) (dual licensed under the GPL v2)
Original Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton, :Original Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton,
John Kacur, and David Teigland. John Kacur, and David Teigland.
Written for: 2.6.28-rc2
Updated for: 3.10 - Written for: 2.6.28-rc2
Updated for: 4.13 - Copyright 2017 VMware Inc. Steven Rostedt - Updated for: 3.10
- Updated for: 4.13 - Copyright 2017 VMware Inc. Steven Rostedt
- Converted to rst format - Changbin Du <changbin.du@intel.com>
Introduction Introduction
------------ ------------
...@@ -36,7 +40,7 @@ See events.txt for more information. ...@@ -36,7 +40,7 @@ See events.txt for more information.
Implementation Details Implementation Details
---------------------- ----------------------
See ftrace-design.txt for details for arch porters and such. See :doc:`ftrace-design` for details for arch porters and such.
The File System The File System
...@@ -47,38 +51,38 @@ well as the files to display output. ...@@ -47,38 +51,38 @@ well as the files to display output.
When tracefs is configured into the kernel (which selecting any ftrace When tracefs is configured into the kernel (which selecting any ftrace
option will do) the directory /sys/kernel/tracing will be created. To mount option will do) the directory /sys/kernel/tracing will be created. To mount
this directory, you can add to your /etc/fstab file: this directory, you can add to your /etc/fstab file::
tracefs /sys/kernel/tracing tracefs defaults 0 0 tracefs /sys/kernel/tracing tracefs defaults 0 0
Or you can mount it at run time with: Or you can mount it at run time with::
mount -t tracefs nodev /sys/kernel/tracing mount -t tracefs nodev /sys/kernel/tracing
For quicker access to that directory you may want to make a soft link to For quicker access to that directory you may want to make a soft link to
it: it::
ln -s /sys/kernel/tracing /tracing ln -s /sys/kernel/tracing /tracing
*** NOTICE *** .. attention::
Before 4.1, all ftrace tracing control files were within the debugfs Before 4.1, all ftrace tracing control files were within the debugfs
file system, which is typically located at /sys/kernel/debug/tracing. file system, which is typically located at /sys/kernel/debug/tracing.
For backward compatibility, when mounting the debugfs file system, For backward compatibility, when mounting the debugfs file system,
the tracefs file system will be automatically mounted at: the tracefs file system will be automatically mounted at:
/sys/kernel/debug/tracing /sys/kernel/debug/tracing
All files located in the tracefs file system will be located in that All files located in the tracefs file system will be located in that
debugfs file system directory as well. debugfs file system directory as well.
*** NOTICE *** .. attention::
Any selected ftrace option will also create the tracefs file system. Any selected ftrace option will also create the tracefs file system.
The rest of the document will assume that you are in the ftrace directory The rest of the document will assume that you are in the ftrace directory
(cd /sys/kernel/tracing) and will only concentrate on the files within that (cd /sys/kernel/tracing) and will only concentrate on the files within that
directory and not distract from the content with the extended directory and not distract from the content with the extended
"/sys/kernel/tracing" path name. "/sys/kernel/tracing" path name.
That's it! (assuming that you have ftrace configured into your kernel) That's it! (assuming that you have ftrace configured into your kernel)
...@@ -407,41 +411,48 @@ of ftrace. Here is a list of some of the key files: ...@@ -407,41 +411,48 @@ of ftrace. Here is a list of some of the key files:
CPUs. In other words, the local clocks may not be in sync CPUs. In other words, the local clocks may not be in sync
with local clocks on other CPUs. with local clocks on other CPUs.
Usual clocks for tracing: Usual clocks for tracing::
# cat trace_clock # cat trace_clock
[local] global counter x86-tsc [local] global counter x86-tsc
The clock with the square brackets around it is the one The clock with the square brackets around it is the one in effect.
in effect.
local: Default clock, but may not be in sync across CPUs local:
Default clock, but may not be in sync across CPUs
global: This clock is in sync with all CPUs but may global:
This clock is in sync with all CPUs but may
be a bit slower than the local clock. be a bit slower than the local clock.
counter: This is not a clock at all, but literally an atomic counter:
This is not a clock at all, but literally an atomic
counter. It counts up one by one, but is in sync counter. It counts up one by one, but is in sync
with all CPUs. This is useful when you need to with all CPUs. This is useful when you need to
know exactly the order events occurred with respect to know exactly the order events occurred with respect to
each other on different CPUs. each other on different CPUs.
uptime: This uses the jiffies counter and the time stamp uptime:
This uses the jiffies counter and the time stamp
is relative to the time since boot up. is relative to the time since boot up.
perf: This makes ftrace use the same clock that perf uses. perf:
This makes ftrace use the same clock that perf uses.
Eventually perf will be able to read ftrace buffers Eventually perf will be able to read ftrace buffers
and this will help out in interleaving the data. and this will help out in interleaving the data.
x86-tsc: Architectures may define their own clocks. For x86-tsc:
Architectures may define their own clocks. For
example, x86 uses its own TSC cycle clock here. example, x86 uses its own TSC cycle clock here.
ppc-tb: This uses the powerpc timebase register value. ppc-tb:
This uses the powerpc timebase register value.
This is in sync across CPUs and can also be used This is in sync across CPUs and can also be used
to correlate events across hypervisor/guest if to correlate events across hypervisor/guest if
tb_offset is known. tb_offset is known.
mono: This uses the fast monotonic clock (CLOCK_MONOTONIC) mono:
This uses the fast monotonic clock (CLOCK_MONOTONIC)
which is monotonic and is subject to NTP rate adjustments. which is monotonic and is subject to NTP rate adjustments.
mono_raw: mono_raw:
...@@ -449,7 +460,8 @@ of ftrace. Here is a list of some of the key files: ...@@ -449,7 +460,8 @@ of ftrace. Here is a list of some of the key files:
which is montonic but is not subject to any rate adjustments which is montonic but is not subject to any rate adjustments
and ticks at the same rate as the hardware clocksource. and ticks at the same rate as the hardware clocksource.
boot: This is the boot clock (CLOCK_BOOTTIME) and is based on the boot:
This is the boot clock (CLOCK_BOOTTIME) and is based on the
fast monotonic clock, but also accounts for time spent in fast monotonic clock, but also accounts for time spent in
suspend. Since the clock access is designed for use in suspend. Since the clock access is designed for use in
tracing in the suspend path, some side effects are possible tracing in the suspend path, some side effects are possible
...@@ -461,7 +473,7 @@ of ftrace. Here is a list of some of the key files: ...@@ -461,7 +473,7 @@ of ftrace. Here is a list of some of the key files:
processing should be able to handle them. See comments in the processing should be able to handle them. See comments in the
ktime_get_boot_fast_ns() function for more information. ktime_get_boot_fast_ns() function for more information.
To set a clock, simply echo the clock name into this file. To set a clock, simply echo the clock name into this file::
echo global > trace_clock echo global > trace_clock
...@@ -473,7 +485,7 @@ of ftrace. Here is a list of some of the key files: ...@@ -473,7 +485,7 @@ of ftrace. Here is a list of some of the key files:
It is useful in applications to open this file at the start It is useful in applications to open this file at the start
of the application and just reference the file descriptor of the application and just reference the file descriptor
for the file. for the file::
void trace_write(const char *fmt, ...) void trace_write(const char *fmt, ...)
{ {
...@@ -491,7 +503,7 @@ of ftrace. Here is a list of some of the key files: ...@@ -491,7 +503,7 @@ of ftrace. Here is a list of some of the key files:
write(trace_fd, buf, n); write(trace_fd, buf, n);
} }
start: start::
trace_fd = open("trace_marker", WR_ONLY); trace_fd = open("trace_marker", WR_ONLY);
...@@ -597,25 +609,33 @@ of ftrace. Here is a list of some of the key files: ...@@ -597,25 +609,33 @@ of ftrace. Here is a list of some of the key files:
This displays certain stats about the ring buffer: This displays certain stats about the ring buffer:
entries: The number of events that are still in the buffer. entries:
The number of events that are still in the buffer.
overrun: The number of lost events due to overwriting when overrun:
The number of lost events due to overwriting when
the buffer was full. the buffer was full.
commit overrun: Should always be zero. commit overrun:
Should always be zero.
This gets set if so many events happened within a nested This gets set if so many events happened within a nested
event (ring buffer is re-entrant), that it fills the event (ring buffer is re-entrant), that it fills the
buffer and starts dropping events. buffer and starts dropping events.
bytes: Bytes actually read (not overwritten). bytes:
Bytes actually read (not overwritten).
oldest event ts: The oldest timestamp in the buffer oldest event ts:
The oldest timestamp in the buffer
now ts: The current timestamp now ts:
The current timestamp
dropped events: Events lost due to overwrite option being off. dropped events:
Events lost due to overwrite option being off.
read events: The number of events read. read events:
The number of events read.
The Tracers The Tracers
----------- -----------
...@@ -716,20 +736,19 @@ user-land utilities). ...@@ -716,20 +736,19 @@ user-land utilities).
Output format: Output format:
-------------- --------------
Here is an example of the output format of the file "trace" Here is an example of the output format of the file "trace"::
-------- # tracer: function
# tracer: function #
# # entries-in-buffer/entries-written: 140080/250280 #P:4
# entries-in-buffer/entries-written: 140080/250280 #P:4 #
# # _-----=> irqs-off
# _-----=> irqs-off # / _----=> need-resched
# / _----=> need-resched # | / _---=> hardirq/softirq
# | / _---=> hardirq/softirq # || / _--=> preempt-depth
# || / _--=> preempt-depth # ||| / delay
# ||| / delay # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # | | | |||| | |
# | | | |||| | |
bash-1977 [000] .... 17284.993652: sys_close <-system_call_fastpath bash-1977 [000] .... 17284.993652: sys_close <-system_call_fastpath
bash-1977 [000] .... 17284.993653: __close_fd <-sys_close bash-1977 [000] .... 17284.993653: __close_fd <-sys_close
bash-1977 [000] .... 17284.993653: _raw_spin_lock <-__close_fd bash-1977 [000] .... 17284.993653: _raw_spin_lock <-__close_fd
...@@ -740,7 +759,7 @@ Here is an example of the output format of the file "trace" ...@@ -740,7 +759,7 @@ Here is an example of the output format of the file "trace"
bash-1977 [000] .... 17284.993657: filp_close <-__close_fd bash-1977 [000] .... 17284.993657: filp_close <-__close_fd
bash-1977 [000] .... 17284.993657: dnotify_flush <-filp_close bash-1977 [000] .... 17284.993657: dnotify_flush <-filp_close
sshd-1974 [003] .... 17284.993658: sys_select <-system_call_fastpath sshd-1974 [003] .... 17284.993658: sys_select <-system_call_fastpath
-------- ....
A header is printed with the tracer name that is represented by A header is printed with the tracer name that is represented by
the trace. In this case the tracer is "function". Then it shows the the trace. In this case the tracer is "function". Then it shows the
...@@ -761,28 +780,28 @@ Latency trace format ...@@ -761,28 +780,28 @@ Latency trace format
When the latency-format option is enabled or when one of the latency When the latency-format option is enabled or when one of the latency
tracers is set, the trace file gives somewhat more information to see tracers is set, the trace file gives somewhat more information to see
why a latency happened. Here is a typical trace. why a latency happened. Here is a typical trace::
# tracer: irqsoff # tracer: irqsoff
# #
# irqsoff latency trace v1.1.5 on 3.8.0-test+ # irqsoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 259 us, #4/4, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 259 us, #4/4, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: ps-6143 (uid:0 nice:0 policy:0 rt_prio:0) # | task: ps-6143 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: __lock_task_sighand # => started at: __lock_task_sighand
# => ended at: _raw_spin_unlock_irqrestore # => ended at: _raw_spin_unlock_irqrestore
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
ps-6143 2d... 0us!: trace_hardirqs_off <-__lock_task_sighand ps-6143 2d... 0us!: trace_hardirqs_off <-__lock_task_sighand
ps-6143 2d..1 259us+: trace_hardirqs_on <-_raw_spin_unlock_irqrestore ps-6143 2d..1 259us+: trace_hardirqs_on <-_raw_spin_unlock_irqrestore
ps-6143 2d..1 263us+: time_hardirqs_on <-_raw_spin_unlock_irqrestore ps-6143 2d..1 263us+: time_hardirqs_on <-_raw_spin_unlock_irqrestore
...@@ -813,8 +832,8 @@ occurred. (ps pid: 6143). ...@@ -813,8 +832,8 @@ occurred. (ps pid: 6143).
The start and stop (the functions in which the interrupts were The start and stop (the functions in which the interrupts were
disabled and enabled respectively) that caused the latencies: disabled and enabled respectively) that caused the latencies:
__lock_task_sighand is where the interrupts were disabled. - __lock_task_sighand is where the interrupts were disabled.
_raw_spin_unlock_irqrestore is where they were enabled again. - _raw_spin_unlock_irqrestore is where they were enabled again.
The next lines after the header are the trace itself. The header The next lines after the header are the trace itself. The header
explains which is which. explains which is which.
...@@ -826,44 +845,47 @@ explains which is which. ...@@ -826,44 +845,47 @@ explains which is which.
CPU#: The CPU which the process was running on. CPU#: The CPU which the process was running on.
irqs-off: 'd' interrupts are disabled. '.' otherwise. irqs-off: 'd' interrupts are disabled. '.' otherwise.
Note: If the architecture does not support a way to .. caution:: If the architecture does not support a way to
read the irq flags variable, an 'X' will always read the irq flags variable, an 'X' will always
be printed here. be printed here.
need-resched: need-resched:
'N' both TIF_NEED_RESCHED and PREEMPT_NEED_RESCHED is set, - 'N' both TIF_NEED_RESCHED and PREEMPT_NEED_RESCHED is set,
'n' only TIF_NEED_RESCHED is set, - 'n' only TIF_NEED_RESCHED is set,
'p' only PREEMPT_NEED_RESCHED is set, - 'p' only PREEMPT_NEED_RESCHED is set,
'.' otherwise. - '.' otherwise.
hardirq/softirq: hardirq/softirq:
'Z' - NMI occurred inside a hardirq - 'Z' - NMI occurred inside a hardirq
'z' - NMI is running - 'z' - NMI is running
'H' - hard irq occurred inside a softirq. - 'H' - hard irq occurred inside a softirq.
'h' - hard irq is running - 'h' - hard irq is running
's' - soft irq is running - 's' - soft irq is running
'.' - normal context. - '.' - normal context.
preempt-depth: The level of preempt_disabled preempt-depth: The level of preempt_disabled
The above is mostly meaningful for kernel developers. The above is mostly meaningful for kernel developers.
time: When the latency-format option is enabled, the trace file time:
When the latency-format option is enabled, the trace file
output includes a timestamp relative to the start of the output includes a timestamp relative to the start of the
trace. This differs from the output when latency-format trace. This differs from the output when latency-format
is disabled, which includes an absolute timestamp. is disabled, which includes an absolute timestamp.
delay: This is just to help catch your eye a bit better. And delay:
This is just to help catch your eye a bit better. And
needs to be fixed to be only relative to the same CPU. needs to be fixed to be only relative to the same CPU.
The marks are determined by the difference between this The marks are determined by the difference between this
current trace and the next trace. current trace and the next trace.
'$' - greater than 1 second
'@' - greater than 100 milisecond - '$' - greater than 1 second
'*' - greater than 10 milisecond - '@' - greater than 100 milisecond
'#' - greater than 1000 microsecond - '*' - greater than 10 milisecond
'!' - greater than 100 microsecond - '#' - greater than 1000 microsecond
'+' - greater than 10 microsecond - '!' - greater than 100 microsecond
' ' - less than or equal to 10 microsecond. - '+' - greater than 10 microsecond
- ' ' - less than or equal to 10 microsecond.
The rest is the same as the 'trace' file. The rest is the same as the 'trace' file.
...@@ -875,50 +897,52 @@ trace_options ...@@ -875,50 +897,52 @@ trace_options
The trace_options file (or the options directory) is used to control The trace_options file (or the options directory) is used to control
what gets printed in the trace output, or manipulate the tracers. what gets printed in the trace output, or manipulate the tracers.
To see what is available, simply cat the file: To see what is available, simply cat the file::
cat trace_options cat trace_options
print-parent print-parent
nosym-offset nosym-offset
nosym-addr nosym-addr
noverbose noverbose
noraw noraw
nohex nohex
nobin nobin
noblock noblock
trace_printk trace_printk
annotate annotate
nouserstacktrace nouserstacktrace
nosym-userobj nosym-userobj
noprintk-msg-only noprintk-msg-only
context-info context-info
nolatency-format nolatency-format
record-cmd record-cmd
norecord-tgid norecord-tgid
overwrite overwrite
nodisable_on_free nodisable_on_free
irq-info irq-info
markers markers
noevent-fork noevent-fork
function-trace function-trace
nofunction-fork nofunction-fork
nodisplay-graph nodisplay-graph
nostacktrace nostacktrace
nobranch nobranch
To disable one of the options, echo in the option prepended with To disable one of the options, echo in the option prepended with
"no". "no"::
echo noprint-parent > trace_options echo noprint-parent > trace_options
To enable an option, leave off the "no". To enable an option, leave off the "no"::
echo sym-offset > trace_options echo sym-offset > trace_options
Here are the available options: Here are the available options:
print-parent - On function traces, display the calling (parent) print-parent
On function traces, display the calling (parent)
function as well as the function being traced. function as well as the function being traced.
::
print-parent: print-parent:
bash-4000 [01] 1477.606694: simple_strtoul <-kstrtoul bash-4000 [01] 1477.606694: simple_strtoul <-kstrtoul
...@@ -927,61 +951,74 @@ Here are the available options: ...@@ -927,61 +951,74 @@ Here are the available options:
bash-4000 [01] 1477.606694: simple_strtoul bash-4000 [01] 1477.606694: simple_strtoul
sym-offset - Display not only the function name, but also the sym-offset
Display not only the function name, but also the
offset in the function. For example, instead of offset in the function. For example, instead of
seeing just "ktime_get", you will see seeing just "ktime_get", you will see
"ktime_get+0xb/0x20". "ktime_get+0xb/0x20".
::
sym-offset: sym-offset:
bash-4000 [01] 1477.606694: simple_strtoul+0x6/0xa0 bash-4000 [01] 1477.606694: simple_strtoul+0x6/0xa0
sym-addr - this will also display the function address as well sym-addr
This will also display the function address as well
as the function name. as the function name.
::
sym-addr: sym-addr:
bash-4000 [01] 1477.606694: simple_strtoul <c0339346> bash-4000 [01] 1477.606694: simple_strtoul <c0339346>
verbose - This deals with the trace file when the verbose
This deals with the trace file when the
latency-format option is enabled. latency-format option is enabled.
::
bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \ bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \
(+0.000ms): simple_strtoul (kstrtoul) (+0.000ms): simple_strtoul (kstrtoul)
raw - This will display raw numbers. This option is best for raw
This will display raw numbers. This option is best for
use with user applications that can translate the raw use with user applications that can translate the raw
numbers better than having it done in the kernel. numbers better than having it done in the kernel.
hex - Similar to raw, but the numbers will be in a hexadecimal hex
format. Similar to raw, but the numbers will be in a hexadecimal format.
bin - This will print out the formats in raw binary. bin
This will print out the formats in raw binary.
block - When set, reading trace_pipe will not block when polled. block
When set, reading trace_pipe will not block when polled.
trace_printk - Can disable trace_printk() from writing into the buffer. trace_printk
Can disable trace_printk() from writing into the buffer.
annotate - It is sometimes confusing when the CPU buffers are full annotate
It is sometimes confusing when the CPU buffers are full
and one CPU buffer had a lot of events recently, thus and one CPU buffer had a lot of events recently, thus
a shorter time frame, were another CPU may have only had a shorter time frame, were another CPU may have only had
a few events, which lets it have older events. When a few events, which lets it have older events. When
the trace is reported, it shows the oldest events first, the trace is reported, it shows the oldest events first,
and it may look like only one CPU ran (the one with the and it may look like only one CPU ran (the one with the
oldest events). When the annotate option is set, it will oldest events). When the annotate option is set, it will
display when a new CPU buffer started: display when a new CPU buffer started::
<idle>-0 [001] dNs4 21169.031481: wake_up_idle_cpu <-add_timer_on <idle>-0 [001] dNs4 21169.031481: wake_up_idle_cpu <-add_timer_on
<idle>-0 [001] dNs4 21169.031482: _raw_spin_unlock_irqrestore <-add_timer_on <idle>-0 [001] dNs4 21169.031482: _raw_spin_unlock_irqrestore <-add_timer_on
<idle>-0 [001] .Ns4 21169.031484: sub_preempt_count <-_raw_spin_unlock_irqrestore <idle>-0 [001] .Ns4 21169.031484: sub_preempt_count <-_raw_spin_unlock_irqrestore
##### CPU 2 buffer started #### ##### CPU 2 buffer started ####
<idle>-0 [002] .N.1 21169.031484: rcu_idle_exit <-cpu_idle <idle>-0 [002] .N.1 21169.031484: rcu_idle_exit <-cpu_idle
<idle>-0 [001] .Ns3 21169.031484: _raw_spin_unlock <-clocksource_watchdog <idle>-0 [001] .Ns3 21169.031484: _raw_spin_unlock <-clocksource_watchdog
<idle>-0 [001] .Ns3 21169.031485: sub_preempt_count <-_raw_spin_unlock <idle>-0 [001] .Ns3 21169.031485: sub_preempt_count <-_raw_spin_unlock
userstacktrace - This option changes the trace. It records a userstacktrace
This option changes the trace. It records a
stacktrace of the current user space thread after stacktrace of the current user space thread after
each trace event. each trace event.
sym-userobj - when user stacktrace are enabled, look up which sym-userobj
when user stacktrace are enabled, look up which
object the address belongs to, and print a object the address belongs to, and print a
relative address. This is especially useful when relative address. This is especially useful when
ASLR is on, otherwise you don't get a chance to ASLR is on, otherwise you don't get a chance to
...@@ -989,91 +1026,106 @@ Here are the available options: ...@@ -989,91 +1026,106 @@ Here are the available options:
the app is no longer running the app is no longer running
The lookup is performed when you read The lookup is performed when you read
trace,trace_pipe. Example: trace,trace_pipe. Example::
a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0
x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6]
printk-msg-only - When set, trace_printk()s will only show the format printk-msg-only
When set, trace_printk()s will only show the format
and not their parameters (if trace_bprintk() or and not their parameters (if trace_bprintk() or
trace_bputs() was used to save the trace_printk()). trace_bputs() was used to save the trace_printk()).
context-info - Show only the event data. Hides the comm, PID, context-info
Show only the event data. Hides the comm, PID,
timestamp, CPU, and other useful data. timestamp, CPU, and other useful data.
latency-format - This option changes the trace output. When it is enabled, latency-format
This option changes the trace output. When it is enabled,
the trace displays additional information about the the trace displays additional information about the
latency, as described in "Latency trace format". latency, as described in "Latency trace format".
record-cmd - When any event or tracer is enabled, a hook is enabled record-cmd
When any event or tracer is enabled, a hook is enabled
in the sched_switch trace point to fill comm cache in the sched_switch trace point to fill comm cache
with mapped pids and comms. But this may cause some with mapped pids and comms. But this may cause some
overhead, and if you only care about pids, and not the overhead, and if you only care about pids, and not the
name of the task, disabling this option can lower the name of the task, disabling this option can lower the
impact of tracing. See "saved_cmdlines". impact of tracing. See "saved_cmdlines".
record-tgid - When any event or tracer is enabled, a hook is enabled record-tgid
When any event or tracer is enabled, a hook is enabled
in the sched_switch trace point to fill the cache of in the sched_switch trace point to fill the cache of
mapped Thread Group IDs (TGID) mapping to pids. See mapped Thread Group IDs (TGID) mapping to pids. See
"saved_tgids". "saved_tgids".
overwrite - This controls what happens when the trace buffer is overwrite
This controls what happens when the trace buffer is
full. If "1" (default), the oldest events are full. If "1" (default), the oldest events are
discarded and overwritten. If "0", then the newest discarded and overwritten. If "0", then the newest
events are discarded. events are discarded.
(see per_cpu/cpu0/stats for overrun and dropped) (see per_cpu/cpu0/stats for overrun and dropped)
disable_on_free - When the free_buffer is closed, tracing will disable_on_free
When the free_buffer is closed, tracing will
stop (tracing_on set to 0). stop (tracing_on set to 0).
irq-info - Shows the interrupt, preempt count, need resched data. irq-info
When disabled, the trace looks like: Shows the interrupt, preempt count, need resched data.
When disabled, the trace looks like::
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 144405/9452052 #P:4 # entries-in-buffer/entries-written: 144405/9452052 #P:4
# #
# TASK-PID CPU# TIMESTAMP FUNCTION # TASK-PID CPU# TIMESTAMP FUNCTION
# | | | | | # | | | | |
<idle>-0 [002] 23636.756054: ttwu_do_activate.constprop.89 <-try_to_wake_up <idle>-0 [002] 23636.756054: ttwu_do_activate.constprop.89 <-try_to_wake_up
<idle>-0 [002] 23636.756054: activate_task <-ttwu_do_activate.constprop.89 <idle>-0 [002] 23636.756054: activate_task <-ttwu_do_activate.constprop.89
<idle>-0 [002] 23636.756055: enqueue_task <-activate_task <idle>-0 [002] 23636.756055: enqueue_task <-activate_task
markers - When set, the trace_marker is writable (only by root). markers
When set, the trace_marker is writable (only by root).
When disabled, the trace_marker will error with EINVAL When disabled, the trace_marker will error with EINVAL
on write. on write.
event-fork - When set, tasks with PIDs listed in set_event_pid will have event-fork
When set, tasks with PIDs listed in set_event_pid will have
the PIDs of their children added to set_event_pid when those the PIDs of their children added to set_event_pid when those
tasks fork. Also, when tasks with PIDs in set_event_pid exit, tasks fork. Also, when tasks with PIDs in set_event_pid exit,
their PIDs will be removed from the file. their PIDs will be removed from the file.
function-trace - The latency tracers will enable function tracing function-trace
The latency tracers will enable function tracing
if this option is enabled (default it is). When if this option is enabled (default it is). When
it is disabled, the latency tracers do not trace it is disabled, the latency tracers do not trace
functions. This keeps the overhead of the tracer down functions. This keeps the overhead of the tracer down
when performing latency tests. when performing latency tests.
function-fork - When set, tasks with PIDs listed in set_ftrace_pid will function-fork
When set, tasks with PIDs listed in set_ftrace_pid will
have the PIDs of their children added to set_ftrace_pid have the PIDs of their children added to set_ftrace_pid
when those tasks fork. Also, when tasks with PIDs in when those tasks fork. Also, when tasks with PIDs in
set_ftrace_pid exit, their PIDs will be removed from the set_ftrace_pid exit, their PIDs will be removed from the
file. file.
display-graph - When set, the latency tracers (irqsoff, wakeup, etc) will display-graph
When set, the latency tracers (irqsoff, wakeup, etc) will
use function graph tracing instead of function tracing. use function graph tracing instead of function tracing.
stacktrace - When set, a stack trace is recorded after any trace event stacktrace
When set, a stack trace is recorded after any trace event
is recorded. is recorded.
branch - Enable branch tracing with the tracer. This enables branch branch
Enable branch tracing with the tracer. This enables branch
tracer along with the currently set tracer. Enabling this tracer along with the currently set tracer. Enabling this
with the "nop" tracer is the same as just enabling the with the "nop" tracer is the same as just enabling the
"branch" tracer. "branch" tracer.
Note: Some tracers have their own options. They only appear in this .. tip:: Some tracers have their own options. They only appear in this
file when the tracer is active. They always appear in the file when the tracer is active. They always appear in the
options directory. options directory.
...@@ -1082,7 +1134,8 @@ Here are the per tracer options: ...@@ -1082,7 +1134,8 @@ Here are the per tracer options:
Options for function tracer: Options for function tracer:
func_stack_trace - When set, a stack trace is recorded after every func_stack_trace
When set, a stack trace is recorded after every
function that is recorded. NOTE! Limit the functions function that is recorded. NOTE! Limit the functions
that are recorded before enabling this, with that are recorded before enabling this, with
"set_ftrace_filter" otherwise the system performance "set_ftrace_filter" otherwise the system performance
...@@ -1094,7 +1147,8 @@ Options for function_graph tracer: ...@@ -1094,7 +1147,8 @@ Options for function_graph tracer:
Since the function_graph tracer has a slightly different output Since the function_graph tracer has a slightly different output
it has its own options to control what is displayed. it has its own options to control what is displayed.
funcgraph-overrun - When set, the "overrun" of the graph stack is funcgraph-overrun
When set, the "overrun" of the graph stack is
displayed after each function traced. The displayed after each function traced. The
overrun, is when the stack depth of the calls overrun, is when the stack depth of the calls
is greater than what is reserved for each task. is greater than what is reserved for each task.
...@@ -1104,41 +1158,49 @@ Options for function_graph tracer: ...@@ -1104,41 +1158,49 @@ Options for function_graph tracer:
The overrun is the number of functions missed The overrun is the number of functions missed
due to exceeding this array. due to exceeding this array.
funcgraph-cpu - When set, the CPU number of the CPU where the trace funcgraph-cpu
When set, the CPU number of the CPU where the trace
occurred is displayed. occurred is displayed.
funcgraph-overhead - When set, if the function takes longer than funcgraph-overhead
When set, if the function takes longer than
A certain amount, then a delay marker is A certain amount, then a delay marker is
displayed. See "delay" above, under the displayed. See "delay" above, under the
header description. header description.
funcgraph-proc - Unlike other tracers, the process' command line funcgraph-proc
Unlike other tracers, the process' command line
is not displayed by default, but instead only is not displayed by default, but instead only
when a task is traced in and out during a context when a task is traced in and out during a context
switch. Enabling this options has the command switch. Enabling this options has the command
of each process displayed at every line. of each process displayed at every line.
funcgraph-duration - At the end of each function (the return) funcgraph-duration
At the end of each function (the return)
the duration of the amount of time in the the duration of the amount of time in the
function is displayed in microseconds. function is displayed in microseconds.
funcgraph-abstime - When set, the timestamp is displayed at each funcgraph-abstime
line. When set, the timestamp is displayed at each line.
funcgraph-irqs - When disabled, functions that happen inside an funcgraph-irqs
When disabled, functions that happen inside an
interrupt will not be traced. interrupt will not be traced.
funcgraph-tail - When set, the return event will include the function funcgraph-tail
When set, the return event will include the function
that it represents. By default this is off, and that it represents. By default this is off, and
only a closing curly bracket "}" is displayed for only a closing curly bracket "}" is displayed for
the return of a function. the return of a function.
sleep-time - When running function graph tracer, to include sleep-time
When running function graph tracer, to include
the time a task schedules out in its function. the time a task schedules out in its function.
When enabled, it will account time the task has been When enabled, it will account time the task has been
scheduled out as part of the function call. scheduled out as part of the function call.
graph-time - When running function profiler with function graph tracer, graph-time
When running function profiler with function graph tracer,
to include the time to call nested functions. When this is to include the time to call nested functions. When this is
not set, the time reported for the function will only not set, the time reported for the function will only
include the time the function itself executed for, not the include the time the function itself executed for, not the
...@@ -1146,7 +1208,8 @@ Options for function_graph tracer: ...@@ -1146,7 +1208,8 @@ Options for function_graph tracer:
Options for blk tracer: Options for blk tracer:
blk_classic - Shows a more minimalistic output. blk_classic
Shows a more minimalistic output.
irqsoff irqsoff
...@@ -1165,7 +1228,7 @@ new maximum is reached, the old saved trace is discarded and the ...@@ -1165,7 +1228,7 @@ new maximum is reached, the old saved trace is discarded and the
new trace is saved. new trace is saved.
To reset the maximum, echo 0 into tracing_max_latency. Here is To reset the maximum, echo 0 into tracing_max_latency. Here is
an example: an example::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo irqsoff > current_tracer # echo irqsoff > current_tracer
...@@ -1175,26 +1238,26 @@ an example: ...@@ -1175,26 +1238,26 @@ an example:
[...] [...]
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: irqsoff # tracer: irqsoff
# #
# irqsoff latency trace v1.1.5 on 3.8.0-test+ # irqsoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 16 us, #4/4, CPU#0 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 16 us, #4/4, CPU#0 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: swapper/0-0 (uid:0 nice:0 policy:0 rt_prio:0) # | task: swapper/0-0 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: run_timer_softirq # => started at: run_timer_softirq
# => ended at: run_timer_softirq # => ended at: run_timer_softirq
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
<idle>-0 0d.s2 0us+: _raw_spin_lock_irq <-run_timer_softirq <idle>-0 0d.s2 0us+: _raw_spin_lock_irq <-run_timer_softirq
<idle>-0 0dNs3 17us : _raw_spin_unlock_irq <-run_timer_softirq <idle>-0 0dNs3 17us : _raw_spin_unlock_irq <-run_timer_softirq
<idle>-0 0dNs3 17us+: trace_hardirqs_on <-run_timer_softirq <idle>-0 0dNs3 17us+: trace_hardirqs_on <-run_timer_softirq
...@@ -1222,30 +1285,30 @@ between the time of recording the max latency and the time of ...@@ -1222,30 +1285,30 @@ between the time of recording the max latency and the time of
recording the function that had that latency. recording the function that had that latency.
Note the above example had function-trace not set. If we set Note the above example had function-trace not set. If we set
function-trace, we get a much larger output: function-trace, we get a much larger output::
with echo 1 > options/function-trace with echo 1 > options/function-trace
# tracer: irqsoff # tracer: irqsoff
# #
# irqsoff latency trace v1.1.5 on 3.8.0-test+ # irqsoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 71 us, #168/168, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 71 us, #168/168, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: bash-2042 (uid:0 nice:0 policy:0 rt_prio:0) # | task: bash-2042 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: ata_scsi_queuecmd # => started at: ata_scsi_queuecmd
# => ended at: ata_scsi_queuecmd # => ended at: ata_scsi_queuecmd
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
bash-2042 3d... 0us : _raw_spin_lock_irqsave <-ata_scsi_queuecmd bash-2042 3d... 0us : _raw_spin_lock_irqsave <-ata_scsi_queuecmd
bash-2042 3d... 0us : add_preempt_count <-_raw_spin_lock_irqsave bash-2042 3d... 0us : add_preempt_count <-_raw_spin_lock_irqsave
bash-2042 3d..1 1us : ata_scsi_find_dev <-ata_scsi_queuecmd bash-2042 3d..1 1us : ata_scsi_find_dev <-ata_scsi_queuecmd
...@@ -1255,7 +1318,7 @@ function-trace, we get a much larger output: ...@@ -1255,7 +1318,7 @@ function-trace, we get a much larger output:
bash-2042 3d..1 3us : ata_sg_init <-__ata_scsi_queuecmd bash-2042 3d..1 3us : ata_sg_init <-__ata_scsi_queuecmd
bash-2042 3d..1 4us : ata_scsi_rw_xlat <-__ata_scsi_queuecmd bash-2042 3d..1 4us : ata_scsi_rw_xlat <-__ata_scsi_queuecmd
bash-2042 3d..1 4us : ata_build_rw_tf <-ata_scsi_rw_xlat bash-2042 3d..1 4us : ata_build_rw_tf <-ata_scsi_rw_xlat
[...] [...]
bash-2042 3d..1 67us : delay_tsc <-__delay bash-2042 3d..1 67us : delay_tsc <-__delay
bash-2042 3d..1 67us : add_preempt_count <-delay_tsc bash-2042 3d..1 67us : add_preempt_count <-delay_tsc
bash-2042 3d..2 67us : sub_preempt_count <-delay_tsc bash-2042 3d..2 67us : sub_preempt_count <-delay_tsc
...@@ -1312,6 +1375,7 @@ The preemptoff tracer traces the places that disable preemption. ...@@ -1312,6 +1375,7 @@ The preemptoff tracer traces the places that disable preemption.
Like the irqsoff tracer, it records the maximum latency for Like the irqsoff tracer, it records the maximum latency for
which preemption was disabled. The control of preemptoff tracer which preemption was disabled. The control of preemptoff tracer
is much like the irqsoff tracer. is much like the irqsoff tracer.
::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo preemptoff > current_tracer # echo preemptoff > current_tracer
...@@ -1321,26 +1385,26 @@ is much like the irqsoff tracer. ...@@ -1321,26 +1385,26 @@ is much like the irqsoff tracer.
[...] [...]
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: preemptoff # tracer: preemptoff
# #
# preemptoff latency trace v1.1.5 on 3.8.0-test+ # preemptoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 46 us, #4/4, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 46 us, #4/4, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: sshd-1991 (uid:0 nice:0 policy:0 rt_prio:0) # | task: sshd-1991 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: do_IRQ # => started at: do_IRQ
# => ended at: do_IRQ # => ended at: do_IRQ
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
sshd-1991 1d.h. 0us+: irq_enter <-do_IRQ sshd-1991 1d.h. 0us+: irq_enter <-do_IRQ
sshd-1991 1d..1 46us : irq_exit <-do_IRQ sshd-1991 1d..1 46us : irq_exit <-do_IRQ
sshd-1991 1d..1 47us+: trace_preempt_on <-do_IRQ sshd-1991 1d..1 47us+: trace_preempt_on <-do_IRQ
...@@ -1357,33 +1421,34 @@ But we also see that interrupts have been disabled when entering ...@@ -1357,33 +1421,34 @@ But we also see that interrupts have been disabled when entering
the preempt off section and leaving it (the 'd'). We do not know if the preempt off section and leaving it (the 'd'). We do not know if
interrupts were enabled in the mean time or shortly after this interrupts were enabled in the mean time or shortly after this
was over. was over.
::
# tracer: preemptoff # tracer: preemptoff
# #
# preemptoff latency trace v1.1.5 on 3.8.0-test+ # preemptoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 83 us, #241/241, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 83 us, #241/241, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: bash-1994 (uid:0 nice:0 policy:0 rt_prio:0) # | task: bash-1994 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: wake_up_new_task # => started at: wake_up_new_task
# => ended at: task_rq_unlock # => ended at: task_rq_unlock
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
bash-1994 1d..1 0us : _raw_spin_lock_irqsave <-wake_up_new_task bash-1994 1d..1 0us : _raw_spin_lock_irqsave <-wake_up_new_task
bash-1994 1d..1 0us : select_task_rq_fair <-select_task_rq bash-1994 1d..1 0us : select_task_rq_fair <-select_task_rq
bash-1994 1d..1 1us : __rcu_read_lock <-select_task_rq_fair bash-1994 1d..1 1us : __rcu_read_lock <-select_task_rq_fair
bash-1994 1d..1 1us : source_load <-select_task_rq_fair bash-1994 1d..1 1us : source_load <-select_task_rq_fair
bash-1994 1d..1 1us : source_load <-select_task_rq_fair bash-1994 1d..1 1us : source_load <-select_task_rq_fair
[...] [...]
bash-1994 1d..1 12us : irq_enter <-smp_apic_timer_interrupt bash-1994 1d..1 12us : irq_enter <-smp_apic_timer_interrupt
bash-1994 1d..1 12us : rcu_irq_enter <-irq_enter bash-1994 1d..1 12us : rcu_irq_enter <-irq_enter
bash-1994 1d..1 13us : add_preempt_count <-irq_enter bash-1994 1d..1 13us : add_preempt_count <-irq_enter
...@@ -1392,7 +1457,7 @@ was over. ...@@ -1392,7 +1457,7 @@ was over.
bash-1994 1d.h1 13us : _raw_spin_lock <-hrtimer_interrupt bash-1994 1d.h1 13us : _raw_spin_lock <-hrtimer_interrupt
bash-1994 1d.h1 14us : add_preempt_count <-_raw_spin_lock bash-1994 1d.h1 14us : add_preempt_count <-_raw_spin_lock
bash-1994 1d.h2 14us : ktime_get_update_offsets <-hrtimer_interrupt bash-1994 1d.h2 14us : ktime_get_update_offsets <-hrtimer_interrupt
[...] [...]
bash-1994 1d.h1 35us : lapic_next_event <-clockevents_program_event bash-1994 1d.h1 35us : lapic_next_event <-clockevents_program_event
bash-1994 1d.h1 35us : irq_exit <-smp_apic_timer_interrupt bash-1994 1d.h1 35us : irq_exit <-smp_apic_timer_interrupt
bash-1994 1d.h1 36us : sub_preempt_count <-irq_exit bash-1994 1d.h1 36us : sub_preempt_count <-irq_exit
...@@ -1403,7 +1468,7 @@ was over. ...@@ -1403,7 +1468,7 @@ was over.
bash-1994 1d.s3 38us : _raw_spin_unlock <-run_timer_softirq bash-1994 1d.s3 38us : _raw_spin_unlock <-run_timer_softirq
bash-1994 1d.s3 39us : sub_preempt_count <-_raw_spin_unlock bash-1994 1d.s3 39us : sub_preempt_count <-_raw_spin_unlock
bash-1994 1d.s2 39us : call_timer_fn <-run_timer_softirq bash-1994 1d.s2 39us : call_timer_fn <-run_timer_softirq
[...] [...]
bash-1994 1dNs2 81us : cpu_needs_another_gp <-rcu_process_callbacks bash-1994 1dNs2 81us : cpu_needs_another_gp <-rcu_process_callbacks
bash-1994 1dNs2 82us : __local_bh_enable <-__do_softirq bash-1994 1dNs2 82us : __local_bh_enable <-__do_softirq
bash-1994 1dNs2 82us : sub_preempt_count <-__local_bh_enable bash-1994 1dNs2 82us : sub_preempt_count <-__local_bh_enable
...@@ -1437,7 +1502,7 @@ preemption disabled for the longest times is helpful. But ...@@ -1437,7 +1502,7 @@ preemption disabled for the longest times is helpful. But
sometimes we would like to know when either preemption and/or sometimes we would like to know when either preemption and/or
interrupts are disabled. interrupts are disabled.
Consider the following code: Consider the following code::
local_irq_disable(); local_irq_disable();
call_function_with_irqs_off(); call_function_with_irqs_off();
...@@ -1462,6 +1527,7 @@ tracer. ...@@ -1462,6 +1527,7 @@ tracer.
Again, using this trace is much like the irqsoff and preemptoff Again, using this trace is much like the irqsoff and preemptoff
tracers. tracers.
::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo preemptirqsoff > current_tracer # echo preemptirqsoff > current_tracer
...@@ -1471,26 +1537,26 @@ tracers. ...@@ -1471,26 +1537,26 @@ tracers.
[...] [...]
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: preemptirqsoff # tracer: preemptirqsoff
# #
# preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ # preemptirqsoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 100 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 100 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: ls-2230 (uid:0 nice:0 policy:0 rt_prio:0) # | task: ls-2230 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: ata_scsi_queuecmd # => started at: ata_scsi_queuecmd
# => ended at: ata_scsi_queuecmd # => ended at: ata_scsi_queuecmd
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
ls-2230 3d... 0us+: _raw_spin_lock_irqsave <-ata_scsi_queuecmd ls-2230 3d... 0us+: _raw_spin_lock_irqsave <-ata_scsi_queuecmd
ls-2230 3...1 100us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd ls-2230 3...1 100us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd
ls-2230 3...1 101us+: trace_preempt_on <-ata_scsi_queuecmd ls-2230 3...1 101us+: trace_preempt_on <-ata_scsi_queuecmd
...@@ -1522,53 +1588,53 @@ function tracing, we do not know if interrupts were enabled ...@@ -1522,53 +1588,53 @@ function tracing, we do not know if interrupts were enabled
within the preemption points. We do see that it started with within the preemption points. We do see that it started with
preemption enabled. preemption enabled.
Here is a trace with function-trace set: Here is a trace with function-trace set::
# tracer: preemptirqsoff # tracer: preemptirqsoff
# #
# preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ # preemptirqsoff latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 161 us, #339/339, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 161 us, #339/339, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: ls-2269 (uid:0 nice:0 policy:0 rt_prio:0) # | task: ls-2269 (uid:0 nice:0 policy:0 rt_prio:0)
# ----------------- # -----------------
# => started at: schedule # => started at: schedule
# => ended at: mutex_unlock # => ended at: mutex_unlock
# #
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
kworker/-59 3...1 0us : __schedule <-schedule kworker/-59 3...1 0us : __schedule <-schedule
kworker/-59 3d..1 0us : rcu_preempt_qs <-rcu_note_context_switch kworker/-59 3d..1 0us : rcu_preempt_qs <-rcu_note_context_switch
kworker/-59 3d..1 1us : add_preempt_count <-_raw_spin_lock_irq kworker/-59 3d..1 1us : add_preempt_count <-_raw_spin_lock_irq
kworker/-59 3d..2 1us : deactivate_task <-__schedule kworker/-59 3d..2 1us : deactivate_task <-__schedule
kworker/-59 3d..2 1us : dequeue_task <-deactivate_task kworker/-59 3d..2 1us : dequeue_task <-deactivate_task
kworker/-59 3d..2 2us : update_rq_clock <-dequeue_task kworker/-59 3d..2 2us : update_rq_clock <-dequeue_task
kworker/-59 3d..2 2us : dequeue_task_fair <-dequeue_task kworker/-59 3d..2 2us : dequeue_task_fair <-dequeue_task
kworker/-59 3d..2 2us : update_curr <-dequeue_task_fair kworker/-59 3d..2 2us : update_curr <-dequeue_task_fair
kworker/-59 3d..2 2us : update_min_vruntime <-update_curr kworker/-59 3d..2 2us : update_min_vruntime <-update_curr
kworker/-59 3d..2 3us : cpuacct_charge <-update_curr kworker/-59 3d..2 3us : cpuacct_charge <-update_curr
kworker/-59 3d..2 3us : __rcu_read_lock <-cpuacct_charge kworker/-59 3d..2 3us : __rcu_read_lock <-cpuacct_charge
kworker/-59 3d..2 3us : __rcu_read_unlock <-cpuacct_charge kworker/-59 3d..2 3us : __rcu_read_unlock <-cpuacct_charge
kworker/-59 3d..2 3us : update_cfs_rq_blocked_load <-dequeue_task_fair kworker/-59 3d..2 3us : update_cfs_rq_blocked_load <-dequeue_task_fair
kworker/-59 3d..2 4us : clear_buddies <-dequeue_task_fair kworker/-59 3d..2 4us : clear_buddies <-dequeue_task_fair
kworker/-59 3d..2 4us : account_entity_dequeue <-dequeue_task_fair kworker/-59 3d..2 4us : account_entity_dequeue <-dequeue_task_fair
kworker/-59 3d..2 4us : update_min_vruntime <-dequeue_task_fair kworker/-59 3d..2 4us : update_min_vruntime <-dequeue_task_fair
kworker/-59 3d..2 4us : update_cfs_shares <-dequeue_task_fair kworker/-59 3d..2 4us : update_cfs_shares <-dequeue_task_fair
kworker/-59 3d..2 5us : hrtick_update <-dequeue_task_fair kworker/-59 3d..2 5us : hrtick_update <-dequeue_task_fair
kworker/-59 3d..2 5us : wq_worker_sleeping <-__schedule kworker/-59 3d..2 5us : wq_worker_sleeping <-__schedule
kworker/-59 3d..2 5us : kthread_data <-wq_worker_sleeping kworker/-59 3d..2 5us : kthread_data <-wq_worker_sleeping
kworker/-59 3d..2 5us : put_prev_task_fair <-__schedule kworker/-59 3d..2 5us : put_prev_task_fair <-__schedule
kworker/-59 3d..2 6us : pick_next_task_fair <-pick_next_task kworker/-59 3d..2 6us : pick_next_task_fair <-pick_next_task
kworker/-59 3d..2 6us : clear_buddies <-pick_next_task_fair kworker/-59 3d..2 6us : clear_buddies <-pick_next_task_fair
kworker/-59 3d..2 6us : set_next_entity <-pick_next_task_fair kworker/-59 3d..2 6us : set_next_entity <-pick_next_task_fair
kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity
ls-2269 3d..2 7us : finish_task_switch <-__schedule ls-2269 3d..2 7us : finish_task_switch <-__schedule
ls-2269 3d..2 7us : _raw_spin_unlock_irq <-finish_task_switch ls-2269 3d..2 7us : _raw_spin_unlock_irq <-finish_task_switch
ls-2269 3d..2 8us : do_IRQ <-ret_from_intr ls-2269 3d..2 8us : do_IRQ <-ret_from_intr
...@@ -1576,7 +1642,7 @@ kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity ...@@ -1576,7 +1642,7 @@ kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity
ls-2269 3d..2 8us : rcu_irq_enter <-irq_enter ls-2269 3d..2 8us : rcu_irq_enter <-irq_enter
ls-2269 3d..2 9us : add_preempt_count <-irq_enter ls-2269 3d..2 9us : add_preempt_count <-irq_enter
ls-2269 3d.h2 9us : exit_idle <-do_IRQ ls-2269 3d.h2 9us : exit_idle <-do_IRQ
[...] [...]
ls-2269 3d.h3 20us : sub_preempt_count <-_raw_spin_unlock ls-2269 3d.h3 20us : sub_preempt_count <-_raw_spin_unlock
ls-2269 3d.h2 20us : irq_exit <-do_IRQ ls-2269 3d.h2 20us : irq_exit <-do_IRQ
ls-2269 3d.h2 21us : sub_preempt_count <-irq_exit ls-2269 3d.h2 21us : sub_preempt_count <-irq_exit
...@@ -1588,14 +1654,14 @@ kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity ...@@ -1588,14 +1654,14 @@ kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity
ls-2269 3d.s5 31us : do_IRQ <-ret_from_intr ls-2269 3d.s5 31us : do_IRQ <-ret_from_intr
ls-2269 3d.s5 31us : irq_enter <-do_IRQ ls-2269 3d.s5 31us : irq_enter <-do_IRQ
ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter
[...] [...]
ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter
ls-2269 3d.s5 32us : add_preempt_count <-irq_enter ls-2269 3d.s5 32us : add_preempt_count <-irq_enter
ls-2269 3d.H5 32us : exit_idle <-do_IRQ ls-2269 3d.H5 32us : exit_idle <-do_IRQ
ls-2269 3d.H5 32us : handle_irq <-do_IRQ ls-2269 3d.H5 32us : handle_irq <-do_IRQ
ls-2269 3d.H5 32us : irq_to_desc <-handle_irq ls-2269 3d.H5 32us : irq_to_desc <-handle_irq
ls-2269 3d.H5 33us : handle_fasteoi_irq <-handle_irq ls-2269 3d.H5 33us : handle_fasteoi_irq <-handle_irq
[...] [...]
ls-2269 3d.s5 158us : _raw_spin_unlock_irqrestore <-rtl8139_poll ls-2269 3d.s5 158us : _raw_spin_unlock_irqrestore <-rtl8139_poll
ls-2269 3d.s3 158us : net_rps_action_and_irq_enable.isra.65 <-net_rx_action ls-2269 3d.s3 158us : net_rps_action_and_irq_enable.isra.65 <-net_rx_action
ls-2269 3d.s3 159us : __local_bh_enable <-__do_softirq ls-2269 3d.s3 159us : __local_bh_enable <-__do_softirq
...@@ -1631,7 +1697,7 @@ time it takes for a task that is woken to actually wake up. ...@@ -1631,7 +1697,7 @@ time it takes for a task that is woken to actually wake up.
Now for non Real-Time tasks, this can be arbitrary. But tracing Now for non Real-Time tasks, this can be arbitrary. But tracing
it none the less can be interesting. it none the less can be interesting.
Without function tracing: Without function tracing::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo wakeup > current_tracer # echo wakeup > current_tracer
...@@ -1640,23 +1706,23 @@ Without function tracing: ...@@ -1640,23 +1706,23 @@ Without function tracing:
# chrt -f 5 sleep 1 # chrt -f 5 sleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: wakeup # tracer: wakeup
# #
# wakeup latency trace v1.1.5 on 3.8.0-test+ # wakeup latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 15 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 15 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: kworker/3:1H-312 (uid:0 nice:-20 policy:0 rt_prio:0) # | task: kworker/3:1H-312 (uid:0 nice:-20 policy:0 rt_prio:0)
# ----------------- # -----------------
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
<idle>-0 3dNs7 0us : 0:120:R + [003] 312:100:R kworker/3:1H <idle>-0 3dNs7 0us : 0:120:R + [003] 312:100:R kworker/3:1H
<idle>-0 3dNs7 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up <idle>-0 3dNs7 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up
<idle>-0 3d..3 15us : __schedule <-schedule <idle>-0 3d..3 15us : __schedule <-schedule
...@@ -1698,6 +1764,7 @@ Since this tracer only deals with RT tasks, we will run this ...@@ -1698,6 +1764,7 @@ Since this tracer only deals with RT tasks, we will run this
slightly differently than we did with the previous tracers. slightly differently than we did with the previous tracers.
Instead of performing an 'ls', we will run 'sleep 1' under Instead of performing an 'ls', we will run 'sleep 1' under
'chrt' which changes the priority of the task. 'chrt' which changes the priority of the task.
::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo wakeup_rt > current_tracer # echo wakeup_rt > current_tracer
...@@ -1706,25 +1773,25 @@ Instead of performing an 'ls', we will run 'sleep 1' under ...@@ -1706,25 +1773,25 @@ Instead of performing an 'ls', we will run 'sleep 1' under
# chrt -f 5 sleep 1 # chrt -f 5 sleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: wakeup # tracer: wakeup
# #
# tracer: wakeup_rt # tracer: wakeup_rt
# #
# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ # wakeup_rt latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 5 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 5 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: sleep-2389 (uid:0 nice:0 policy:1 rt_prio:5) # | task: sleep-2389 (uid:0 nice:0 policy:1 rt_prio:5)
# ----------------- # -----------------
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
<idle>-0 3d.h4 0us : 0:120:R + [003] 2389: 94:R sleep <idle>-0 3d.h4 0us : 0:120:R + [003] 2389: 94:R sleep
<idle>-0 3d.h4 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up <idle>-0 3d.h4 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up
<idle>-0 3d..3 5us : __schedule <-schedule <idle>-0 3d..3 5us : __schedule <-schedule
...@@ -1743,6 +1810,7 @@ and not the internal kernel priority. The policy is 1 for ...@@ -1743,6 +1810,7 @@ and not the internal kernel priority. The policy is 1 for
SCHED_FIFO and 2 for SCHED_RR. SCHED_FIFO and 2 for SCHED_RR.
Note, that the trace data shows the internal priority (99 - rtprio). Note, that the trace data shows the internal priority (99 - rtprio).
::
<idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep
...@@ -1752,26 +1820,27 @@ and in the running state 'R'. The sleep task was scheduled in with ...@@ -1752,26 +1820,27 @@ and in the running state 'R'. The sleep task was scheduled in with
and it too is in the running state. and it too is in the running state.
Doing the same with chrt -r 5 and function-trace set. Doing the same with chrt -r 5 and function-trace set.
::
echo 1 > options/function-trace echo 1 > options/function-trace
# tracer: wakeup_rt # tracer: wakeup_rt
# #
# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ # wakeup_rt latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 29 us, #85/85, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 29 us, #85/85, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: sleep-2448 (uid:0 nice:0 policy:1 rt_prio:5) # | task: sleep-2448 (uid:0 nice:0 policy:1 rt_prio:5)
# ----------------- # -----------------
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
<idle>-0 3d.h4 1us+: 0:120:R + [003] 2448: 94:R sleep <idle>-0 3d.h4 1us+: 0:120:R + [003] 2448: 94:R sleep
<idle>-0 3d.h4 2us : ttwu_do_activate.constprop.87 <-try_to_wake_up <idle>-0 3d.h4 2us : ttwu_do_activate.constprop.87 <-try_to_wake_up
<idle>-0 3d.h3 3us : check_preempt_curr <-ttwu_do_wakeup <idle>-0 3d.h3 3us : check_preempt_curr <-ttwu_do_wakeup
...@@ -1871,6 +1940,7 @@ As function tracing can induce a much larger latency, but without ...@@ -1871,6 +1940,7 @@ As function tracing can induce a much larger latency, but without
seeing what happens within the latency it is hard to know what seeing what happens within the latency it is hard to know what
caused it. There is a middle ground, and that is with enabling caused it. There is a middle ground, and that is with enabling
events. events.
::
# echo 0 > options/function-trace # echo 0 > options/function-trace
# echo wakeup_rt > current_tracer # echo wakeup_rt > current_tracer
...@@ -1880,23 +1950,23 @@ events. ...@@ -1880,23 +1950,23 @@ events.
# chrt -f 5 sleep 1 # chrt -f 5 sleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: wakeup_rt # tracer: wakeup_rt
# #
# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ # wakeup_rt latency trace v1.1.5 on 3.8.0-test+
# -------------------------------------------------------------------- # --------------------------------------------------------------------
# latency: 6 us, #12/12, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) # latency: 6 us, #12/12, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
# ----------------- # -----------------
# | task: sleep-5882 (uid:0 nice:0 policy:1 rt_prio:5) # | task: sleep-5882 (uid:0 nice:0 policy:1 rt_prio:5)
# ----------------- # -----------------
# #
# _------=> CPU# # _------=> CPU#
# / _-----=> irqs-off # / _-----=> irqs-off
# | / _----=> need-resched # | / _----=> need-resched
# || / _---=> hardirq/softirq # || / _---=> hardirq/softirq
# ||| / _--=> preempt-depth # ||| / _--=> preempt-depth
# |||| / delay # |||| / delay
# cmd pid ||||| time | caller # cmd pid ||||| time | caller
# \ / ||||| \ | / # \ / ||||| \ | /
<idle>-0 2d.h4 0us : 0:120:R + [002] 5882: 94:R sleep <idle>-0 2d.h4 0us : 0:120:R + [002] 5882: 94:R sleep
<idle>-0 2d.h4 0us : ttwu_do_activate.constprop.87 <-try_to_wake_up <idle>-0 2d.h4 0us : ttwu_do_activate.constprop.87 <-try_to_wake_up
<idle>-0 2d.h4 1us : sched_wakeup: comm=sleep pid=5882 prio=94 success=1 target_cpu=002 <idle>-0 2d.h4 1us : sched_wakeup: comm=sleep pid=5882 prio=94 success=1 target_cpu=002
...@@ -1918,19 +1988,20 @@ The hardware latency detector is executed by enabling the "hwlat" tracer. ...@@ -1918,19 +1988,20 @@ The hardware latency detector is executed by enabling the "hwlat" tracer.
NOTE, this tracer will affect the performance of the system as it will NOTE, this tracer will affect the performance of the system as it will
periodically make a CPU constantly busy with interrupts disabled. periodically make a CPU constantly busy with interrupts disabled.
::
# echo hwlat > current_tracer # echo hwlat > current_tracer
# sleep 100 # sleep 100
# cat trace # cat trace
# tracer: hwlat # tracer: hwlat
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
<...>-3638 [001] d... 19452.055471: #1 inner/outer(us): 12/14 ts:1499801089.066141940 <...>-3638 [001] d... 19452.055471: #1 inner/outer(us): 12/14 ts:1499801089.066141940
<...>-3638 [003] d... 19454.071354: #2 inner/outer(us): 11/9 ts:1499801091.082164365 <...>-3638 [003] d... 19454.071354: #2 inner/outer(us): 11/9 ts:1499801091.082164365
<...>-3638 [002] dn.. 19461.126852: #3 inner/outer(us): 12/9 ts:1499801098.138150062 <...>-3638 [002] dn.. 19461.126852: #3 inner/outer(us): 12/9 ts:1499801098.138150062
...@@ -1942,7 +2013,8 @@ periodically make a CPU constantly busy with interrupts disabled. ...@@ -1942,7 +2013,8 @@ periodically make a CPU constantly busy with interrupts disabled.
The above output is somewhat the same in the header. All events will have The above output is somewhat the same in the header. All events will have
interrupts disabled 'd'. Under the FUNCTION title there is: interrupts disabled 'd'. Under the FUNCTION title there is:
#1 - This is the count of events recorded that were greater than the #1
This is the count of events recorded that were greater than the
tracing_threshold (See below). tracing_threshold (See below).
inner/outer(us): 12/14 inner/outer(us): 12/14
...@@ -1968,7 +2040,8 @@ interrupts disabled 'd'. Under the FUNCTION title there is: ...@@ -1968,7 +2040,8 @@ interrupts disabled 'd'. Under the FUNCTION title there is:
hwlat files: hwlat files:
tracing_threshold - This gets automatically set to "10" to represent 10 tracing_threshold
This gets automatically set to "10" to represent 10
microseconds. This is the threshold of latency that microseconds. This is the threshold of latency that
needs to be detected before the trace will be recorded. needs to be detected before the trace will be recorded.
...@@ -1976,14 +2049,16 @@ hwlat files: ...@@ -1976,14 +2049,16 @@ hwlat files:
written into "current_tracer"), the original value for written into "current_tracer"), the original value for
tracing_threshold is placed back into this file. tracing_threshold is placed back into this file.
hwlat_detector/width - The length of time the test runs with interrupts hwlat_detector/width
disabled. The length of time the test runs with interrupts disabled.
hwlat_detector/window - The length of time of the window which the test hwlat_detector/window
The length of time of the window which the test
runs. That is, the test will run for "width" runs. That is, the test will run for "width"
microseconds per "window" microseconds microseconds per "window" microseconds
tracing_cpumask - When the test is started. A kernel thread is created that tracing_cpumask
When the test is started. A kernel thread is created that
runs the test. This thread will alternate between CPUs runs the test. This thread will alternate between CPUs
listed in the tracing_cpumask between each period listed in the tracing_cpumask between each period
(one "window"). To limit the test to specific CPUs (one "window"). To limit the test to specific CPUs
...@@ -1997,6 +2072,7 @@ This tracer is the function tracer. Enabling the function tracer ...@@ -1997,6 +2072,7 @@ This tracer is the function tracer. Enabling the function tracer
can be done from the debug file system. Make sure the can be done from the debug file system. Make sure the
ftrace_enabled is set; otherwise this tracer is a nop. ftrace_enabled is set; otherwise this tracer is a nop.
See the "ftrace_enabled" section below. See the "ftrace_enabled" section below.
::
# sysctl kernel.ftrace_enabled=1 # sysctl kernel.ftrace_enabled=1
# echo function > current_tracer # echo function > current_tracer
...@@ -2004,17 +2080,17 @@ See the "ftrace_enabled" section below. ...@@ -2004,17 +2080,17 @@ See the "ftrace_enabled" section below.
# usleep 1 # usleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 24799/24799 #P:4 # entries-in-buffer/entries-written: 24799/24799 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
bash-1994 [002] .... 3082.063030: mutex_unlock <-rb_simple_write bash-1994 [002] .... 3082.063030: mutex_unlock <-rb_simple_write
bash-1994 [002] .... 3082.063031: __mutex_unlock_slowpath <-mutex_unlock bash-1994 [002] .... 3082.063031: __mutex_unlock_slowpath <-mutex_unlock
bash-1994 [002] .... 3082.063031: __fsnotify_parent <-fsnotify_modify bash-1994 [002] .... 3082.063031: __fsnotify_parent <-fsnotify_modify
...@@ -2023,7 +2099,7 @@ See the "ftrace_enabled" section below. ...@@ -2023,7 +2099,7 @@ See the "ftrace_enabled" section below.
bash-1994 [002] .... 3082.063032: add_preempt_count <-__srcu_read_lock bash-1994 [002] .... 3082.063032: add_preempt_count <-__srcu_read_lock
bash-1994 [002] ...1 3082.063032: sub_preempt_count <-__srcu_read_lock bash-1994 [002] ...1 3082.063032: sub_preempt_count <-__srcu_read_lock
bash-1994 [002] .... 3082.063033: __srcu_read_unlock <-fsnotify bash-1994 [002] .... 3082.063033: __srcu_read_unlock <-fsnotify
[...] [...]
Note: function tracer uses ring buffers to store the above Note: function tracer uses ring buffers to store the above
...@@ -2034,11 +2110,11 @@ record. For this reason, it is sometimes better to disable ...@@ -2034,11 +2110,11 @@ record. For this reason, it is sometimes better to disable
tracing directly from a program. This allows you to stop the tracing directly from a program. This allows you to stop the
tracing at the point that you hit the part that you are tracing at the point that you hit the part that you are
interested in. To disable the tracing directly from a C program, interested in. To disable the tracing directly from a C program,
something like following code snippet can be used: something like following code snippet can be used::
int trace_fd; int trace_fd;
[...] [...]
int main(int argc, char *argv[]) { int main(int argc, char *argv[]) {
[...] [...]
trace_fd = open(tracing_file("tracing_on"), O_WRONLY); trace_fd = open(tracing_file("tracing_on"), O_WRONLY);
[...] [...]
...@@ -2046,22 +2122,22 @@ int main(int argc, char *argv[]) { ...@@ -2046,22 +2122,22 @@ int main(int argc, char *argv[]) {
write(trace_fd, "0", 1); write(trace_fd, "0", 1);
} }
[...] [...]
} }
Single thread tracing Single thread tracing
--------------------- ---------------------
By writing into set_ftrace_pid you can trace a By writing into set_ftrace_pid you can trace a
single thread. For example: single thread. For example::
# cat set_ftrace_pid # cat set_ftrace_pid
no pid no pid
# echo 3111 > set_ftrace_pid # echo 3111 > set_ftrace_pid
# cat set_ftrace_pid # cat set_ftrace_pid
3111 3111
# echo function > current_tracer # echo function > current_tracer
# cat trace | head # cat trace | head
# tracer: function # tracer: function
# #
# TASK-PID CPU# TIMESTAMP FUNCTION # TASK-PID CPU# TIMESTAMP FUNCTION
...@@ -2072,8 +2148,8 @@ no pid ...@@ -2072,8 +2148,8 @@ no pid
yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel
yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll
yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll
# echo > set_ftrace_pid # echo > set_ftrace_pid
# cat trace |head # cat trace |head
# tracer: function # tracer: function
# #
# TASK-PID CPU# TIMESTAMP FUNCTION # TASK-PID CPU# TIMESTAMP FUNCTION
...@@ -2086,22 +2162,23 @@ no pid ...@@ -2086,22 +2162,23 @@ no pid
yum-updatesd-3111 [003] 1701.957693: path_put <-audit_syscall_exit yum-updatesd-3111 [003] 1701.957693: path_put <-audit_syscall_exit
If you want to trace a function when executing, you could use If you want to trace a function when executing, you could use
something like this simple program: something like this simple program.
::
#include <stdio.h>
#include <stdlib.h> #include <stdio.h>
#include <sys/types.h> #include <stdlib.h>
#include <sys/stat.h> #include <sys/types.h>
#include <fcntl.h> #include <sys/stat.h>
#include <unistd.h> #include <fcntl.h>
#include <string.h> #include <unistd.h>
#include <string.h>
#define _STR(x) #x
#define STR(x) _STR(x) #define _STR(x) #x
#define MAX_PATH 256 #define STR(x) _STR(x)
#define MAX_PATH 256
const char *find_tracefs(void)
{ const char *find_tracefs(void)
{
static char tracefs[MAX_PATH+1]; static char tracefs[MAX_PATH+1];
static int tracefs_found; static int tracefs_found;
char type[100]; char type[100];
...@@ -2133,17 +2210,17 @@ const char *find_tracefs(void) ...@@ -2133,17 +2210,17 @@ const char *find_tracefs(void)
tracefs_found = 1; tracefs_found = 1;
return tracefs; return tracefs;
} }
const char *tracing_file(const char *file_name) const char *tracing_file(const char *file_name)
{ {
static char trace_file[MAX_PATH+1]; static char trace_file[MAX_PATH+1];
snprintf(trace_file, MAX_PATH, "%s/%s", find_tracefs(), file_name); snprintf(trace_file, MAX_PATH, "%s/%s", find_tracefs(), file_name);
return trace_file; return trace_file;
} }
int main (int argc, char **argv) int main (int argc, char **argv)
{ {
if (argc < 1) if (argc < 1)
exit(-1); exit(-1);
...@@ -2170,21 +2247,20 @@ int main (int argc, char **argv) ...@@ -2170,21 +2247,20 @@ int main (int argc, char **argv)
} }
return 0; return 0;
} }
Or this simple script! Or this simple script!
::
------ #!/bin/bash
#!/bin/bash
tracefs=`sed -ne 's/^tracefs \(.*\) tracefs.*/\1/p' /proc/mounts`
tracefs=`sed -ne 's/^tracefs \(.*\) tracefs.*/\1/p' /proc/mounts` echo nop > $tracefs/tracing/current_tracer
echo nop > $tracefs/tracing/current_tracer echo 0 > $tracefs/tracing/tracing_on
echo 0 > $tracefs/tracing/tracing_on echo $$ > $tracefs/tracing/set_ftrace_pid
echo $$ > $tracefs/tracing/set_ftrace_pid echo function > $tracefs/tracing/current_tracer
echo function > $tracefs/tracing/current_tracer echo 1 > $tracefs/tracing/tracing_on
echo 1 > $tracefs/tracing/tracing_on exec "$@"
exec "$@"
------
function graph tracer function graph tracer
...@@ -2219,10 +2295,12 @@ This tracer is useful in several situations: ...@@ -2219,10 +2295,12 @@ This tracer is useful in several situations:
- you just want to peek inside a working kernel and want to see - you just want to peek inside a working kernel and want to see
what happens there. what happens there.
# tracer: function_graph ::
#
# CPU DURATION FUNCTION CALLS # tracer: function_graph
# | | | | | | | #
# CPU DURATION FUNCTION CALLS
# | | | | | | |
0) | sys_open() { 0) | sys_open() {
0) | do_sys_open() { 0) | do_sys_open() {
...@@ -2251,25 +2329,25 @@ want, depending on your needs. ...@@ -2251,25 +2329,25 @@ want, depending on your needs.
tracing_cpu_mask file) or you might sometimes see unordered tracing_cpu_mask file) or you might sometimes see unordered
function calls while cpu tracing switch. function calls while cpu tracing switch.
hide: echo nofuncgraph-cpu > trace_options - hide: echo nofuncgraph-cpu > trace_options
show: echo funcgraph-cpu > trace_options - show: echo funcgraph-cpu > trace_options
- The duration (function's time of execution) is displayed on - The duration (function's time of execution) is displayed on
the closing bracket line of a function or on the same line the closing bracket line of a function or on the same line
than the current function in case of a leaf one. It is default than the current function in case of a leaf one. It is default
enabled. enabled.
hide: echo nofuncgraph-duration > trace_options - hide: echo nofuncgraph-duration > trace_options
show: echo funcgraph-duration > trace_options - show: echo funcgraph-duration > trace_options
- The overhead field precedes the duration field in case of - The overhead field precedes the duration field in case of
reached duration thresholds. reached duration thresholds.
hide: echo nofuncgraph-overhead > trace_options - hide: echo nofuncgraph-overhead > trace_options
show: echo funcgraph-overhead > trace_options - show: echo funcgraph-overhead > trace_options
depends on: funcgraph-duration - depends on: funcgraph-duration
ie: ie::
3) # 1837.709 us | } /* __switch_to */ 3) # 1837.709 us | } /* __switch_to */
3) | finish_task_switch() { 3) | finish_task_switch() {
...@@ -2309,6 +2387,8 @@ want, depending on your needs. ...@@ -2309,6 +2387,8 @@ want, depending on your needs.
1) + 18.542 us | } 1) + 18.542 us | }
2) $ 3594274 us | } 2) $ 3594274 us | }
Flags::
+ means that the function exceeded 10 usecs. + means that the function exceeded 10 usecs.
! means that the function exceeded 100 usecs. ! means that the function exceeded 100 usecs.
# means that the function exceeded 1000 usecs. # means that the function exceeded 1000 usecs.
...@@ -2320,10 +2400,10 @@ want, depending on your needs. ...@@ -2320,10 +2400,10 @@ want, depending on your needs.
- The task/pid field displays the thread cmdline and pid which - The task/pid field displays the thread cmdline and pid which
executed the function. It is default disabled. executed the function. It is default disabled.
hide: echo nofuncgraph-proc > trace_options - hide: echo nofuncgraph-proc > trace_options
show: echo funcgraph-proc > trace_options - show: echo funcgraph-proc > trace_options
ie: ie::
# tracer: function_graph # tracer: function_graph
# #
...@@ -2344,10 +2424,10 @@ want, depending on your needs. ...@@ -2344,10 +2424,10 @@ want, depending on your needs.
system clock since it started. A snapshot of this time is system clock since it started. A snapshot of this time is
given on each entry/exit of functions given on each entry/exit of functions
hide: echo nofuncgraph-abstime > trace_options - hide: echo nofuncgraph-abstime > trace_options
show: echo funcgraph-abstime > trace_options - show: echo funcgraph-abstime > trace_options
ie: ie::
# #
# TIME CPU DURATION FUNCTION CALLS # TIME CPU DURATION FUNCTION CALLS
...@@ -2376,17 +2456,19 @@ enabled for functions whose start is in the trace buffer, ...@@ -2376,17 +2456,19 @@ enabled for functions whose start is in the trace buffer,
allowing easier searching with grep for function durations. allowing easier searching with grep for function durations.
It is default disabled. It is default disabled.
hide: echo nofuncgraph-tail > trace_options - hide: echo nofuncgraph-tail > trace_options
show: echo funcgraph-tail > trace_options - show: echo funcgraph-tail > trace_options
Example with nofuncgraph-tail (default)::
Example with nofuncgraph-tail (default):
0) | putname() { 0) | putname() {
0) | kmem_cache_free() { 0) | kmem_cache_free() {
0) 0.518 us | __phys_addr(); 0) 0.518 us | __phys_addr();
0) 1.757 us | } 0) 1.757 us | }
0) 2.861 us | } 0) 2.861 us | }
Example with funcgraph-tail: Example with funcgraph-tail::
0) | putname() { 0) | putname() {
0) | kmem_cache_free() { 0) | kmem_cache_free() {
0) 0.518 us | __phys_addr(); 0) 0.518 us | __phys_addr();
...@@ -2396,11 +2478,11 @@ It is default disabled. ...@@ -2396,11 +2478,11 @@ It is default disabled.
You can put some comments on specific functions by using You can put some comments on specific functions by using
trace_printk() For example, if you want to put a comment inside trace_printk() For example, if you want to put a comment inside
the __might_sleep() function, you just have to include the __might_sleep() function, you just have to include
<linux/ftrace.h> and call trace_printk() inside __might_sleep() <linux/ftrace.h> and call trace_printk() inside __might_sleep()::
trace_printk("I'm a comment!\n") trace_printk("I'm a comment!\n")
will produce: will produce::
1) | __might_sleep() { 1) | __might_sleep() {
1) | /* I'm a comment! */ 1) | /* I'm a comment! */
...@@ -2487,16 +2569,18 @@ listed in: ...@@ -2487,16 +2569,18 @@ listed in:
available_filter_functions available_filter_functions
::
# cat available_filter_functions # cat available_filter_functions
put_prev_task_idle put_prev_task_idle
kmem_cache_create kmem_cache_create
pick_next_task_rt pick_next_task_rt
get_online_cpus get_online_cpus
pick_next_task_fair pick_next_task_fair
mutex_lock mutex_lock
[...] [...]
If I am only interested in sys_nanosleep and hrtimer_interrupt: If I am only interested in sys_nanosleep and hrtimer_interrupt::
# echo sys_nanosleep hrtimer_interrupt > set_ftrace_filter # echo sys_nanosleep hrtimer_interrupt > set_ftrace_filter
# echo function > current_tracer # echo function > current_tracer
...@@ -2504,17 +2588,17 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt: ...@@ -2504,17 +2588,17 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt:
# usleep 1 # usleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 5/5 #P:4 # entries-in-buffer/entries-written: 5/5 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
usleep-2665 [001] .... 4186.475355: sys_nanosleep <-system_call_fastpath usleep-2665 [001] .... 4186.475355: sys_nanosleep <-system_call_fastpath
<idle>-0 [001] d.h1 4186.475409: hrtimer_interrupt <-smp_apic_timer_interrupt <idle>-0 [001] d.h1 4186.475409: hrtimer_interrupt <-smp_apic_timer_interrupt
usleep-2665 [001] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt usleep-2665 [001] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt
...@@ -2522,39 +2606,46 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt: ...@@ -2522,39 +2606,46 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt:
<idle>-0 [002] d.h1 4186.475427: hrtimer_interrupt <-smp_apic_timer_interrupt <idle>-0 [002] d.h1 4186.475427: hrtimer_interrupt <-smp_apic_timer_interrupt
To see which functions are being traced, you can cat the file: To see which functions are being traced, you can cat the file:
::
# cat set_ftrace_filter # cat set_ftrace_filter
hrtimer_interrupt hrtimer_interrupt
sys_nanosleep sys_nanosleep
Perhaps this is not enough. The filters also allow glob(7) matching. Perhaps this is not enough. The filters also allow glob(7) matching.
<match>* - will match functions that begin with <match> ``<match>*``
*<match> - will match functions that end with <match> will match functions that begin with <match>
*<match>* - will match functions that have <match> in it ``*<match>``
<match1>*<match2> - will match functions that begin with will match functions that end with <match>
<match1> and end with <match2> ``*<match>*``
will match functions that have <match> in it
Note: It is better to use quotes to enclose the wild cards, ``<match1>*<match2>``
will match functions that begin with <match1> and end with <match2>
.. note::
It is better to use quotes to enclose the wild cards,
otherwise the shell may expand the parameters into names otherwise the shell may expand the parameters into names
of files in the local directory. of files in the local directory.
::
# echo 'hrtimer_*' > set_ftrace_filter # echo 'hrtimer_*' > set_ftrace_filter
Produces: Produces::
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 897/897 #P:4 # entries-in-buffer/entries-written: 897/897 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
<idle>-0 [003] dN.1 4228.547803: hrtimer_cancel <-tick_nohz_idle_exit <idle>-0 [003] dN.1 4228.547803: hrtimer_cancel <-tick_nohz_idle_exit
<idle>-0 [003] dN.1 4228.547804: hrtimer_try_to_cancel <-hrtimer_cancel <idle>-0 [003] dN.1 4228.547804: hrtimer_try_to_cancel <-hrtimer_cancel
<idle>-0 [003] dN.2 4228.547805: hrtimer_force_reprogram <-__remove_hrtimer <idle>-0 [003] dN.2 4228.547805: hrtimer_force_reprogram <-__remove_hrtimer
...@@ -2565,24 +2656,25 @@ Produces: ...@@ -2565,24 +2656,25 @@ Produces:
<idle>-0 [003] d..2 4228.547860: hrtimer_force_reprogram <-__rem <idle>-0 [003] d..2 4228.547860: hrtimer_force_reprogram <-__rem
Notice that we lost the sys_nanosleep. Notice that we lost the sys_nanosleep.
::
# cat set_ftrace_filter # cat set_ftrace_filter
hrtimer_run_queues hrtimer_run_queues
hrtimer_run_pending hrtimer_run_pending
hrtimer_init hrtimer_init
hrtimer_cancel hrtimer_cancel
hrtimer_try_to_cancel hrtimer_try_to_cancel
hrtimer_forward hrtimer_forward
hrtimer_start hrtimer_start
hrtimer_reprogram hrtimer_reprogram
hrtimer_force_reprogram hrtimer_force_reprogram
hrtimer_get_next_event hrtimer_get_next_event
hrtimer_interrupt hrtimer_interrupt
hrtimer_nanosleep hrtimer_nanosleep
hrtimer_wakeup hrtimer_wakeup
hrtimer_get_remaining hrtimer_get_remaining
hrtimer_get_res hrtimer_get_res
hrtimer_init_sleeper hrtimer_init_sleeper
This is because the '>' and '>>' act just like they do in bash. This is because the '>' and '>>' act just like they do in bash.
...@@ -2590,7 +2682,7 @@ To rewrite the filters, use '>' ...@@ -2590,7 +2682,7 @@ To rewrite the filters, use '>'
To append to the filters, use '>>' To append to the filters, use '>>'
To clear out a filter so that all functions will be recorded To clear out a filter so that all functions will be recorded
again: again::
# echo > set_ftrace_filter # echo > set_ftrace_filter
# cat set_ftrace_filter # cat set_ftrace_filter
...@@ -2598,48 +2690,51 @@ again: ...@@ -2598,48 +2690,51 @@ again:
Again, now we want to append. Again, now we want to append.
::
# echo sys_nanosleep > set_ftrace_filter # echo sys_nanosleep > set_ftrace_filter
# cat set_ftrace_filter # cat set_ftrace_filter
sys_nanosleep sys_nanosleep
# echo 'hrtimer_*' >> set_ftrace_filter # echo 'hrtimer_*' >> set_ftrace_filter
# cat set_ftrace_filter # cat set_ftrace_filter
hrtimer_run_queues hrtimer_run_queues
hrtimer_run_pending hrtimer_run_pending
hrtimer_init hrtimer_init
hrtimer_cancel hrtimer_cancel
hrtimer_try_to_cancel hrtimer_try_to_cancel
hrtimer_forward hrtimer_forward
hrtimer_start hrtimer_start
hrtimer_reprogram hrtimer_reprogram
hrtimer_force_reprogram hrtimer_force_reprogram
hrtimer_get_next_event hrtimer_get_next_event
hrtimer_interrupt hrtimer_interrupt
sys_nanosleep sys_nanosleep
hrtimer_nanosleep hrtimer_nanosleep
hrtimer_wakeup hrtimer_wakeup
hrtimer_get_remaining hrtimer_get_remaining
hrtimer_get_res hrtimer_get_res
hrtimer_init_sleeper hrtimer_init_sleeper
The set_ftrace_notrace prevents those functions from being The set_ftrace_notrace prevents those functions from being
traced. traced.
::
# echo '*preempt*' '*lock*' > set_ftrace_notrace # echo '*preempt*' '*lock*' > set_ftrace_notrace
Produces: Produces::
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 39608/39608 #P:4 # entries-in-buffer/entries-written: 39608/39608 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
bash-1994 [000] .... 4342.324896: file_ra_state_init <-do_dentry_open bash-1994 [000] .... 4342.324896: file_ra_state_init <-do_dentry_open
bash-1994 [000] .... 4342.324897: open_check_o_direct <-do_last bash-1994 [000] .... 4342.324897: open_check_o_direct <-do_last
bash-1994 [000] .... 4342.324897: ima_file_check <-do_last bash-1994 [000] .... 4342.324897: ima_file_check <-do_last
...@@ -2664,12 +2759,12 @@ function tracer and the function-graph-tracer, there are some ...@@ -2664,12 +2759,12 @@ function tracer and the function-graph-tracer, there are some
special features only available in the function-graph tracer. special features only available in the function-graph tracer.
If you want to trace only one function and all of its children, If you want to trace only one function and all of its children,
you just have to echo its name into set_graph_function: you just have to echo its name into set_graph_function::
echo __do_fault > set_graph_function echo __do_fault > set_graph_function
will produce the following "expanded" trace of the __do_fault() will produce the following "expanded" trace of the __do_fault()
function: function::
0) | __do_fault() { 0) | __do_fault() {
0) | filemap_fault() { 0) | filemap_fault() {
...@@ -2706,13 +2801,13 @@ function: ...@@ -2706,13 +2801,13 @@ function:
0) 2.793 us | } 0) 2.793 us | }
0) + 14.012 us | } 0) + 14.012 us | }
You can also expand several functions at once: You can also expand several functions at once::
echo sys_open > set_graph_function echo sys_open > set_graph_function
echo sys_close >> set_graph_function echo sys_close >> set_graph_function
Now if you want to go back to trace all functions you can clear Now if you want to go back to trace all functions you can clear
this special filter via: this special filter via::
echo > set_graph_function echo > set_graph_function
...@@ -2728,7 +2823,7 @@ also for any other uses (perf, kprobes, stack tracing, profiling, etc). ...@@ -2728,7 +2823,7 @@ also for any other uses (perf, kprobes, stack tracing, profiling, etc).
Please disable this with care. Please disable this with care.
This can be disable (and enabled) with: This can be disable (and enabled) with::
sysctl kernel.ftrace_enabled=0 sysctl kernel.ftrace_enabled=0
sysctl kernel.ftrace_enabled=1 sysctl kernel.ftrace_enabled=1
...@@ -2743,13 +2838,13 @@ Filter commands ...@@ -2743,13 +2838,13 @@ Filter commands
--------------- ---------------
A few commands are supported by the set_ftrace_filter interface. A few commands are supported by the set_ftrace_filter interface.
Trace commands have the following format: Trace commands have the following format::
<function>:<command>:<parameter> <function>:<command>:<parameter>
The following commands are supported: The following commands are supported:
- mod - mod:
This command enables function filtering per module. The This command enables function filtering per module. The
parameter defines the module. For example, if only the write* parameter defines the module. For example, if only the write*
functions in the ext3 module are desired, run: functions in the ext3 module are desired, run:
...@@ -2760,97 +2855,99 @@ The following commands are supported: ...@@ -2760,97 +2855,99 @@ The following commands are supported:
filtering based on function names. Thus, adding more functions filtering based on function names. Thus, adding more functions
in a different module is accomplished by appending (>>) to the in a different module is accomplished by appending (>>) to the
filter file. Remove specific module functions by prepending filter file. Remove specific module functions by prepending
'!': '!'::
echo '!writeback*:mod:ext3' >> set_ftrace_filter echo '!writeback*:mod:ext3' >> set_ftrace_filter
Mod command supports module globbing. Disable tracing for all Mod command supports module globbing. Disable tracing for all
functions except a specific module: functions except a specific module::
echo '!*:mod:!ext3' >> set_ftrace_filter echo '!*:mod:!ext3' >> set_ftrace_filter
Disable tracing for all modules, but still trace kernel: Disable tracing for all modules, but still trace kernel::
echo '!*:mod:*' >> set_ftrace_filter echo '!*:mod:*' >> set_ftrace_filter
Enable filter only for kernel: Enable filter only for kernel::
echo '*write*:mod:!*' >> set_ftrace_filter echo '*write*:mod:!*' >> set_ftrace_filter
Enable filter for module globbing: Enable filter for module globbing::
echo '*write*:mod:*snd*' >> set_ftrace_filter echo '*write*:mod:*snd*' >> set_ftrace_filter
- traceon/traceoff - traceon/traceoff:
These commands turn tracing on and off when the specified These commands turn tracing on and off when the specified
functions are hit. The parameter determines how many times the functions are hit. The parameter determines how many times the
tracing system is turned on and off. If unspecified, there is tracing system is turned on and off. If unspecified, there is
no limit. For example, to disable tracing when a schedule bug no limit. For example, to disable tracing when a schedule bug
is hit the first 5 times, run: is hit the first 5 times, run::
echo '__schedule_bug:traceoff:5' > set_ftrace_filter echo '__schedule_bug:traceoff:5' > set_ftrace_filter
To always disable tracing when __schedule_bug is hit: To always disable tracing when __schedule_bug is hit::
echo '__schedule_bug:traceoff' > set_ftrace_filter echo '__schedule_bug:traceoff' > set_ftrace_filter
These commands are cumulative whether or not they are appended These commands are cumulative whether or not they are appended
to set_ftrace_filter. To remove a command, prepend it by '!' to set_ftrace_filter. To remove a command, prepend it by '!'
and drop the parameter: and drop the parameter::
echo '!__schedule_bug:traceoff:0' > set_ftrace_filter echo '!__schedule_bug:traceoff:0' > set_ftrace_filter
The above removes the traceoff command for __schedule_bug The above removes the traceoff command for __schedule_bug
that have a counter. To remove commands without counters: that have a counter. To remove commands without counters::
echo '!__schedule_bug:traceoff' > set_ftrace_filter echo '!__schedule_bug:traceoff' > set_ftrace_filter
- snapshot - snapshot:
Will cause a snapshot to be triggered when the function is hit. Will cause a snapshot to be triggered when the function is hit.
::
echo 'native_flush_tlb_others:snapshot' > set_ftrace_filter echo 'native_flush_tlb_others:snapshot' > set_ftrace_filter
To only snapshot once: To only snapshot once:
::
echo 'native_flush_tlb_others:snapshot:1' > set_ftrace_filter echo 'native_flush_tlb_others:snapshot:1' > set_ftrace_filter
To remove the above commands: To remove the above commands::
echo '!native_flush_tlb_others:snapshot' > set_ftrace_filter echo '!native_flush_tlb_others:snapshot' > set_ftrace_filter
echo '!native_flush_tlb_others:snapshot:0' > set_ftrace_filter echo '!native_flush_tlb_others:snapshot:0' > set_ftrace_filter
- enable_event/disable_event - enable_event/disable_event:
These commands can enable or disable a trace event. Note, because These commands can enable or disable a trace event. Note, because
function tracing callbacks are very sensitive, when these commands function tracing callbacks are very sensitive, when these commands
are registered, the trace point is activated, but disabled in are registered, the trace point is activated, but disabled in
a "soft" mode. That is, the tracepoint will be called, but a "soft" mode. That is, the tracepoint will be called, but
just will not be traced. The event tracepoint stays in this mode just will not be traced. The event tracepoint stays in this mode
as long as there's a command that triggers it. as long as there's a command that triggers it.
::
echo 'try_to_wake_up:enable_event:sched:sched_switch:2' > \ echo 'try_to_wake_up:enable_event:sched:sched_switch:2' > \
set_ftrace_filter set_ftrace_filter
The format is: The format is::
<function>:enable_event:<system>:<event>[:count] <function>:enable_event:<system>:<event>[:count]
<function>:disable_event:<system>:<event>[:count] <function>:disable_event:<system>:<event>[:count]
To remove the events commands: To remove the events commands::
echo '!try_to_wake_up:enable_event:sched:sched_switch:0' > \ echo '!try_to_wake_up:enable_event:sched:sched_switch:0' > \
set_ftrace_filter set_ftrace_filter
echo '!schedule:disable_event:sched:sched_switch' > \ echo '!schedule:disable_event:sched:sched_switch' > \
set_ftrace_filter set_ftrace_filter
- dump - dump:
When the function is hit, it will dump the contents of the ftrace When the function is hit, it will dump the contents of the ftrace
ring buffer to the console. This is useful if you need to debug ring buffer to the console. This is useful if you need to debug
something, and want to dump the trace when a certain function something, and want to dump the trace when a certain function
is hit. Perhaps its a function that is called before a tripple is hit. Perhaps its a function that is called before a tripple
fault happens and does not allow you to get a regular dump. fault happens and does not allow you to get a regular dump.
- cpudump - cpudump:
When the function is hit, it will dump the contents of the ftrace When the function is hit, it will dump the contents of the ftrace
ring buffer for the current CPU to the console. Unlike the "dump" ring buffer for the current CPU to the console. Unlike the "dump"
command, it only prints out the contents of the ring buffer for the command, it only prints out the contents of the ring buffer for the
...@@ -2863,25 +2960,26 @@ The trace_pipe outputs the same content as the trace file, but ...@@ -2863,25 +2960,26 @@ The trace_pipe outputs the same content as the trace file, but
the effect on the tracing is different. Every read from the effect on the tracing is different. Every read from
trace_pipe is consumed. This means that subsequent reads will be trace_pipe is consumed. This means that subsequent reads will be
different. The trace is live. different. The trace is live.
::
# echo function > current_tracer # echo function > current_tracer
# cat trace_pipe > /tmp/trace.out & # cat trace_pipe > /tmp/trace.out &
[1] 4153 [1] 4153
# echo 1 > tracing_on # echo 1 > tracing_on
# usleep 1 # usleep 1
# echo 0 > tracing_on # echo 0 > tracing_on
# cat trace # cat trace
# tracer: function # tracer: function
# #
# entries-in-buffer/entries-written: 0/0 #P:4 # entries-in-buffer/entries-written: 0/0 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
# #
# cat /tmp/trace.out # cat /tmp/trace.out
...@@ -2908,44 +3006,51 @@ used to modify the size of the internal trace buffers. The ...@@ -2908,44 +3006,51 @@ used to modify the size of the internal trace buffers. The
number listed is the number of entries that can be recorded per number listed is the number of entries that can be recorded per
CPU. To know the full size, multiply the number of possible CPUs CPU. To know the full size, multiply the number of possible CPUs
with the number of entries. with the number of entries.
::
# cat buffer_size_kb # cat buffer_size_kb
1408 (units kilobytes) 1408 (units kilobytes)
Or simply read buffer_total_size_kb Or simply read buffer_total_size_kb
::
# cat buffer_total_size_kb # cat buffer_total_size_kb
5632 5632
To modify the buffer, simple echo in a number (in 1024 byte segments). To modify the buffer, simple echo in a number (in 1024 byte segments).
::
# echo 10000 > buffer_size_kb # echo 10000 > buffer_size_kb
# cat buffer_size_kb # cat buffer_size_kb
10000 (units kilobytes) 10000 (units kilobytes)
It will try to allocate as much as possible. If you allocate too It will try to allocate as much as possible. If you allocate too
much, it can cause Out-Of-Memory to trigger. much, it can cause Out-Of-Memory to trigger.
::
# echo 1000000000000 > buffer_size_kb # echo 1000000000000 > buffer_size_kb
-bash: echo: write error: Cannot allocate memory -bash: echo: write error: Cannot allocate memory
# cat buffer_size_kb # cat buffer_size_kb
85 85
The per_cpu buffers can be changed individually as well: The per_cpu buffers can be changed individually as well:
::
# echo 10000 > per_cpu/cpu0/buffer_size_kb # echo 10000 > per_cpu/cpu0/buffer_size_kb
# echo 100 > per_cpu/cpu1/buffer_size_kb # echo 100 > per_cpu/cpu1/buffer_size_kb
When the per_cpu buffers are not the same, the buffer_size_kb When the per_cpu buffers are not the same, the buffer_size_kb
at the top level will just show an X at the top level will just show an X
::
# cat buffer_size_kb # cat buffer_size_kb
X X
This is where the buffer_total_size_kb is useful: This is where the buffer_total_size_kb is useful:
::
# cat buffer_total_size_kb # cat buffer_total_size_kb
12916 12916
Writing to the top level buffer_size_kb will reset all the buffers Writing to the top level buffer_size_kb will reset all the buffers
to be the same again. to be the same again.
...@@ -2979,59 +3084,62 @@ feature: ...@@ -2979,59 +3084,62 @@ feature:
snapshot contents. snapshot contents.
More details are shown in the table below. More details are shown in the table below.
status\input | 0 | 1 | else | +--------------+------------+------------+------------+
--------------+------------+------------+------------+ |status\\input | 0 | 1 | else |
not allocated |(do nothing)| alloc+swap |(do nothing)| +==============+============+============+============+
--------------+------------+------------+------------+ |not allocated |(do nothing)| alloc+swap |(do nothing)|
allocated | free | swap | clear | +--------------+------------+------------+------------+
--------------+------------+------------+------------+ |allocated | free | swap | clear |
+--------------+------------+------------+------------+
Here is an example of using the snapshot feature. Here is an example of using the snapshot feature.
::
# echo 1 > events/sched/enable # echo 1 > events/sched/enable
# echo 1 > snapshot # echo 1 > snapshot
# cat snapshot # cat snapshot
# tracer: nop # tracer: nop
# #
# entries-in-buffer/entries-written: 71/71 #P:8 # entries-in-buffer/entries-written: 71/71 #P:8
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
<idle>-0 [005] d... 2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120 <idle>-0 [005] d... 2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120
sleep-2242 [005] d... 2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120 prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120 sleep-2242 [005] d... 2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120 prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120
[...] [...]
<idle>-0 [002] d... 2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120 <idle>-0 [002] d... 2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120
# cat trace # cat trace
# tracer: nop # tracer: nop
# #
# entries-in-buffer/entries-written: 77/77 #P:8 # entries-in-buffer/entries-written: 77/77 #P:8
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
<idle>-0 [007] d... 2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120 <idle>-0 [007] d... 2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120
snapshot-test-2-2229 [002] d... 2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120 snapshot-test-2-2229 [002] d... 2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120
[...] [...]
If you try to use this snapshot feature when current tracer is If you try to use this snapshot feature when current tracer is
one of the latency tracers, you will get the following results. one of the latency tracers, you will get the following results.
::
# echo wakeup > current_tracer # echo wakeup > current_tracer
# echo 1 > snapshot # echo 1 > snapshot
bash: echo: write error: Device or resource busy bash: echo: write error: Device or resource busy
# cat snapshot # cat snapshot
cat: snapshot: Device or resource busy cat: snapshot: Device or resource busy
Instances Instances
...@@ -3041,12 +3149,13 @@ This directory can have new directories created inside of it using ...@@ -3041,12 +3149,13 @@ This directory can have new directories created inside of it using
mkdir, and removing directories with rmdir. The directory created mkdir, and removing directories with rmdir. The directory created
with mkdir in this directory will already contain files and other with mkdir in this directory will already contain files and other
directories after it is created. directories after it is created.
::
# mkdir instances/foo # mkdir instances/foo
# ls instances/foo # ls instances/foo
buffer_size_kb buffer_total_size_kb events free_buffer per_cpu buffer_size_kb buffer_total_size_kb events free_buffer per_cpu
set_event snapshot trace trace_clock trace_marker trace_options set_event snapshot trace trace_clock trace_marker trace_options
trace_pipe tracing_on trace_pipe tracing_on
As you can see, the new directory looks similar to the tracing directory As you can see, the new directory looks similar to the tracing directory
itself. In fact, it is very similar, except that the buffer and itself. In fact, it is very similar, except that the buffer and
...@@ -3064,6 +3173,7 @@ may become specific to the instance they reside in. ...@@ -3064,6 +3173,7 @@ may become specific to the instance they reside in.
Notice that none of the function tracer files are there, nor is Notice that none of the function tracer files are there, nor is
current_tracer and available_tracers. This is because the buffers current_tracer and available_tracers. This is because the buffers
can currently only have events enabled for them. can currently only have events enabled for them.
::
# mkdir instances/foo # mkdir instances/foo
# mkdir instances/bar # mkdir instances/bar
...@@ -3078,7 +3188,7 @@ can currently only have events enabled for them. ...@@ -3078,7 +3188,7 @@ can currently only have events enabled for them.
# echo 1 > instances/bar/events/irq/enable # echo 1 > instances/bar/events/irq/enable
# echo 1 > instances/zoot/events/syscalls/enable # echo 1 > instances/zoot/events/syscalls/enable
# cat trace_pipe # cat trace_pipe
CPU:2 [LOST 11745 EVENTS] CPU:2 [LOST 11745 EVENTS]
bash-2044 [002] .... 10594.481032: _raw_spin_lock_irqsave <-get_page_from_freelist bash-2044 [002] .... 10594.481032: _raw_spin_lock_irqsave <-get_page_from_freelist
bash-2044 [002] d... 10594.481032: add_preempt_count <-_raw_spin_lock_irqsave bash-2044 [002] d... 10594.481032: add_preempt_count <-_raw_spin_lock_irqsave
bash-2044 [002] d..1 10594.481032: __rmqueue <-get_page_from_freelist bash-2044 [002] d..1 10594.481032: __rmqueue <-get_page_from_freelist
...@@ -3090,7 +3200,7 @@ CPU:2 [LOST 11745 EVENTS] ...@@ -3090,7 +3200,7 @@ CPU:2 [LOST 11745 EVENTS]
bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics
bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics
bash-2044 [002] .... 10594.481035: arch_dup_task_struct <-copy_process bash-2044 [002] .... 10594.481035: arch_dup_task_struct <-copy_process
[...] [...]
# cat instances/foo/trace_pipe # cat instances/foo/trace_pipe
bash-1998 [000] d..4 136.676759: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000 bash-1998 [000] d..4 136.676759: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000
...@@ -3103,7 +3213,7 @@ CPU:2 [LOST 11745 EVENTS] ...@@ -3103,7 +3213,7 @@ CPU:2 [LOST 11745 EVENTS]
bash-1998 [000] d..3 136.677018: sched_switch: prev_comm=bash prev_pid=1998 prev_prio=120 prev_state=R+ ==> next_comm=kworker/0:1 next_pid=59 next_prio=120 bash-1998 [000] d..3 136.677018: sched_switch: prev_comm=bash prev_pid=1998 prev_prio=120 prev_state=R+ ==> next_comm=kworker/0:1 next_pid=59 next_prio=120
kworker/0:1-59 [000] d..4 136.677022: sched_wakeup: comm=sshd pid=1995 prio=120 success=1 target_cpu=001 kworker/0:1-59 [000] d..4 136.677022: sched_wakeup: comm=sshd pid=1995 prio=120 success=1 target_cpu=001
kworker/0:1-59 [000] d..3 136.677025: sched_switch: prev_comm=kworker/0:1 prev_pid=59 prev_prio=120 prev_state=S ==> next_comm=bash next_pid=1998 next_prio=120 kworker/0:1-59 [000] d..3 136.677025: sched_switch: prev_comm=kworker/0:1 prev_pid=59 prev_prio=120 prev_state=S ==> next_comm=bash next_pid=1998 next_prio=120
[...] [...]
# cat instances/bar/trace_pipe # cat instances/bar/trace_pipe
migration/1-14 [001] d.h3 138.732674: softirq_raise: vec=3 [action=NET_RX] migration/1-14 [001] d.h3 138.732674: softirq_raise: vec=3 [action=NET_RX]
...@@ -3118,20 +3228,20 @@ CPU:2 [LOST 11745 EVENTS] ...@@ -3118,20 +3228,20 @@ CPU:2 [LOST 11745 EVENTS]
sshd-1995 [001] d.h1 138.733280: irq_handler_exit: irq=21 ret=unhandled sshd-1995 [001] d.h1 138.733280: irq_handler_exit: irq=21 ret=unhandled
sshd-1995 [001] d.h1 138.733281: irq_handler_entry: irq=21 name=eth0 sshd-1995 [001] d.h1 138.733281: irq_handler_entry: irq=21 name=eth0
sshd-1995 [001] d.h1 138.733283: irq_handler_exit: irq=21 ret=handled sshd-1995 [001] d.h1 138.733283: irq_handler_exit: irq=21 ret=handled
[...] [...]
# cat instances/zoot/trace # cat instances/zoot/trace
# tracer: nop # tracer: nop
# #
# entries-in-buffer/entries-written: 18996/18996 #P:4 # entries-in-buffer/entries-written: 18996/18996 #P:4
# #
# _-----=> irqs-off # _-----=> irqs-off
# / _----=> need-resched # / _----=> need-resched
# | / _---=> hardirq/softirq # | / _---=> hardirq/softirq
# || / _--=> preempt-depth # || / _--=> preempt-depth
# ||| / delay # ||| / delay
# TASK-PID CPU# |||| TIMESTAMP FUNCTION # TASK-PID CPU# |||| TIMESTAMP FUNCTION
# | | | |||| | | # | | | |||| | |
bash-1998 [000] d... 140.733501: sys_write -> 0x2 bash-1998 [000] d... 140.733501: sys_write -> 0x2
bash-1998 [000] d... 140.733504: sys_dup2(oldfd: a, newfd: 1) bash-1998 [000] d... 140.733504: sys_dup2(oldfd: a, newfd: 1)
bash-1998 [000] d... 140.733506: sys_dup2 -> 0x1 bash-1998 [000] d... 140.733506: sys_dup2 -> 0x1
...@@ -3149,6 +3259,7 @@ the function tracing. The foo instance displays wakeups and task ...@@ -3149,6 +3259,7 @@ the function tracing. The foo instance displays wakeups and task
switches. switches.
To remove the instances, simply delete their directories: To remove the instances, simply delete their directories:
::
# rmdir instances/foo # rmdir instances/foo
# rmdir instances/bar # rmdir instances/bar
...@@ -3174,6 +3285,7 @@ at every function call. This is enabled via the stack tracer. ...@@ -3174,6 +3285,7 @@ at every function call. This is enabled via the stack tracer.
CONFIG_STACK_TRACER enables the ftrace stack tracing functionality. CONFIG_STACK_TRACER enables the ftrace stack tracing functionality.
To enable it, write a '1' into /proc/sys/kernel/stack_tracer_enabled. To enable it, write a '1' into /proc/sys/kernel/stack_tracer_enabled.
::
# echo 1 > /proc/sys/kernel/stack_tracer_enabled # echo 1 > /proc/sys/kernel/stack_tracer_enabled
...@@ -3182,9 +3294,10 @@ the stack size of the kernel during boot up, by adding "stacktrace" ...@@ -3182,9 +3294,10 @@ the stack size of the kernel during boot up, by adding "stacktrace"
to the kernel command line parameter. to the kernel command line parameter.
After running it for a few minutes, the output looks like: After running it for a few minutes, the output looks like:
::
# cat stack_max_size # cat stack_max_size
2928 2928
# cat stack_trace # cat stack_trace
Depth Size Location (18 entries) Depth Size Location (18 entries)
...@@ -3214,7 +3327,6 @@ are not tested by the stack tracer when -mfentry is used. ...@@ -3214,7 +3327,6 @@ are not tested by the stack tracer when -mfentry is used.
Currently, -mfentry is used by gcc 4.6.0 and above on x86 only. Currently, -mfentry is used by gcc 4.6.0 and above on x86 only.
--------- More
----
More details can be found in the source code, in the More details can be found in the source code, in the `kernel/trace/*.c` files.
kernel/trace/*.c files.
Documentation/trace/hwlat_detector.txt → Documentation/trace/hwlat_detector.rst
View file @ bb2407a7
Introduction: =========================
Hardware Latency Detector
=========================
Introduction
------------- -------------
The tracer hwlat_detector is a special purpose tracer that is used to 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. ...@@ -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 It is intended to be run manually to determine if the hardware platform has a
problem with long system firmware service routines. problem with long system firmware service routines.
Usage: Usage
------ ------
Write the ASCII text "hwlat" into the current_tracer file of the tracing system 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 ...@@ -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 redefine the threshold in microseconds (us) above which latency spikes will
be taken into account. be taken into account.
Example: Example::
# echo hwlat > /sys/kernel/tracing/current_tracer # echo hwlat > /sys/kernel/tracing/current_tracer
# echo 100 > /sys/kernel/tracing/tracing_thresh # echo 100 > /sys/kernel/tracing/tracing_thresh
The /sys/kernel/tracing/hwlat_detector interface contains the following files: The /sys/kernel/tracing/hwlat_detector interface contains the following files:
width - time period to sample with CPUs held (usecs) - width - time period to sample with CPUs held (usecs)
must be less than the total window size (enforced) must be less than the total window size (enforced)
window - total period of sampling, width being inside (usecs) - 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 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 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: ...@@ -67,11 +71,11 @@ The following tracing directory files are used by the hwlat_detector:
in /sys/kernel/tracing: in /sys/kernel/tracing:
tracing_threshold - minimum latency value to be considered (usecs) - tracing_threshold - minimum latency value to be considered (usecs)
tracing_max_latency - maximum hardware latency actually observed (usecs) - tracing_max_latency - maximum hardware latency actually observed (usecs)
tracing_cpumask - the CPUs to move the hwlat thread across - tracing_cpumask - the CPUs to move the hwlat thread across
hwlat_detector/width - specified amount of time to spin within window (usecs) - hwlat_detector/width - specified amount of time to spin within window (usecs)
hwlat_detector/window - amount of time between (width) runs (usecs) - hwlat_detector/window - amount of time between (width) runs (usecs)
The hwlat detector's kernel thread will migrate across each CPU specified in The hwlat detector's kernel thread will migrate across each CPU specified in
tracing_cpumask between each window. To limit the migration, either modify tracing_cpumask between each window. To limit the migration, either modify
......
Documentation/trace/index.rst 0 → 100644
View file @ bb2407a7
==========================
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
Documentation/trace/intel_th.txt → Documentation/trace/intel_th.rst
View file @ bb2407a7
=======================
Intel(R) Trace Hub (TH) Intel(R) Trace Hub (TH)
======================= =======================
...@@ -65,41 +66,41 @@ allocated, are accessible via /dev/intel_th0/msc{0,1}. ...@@ -65,41 +66,41 @@ allocated, are accessible via /dev/intel_th0/msc{0,1}.
Quick example 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 $ cat /sys/bus/intel_th/devices/0-msc0/port
0 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 # 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 multi > /sys/bus/intel_th/devices/0-msc0/mode
$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages $ 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 .. # .. send data to master 33, see stm.txt for more details ..
# .. wait for traces to pile up .. # .. 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 Host Debugger Mode
================== ------------------
It is possible to configure the Trace Hub and control its trace 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 capture from a remote debug host, which should be connected via one of
......
Documentation/trace/kprobetrace.txt → Documentation/trace/kprobetrace.rst
View file @ bb2407a7
Kprobe-based Event Tracing ==========================
========================== Kprobe-based Event Tracing
==========================
Documentation is written by Masami Hiramatsu
:Author: Masami Hiramatsu
Overview Overview
-------- --------
...@@ -23,6 +23,8 @@ current_tracer. Instead of that, add probe points via ...@@ -23,6 +23,8 @@ current_tracer. Instead of that, add probe points via
Synopsis of kprobe_events Synopsis of kprobe_events
------------------------- -------------------------
::
p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe
r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe
-:[GRP/]EVENT : Clear a probe -:[GRP/]EVENT : Clear a probe
...@@ -66,7 +68,7 @@ String type is a special type, which fetches a "null-terminated" string from ...@@ -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 kernel space. This means it will fail and store NULL if the string container
has been paged out. has been paged out.
Bitfield is another special type, which takes 3 parameters, bit-width, bit- 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> b<bit-width>@<bit-offset>/<container-size>
...@@ -75,7 +77,7 @@ For $comm, the default type is "string"; any other type is invalid. ...@@ -75,7 +77,7 @@ For $comm, the default type is "string"; any other type is invalid.
Per-Probe Event Filtering 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 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 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', under tracing/events/kprobes/<EVENT>, at the directory you can see 'id',
...@@ -96,37 +98,39 @@ id: ...@@ -96,37 +98,39 @@ id:
Event Profiling 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. /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. the third is the number of probe miss-hits.
Usage examples Usage examples
-------------- --------------
To add a probe as a new event, write a new definition to kprobe_events 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 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 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 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 the ABI, please try to use probe subcommand of perf-tools (you can find it
under tools/perf/). under tools/perf/).
As this example shows, users can choose more familiar names for each arguments. 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 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. 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. /sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
::
cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
name: myprobe name: myprobe
ID: 780 ID: 780
format: format:
field:unsigned short common_type; offset:0; size:2; signed:0; 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_flags; offset:2; size:1; signed:0;
field:unsigned char common_preempt_count; offset:3; size:1;signed:0; field:unsigned char common_preempt_count; offset:3; size:1;signed:0;
...@@ -140,34 +144,38 @@ format: ...@@ -140,34 +144,38 @@ format:
field:unsigned long mode; offset:32; 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, print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
REC->dfd, REC->filename, REC->flags, REC->mode 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 echo > /sys/kernel/debug/tracing/kprobe_events
This clears all probe points. This clears all probe points.
Or, Or,
::
echo -:myprobe >> kprobe_events 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. events, you need to enable it.
::
echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/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 cat /sys/kernel/debug/tracing/trace
# tracer: nop # tracer: nop
# #
# TASK-PID CPU# TIMESTAMP FUNCTION # 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.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.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.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6
...@@ -176,7 +184,7 @@ events, you need to enable it. ...@@ -176,7 +184,7 @@ events, you need to enable it.
<...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3 <...>-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 SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
returns from do_sys_open to sys_open+0x1b). returns from do_sys_open to sys_open+0x1b).
Documentation/trace/mmiotrace.txt → Documentation/trace/mmiotrace.rst
View file @ bb2407a7
In-kernel memory-mapped I/O tracing ===================================
In-kernel memory-mapped I/O tracing
===================================
Home page and links to optional user space tools: 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. ...@@ -31,30 +33,35 @@ is no way to automatically detect if you are losing events due to CPUs racing.
Usage Quick Reference Usage Quick Reference
--------------------- ---------------------
::
$ mount -t debugfs debugfs /sys/kernel/debug $ mount -t debugfs debugfs /sys/kernel/debug
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt &
Start X or whatever. Start X or whatever.
$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker $ echo "X is up" > /sys/kernel/debug/tracing/trace_marker
$ echo nop > /sys/kernel/debug/tracing/current_tracer $ echo nop > /sys/kernel/debug/tracing/current_tracer
Check for lost events. Check for lost events.
Usage Usage
----- -----
Make sure debugfs is mounted to /sys/kernel/debug. Make sure debugfs is mounted to /sys/kernel/debug.
If not (requires root privileges): If not (requires root privileges)::
$ mount -t debugfs debugfs /sys/kernel/debug
$ mount -t debugfs debugfs /sys/kernel/debug
Check that the driver you are about to trace is not loaded. Check that the driver you are about to trace is not loaded.
Activate mmiotrace (requires root privileges): Activate mmiotrace (requires root privileges)::
$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer
$ 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. 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 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 ...@@ -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 which action. It is recommended to place descriptive markers about what you
do. do.
Shut down mmiotrace (requires root privileges): Shut down mmiotrace (requires root privileges)::
$ echo nop > /sys/kernel/debug/tracing/current_tracer
$ echo nop > /sys/kernel/debug/tracing/current_tracer
The 'cat' process exits. If it does not, kill it by issuing 'fg' command and The 'cat' process exits. If it does not, kill it by issuing 'fg' command and
pressing ctrl+c. pressing ctrl+c.
Check that mmiotrace did not lose events due to a buffer filling up. Either 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 $ grep -i lost mydump.txt
$ dmesg
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 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 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 try again. Buffers are enlarged by first seeing how large the current buffers
are: are::
$ cat /sys/kernel/debug/tracing/buffer_size_kb
$ cat /sys/kernel/debug/tracing/buffer_size_kb
gives you a number. Approximately double this number and write it back, for gives you a number. Approximately double this number and write it back, for
instance: instance::
$ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb
$ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb
Then start again from the top. Then start again from the top.
If you are doing a trace for a driver project, e.g. Nouveau, you should also If you are doing a trace for a driver project, e.g. Nouveau, you should also
do the following before sending your results: do the following before sending your results::
$ lspci -vvv > lspci.txt
$ dmesg > dmesg.txt $ lspci -vvv > lspci.txt
$ tar zcf pciid-nick-mmiotrace.tar.gz mydump.txt lspci.txt dmesg.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 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 "pciid" and "nick" with the PCI ID or model name of your piece of hardware
under investigation and your nickname. under investigation and your nickname.
...@@ -148,17 +167,18 @@ zero if it is not recorded. PID is always zero as tracing MMIO accesses ...@@ -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. originating in user space memory is not yet supported.
For instance, the following awk filter will pass all 32-bit writes that target 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 && $ awk '/W 4 / { adr=strtonum($5); if (adr >= 0xfb73ce40 &&
adr < 0xfb800000) print; }' adr < 0xfb800000) print; }'
Tools for Developers Tools for Developers
-------------------- --------------------
The user space tools include utilities for: The user space tools include utilities for:
- replacing numeric addresses and values with hardware register names - replacing numeric addresses and values with hardware register names
- replaying MMIO logs, i.e., re-executing the recorded writes - replaying MMIO logs, i.e., re-executing the recorded writes
Documentation/trace/stm.txt → Documentation/trace/stm.rst
View file @ bb2407a7
===================
System Trace Module System Trace Module
=================== ===================
...@@ -32,14 +33,14 @@ associated with it, located in "stp-policy" subsystem directory in ...@@ -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 configfs. The topmost directory's name (the policy) is formatted as
the STM device name to which this policy applies and and arbitrary the STM device name to which this policy applies and and arbitrary
string identifier separated by a stop. From the examle above, a rule 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 $ ls /config/stp-policy/dummy_stm.my-policy/user
channels masters channels masters
$ cat /config/stp-policy/dummy_stm.my-policy/user/masters $ cat /config/stp-policy/dummy_stm.my-policy/user/masters
48 63 48 63
$ cat /config/stp-policy/dummy_stm.my-policy/user/channels $ cat /config/stp-policy/dummy_stm.my-policy/user/channels
0 127 0 127
which means that the master allocation pool for this rule consists of which means that the master allocation pool for this rule consists of
masters 48 through 63 and channel allocation pool has channels 0 masters 48 through 63 and channel allocation pool has channels 0
...@@ -78,9 +79,9 @@ stm_source ...@@ -78,9 +79,9 @@ stm_source
For kernel-based trace sources, there is "stm_source" device For kernel-based trace sources, there is "stm_source" device
class. Devices of this class can be connected and disconnected to/from class. Devices of this class can be connected and disconnected to/from
stm devices at runtime via a sysfs attribute called "stm_source_link" 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 For examples on how to use stm_source interface in the kernel, refer
to stm_console, stm_heartbeat or stm_ftrace drivers. to stm_console, stm_heartbeat or stm_ftrace drivers.
...@@ -118,5 +119,5 @@ the same time. ...@@ -118,5 +119,5 @@ the same time.
Currently only Ftrace "function" tracer is supported. Currently only Ftrace "function" tracer is supported.
[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf * [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 * [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
Documentation/trace/tracepoint-analysis.txt → Documentation/trace/tracepoint-analysis.rst
View file @ bb2407a7
Notes on Analysing Behaviour Using Events and Tracepoints =========================================================
Notes on Analysing Behaviour Using Events and Tracepoints
Documentation written by Mel Gorman =========================================================
PCL information heavily based on email from Ingo Molnar :Author: Mel Gorman (PCL information heavily based on email from Ingo Molnar)
1. Introduction 1. Introduction
=============== ===============
...@@ -27,18 +27,18 @@ assumed that the PCL tool tools/perf has been installed and is in your path. ...@@ -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 All possible events are visible from /sys/kernel/debug/tracing/events. Simply
calling calling::
$ find /sys/kernel/debug/tracing/events -type d $ find /sys/kernel/debug/tracing/events -type d
will give a fair indication of the number of events available. will give a fair indication of the number of events available.
2.2 PCL (Performance Counters for Linux) 2.2 PCL (Performance Counters for Linux)
------- ----------------------------------------
Discovery and enumeration of all counters and events, including tracepoints, Discovery and enumeration of all counters and events, including tracepoints,
are available with the perf tool. Getting a list of available events is a 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 $ perf list 2>&1 | grep Tracepoint
ext4:ext4_free_inode [Tracepoint event] ext4:ext4_free_inode [Tracepoint event]
...@@ -57,7 +57,7 @@ simple case of: ...@@ -57,7 +57,7 @@ simple case of:
See Documentation/trace/events.txt for a proper description on how events 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 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 $ 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: ...@@ -67,6 +67,7 @@ to page allocation would look something like:
In SystemTap, tracepoints are accessible using the kernel.trace() function In SystemTap, tracepoints are accessible using the kernel.trace() function
call. The following is an example that reports every 5 seconds what processes call. The following is an example that reports every 5 seconds what processes
were allocating the pages. were allocating the pages.
::
global page_allocs global page_allocs
...@@ -91,6 +92,7 @@ were allocating the pages. ...@@ -91,6 +92,7 @@ were allocating the pages.
By specifying the -a switch and analysing sleep, the system-wide events By specifying the -a switch and analysing sleep, the system-wide events
for a duration of time can be examined. for a duration of time can be examined.
::
$ perf stat -a \ $ perf stat -a \
-e kmem:mm_page_alloc -e kmem:mm_page_free \ -e kmem:mm_page_alloc -e kmem:mm_page_free \
...@@ -118,6 +120,7 @@ basis using set_ftrace_pid. ...@@ -118,6 +120,7 @@ basis using set_ftrace_pid.
Events can be activated and tracked for the duration of a process on a local Events can be activated and tracked for the duration of a process on a local
basis using PCL such as follows. basis using PCL such as follows.
::
$ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \ $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \
-e kmem:mm_page_free_batched ./hackbench 10 -e kmem:mm_page_free_batched ./hackbench 10
...@@ -145,6 +148,7 @@ Any workload can exhibit variances between runs and it can be important ...@@ -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 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 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. 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 $ perf stat --repeat 5 -e kmem:mm_page_alloc -e kmem:mm_page_free
-e kmem:mm_page_free_batched ./hackbench 10 -e kmem:mm_page_free_batched ./hackbench 10
...@@ -167,6 +171,7 @@ aggregation of discrete events, then a script would need to be developed. ...@@ -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 Using --repeat, it is also possible to view how events are fluctuating over
time on a system-wide basis using -a and sleep. time on a system-wide basis using -a and sleep.
::
$ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \ $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \
-e kmem:mm_page_free_batched \ -e kmem:mm_page_free_batched \
...@@ -188,9 +193,9 @@ When events are enabled the events that are triggering can be read from ...@@ -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 options exist as well. By post-processing the output, further information can
be gathered on-line as appropriate. Examples of post-processing might include be gathered on-line as appropriate. Examples of post-processing might include
o Reading information from /proc for the PID that triggered the event - Reading information from /proc for the PID that triggered the event
o Deriving a higher-level event from a series of lower-level events. - Deriving a higher-level event from a series of lower-level events.
o Calculating latencies between two events - Calculating latencies between two events
Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example 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 script that can read trace_pipe from STDIN or a copy of a trace. When used
...@@ -200,14 +205,14 @@ and twice to exit. ...@@ -200,14 +205,14 @@ and twice to exit.
Simplistically, the script just reads STDIN and counts up events but it Simplistically, the script just reads STDIN and counts up events but it
also can do more such as 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 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 that as one per-CPU drain even though there is no specific tracepoint
for that event for that event
o It can aggregate based on PID or individual process number - It can aggregate based on PID or individual process number
o In the event memory is getting externally fragmented, it reports - In the event memory is getting externally fragmented, it reports
on whether the fragmentation event was severe or moderate. 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 that if large numbers of events are coming from very short-lived
processes, the parent process responsible for creating all the helpers processes, the parent process responsible for creating all the helpers
can be identified can be identified
...@@ -218,6 +223,7 @@ also can do more such as ...@@ -218,6 +223,7 @@ also can do more such as
There may also be a requirement to identify what functions within a program 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 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: data must be recorded. At the time of writing, this required root:
::
$ perf record -c 1 \ $ perf record -c 1 \
-e kmem:mm_page_alloc -e kmem:mm_page_free \ -e kmem:mm_page_alloc -e kmem:mm_page_free \
...@@ -232,6 +238,7 @@ very coarse as a result. ...@@ -232,6 +238,7 @@ very coarse as a result.
This record outputted a file called perf.data which can be analysed using This record outputted a file called perf.data which can be analysed using
perf report. perf report.
::
$ perf report $ perf report
# Samples: 30922 # Samples: 30922
...@@ -258,6 +265,7 @@ within the VDSO. With simple binaries, this will often be the case so let's ...@@ -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 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 noticed that X was generating an insane amount of page allocations so let's look
at it: at it:
::
$ perf record -c 1 -f \ $ perf record -c 1 -f \
-e kmem:mm_page_alloc -e kmem:mm_page_free \ -e kmem:mm_page_alloc -e kmem:mm_page_free \
...@@ -265,6 +273,7 @@ at it: ...@@ -265,6 +273,7 @@ at it:
-p `pidof X` -p `pidof X`
This was interrupted after a few seconds and This was interrupted after a few seconds and
::
$ perf report $ perf report
# Samples: 27666 # Samples: 27666
...@@ -282,6 +291,7 @@ This was interrupted after a few seconds and ...@@ -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 So, almost half of the events are occurring in a library. To get an idea which
symbol: symbol:
::
$ perf report --sort comm,dso,symbol $ perf report --sort comm,dso,symbol
# Samples: 27666 # Samples: 27666
...@@ -298,6 +308,7 @@ symbol: ...@@ -298,6 +308,7 @@ symbol:
0.00% Xorg [kernel] [k] ftrace_trace_userstack 0.00% Xorg [kernel] [k] ftrace_trace_userstack
To see where within the function pixmanFillsse2 things are going wrong: To see where within the function pixmanFillsse2 things are going wrong:
::
$ perf annotate pixmanFillsse2 $ perf annotate pixmanFillsse2
[ ... ] [ ... ]
......
Documentation/trace/tracepoints.txt → Documentation/trace/tracepoints.rst
View file @ bb2407a7
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 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 ...@@ -9,8 +11,8 @@ connect probe functions to them and provides some examples of probe
functions. functions.
* Purpose of tracepoints Purpose of tracepoints
----------------------
A tracepoint placed in code provides a hook to call a function (probe) 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 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 connected to it) or "off" (no probe is attached). When a tracepoint is
...@@ -31,8 +33,8 @@ header file. ...@@ -31,8 +33,8 @@ header file.
They can be used for tracing and performance accounting. They can be used for tracing and performance accounting.
* Usage Usage
-----
Two elements are required for tracepoints : Two elements are required for tracepoints :
- A tracepoint definition, placed in a header file. - A tracepoint definition, placed in a header file.
...@@ -40,51 +42,52 @@ Two elements are required for tracepoints : ...@@ -40,51 +42,52 @@ Two elements are required for tracepoints :
In order to use tracepoints, you should include linux/tracepoint.h. 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 #undef TRACE_SYSTEM
#define TRACE_SYSTEM subsys #define TRACE_SYSTEM subsys
#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
#define _TRACE_SUBSYS_H #define _TRACE_SUBSYS_H
#include <linux/tracepoint.h> #include <linux/tracepoint.h>
DECLARE_TRACE(subsys_eventname, DECLARE_TRACE(subsys_eventname,
TP_PROTO(int firstarg, struct task_struct *p), TP_PROTO(int firstarg, struct task_struct *p),
TP_ARGS(firstarg, p)); TP_ARGS(firstarg, p));
#endif /* _TRACE_SUBSYS_H */ #endif /* _TRACE_SUBSYS_H */
/* This part must be outside protection */ /* This part must be outside protection */
#include <trace/define_trace.h> #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 CREATE_TRACE_POINTS
DEFINE_TRACE(subsys_eventname); DEFINE_TRACE(subsys_eventname);
void somefct(void) void somefct(void)
{ {
... ...
trace_subsys_eventname(arg, task); trace_subsys_eventname(arg, task);
... ...
} }
Where : 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. - subsys is the name of your subsystem.
- eventname is the name of the event to trace. - eventname is the name of the event to trace.
- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the
function called by this tracepoint. function called by this tracepoint.
- TP_ARGS(firstarg, p) are the parameters names, same as found in the - `TP_ARGS(firstarg, p)` are the parameters names, same as found in the
prototype. prototype.
- if you use the header in multiple source files, #define CREATE_TRACE_POINTS - if you use the header in multiple source files, `#define CREATE_TRACE_POINTS`
should appear only in one source file. should appear only in one source file.
Connecting a function (probe) to a tracepoint is done by providing a Connecting a function (probe) to a tracepoint is done by providing a
...@@ -117,7 +120,7 @@ used to export the defined tracepoints. ...@@ -117,7 +120,7 @@ used to export the defined tracepoints.
If you need to do a bit of work for a tracepoint parameter, and 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 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()) { if (trace_foo_bar_enabled()) {
int i; int i;
...@@ -139,7 +142,7 @@ The advantage of using the trace_<tracepoint>_enabled() is that it uses ...@@ -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 the static_key of the tracepoint to allow the if statement to be implemented
with jump labels and avoid conditional branches. 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, define tracepoints. Check http://lwn.net/Articles/379903,
http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362 http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362
for a series of articles with more details. for a series of articles with more details.
Documentation/trace/uprobetracer.txt → Documentation/trace/uprobetracer.rst
View file @ bb2407a7
Uprobe-tracer: Uprobe-based Event Tracing =========================================
========================================= Uprobe-tracer: Uprobe-based Event Tracing
=========================================
Documentation written by Srikar Dronamraju :Author: Srikar Dronamraju
Overview Overview
...@@ -19,6 +20,8 @@ user to calculate the offset of the probepoint in the object. ...@@ -19,6 +20,8 @@ user to calculate the offset of the probepoint in the object.
Synopsis of uprobe_tracer Synopsis of uprobe_tracer
------------------------- -------------------------
::
p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe
r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe) r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe)
-:[GRP/]EVENT : Clear uprobe or uretprobe event -:[GRP/]EVENT : Clear uprobe or uretprobe event
...@@ -57,7 +60,7 @@ x86-64 uses x64). ...@@ -57,7 +60,7 @@ x86-64 uses x64).
String type is a special type, which fetches a "null-terminated" string from String type is a special type, which fetches a "null-terminated" string from
user space. user space.
Bitfield is another special type, which takes 3 parameters, bit-width, bit- 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> b<bit-width>@<bit-offset>/<container-size>
...@@ -74,28 +77,28 @@ the third is the number of probe miss-hits. ...@@ -74,28 +77,28 @@ the third is the number of probe miss-hits.
Usage examples Usage examples
-------------- --------------
* Add a probe as a new uprobe event, write a new definition to uprobe_events * 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 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 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 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 cat /sys/kernel/debug/tracing/uprobe_events
* Clear all events: * Clear all events::
echo > /sys/kernel/debug/tracing/uprobe_events echo > /sys/kernel/debug/tracing/uprobe_events
Following example shows how to dump the instruction pointer and %ax register 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/ # cd /sys/kernel/debug/tracing/
# cat /proc/`pgrep zsh`/maps | grep /bin/zsh | grep r-xp # 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: ...@@ -103,24 +106,27 @@ at the probed text address. Probe zfree function in /bin/zsh:
# objdump -T /bin/zsh | grep -w zfree # objdump -T /bin/zsh | grep -w zfree
0000000000446420 g DF .text 0000000000000012 Base zfree 0000000000446420 g DF .text 0000000000000012 Base zfree
0x46420 is the offset of zfree in object /bin/zsh that is loaded at 0x46420 is the offset of zfree in object /bin/zsh that is loaded at
0x00400000. Hence the command to uprobe would be: 0x00400000. Hence the command to uprobe would be::
# echo 'p:zfree_entry /bin/zsh:0x46420 %ip %ax' > uprobe_events # 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 # echo 'r:zfree_exit /bin/zsh:0x46420 %ip %ax' >> uprobe_events
Please note: User has to explicitly calculate the offset of the probe-point .. 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 in the object.
uprobe_events file.
We can see the events that are registered by looking at the uprobe_events file.
::
# cat uprobe_events # cat uprobe_events
p:uprobes/zfree_entry /bin/zsh:0x00046420 arg1=%ip arg2=%ax p:uprobes/zfree_entry /bin/zsh:0x00046420 arg1=%ip arg2=%ax
r:uprobes/zfree_exit /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 # cat events/uprobes/zfree_entry/format
name: zfree_entry name: zfree_entry
...@@ -139,16 +145,18 @@ Format of events can be seen by viewing the file events/uprobes/zfree_entry/form ...@@ -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 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 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 # echo 1 > events/uprobes/enable
Lets disable the event after sleeping for some time. Lets disable the event after sleeping for some time.
::
# sleep 20 # sleep 20
# echo 0 > events/uprobes/enable # echo 0 > events/uprobes/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 trace # cat trace
# tracer: nop # tracer: nop
......
Documentation/vm/00-INDEX
View file @ bb2407a7
...@@ -10,6 +10,8 @@ frontswap.txt ...@@ -10,6 +10,8 @@ frontswap.txt
- Outline frontswap, part of the transcendent memory frontend. - Outline frontswap, part of the transcendent memory frontend.
highmem.txt highmem.txt
- Outline of highmem and common issues. - Outline of highmem and common issues.
hmm.txt
- Documentation of heterogeneous memory management
hugetlbpage.txt hugetlbpage.txt
- a brief summary of hugetlbpage support in the Linux kernel. - a brief summary of hugetlbpage support in the Linux kernel.
hugetlbfs_reserv.txt hugetlbfs_reserv.txt
...@@ -20,25 +22,41 @@ idle_page_tracking.txt ...@@ -20,25 +22,41 @@ idle_page_tracking.txt
- description of the idle page tracking feature. - description of the idle page tracking feature.
ksm.txt ksm.txt
- how to use the Kernel Samepage Merging feature. - how to use the Kernel Samepage Merging feature.
mmu_notifier.txt
- a note about clearing pte/pmd and mmu notifications
numa numa
- information about NUMA specific code in the Linux vm. - information about NUMA specific code in the Linux vm.
numa_memory_policy.txt numa_memory_policy.txt
- documentation of concepts and APIs of the 2.6 memory policy support. - documentation of concepts and APIs of the 2.6 memory policy support.
overcommit-accounting overcommit-accounting
- description of the Linux kernels overcommit handling modes. - description of the Linux kernels overcommit handling modes.
page_frags
- description of page fragments allocator
page_migration page_migration
- description of page migration in NUMA systems. - description of page migration in NUMA systems.
pagemap.txt pagemap.txt
- pagemap, from the userspace perspective - 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 slub.txt
- a short users guide for SLUB. - a short users guide for SLUB.
soft-dirty.txt soft-dirty.txt
- short explanation for soft-dirty PTEs - short explanation for soft-dirty PTEs
split_page_table_lock split_page_table_lock
- Separate per-table lock to improve scalability of the old 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 transhuge.txt
- Transparent Hugepage Support, alternative way of using hugepages. - Transparent Hugepage Support, alternative way of using hugepages.
unevictable-lru.txt unevictable-lru.txt
- Unevictable LRU infrastructure - 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 zswap.txt
- Intro to compressed cache for swap pages - Intro to compressed cache for swap pages
README
View file @ bb2407a7
Linux kernel Linux kernel
============ ============
This file was moved to Documentation/admin-guide/README.rst 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
Please notice that there are several guides for kernel developers and users. Documentation/admin-guide/README.rst first.
These guides can be rendered in a number of formats, like HTML and PDF.
In order to build the documentation, use ``make htmldocs`` or 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, There are various text files in the Documentation/ subdirectory,
several of them using the Restructured Text markup notation. several of them using the Restructured Text markup notation.
......
scripts/kernel-doc
View file @ bb2407a7
#!/usr/bin/env perl #!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
use warnings; use warnings;
use strict; use strict;
...@@ -328,13 +329,15 @@ my $lineprefix=""; ...@@ -328,13 +329,15 @@ my $lineprefix="";
use constant { use constant {
STATE_NORMAL => 0, # normal code STATE_NORMAL => 0, # normal code
STATE_NAME => 1, # looking for function name STATE_NAME => 1, # looking for function name
STATE_FIELD => 2, # scanning field start STATE_BODY_MAYBE => 2, # body - or maybe more description
STATE_PROTO => 3, # scanning prototype STATE_BODY => 3, # the body of the comment
STATE_DOCBLOCK => 4, # documentation block STATE_PROTO => 4, # scanning prototype
STATE_INLINE => 5, # gathering documentation outside main block STATE_DOCBLOCK => 5, # documentation block
STATE_INLINE => 6, # gathering documentation outside main block
}; };
my $state; my $state;
my $in_doc_sect; my $in_doc_sect;
my $leading_space;
# Inline documentation state # Inline documentation state
use constant { use constant {
...@@ -363,7 +366,7 @@ my $doc_sect = $doc_com . ...@@ -363,7 +366,7 @@ my $doc_sect = $doc_com .
my $doc_content = $doc_com_body . '(.*)'; my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\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_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\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*;'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
...@@ -553,10 +556,9 @@ sub output_highlight { ...@@ -553,10 +556,9 @@ sub output_highlight {
} }
if ($line eq ""){ if ($line eq ""){
if (! $output_preformatted) { if (! $output_preformatted) {
print $lineprefix, local_unescape($blankline); print $lineprefix, $blankline;
} }
} else { } else {
$line =~ s/\\\\\\/\&/g;
if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
print "\\&$line"; print "\\&$line";
} else { } else {
...@@ -747,17 +749,73 @@ sub output_blockhead_rst(%) { ...@@ -747,17 +749,73 @@ sub output_blockhead_rst(%) {
} }
} }
#
# 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;
}
#
# Regexes used only here.
#
my $sphinx_literal = '^[^.].*::$';
my $sphinx_cblock = '^\.\.\ +code-block::';
sub output_highlight_rst { sub output_highlight_rst {
my $contents = join "\n",@_; my $input = join "\n",@_;
my $output = "";
my $line; my $line;
my $in_literal = 0;
my $litprefix;
my $block = "";
# undo the evil effects of xml_escape() earlier foreach $line (split "\n",$input) {
$contents = xml_unescape($contents); #
# If we're in a literal block, see if we should drop out
eval $dohighlight; # of it. Otherwise pass the line straight through unmunged.
die $@ if $@; #
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 = ""
}
}
}
foreach $line (split "\n", $contents) { if ($block) {
$output .= highlight_block($block);
}
foreach $line (split "\n", $output) {
print $lineprefix . $line . "\n"; print $lineprefix . $line . "\n";
} }
} }
...@@ -1062,7 +1120,7 @@ sub dump_struct($$) { ...@@ -1062,7 +1120,7 @@ sub dump_struct($$) {
# Handle bitmaps # Handle bitmaps
$arg =~ s/:\s*\d+\s*//g; $arg =~ s/:\s*\d+\s*//g;
# Handle arrays # Handle arrays
$arg =~ s/\[\S+\]//g; $arg =~ s/\[.*\]//g;
# The type may have multiple words, # The type may have multiple words,
# and multiple IDs can be defined, like: # and multiple IDs can be defined, like:
# const struct foo, *bar, foobar # const struct foo, *bar, foobar
...@@ -1422,8 +1480,6 @@ sub push_parameter($$$$) { ...@@ -1422,8 +1480,6 @@ sub push_parameter($$$$) {
} }
} }
$param = xml_escape($param);
# strip spaces from $param so that it is one continuous string # strip spaces from $param so that it is one continuous string
# on @parameterlist; # on @parameterlist;
# this fixes a problem where check_sections() cannot find # this fixes a problem where check_sections() cannot find
...@@ -1522,6 +1578,7 @@ sub dump_function($$) { ...@@ -1522,6 +1578,7 @@ sub dump_function($$) {
$prototype =~ s/__meminit +//; $prototype =~ s/__meminit +//;
$prototype =~ s/__must_check +//; $prototype =~ s/__must_check +//;
$prototype =~ s/__weak +//; $prototype =~ s/__weak +//;
$prototype =~ s/__sched +//;
my $define = $prototype =~ s/^#\s*define\s+//; #ak added my $define = $prototype =~ s/^#\s*define\s+//; #ak added
$prototype =~ s/__attribute__\s*\(\( $prototype =~ s/__attribute__\s*\(\(
(?: (?:
...@@ -1748,47 +1805,6 @@ sub process_proto_type($$) { ...@@ -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($) { sub map_filename($) {
my $file; my $file;
...@@ -1826,40 +1842,27 @@ sub process_export_file($) { ...@@ -1826,40 +1842,27 @@ sub process_export_file($) {
close(IN); close(IN);
} }
sub process_file($) { #
my $file; # Parsers for the various processing states.
my $identifier; #
my $func; # STATE_NORMAL: looking for the /** to begin everything.
my $descr; #
my $in_purpose = 0; sub process_normal() {
my $initial_section_counter = $section_counter;
my ($orig_file) = @_;
my $leading_space;
$file = map_filename($orig_file);
if (!open(IN,"<$file")) {
print STDERR "Error: Cannot open file $file\n";
++$errors;
return;
}
$. = 1;
$section_counter = 0;
while (<IN>) {
while (s/\\\s*$//) {
$_ .= <IN>;
}
# Replace tabs by spaces
while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
if ($state == STATE_NORMAL) {
if (/$doc_start/o) { if (/$doc_start/o) {
$state = STATE_NAME; # next line is always the function name $state = STATE_NAME; # next line is always the function name
$in_doc_sect = 0; $in_doc_sect = 0;
$declaration_start_line = $. + 1; $declaration_start_line = $. + 1;
} }
} elsif ($state == STATE_NAME) {# this line is the function name (always) }
#
# STATE_NAME: Looking for the "name - description" line
#
sub process_name($$) {
my $file = shift;
my $identifier;
my $descr;
if (/$doc_block/o) { if (/$doc_block/o) {
$state = STATE_DOCBLOCK; $state = STATE_DOCBLOCK;
$contents = ""; $contents = "";
...@@ -1873,11 +1876,11 @@ sub process_file($) { ...@@ -1873,11 +1876,11 @@ sub process_file($) {
} }
elsif (/$doc_decl/o) { elsif (/$doc_decl/o) {
$identifier = $1; $identifier = $1;
if (/\s*([\w\s]+?)\s*-/) { if (/\s*([\w\s]+?)(\(\))?\s*-/) {
$identifier = $1; $identifier = $1;
} }
$state = STATE_FIELD; $state = STATE_BODY;
# if there's no @param blocks need to set up default section # if there's no @param blocks need to set up default section
# here # here
$contents = ""; $contents = "";
...@@ -1889,8 +1892,8 @@ sub process_file($) { ...@@ -1889,8 +1892,8 @@ sub process_file($) {
$descr =~ s/^\s*//; $descr =~ s/^\s*//;
$descr =~ s/\s*$//; $descr =~ s/\s*$//;
$descr =~ s/\s+/ /g; $descr =~ s/\s+/ /g;
$declaration_purpose = xml_escape($descr); $declaration_purpose = $descr;
$in_purpose = 1; $state = STATE_BODY_MAYBE;
} else { } else {
$declaration_purpose = ""; $declaration_purpose = "";
} }
...@@ -1922,7 +1925,15 @@ sub process_file($) { ...@@ -1922,7 +1925,15 @@ sub process_file($) {
++$warnings; ++$warnings;
$state = STATE_NORMAL; $state = STATE_NORMAL;
} }
} elsif ($state == STATE_FIELD) { # look for head: lines, and include content }
#
# 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 if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1; $newsection = $1;
$newcontents = $2; $newcontents = $2;
...@@ -1944,12 +1955,12 @@ sub process_file($) { ...@@ -1944,12 +1955,12 @@ sub process_file($) {
print STDERR "${file}:$.: warning: contents before sections\n"; print STDERR "${file}:$.: warning: contents before sections\n";
++$warnings; ++$warnings;
} }
dump_section($file, $section, xml_escape($contents)); dump_section($file, $section, $contents);
$section = $section_default; $section = $section_default;
} }
$in_doc_sect = 1; $in_doc_sect = 1;
$in_purpose = 0; $state = STATE_BODY;
$contents = $newcontents; $contents = $newcontents;
$new_start_line = $.; $new_start_line = $.;
while (substr($contents, 0, 1) eq " ") { while (substr($contents, 0, 1) eq " ") {
...@@ -1962,7 +1973,7 @@ sub process_file($) { ...@@ -1962,7 +1973,7 @@ sub process_file($) {
$leading_space = undef; $leading_space = undef;
} elsif (/$doc_end/) { } elsif (/$doc_end/) {
if (($contents ne "") && ($contents ne "\n")) { if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents)); dump_section($file, $section, $contents);
$section = $section_default; $section = $section_default;
$contents = ""; $contents = "";
} }
...@@ -1975,24 +1986,23 @@ sub process_file($) { ...@@ -1975,24 +1986,23 @@ sub process_file($) {
$prototype = ""; $prototype = "";
$state = STATE_PROTO; $state = STATE_PROTO;
$brcount = 0; $brcount = 0;
# print STDERR "end of doc comment, looking for prototype\n";
} elsif (/$doc_content/) { } elsif (/$doc_content/) {
# miguel-style comment kludge, look for blank lines after # miguel-style comment kludge, look for blank lines after
# @parameter line to signify start of description # @parameter line to signify start of description
if ($1 eq "") { if ($1 eq "") {
if ($section =~ m/^@/ || $section eq $section_context) { if ($section =~ m/^@/ || $section eq $section_context) {
dump_section($file, $section, xml_escape($contents)); dump_section($file, $section, $contents);
$section = $section_default; $section = $section_default;
$contents = ""; $contents = "";
$new_start_line = $.; $new_start_line = $.;
} else { } else {
$contents .= "\n"; $contents .= "\n";
} }
$in_purpose = 0; $state = STATE_BODY;
} elsif ($in_purpose == 1) { } elsif ($state == STATE_BODY_MAYBE) {
# Continued declaration purpose # Continued declaration purpose
chomp($declaration_purpose); chomp($declaration_purpose);
$declaration_purpose .= " " . xml_escape($1); $declaration_purpose .= " " . $1;
$declaration_purpose =~ s/\s+/ /g; $declaration_purpose =~ s/\s+/ /g;
} else { } else {
my $cont = $1; my $cont = $1;
...@@ -2004,7 +2014,6 @@ sub process_file($) { ...@@ -2004,7 +2014,6 @@ sub process_file($) {
$leading_space = ""; $leading_space = "";
} }
} }
$cont =~ s/^$leading_space//; $cont =~ s/^$leading_space//;
} }
$contents .= $cont . "\n"; $contents .= $cont . "\n";
...@@ -2014,7 +2023,67 @@ sub process_file($) { ...@@ -2014,7 +2023,67 @@ sub process_file($) {
print STDERR "${file}:$.: warning: bad line: $_"; print STDERR "${file}:$.: warning: bad line: $_";
++$warnings; ++$warnings;
} }
} elsif ($state == STATE_INLINE) { # scanning for inline parameters }
#
# 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 # First line (state 1) needs to be a @parameter
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
$section = $1; $section = $1;
...@@ -2030,7 +2099,7 @@ sub process_file($) { ...@@ -2030,7 +2099,7 @@ sub process_file($) {
# Documentation block end */ # Documentation block end */
} elsif (/$doc_inline_end/) { } elsif (/$doc_inline_end/) {
if (($contents ne "") && ($contents ne "\n")) { if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents)); dump_section($file, $section, $contents);
$section = $section_default; $section = $section_default;
$contents = ""; $contents = "";
} }
...@@ -2051,52 +2120,48 @@ sub process_file($) { ...@@ -2051,52 +2120,48 @@ sub process_file($) {
++$warnings; ++$warnings;
} }
} }
} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype) }
if (/$doc_inline_oneline/) {
$section = $1;
$contents = $2; sub process_file($) {
if ($contents ne "") { my $file;
$contents .= "\n"; my $initial_section_counter = $section_counter;
dump_section($file, $section, xml_escape($contents)); my ($orig_file) = @_;
$section = $section_default;
$contents = ""; $file = map_filename($orig_file);
if (!open(IN,"<$file")) {
print STDERR "Error: Cannot open file $file\n";
++$errors;
return;
} }
} elsif (/$doc_inline_start/) {
$state = STATE_INLINE; $. = 1;
$inline_doc_state = STATE_INLINE_NAME;
} elsif ($decl_type eq 'function') { $section_counter = 0;
process_proto_function($_, $file); while (<IN>) {
} else { while (s/\\\s*$//) {
process_proto_type($_, $file); $_ .= <IN>;
} }
# 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) {
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
process_inline($file, $_);
} elsif ($state == STATE_PROTO) {
process_proto($file, $_);
} elsif ($state == STATE_DOCBLOCK) { } elsif ($state == STATE_DOCBLOCK) {
if (/$doc_end/) process_docblock($file, $_);
{
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";
}
}
} }
} }
# Make sure we got something interesting.
if ($initial_section_counter == $section_counter) { if ($initial_section_counter == $section_counter) {
if ($output_mode ne "none") { if ($output_mode ne "none") {
print STDERR "${file}:1: warning: no structured comments found\n"; print STDERR "${file}:1: warning: no structured comments found\n";
......
scripts/split-man.pl 0 → 100755
View file @ bb2407a7
#!/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;
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7