linux This list is the Linux Device List the official registry of allocated admindevices Linux allocated devices 4 x version system The version of this document at lanana org is no longer maintained This device numbers and directory nodes for the Linux operating

Answer:
.. _admin_devices:

Linux allocated devices (4.x+ version)
======================================

This list is the Linux Device List, the official registry of allocated
device numbers and ``/dev`` directory nodes for the Linux operating
system.

The version of this document at lanana.org is no longer maintained.  This
version in the mainline Linux kernel is the master document.  Updates
shall be sent as patches to the kernel maintainers (see the
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
Specifically explore the sections titled "CHAR and MISC DRIVERS", and
"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
to involve for character and block devices.

This document is included by reference into the Filesystem Hierarchy
Standard (FHS).	 The FHS is available from https://www.pathname.com/fhs/.

Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga
platform only.	Allocations marked (68k/Atari) apply to Linux/68k on
the Atari platform only.

This document is in the public domain.	The authors requests, however,
that semantically altered versions are not distributed without
permission of the authors, assuming the authors can be contacted without
an unreasonable effort.

.. attention::

  DEVICE DRIVERS AUTHORS PLEASE READ THIS

  Linux now has extensive support for dynamic allocation of device numbering
  and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs.
  There are still some exceptions in the serial and boot device area. Before
  asking   for a device number make sure you actually need one.

  To have a major number allocated, or a minor number in situations
  where that applies (e.g. busmice), please submit a patch and send to
  the authors as indicated above.

  Keep the description of the device *in the same format
  as this list*. The reason for this is that it is the only way we have
  found to ensure we have all the requisite information to publish your
  device and avoid conflicts.

  Finally, sometimes we have to play "namespace police."  Please don't be
  offended.  We often get submissions for ``/dev`` names that would be bound
  to cause conflicts down the road.  We are trying to avoid getting in a
  situation where we would have to suffer an incompatible forward
  change.  Therefore, please consult with us **before** you make your
  device names and numbers in any way public, at least to the point
  where it would be at all difficult to get them changed.

  Your cooperation is appreciated.

.. include:: devices.txt
   :literal:

Additional ``/dev/`` directory entries
--------------------------------------

This section details additional entries that should or may exist in
the /dev directory.  It is preferred that symbolic links use the same
form (absolute or relative) as is indicated here.  Links are
classified as "hard" or "symbolic" depending on the preferred type of
link; if possible, the indicated type of link should be used.

Compulsory links
++++++++++++++++

These links should exist on all systems:

=============== =============== =============== ===============================
/dev/fd		/proc/self/fd	symbolic	File descriptors
/dev/stdin	fd/0		symbolic	stdin file descriptor
/dev/stdout	fd/1		symbolic	stdout file descriptor
/dev/stderr	fd/2		symbolic	stderr file descriptor
/dev/nfsd	socksys		symbolic	Required by iBCS-2
/dev/X0R	null		symbolic	Required by iBCS-2
=============== =============== =============== ===============================

Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.

Recommended links
+++++++++++++++++

It is recommended that these links exist on all systems:

=============== =============== =============== ===============================
/dev/core	/proc/kcore	symbolic	Backward compatibility
/dev/ramdisk	ram0		symbolic	Backward compatibility
/dev/ftape	qft0		symbolic	Backward compatibility
/dev/bttv0	video0		symbolic	Backward compatibility
/dev/radio	radio0		symbolic	Backward compatibility
/dev/i2o*	/dev/i2o/*	symbolic	Backward compatibility
/dev/scd?	sr?		hard		Alternate SCSI CD-ROM name
=============== =============== =============== ===============================

Locally defined links
+++++++++++++++++++++

The following links may be established locally to conform to the
configuration of the system.  This is merely a tabulation of existing
practice, and does not constitute a recommendation.  However, if they
exist, they should have the following uses.

=============== =============== =============== ===============================
/dev/mouse	mouse port	symbolic	Current mouse device
/dev/tape	tape device	symbolic	Current tape device
/dev/cdrom	CD-ROM device	symbolic	Current CD-ROM device
/dev/cdwriter	CD-writer	symbolic	Current CD-writer device
/dev/scanner	scanner		symbolic	Current scanner device
/dev/modem	modem port	symbolic	Current dialout device
/dev/root	root device	symbolic	Current root filesystem
/dev/swap	swap device	symbolic	Current swap device
=============== =============== =============== ===============================

``/dev/modem`` should not be used for a modem which supports dialin as
well as dialout, as it tends to cause lock file problems.  If it
exists, ``/dev/modem`` should point to the appropriate primary TTY device
(the use of the alternate callout devices is deprecated).

For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the
*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas
``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic
SCSI devices (/dev/sg*).

``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).

Sockets and pipes
+++++++++++++++++

Non-transient sockets and named pipes may exist in /dev.  Common entries are:

=============== =============== ===============================================
/dev/printer	socket		lpd local socket
/dev/log	socket		syslog local socket
/dev/gpmdata	socket		gpm mouse multiplexer
=============== =============== ===============================================

Mount points
++++++++++++

The following names are reserved for mounting special filesystems
under /dev.  These special filesystems provide kernel interfaces that
cannot be provided with standard device nodes.

=============== =============== ===============================================
/dev/pts	devpts		PTY slave filesystem
/dev/shm	tmpfs		POSIX shared memory maintenance access
=============== =============== ===============================================

Terminal devices
----------------

Terminal, or TTY devices are a special class of character devices.  A
terminal device is any device that could act as a controlling terminal
for a session; this includes virtual consoles, serial ports, and
pseudoterminals (PTYs).

All terminal devices share a common set of capabilities known as line
disciplines; these include the common terminal line discipline as well
as SLIP and PPP modes.

All terminal devices are named similarly; this section explains the
naming and use of the various types of TTYs.  Note that the naming
conventions include several historical warts; some of these are
Linux-specific, some were inherited from other systems, and some
reflect Linux outgrowing a borrowed convention.

A hash mark (``#``) in a device name is used here to indicate a decimal
number without leading zeroes.

Virtual consoles and the console device
+++++++++++++++++++++++++++++++++++++++

Virtual consoles are full-screen terminal displays on the system video
monitor.  Virtual consoles are named ``/dev/tty#``, with numbering
starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console.
``/dev/tty0`` is the device that should be used to access the system video
card on those architectures for which the frame buffer devices
(``/dev/fb*``) are not applicable. Do not use ``/dev/console``
for this purpose.

The console device, ``/dev/console``, is the device to which system
messages should be sent, and on which logins should be permitted in
single-user mode.  Starting with Linux 2.1.71, ``/dev/console`` is managed
by the kernel; for previous versions it should be a symbolic link to
either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
a serial port primary (``tty*``, not ``cu*``) device, depending on the
configuration of the system.

Serial ports
++++++++++++

Serial ports are RS-232 serial ports and any device which simulates
one, either in hardware (such as internal modems) or in software (such
as the ISDN driver.)  Under Linux, each serial ports has two device
names, the primary or callin device and the alternate or callout one.
Each kind of device is indicated by a different letter.	 For any
letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
expected that multiple letters will be used; all letters will be upper
case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
"cu" device (e.g. ``/dev/cudp#``).

The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.

The alternate devices provide for kernel-based exclusion and somewhat
different defaults than the primary devices.  Their main purpose is to
allow the use of serial ports with programs with no inherent or broken
support for serial ports.  Their use is deprecated, and they may be
removed from a future version of Linux.

Arbitration of serial ports is provided by the use of lock files with
the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
be the PID of the locking process as an ASCII number.

It is common practice to install links such as /dev/modem
which point to serial ports.  In order to ensure proper locking in the
presence of these links, it is recommended that software chase
symlinks and lock all possible names; additionally, it is recommended
that a lock file be installed with the corresponding alternate
device.	 In order to avoid deadlocks, it is recommended that the locks
are acquired in the following order, and released in the reverse:

	1. The symbolic link name, if any (``/var/lock/LCK..modem``)
	2. The "tty" name (``/var/lock/LCK..ttyS2``)
	3. The alternate device name (``/var/lock/LCK..cua2``)

In the case of nested symbolic links, the lock files should be
installed in the order the symlinks are resolved.

Under no circumstances should an application hold a lock while waiting
for another to be released.  In addition, applications which attempt
to create lock files for the corresponding alternate device names
should take into account the possibility of being used on a non-serial
port TTY, for which no alternate device would exist.

Pseudoterminals (PTYs)
++++++++++++++++++++++

Pseudoterminals, or PTYs, are used to create login sessions or provide
other capabilities requiring a TTY line discipline (including SLIP or
PPP capability) to arbitrary data-generation processes.	 Each PTY has
a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named
``/dev/tty[p-za-e][0-9a-f]``.  The kernel arbitrates the use of PTYs by
allowing each master side to be opened only once.

Once the master side has been opened, the corresponding slave device
can be used in the same manner as any TTY device.  The master and
slave devices are connected by the kernel, generating the equivalent
of a bidirectional pipe with TTY capabilities.

Recent versions of the Linux kernels and GNU libc contain support for
the System V/Unix98 naming scheme for PTYs, which assigns a common
device, ``/dev/ptmx``, to all the masters (opening it will automatically
give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
in our notation).  This removes the problem of exhausting the
namespace and enables the kernel to automatically create the device
nodes for the slaves on demand using the "devpts" filesystem.

admin devices   Linux allocated devices  4 x  version                                          This list is the Linux Device List  the official registry of allocated device numbers and    dev   directory nodes for the Linux operating system   The version of this document at lanana org is no longer maintained   This version in the mainline Linux kernel is the master document   Updates shall be sent as patches to the kernel maintainers  see the  ref  Documentation process submitting patches rst  submittingpatches   document   Specifically explore the sections titled  CHAR and MISC DRIVERS   and  BLOCK LAYER  in the MAINTAINERS file to find the right maintainers to involve for character and block devices   This document is included by reference into the Filesystem Hierarchy Standard  FHS    The FHS is available from https   www pathname com fhs    Allocations marked  68k Amiga  apply to Linux 68k on the Amiga platform only  Allocations marked  68k Atari  apply to Linux 68k on the Atari platform only   This document is in the public domain  The authors requests  however  that semantically altered versions are not distributed without permission of the authors  assuming the authors can be contacted without an unreasonable effort       attention      DEVICE DRIVERS AUTHORS PLEASE READ THIS    Linux now has extensive support for dynamic allocation of device numbering   and can use   sysfs   and   udev      systemd    to handle the naming needs    There are still some exceptions in the serial and boot device area  Before   asking   for a device number make sure you actually need one     To have a major number allocated  or a minor number in situations   where that applies  e g  busmice   please submit a patch and send to   the authors as indicated above     Keep the description of the device  in the same format   as this list   The reason for this is that it is the only way we have   found to ensure we have all the requisite information to publish your   device and avoid conflicts     Finally  sometimes we have to play  namespace police    Please don t be   offended   We often get submissions for    dev   names that would be bound   to cause conflicts down the road   We are trying to avoid getting in a   situation where we would have to suffer an incompatible forward   change   Therefore  please consult with us   before   you make your   device names and numbers in any way public  at least to the point   where it would be at all difficult to get them changed     Your cooperation is appreciated      include   devices txt     literal   Additional    dev    directory entries                                         This section details additional entries that should or may exist in the  dev directory   It is preferred that symbolic links use the same form  absolute or relative  as is indicated here   Links are classified as  hard  or  symbolic  depending on the preferred type of link  if possible  the indicated type of link should be used   Compulsory links                   These links should exist on all systems                                                                                dev fd   proc self fd symbolic File descriptors  dev stdin fd 0  symbolic stdin file descriptor  dev stdout fd 1  symbolic stdout file descriptor  dev stderr fd 2  symbolic stderr file descriptor  dev nfsd socksys  symbolic Required by iBCS 2  dev X0R null  symbolic Required by iBCS 2                                                                                Note     dev X0R   is  letter X   digit 0   letter R    Recommended links                    It is recommended that these links exist on all systems                                                                                dev core  proc kcore symbolic Backward compatibility  dev ramdisk ram0  symbolic Backward compatibility  dev ftape qft0  symbolic Backward compatibility  dev bttv0 video0  symbolic Backward compatibility  dev radio radio0  symbolic Backward compatibility  dev i2o   dev i2o   symbolic Backward compatibility  dev scd  sr   hard  Alternate SCSI CD ROM name                                                                                Locally defined links                        The following links may be established locally to conform to the configuration of the system   This is merely a tabulation of existing practice  and does not constitute a recommendation   However  if they exist  they should have the following uses                                                                                dev mouse mouse port symbolic Current mouse device  dev tape tape device symbolic Current tape device  dev cdrom CD ROM device symbolic Current CD ROM device  dev cdwriter CD writer symbolic Current CD writer device  dev scanner scanner  symbolic Current scanner device  dev modem modem port symbolic Current dialout device  dev root root device symbolic Current root filesystem  dev swap swap device symbolic Current swap device                                                                                dev modem   should not be used for a modem which supports dialin as well as dialout  as it tends to cause lock file problems   If it exists     dev modem   should point to the appropriate primary TTY device  the use of the alternate callout devices is deprecated    For SCSI devices     dev tape   and    dev cdrom   should point to the  cooked  devices     dev st    and    dev sr     respectively   whereas    dev cdwriter   and  dev scanner should point to the appropriate generic SCSI devices   dev sg        dev mouse   may point to a primary serial TTY device  a hardware mouse device  or a socket for a mouse driver program  e g     dev gpmdata      Sockets and pipes                    Non transient sockets and named pipes may exist in  dev   Common entries are                                                                                dev printer socket  lpd local socket  dev log socket  syslog local socket  dev gpmdata socket  gpm mouse multiplexer                                                                                Mount points               The following names are reserved for mounting special filesystems under  dev   These special filesystems provide kernel interfaces that cannot be provided with standard device nodes                                                                                dev pts devpts  PTY slave filesystem  dev shm tmpfs  POSIX shared memory maintenance access                                                                                Terminal devices                   Terminal  or TTY devices are a special class of character devices   A terminal device is any device that could act as a controlling terminal for a session  this includes virtual consoles  serial ports  and pseudoterminals  PTYs    All terminal devices share a common set of capabilities known as line disciplines  these include the common terminal line discipline as well as SLIP and PPP modes   All terminal devices are named similarly  this section explains the naming and use of the various types of TTYs   Note that the naming conventions include several historical warts  some of these are Linux specific  some were inherited from other systems  and some reflect Linux outgrowing a borrowed convention   A hash mark         in a device name is used here to indicate a decimal number without leading zeroes   Virtual consoles and the console device                                          Virtual consoles are full screen terminal displays on the system video monitor   Virtual consoles are named    dev tty     with numbering starting at    dev tty1       dev tty0   is the current virtual console     dev tty0   is the device that should be used to access the system video card on those architectures for which the frame buffer devices     dev fb     are not applicable  Do not use    dev console   for this purpose   The console device     dev console    is the device to which system messages should be sent  and on which logins should be permitted in single user mode   Starting with Linux 2 1 71     dev console   is managed by the kernel  for previous versions it should be a symbolic link to either    dev tty0    a specific virtual console such as    dev tty1    or to a serial port primary    tty     not   cu     device  depending on the configuration of the system   Serial ports               Serial ports are RS 232 serial ports and any device which simulates one  either in hardware  such as internal modems  or in software  such as the ISDN driver    Under Linux  each serial ports has two device names  the primary or callin device and the alternate or callout one  Each kind of device is indicated by a different letter   For any letter X  the names of the devices are    dev ttyX    and    dev cux     respectively  for historical reasons     dev ttyS    and    dev ttyC    correspond to    dev cua    and    dev cub     In the future  it should be expected that multiple letters will be used  all letters will be upper case for the  tty  device  e g     dev ttyDP     and lower case for the  cu  device  e g     dev cudp       The names    dev ttyQ    and    dev cuq    are reserved for local use   The alternate devices provide for kernel based exclusion and somewhat different defaults than the primary devices   Their main purpose is to allow the use of serial ports with programs with no inherent or broken support for serial ports   Their use is deprecated  and they may be removed from a future version of Linux   Arbitration of serial ports is provided by the use of lock files with the names    var lock LCK  ttyX     The contents of the lock file should be the PID of the locking process as an ASCII number   It is common practice to install links such as  dev modem which point to serial ports   In order to ensure proper locking in the presence of these links  it is recommended that software chase symlinks and lock all possible names  additionally  it is recommended that a lock file be installed with the corresponding alternate device   In order to avoid deadlocks  it is recommended that the locks are acquired in the following order  and released in the reverse    1  The symbolic link name  if any     var lock LCK  modem     2  The  tty  name     var lock LCK  ttyS2     3  The alternate device name     var lock LCK  cua2     In the case of nested symbolic links  the lock files should be installed in the order the symlinks are resolved   Under no circumstances should an application hold a lock while waiting for another to be released   In addition  applications which attempt to create lock files for the corresponding alternate device names should take into account the possibility of being used on a non serial port TTY  for which no alternate device would exist   Pseudoterminals  PTYs                          Pseudoterminals  or PTYs  are used to create login sessions or provide other capabilities requiring a TTY line discipline  including SLIP or PPP capability  to arbitrary data generation processes   Each PTY has a master side  named    dev pty p za e  0 9a f     and a slave side  named    dev tty p za e  0 9a f      The kernel arbitrates the use of PTYs by allowing each master side to be opened only once   Once the master side has been opened  the corresponding slave device can be used in the same manner as any TTY device   The master and slave devices are connected by the kernel  generating the equivalent of a bidirectional pipe with TTY capabilities   Recent versions of the Linux kernels and GNU libc contain support for the System V Unix98 naming scheme for PTYs  which assigns a common device     dev ptmx    to all the masters  opening it will automatically give you a previously unassigned PTY  and a subdirectory     dev pts    for the slaves  the slaves are named with decimal integers     dev pts     in our notation    This removes the problem of exhausting the namespace and enables the kernel to automatically create the device nodes for the slaves on demand using the  devpts  filesystem


linux When Linux developers talk about a Real Time Clock they usually mean UTC formerly Greenwich Mean Time works even with system power off Such clocks will normally not track the local time zone or daylight savings time unless they dual boot Real Time Clock RTC Drivers for Linux with MS Windows but will instead be set to Coordinated Universal Time something that tracks wall clock time and is battery backed so that it

Answer:
=======================================
Real Time Clock (RTC) Drivers for Linux
=======================================

When Linux developers talk about a "Real Time Clock", they usually mean
something that tracks wall clock time and is battery backed so that it
works even with system power off.  Such clocks will normally not track
the local time zone or daylight savings time -- unless they dual boot
with MS-Windows -- but will instead be set to Coordinated Universal Time
(UTC, formerly "Greenwich Mean Time").

The newest non-PC hardware tends to just count seconds, like the time(2)
system call reports, but RTCs also very commonly represent time using
the Gregorian calendar and 24 hour time, as reported by gmtime(3).

Linux has two largely-compatible userspace RTC API families you may
need to know about:

    *	/dev/rtc ... is the RTC provided by PC compatible systems,
	so it's not very portable to non-x86 systems.

    *	/dev/rtc0, /dev/rtc1 ... are part of a framework that's
	supported by a wide variety of RTC chips on all systems.

Programmers need to understand that the PC/AT functionality is not
always available, and some systems can do much more.  That is, the
RTCs use the same API to make requests in both RTC frameworks (using
different filenames of course), but the hardware may not offer the
same functionality.  For example, not every RTC is hooked up to an
IRQ, so they can't all issue alarms; and where standard PC RTCs can
only issue an alarm up to 24 hours in the future, other hardware may
be able to schedule one any time in the upcoming century.

Old PC/AT-Compatible driver:  /dev/rtc
--------------------------------------

All PCs (even Alpha machines) have a Real Time Clock built into them.
Usually they are built into the chipset of the computer, but some may
actually have a Motorola MC146818 (or clone) on the board. This is the
clock that keeps the date and time while your computer is turned off.

ACPI has standardized that MC146818 functionality, and extended it in
a few ways (enabling longer alarm periods, and wake-from-hibernate).
That functionality is NOT exposed in the old driver.

However it can also be used to generate signals from a slow 2Hz to a
relatively fast 8192Hz, in increments of powers of two. These signals
are reported by interrupt number 8. (Oh! So *that* is what IRQ 8 is
for...) It can also function as a 24hr alarm, raising IRQ 8 when the
alarm goes off. The alarm can also be programmed to only check any
subset of the three programmable values, meaning that it could be set to
ring on the 30th second of the 30th minute of every hour, for example.
The clock can also be set to generate an interrupt upon every clock
update, thus generating a 1Hz signal.

The interrupts are reported via /dev/rtc (major 10, minor 135, read only
character device) in the form of an unsigned long. The low byte contains
the type of interrupt (update-done, alarm-rang, or periodic) that was
raised, and the remaining bytes contain the number of interrupts since
the last read.  Status information is reported through the pseudo-file
/proc/driver/rtc if the /proc filesystem was enabled.  The driver has
built in locking so that only one process is allowed to have the /dev/rtc
interface open at a time.

A user process can monitor these interrupts by doing a read(2) or a
select(2) on /dev/rtc -- either will block/stop the user process until
the next interrupt is received. This is useful for things like
reasonably high frequency data acquisition where one doesn't want to
burn up 100% CPU by polling gettimeofday etc. etc.

At high frequencies, or under high loads, the user process should check
the number of interrupts received since the last read to determine if
there has been any interrupt "pileup" so to speak. Just for reference, a
typical 486-33 running a tight read loop on /dev/rtc will start to suffer
occasional interrupt pileup (i.e. > 1 IRQ event since last read) for
frequencies above 1024Hz. So you really should check the high bytes
of the value you read, especially at frequencies above that of the
normal timer interrupt, which is 100Hz.

Programming and/or enabling interrupt frequencies greater than 64Hz is
only allowed by root. This is perhaps a bit conservative, but we don't want
an evil user generating lots of IRQs on a slow 386sx-16, where it might have
a negative impact on performance. This 64Hz limit can be changed by writing
a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
interrupt handler is only a few lines of code to minimize any possibility
of this effect.

Also, if the kernel time is synchronized with an external source, the
kernel will write the time back to the CMOS clock every 11 minutes. In
the process of doing this, the kernel briefly turns off RTC periodic
interrupts, so be aware of this if you are doing serious work. If you
don't synchronize the kernel time with an external source (via ntp or
whatever) then the kernel will keep its hands off the RTC, allowing you
exclusive access to the device for your applications.

The alarm and/or interrupt frequency are programmed into the RTC via
various ioctl(2) calls as listed in ./include/linux/rtc.h
Rather than write 50 pages describing the ioctl() and so on, it is
perhaps more useful to include a small test program that demonstrates
how to use them, and demonstrates the features of the driver. This is
probably a lot more useful to people interested in writing applications
that will be using this driver.  See the code at the end of this document.

(The original /dev/rtc driver was written by Paul Gortmaker.)

New portable "RTC Class" drivers:  /dev/rtcN
--------------------------------------------

Because Linux supports many non-ACPI and non-PC platforms, some of which
have more than one RTC style clock, it needed a more portable solution
than expecting a single battery-backed MC146818 clone on every system.
Accordingly, a new "RTC Class" framework has been defined.  It offers
three different userspace interfaces:

    *	/dev/rtcN ... much the same as the older /dev/rtc interface

    *	/sys/class/rtc/rtcN ... sysfs attributes support readonly
	access to some RTC attributes.

    *	/proc/driver/rtc ... the system clock RTC may expose itself
	using a procfs interface. If there is no RTC for the system clock,
	rtc0 is used by default. More information is (currently) shown
	here than through sysfs.

The RTC Class framework supports a wide variety of RTCs, ranging from those
integrated into embeddable system-on-chip (SOC) processors to discrete chips
using I2C, SPI, or some other bus to communicate with the host CPU.  There's
even support for PC-style RTCs ... including the features exposed on newer PCs
through ACPI.

The new framework also removes the "one RTC per system" restriction.  For
example, maybe the low-power battery-backed RTC is a discrete I2C chip, but
a high functionality RTC is integrated into the SOC.  That system might read
the system clock from the discrete RTC, but use the integrated one for all
other tasks, because of its greater functionality.

Check out tools/testing/selftests/rtc/rtctest.c for an example usage of the
ioctl interface.

Real Time Clock  RTC  Drivers for Linux                                          When Linux developers talk about a  Real Time Clock   they usually mean something that tracks wall clock time and is battery backed so that it works even with system power off   Such clocks will normally not track the local time zone or daylight savings time    unless they dual boot with MS Windows    but will instead be set to Coordinated Universal Time  UTC  formerly  Greenwich Mean Time     The newest non PC hardware tends to just count seconds  like the time 2  system call reports  but RTCs also very commonly represent time using the Gregorian calendar and 24 hour time  as reported by gmtime 3    Linux has two largely compatible userspace RTC API families you may need to know about          dev rtc     is the RTC provided by PC compatible systems   so it s not very portable to non x86 systems          dev rtc0   dev rtc1     are part of a framework that s  supported by a wide variety of RTC chips on all systems   Programmers need to understand that the PC AT functionality is not always available  and some systems can do much more   That is  the RTCs use the same API to make requests in both RTC frameworks  using different filenames of course   but the hardware may not offer the same functionality   For example  not every RTC is hooked up to an IRQ  so they can t all issue alarms  and where standard PC RTCs can only issue an alarm up to 24 hours in the future  other hardware may be able to schedule one any time in the upcoming century    Old PC AT Compatible driver    dev rtc                                         All PCs  even Alpha machines  have a Real Time Clock built into them  Usually they are built into the chipset of the computer  but some may actually have a Motorola MC146818  or clone  on the board  This is the clock that keeps the date and time while your computer is turned off   ACPI has standardized that MC146818 functionality  and extended it in a few ways  enabling longer alarm periods  and wake from hibernate   That functionality is NOT exposed in the old driver   However it can also be used to generate signals from a slow 2Hz to a relatively fast 8192Hz  in increments of powers of two  These signals are reported by interrupt number 8   Oh  So  that  is what IRQ 8 is for     It can also function as a 24hr alarm  raising IRQ 8 when the alarm goes off  The alarm can also be programmed to only check any subset of the three programmable values  meaning that it could be set to ring on the 30th second of the 30th minute of every hour  for example  The clock can also be set to generate an interrupt upon every clock update  thus generating a 1Hz signal   The interrupts are reported via  dev rtc  major 10  minor 135  read only character device  in the form of an unsigned long  The low byte contains the type of interrupt  update done  alarm rang  or periodic  that was raised  and the remaining bytes contain the number of interrupts since the last read   Status information is reported through the pseudo file  proc driver rtc if the  proc filesystem was enabled   The driver has built in locking so that only one process is allowed to have the  dev rtc interface open at a time   A user process can monitor these interrupts by doing a read 2  or a select 2  on  dev rtc    either will block stop the user process until the next interrupt is received  This is useful for things like reasonably high frequency data acquisition where one doesn t want to burn up 100  CPU by polling gettimeofday etc  etc   At high frequencies  or under high loads  the user process should check the number of interrupts received since the last read to determine if there has been any interrupt  pileup  so to speak  Just for reference  a typical 486 33 running a tight read loop on  dev rtc will start to suffer occasional interrupt pileup  i e    1 IRQ event since last read  for frequencies above 1024Hz  So you really should check the high bytes of the value you read  especially at frequencies above that of the normal timer interrupt  which is 100Hz   Programming and or enabling interrupt frequencies greater than 64Hz is only allowed by root  This is perhaps a bit conservative  but we don t want an evil user generating lots of IRQs on a slow 386sx 16  where it might have a negative impact on performance  This 64Hz limit can be changed by writing a different value to  proc sys dev rtc max user freq  Note that the interrupt handler is only a few lines of code to minimize any possibility of this effect   Also  if the kernel time is synchronized with an external source  the  kernel will write the time back to the CMOS clock every 11 minutes  In  the process of doing this  the kernel briefly turns off RTC periodic  interrupts  so be aware of this if you are doing serious work  If you don t synchronize the kernel time with an external source  via ntp or whatever  then the kernel will keep its hands off the RTC  allowing you exclusive access to the device for your applications   The alarm and or interrupt frequency are programmed into the RTC via various ioctl 2  calls as listed in   include linux rtc h Rather than write 50 pages describing the ioctl   and so on  it is perhaps more useful to include a small test program that demonstrates how to use them  and demonstrates the features of the driver  This is probably a lot more useful to people interested in writing applications that will be using this driver   See the code at the end of this document    The original  dev rtc driver was written by Paul Gortmaker     New portable  RTC Class  drivers    dev rtcN                                               Because Linux supports many non ACPI and non PC platforms  some of which have more than one RTC style clock  it needed a more portable solution than expecting a single battery backed MC146818 clone on every system  Accordingly  a new  RTC Class  framework has been defined   It offers three different userspace interfaces          dev rtcN     much the same as the older  dev rtc interface         sys class rtc rtcN     sysfs attributes support readonly  access to some RTC attributes          proc driver rtc     the system clock RTC may expose itself  using a procfs interface  If there is no RTC for the system clock   rtc0 is used by default  More information is  currently  shown  here than through sysfs   The RTC Class framework supports a wide variety of RTCs  ranging from those integrated into embeddable system on chip  SOC  processors to discrete chips using I2C  SPI  or some other bus to communicate with the host CPU   There s even support for PC style RTCs     including the features exposed on newer PCs through ACPI   The new framework also removes the  one RTC per system  restriction   For example  maybe the low power battery backed RTC is a discrete I2C chip  but a high functionality RTC is integrated into the SOC   That system might read the system clock from the discrete RTC  but use the integrated one for all other tasks  because of its greater functionality   Check out tools testing selftests rtc rtctest c for an example usage of the ioctl interface


linux Author Matt Porter RapidIO is a high speed switched fabric interconnect with features aimed Introduction RapidIO Subsystem Guide

Answer:
=======================
RapidIO Subsystem Guide
=======================

:Author: Matt Porter

Introduction
============

RapidIO is a high speed switched fabric interconnect with features aimed
at the embedded market. RapidIO provides support for memory-mapped I/O
as well as message-based transactions over the switched fabric network.
RapidIO has a standardized discovery mechanism not unlike the PCI bus
standard that allows simple detection of devices in a network.

This documentation is provided for developers intending to support
RapidIO on new architectures, write new drivers, or to understand the
subsystem internals.

Known Bugs and Limitations
==========================

Bugs
----

None. ;)

Limitations
-----------

1. Access/management of RapidIO memory regions is not supported

2. Multiple host enumeration is not supported

RapidIO driver interface
========================

Drivers are provided a set of calls in order to interface with the
subsystem to gather info on devices, request/map memory region
resources, and manage mailboxes/doorbells.

Functions
---------

.. kernel-doc:: include/linux/rio_drv.h
   :internal:

.. kernel-doc:: drivers/rapidio/rio-driver.c
   :export:

.. kernel-doc:: drivers/rapidio/rio.c
   :export:

Internals
=========

This chapter contains the autogenerated documentation of the RapidIO
subsystem.

Structures
----------

.. kernel-doc:: include/linux/rio.h
   :internal:

Enumeration and Discovery
-------------------------

.. kernel-doc:: drivers/rapidio/rio-scan.c
   :internal:

Driver functionality
--------------------

.. kernel-doc:: drivers/rapidio/rio.c
   :internal:

.. kernel-doc:: drivers/rapidio/rio-access.c
   :internal:

Device model support
--------------------

.. kernel-doc:: drivers/rapidio/rio-driver.c
   :internal:

PPC32 support
-------------

.. kernel-doc:: arch/powerpc/sysdev/fsl_rio.c
   :internal:

Credits
=======

The following people have contributed to the RapidIO subsystem directly
or indirectly:

1. Matt Porter\ mporter@kernel.crashing.org

2. Randy Vinson\ rvinson@mvista.com

3. Dan Malek\ dan@embeddedalley.com

The following people have contributed to this document:

1. Matt Porter\ mporter@kernel.crashing.org

RapidIO Subsystem Guide                           Author  Matt Porter  Introduction               RapidIO is a high speed switched fabric interconnect with features aimed at the embedded market  RapidIO provides support for memory mapped I O as well as message based transactions over the switched fabric network  RapidIO has a standardized discovery mechanism not unlike the PCI bus standard that allows simple detection of devices in a network   This documentation is provided for developers intending to support RapidIO on new architectures  write new drivers  or to understand the subsystem internals   Known Bugs and Limitations                             Bugs       None      Limitations              1  Access management of RapidIO memory regions is not supported  2  Multiple host enumeration is not supported  RapidIO driver interface                           Drivers are provided a set of calls in order to interface with the subsystem to gather info on devices  request map memory region resources  and manage mailboxes doorbells   Functions               kernel doc   include linux rio drv h     internal      kernel doc   drivers rapidio rio driver c     export      kernel doc   drivers rapidio rio c     export   Internals            This chapter contains the autogenerated documentation of the RapidIO subsystem   Structures                kernel doc   include linux rio h     internal   Enumeration and Discovery                               kernel doc   drivers rapidio rio scan c     internal   Driver functionality                          kernel doc   drivers rapidio rio c     internal      kernel doc   drivers rapidio rio access c     internal   Device model support                          kernel doc   drivers rapidio rio driver c     internal   PPC32 support                   kernel doc   arch powerpc sysdev fsl rio c     internal   Credits          The following people have contributed to the RapidIO subsystem directly or indirectly   1  Matt Porter  mporter kernel crashing org  2  Randy Vinson  rvinson mvista com  3  Dan Malek  dan embeddedalley com  The following people have contributed to this document   1  Matt Porter  mporter kernel crashing org


linux Usage of Performance Counters for Linux perfevents 1 2 3 Perf events and tool security can impose a considerable risk of leaking sensitive data accessed by Overview perfsecurity

Answer:
.. _perf_security:

Perf events and tool security
=============================

Overview
--------

Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_
can impose a considerable risk of leaking sensitive data accessed by
monitored processes. The data leakage is possible both in scenarios of
direct usage of perf_events system call API [2]_ and over data files
generated by Perf tool user mode utility (Perf) [3]_ , [4]_ . The risk
depends on the nature of data that perf_events performance monitoring
units (PMU) [2]_ and Perf collect and expose for performance analysis.
Collected system and performance data may be split into several
categories:

1. System hardware and software configuration data, for example: a CPU
   model and its cache configuration, an amount of available memory and
   its topology, used kernel and Perf versions, performance monitoring
   setup including experiment time, events configuration, Perf command
   line parameters, etc.

2. User and kernel module paths and their load addresses with sizes,
   process and thread names with their PIDs and TIDs, timestamps for
   captured hardware and software events.

3. Content of kernel software counters (e.g., for context switches, page
   faults, CPU migrations), architectural hardware performance counters
   (PMC) [8]_ and machine specific registers (MSR) [9]_ that provide
   execution metrics for various monitored parts of the system (e.g.,
   memory controller (IMC), interconnect (QPI/UPI) or peripheral (PCIe)
   uncore counters) without direct attribution to any execution context
   state.

4. Content of architectural execution context registers (e.g., RIP, RSP,
   RBP on x86_64), process user and kernel space memory addresses and
   data, content of various architectural MSRs that capture data from
   this category.

Data that belong to the fourth category can potentially contain
sensitive process data. If PMUs in some monitoring modes capture values
of execution context registers or data from process memory then access
to such monitoring modes requires to be ordered and secured properly.
So, perf_events performance monitoring and observability operations are
the subject for security access control management [5]_ .

perf_events access control
-------------------------------

To perform security checks, the Linux implementation splits processes
into two categories [6]_ : a) privileged processes (whose effective user
ID is 0, referred to as superuser or root), and b) unprivileged
processes (whose effective UID is nonzero). Privileged processes bypass
all kernel security permission checks so perf_events performance
monitoring is fully available to privileged processes without access,
scope and resource restrictions.

Unprivileged processes are subject to a full security permission check
based on the process's credentials [5]_ (usually: effective UID,
effective GID, and supplementary group list).

Linux divides the privileges traditionally associated with superuser
into distinct units, known as capabilities [6]_ , which can be
independently enabled and disabled on per-thread basis for processes and
files of unprivileged users.

Unprivileged processes with enabled CAP_PERFMON capability are treated
as privileged processes with respect to perf_events performance
monitoring and observability operations, thus, bypass *scope* permissions
checks in the kernel. CAP_PERFMON implements the principle of least
privilege [13]_ (POSIX 1003.1e: 2.2.2.39) for performance monitoring and
observability operations in the kernel and provides a secure approach to
performance monitoring and observability in the system.

For backward compatibility reasons the access to perf_events monitoring and
observability operations is also open for CAP_SYS_ADMIN privileged
processes but CAP_SYS_ADMIN usage for secure monitoring and observability
use cases is discouraged with respect to the CAP_PERFMON capability.
If system audit records [14]_ for a process using perf_events system call
API contain denial records of acquiring both CAP_PERFMON and CAP_SYS_ADMIN
capabilities then providing the process with CAP_PERFMON capability singly
is recommended as the preferred secure approach to resolve double access
denial logging related to usage of performance monitoring and observability.

Prior Linux v5.9 unprivileged processes using perf_events system call
are also subject for PTRACE_MODE_READ_REALCREDS ptrace access mode check
[7]_ , whose outcome determines whether monitoring is permitted.
So unprivileged processes provided with CAP_SYS_PTRACE capability are
effectively permitted to pass the check. Starting from Linux v5.9
CAP_SYS_PTRACE capability is not required and CAP_PERFMON is enough to
be provided for processes to make performance monitoring and observability
operations.

Other capabilities being granted to unprivileged processes can
effectively enable capturing of additional data required for later
performance analysis of monitored processes or a system. For example,
CAP_SYSLOG capability permits reading kernel space memory addresses from
/proc/kallsyms file.

Privileged Perf users groups
---------------------------------

Mechanisms of capabilities, privileged capability-dumb files [6]_,
file system ACLs [10]_ and sudo [15]_ utility can be used to create
dedicated groups of privileged Perf users who are permitted to execute
performance monitoring and observability without limits. The following
steps can be taken to create such groups of privileged Perf users.

1. Create perf_users group of privileged Perf users, assign perf_users
   group to Perf tool executable and limit access to the executable for
   other users in the system who are not in the perf_users group:

::

   # groupadd perf_users
   # ls -alhF
   -rwxr-xr-x  2 root root  11M Oct 19 15:12 perf
   # chgrp perf_users perf
   # ls -alhF
   -rwxr-xr-x  2 root perf_users  11M Oct 19 15:12 perf
   # chmod o-rwx perf
   # ls -alhF
   -rwxr-x---  2 root perf_users  11M Oct 19 15:12 perf

2. Assign the required capabilities to the Perf tool executable file and
   enable members of perf_users group with monitoring and observability
   privileges [6]_ :

::

   # setcap "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
   # setcap -v "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
   perf: OK
   # getcap perf
   perf = cap_sys_ptrace,cap_syslog,cap_perfmon+ep

If the libcap [16]_ installed doesn't yet support "cap_perfmon", use "38" instead,
i.e.:

::

   # setcap "38,cap_ipc_lock,cap_sys_ptrace,cap_syslog=ep" perf

Note that you may need to have 'cap_ipc_lock' in the mix for tools such as
'perf top', alternatively use 'perf top -m N', to reduce the memory that
it uses for the perf ring buffer, see the memory allocation section below.

Using a libcap without support for CAP_PERFMON will make cap_get_flag(caps, 38,
CAP_EFFECTIVE, &val) fail, which will lead the default event to be 'cycles:u',
so as a workaround explicitly ask for the 'cycles' event, i.e.:

::

  # perf top -e cycles

To get kernel and user samples with a perf binary with just CAP_PERFMON.

As a result, members of perf_users group are capable of conducting
performance monitoring and observability by using functionality of the
configured Perf tool executable that, when executes, passes perf_events
subsystem scope checks.

In case Perf tool executable can't be assigned required capabilities (e.g.
file system is mounted with nosuid option or extended attributes are
not supported by the file system) then creation of the capabilities
privileged environment, naturally shell, is possible. The shell provides
inherent processes with CAP_PERFMON and other required capabilities so that
performance monitoring and observability operations are available in the
environment without limits. Access to the environment can be open via sudo
utility for members of perf_users group only. In order to create such
environment:

1. Create shell script that uses capsh utility [16]_ to assign CAP_PERFMON
   and other required capabilities into ambient capability set of the shell
   process, lock the process security bits after enabling SECBIT_NO_SETUID_FIXUP,
   SECBIT_NOROOT and SECBIT_NO_CAP_AMBIENT_RAISE bits and then change
   the process identity to sudo caller of the script who should essentially
   be a member of perf_users group:

::

   # ls -alh /usr/local/bin/perf.shell
   -rwxr-xr-x. 1 root root 83 Oct 13 23:57 /usr/local/bin/perf.shell
   # cat /usr/local/bin/perf.shell
   exec /usr/sbin/capsh --iab=^cap_perfmon --secbits=239 --user=$SUDO_USER -- -l

2. Extend sudo policy at /etc/sudoers file with a rule for perf_users group:

::

   # grep perf_users /etc/sudoers
   %perf_users    ALL=/usr/local/bin/perf.shell

3. Check that members of perf_users group have access to the privileged
   shell and have CAP_PERFMON and other required capabilities enabled
   in permitted, effective and ambient capability sets of an inherent process:

::

  $ id
  uid=1003(capsh_test) gid=1004(capsh_test) groups=1004(capsh_test),1000(perf_users) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
  $ sudo perf.shell
  [sudo] password for capsh_test:
  $ grep Cap /proc/self/status
  CapInh:        0000004000000000
  CapPrm:        0000004000000000
  CapEff:        0000004000000000
  CapBnd:        000000ffffffffff
  CapAmb:        0000004000000000
  $ capsh --decode=0000004000000000
  0x0000004000000000=cap_perfmon

As a result, members of perf_users group have access to the privileged
environment where they can use tools employing performance monitoring APIs
governed by CAP_PERFMON Linux capability.

This specific access control management is only available to superuser
or root running processes with CAP_SETPCAP, CAP_SETFCAP [6]_
capabilities.

Unprivileged users
-----------------------------------

perf_events *scope* and *access* control for unprivileged processes
is governed by perf_event_paranoid [2]_ setting:

-1:
     Impose no *scope* and *access* restrictions on using perf_events
     performance monitoring. Per-user per-cpu perf_event_mlock_kb [2]_
     locking limit is ignored when allocating memory buffers for storing
     performance data. This is the least secure mode since allowed
     monitored *scope* is maximized and no perf_events specific limits
     are imposed on *resources* allocated for performance monitoring.

>=0:
     *scope* includes per-process and system wide performance monitoring
     but excludes raw tracepoints and ftrace function tracepoints
     monitoring. CPU and system events happened when executing either in
     user or in kernel space can be monitored and captured for later
     analysis. Per-user per-cpu perf_event_mlock_kb locking limit is
     imposed but ignored for unprivileged processes with CAP_IPC_LOCK
     [6]_ capability.

>=1:
     *scope* includes per-process performance monitoring only and
     excludes system wide performance monitoring. CPU and system events
     happened when executing either in user or in kernel space can be
     monitored and captured for later analysis. Per-user per-cpu
     perf_event_mlock_kb locking limit is imposed but ignored for
     unprivileged processes with CAP_IPC_LOCK capability.

>=2:
     *scope* includes per-process performance monitoring only. CPU and
     system events happened when executing in user space only can be
     monitored and captured for later analysis. Per-user per-cpu
     perf_event_mlock_kb locking limit is imposed but ignored for
     unprivileged processes with CAP_IPC_LOCK capability.

Resource control
---------------------------------

Open file descriptors
+++++++++++++++++++++

The perf_events system call API [2]_ allocates file descriptors for
every configured PMU event. Open file descriptors are a per-process
accountable resource governed by the RLIMIT_NOFILE [11]_ limit
(ulimit -n), which is usually derived from the login shell process. When
configuring Perf collection for a long list of events on a large server
system, this limit can be easily hit preventing required monitoring
configuration. RLIMIT_NOFILE limit can be increased on per-user basis
modifying content of the limits.conf file [12]_ . Ordinarily, a Perf
sampling session (perf record) requires an amount of open perf_event
file descriptors that is not less than the number of monitored events
multiplied by the number of monitored CPUs.

Memory allocation
+++++++++++++++++

The amount of memory available to user processes for capturing
performance monitoring data is governed by the perf_event_mlock_kb [2]_
setting. This perf_event specific resource setting defines overall
per-cpu limits of memory allowed for mapping by the user processes to
execute performance monitoring. The setting essentially extends the
RLIMIT_MEMLOCK [11]_ limit, but only for memory regions mapped
specifically for capturing monitored performance events and related data.

For example, if a machine has eight cores and perf_event_mlock_kb limit
is set to 516 KiB, then a user process is provided with 516 KiB * 8 =
4128 KiB of memory above the RLIMIT_MEMLOCK limit (ulimit -l) for
perf_event mmap buffers. In particular, this means that, if the user
wants to start two or more performance monitoring processes, the user is
required to manually distribute the available 4128 KiB between the
monitoring processes, for example, using the --mmap-pages Perf record
mode option. Otherwise, the first started performance monitoring process
allocates all available 4128 KiB and the other processes will fail to
proceed due to the lack of memory.

RLIMIT_MEMLOCK and perf_event_mlock_kb resource constraints are ignored
for processes with the CAP_IPC_LOCK capability. Thus, perf_events/Perf
privileged users can be provided with memory above the constraints for
perf_events/Perf performance monitoring purpose by providing the Perf
executable with CAP_IPC_LOCK capability.

Bibliography
------------

.. [1] `<https://lwn.net/Articles/337493/>`_
.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
.. [8] `<https://en.wikipedia.org/wiki/Hardware_performance_counter>`_
.. [9] `<https://en.wikipedia.org/wiki/Model-specific_register>`_
.. [10] `<http://man7.org/linux/man-pages/man5/acl.5.html>`_
.. [11] `<http://man7.org/linux/man-pages/man2/getrlimit.2.html>`_
.. [12] `<http://man7.org/linux/man-pages/man5/limits.conf.5.html>`_
.. [13] `<https://sites.google.com/site/fullycapable>`_
.. [14] `<http://man7.org/linux/man-pages/man8/auditd.8.html>`_
.. [15] `<https://man7.org/linux/man-pages/man8/sudo.8.html>`_
.. [16] `<https://git.kernel.org/pub/scm/libs/libcap/libcap.git/>`_

perf security   Perf events and tool security                                Overview           Usage of Performance Counters for Linux  perf events   1      2      3   can impose a considerable risk of leaking sensitive data accessed by monitored processes  The data leakage is possible both in scenarios of direct usage of perf events system call API  2   and over data files generated by Perf tool user mode utility  Perf   3      4     The risk depends on the nature of data that perf events performance monitoring units  PMU   2   and Perf collect and expose for performance analysis  Collected system and performance data may be split into several categories   1  System hardware and software configuration data  for example  a CPU    model and its cache configuration  an amount of available memory and    its topology  used kernel and Perf versions  performance monitoring    setup including experiment time  events configuration  Perf command    line parameters  etc   2  User and kernel module paths and their load addresses with sizes     process and thread names with their PIDs and TIDs  timestamps for    captured hardware and software events   3  Content of kernel software counters  e g   for context switches  page    faults  CPU migrations   architectural hardware performance counters     PMC   8   and machine specific registers  MSR   9   that provide    execution metrics for various monitored parts of the system  e g      memory controller  IMC   interconnect  QPI UPI  or peripheral  PCIe     uncore counters  without direct attribution to any execution context    state   4  Content of architectural execution context registers  e g   RIP  RSP     RBP on x86 64   process user and kernel space memory addresses and    data  content of various architectural MSRs that capture data from    this category   Data that belong to the fourth category can potentially contain sensitive process data  If PMUs in some monitoring modes capture values of execution context registers or data from process memory then access to such monitoring modes requires to be ordered and secured properly  So  perf events performance monitoring and observability operations are the subject for security access control management  5      perf events access control                                  To perform security checks  the Linux implementation splits processes into two categories  6     a  privileged processes  whose effective user ID is 0  referred to as superuser or root   and b  unprivileged processes  whose effective UID is nonzero   Privileged processes bypass all kernel security permission checks so perf events performance monitoring is fully available to privileged processes without access  scope and resource restrictions   Unprivileged processes are subject to a full security permission check based on the process s credentials  5    usually  effective UID  effective GID  and supplementary group list    Linux divides the privileges traditionally associated with superuser into distinct units  known as capabilities  6     which can be independently enabled and disabled on per thread basis for processes and files of unprivileged users   Unprivileged processes with enabled CAP PERFMON capability are treated as privileged processes with respect to perf events performance monitoring and observability operations  thus  bypass  scope  permissions checks in the kernel  CAP PERFMON implements the principle of least privilege  13    POSIX 1003 1e  2 2 2 39  for performance monitoring and observability operations in the kernel and provides a secure approach to performance monitoring and observability in the system   For backward compatibility reasons the access to perf events monitoring and observability operations is also open for CAP SYS ADMIN privileged processes but CAP SYS ADMIN usage for secure monitoring and observability use cases is discouraged with respect to the CAP PERFMON capability  If system audit records  14   for a process using perf events system call API contain denial records of acquiring both CAP PERFMON and CAP SYS ADMIN capabilities then providing the process with CAP PERFMON capability singly is recommended as the preferred secure approach to resolve double access denial logging related to usage of performance monitoring and observability   Prior Linux v5 9 unprivileged processes using perf events system call are also subject for PTRACE MODE READ REALCREDS ptrace access mode check  7     whose outcome determines whether monitoring is permitted  So unprivileged processes provided with CAP SYS PTRACE capability are effectively permitted to pass the check  Starting from Linux v5 9 CAP SYS PTRACE capability is not required and CAP PERFMON is enough to be provided for processes to make performance monitoring and observability operations   Other capabilities being granted to unprivileged processes can effectively enable capturing of additional data required for later performance analysis of monitored processes or a system  For example  CAP SYSLOG capability permits reading kernel space memory addresses from  proc kallsyms file   Privileged Perf users groups                                    Mechanisms of capabilities  privileged capability dumb files  6    file system ACLs  10   and sudo  15   utility can be used to create dedicated groups of privileged Perf users who are permitted to execute performance monitoring and observability without limits  The following steps can be taken to create such groups of privileged Perf users   1  Create perf users group of privileged Perf users  assign perf users    group to Perf tool executable and limit access to the executable for    other users in the system who are not in the perf users group            groupadd perf users      ls  alhF     rwxr xr x  2 root root  11M Oct 19 15 12 perf      chgrp perf users perf      ls  alhF     rwxr xr x  2 root perf users  11M Oct 19 15 12 perf      chmod o rwx perf      ls  alhF     rwxr x     2 root perf users  11M Oct 19 15 12 perf  2  Assign the required capabilities to the Perf tool executable file and    enable members of perf users group with monitoring and observability    privileges  6               setcap  cap perfmon cap sys ptrace cap syslog ep  perf      setcap  v  cap perfmon cap sys ptrace cap syslog ep  perf    perf  OK      getcap perf    perf   cap sys ptrace cap syslog cap perfmon ep  If the libcap  16   installed doesn t yet support  cap perfmon   use  38  instead  i e             setcap  38 cap ipc lock cap sys ptrace cap syslog ep  perf  Note that you may need to have  cap ipc lock  in the mix for tools such as  perf top   alternatively use  perf top  m N   to reduce the memory that it uses for the perf ring buffer  see the memory allocation section below   Using a libcap without support for CAP PERFMON will make cap get flag caps  38  CAP EFFECTIVE   val  fail  which will lead the default event to be  cycles u   so as a workaround explicitly ask for the  cycles  event  i e            perf top  e cycles  To get kernel and user samples with a perf binary with just CAP PERFMON   As a result  members of perf users group are capable of conducting performance monitoring and observability by using functionality of the configured Perf tool executable that  when executes  passes perf events subsystem scope checks   In case Perf tool executable can t be assigned required capabilities  e g  file system is mounted with nosuid option or extended attributes are not supported by the file system  then creation of the capabilities privileged environment  naturally shell  is possible  The shell provides inherent processes with CAP PERFMON and other required capabilities so that performance monitoring and observability operations are available in the environment without limits  Access to the environment can be open via sudo utility for members of perf users group only  In order to create such environment   1  Create shell script that uses capsh utility  16   to assign CAP PERFMON    and other required capabilities into ambient capability set of the shell    process  lock the process security bits after enabling SECBIT NO SETUID FIXUP     SECBIT NOROOT and SECBIT NO CAP AMBIENT RAISE bits and then change    the process identity to sudo caller of the script who should essentially    be a member of perf users group            ls  alh  usr local bin perf shell     rwxr xr x  1 root root 83 Oct 13 23 57  usr local bin perf shell      cat  usr local bin perf shell    exec  usr sbin capsh   iab  cap perfmon   secbits 239   user  SUDO USER     l  2  Extend sudo policy at  etc sudoers file with a rule for perf users group            grep perf users  etc sudoers     perf users    ALL  usr local bin perf shell  3  Check that members of perf users group have access to the privileged    shell and have CAP PERFMON and other required capabilities enabled    in permitted  effective and ambient capability sets of an inherent process           id   uid 1003 capsh test  gid 1004 capsh test  groups 1004 capsh test  1000 perf users  context unconfined u unconfined r unconfined t s0 s0 c0 c1023     sudo perf shell    sudo  password for capsh test      grep Cap  proc self status   CapInh         0000004000000000   CapPrm         0000004000000000   CapEff         0000004000000000   CapBnd         000000ffffffffff   CapAmb         0000004000000000     capsh   decode 0000004000000000   0x0000004000000000 cap perfmon  As a result  members of perf users group have access to the privileged environment where they can use tools employing performance monitoring APIs governed by CAP PERFMON Linux capability   This specific access control management is only available to superuser or root running processes with CAP SETPCAP  CAP SETFCAP  6   capabilities   Unprivileged users                                      perf events  scope  and  access  control for unprivileged processes is governed by perf event paranoid  2   setting    1       Impose no  scope  and  access  restrictions on using perf events      performance monitoring  Per user per cpu perf event mlock kb  2        locking limit is ignored when allocating memory buffers for storing      performance data  This is the least secure mode since allowed      monitored  scope  is maximized and no perf events specific limits      are imposed on  resources  allocated for performance monitoring     0        scope  includes per process and system wide performance monitoring      but excludes raw tracepoints and ftrace function tracepoints      monitoring  CPU and system events happened when executing either in      user or in kernel space can be monitored and captured for later      analysis  Per user per cpu perf event mlock kb locking limit is      imposed but ignored for unprivileged processes with CAP IPC LOCK       6   capability     1        scope  includes per process performance monitoring only and      excludes system wide performance monitoring  CPU and system events      happened when executing either in user or in kernel space can be      monitored and captured for later analysis  Per user per cpu      perf event mlock kb locking limit is imposed but ignored for      unprivileged processes with CAP IPC LOCK capability     2        scope  includes per process performance monitoring only  CPU and      system events happened when executing in user space only can be      monitored and captured for later analysis  Per user per cpu      perf event mlock kb locking limit is imposed but ignored for      unprivileged processes with CAP IPC LOCK capability   Resource control                                    Open file descriptors                        The perf events system call API  2   allocates file descriptors for every configured PMU event  Open file descriptors are a per process accountable resource governed by the RLIMIT NOFILE  11   limit  ulimit  n   which is usually derived from the login shell process  When configuring Perf collection for a long list of events on a large server system  this limit can be easily hit preventing required monitoring configuration  RLIMIT NOFILE limit can be increased on per user basis modifying content of the limits conf file  12     Ordinarily  a Perf sampling session  perf record  requires an amount of open perf event file descriptors that is not less than the number of monitored events multiplied by the number of monitored CPUs   Memory allocation                    The amount of memory available to user processes for capturing performance monitoring data is governed by the perf event mlock kb  2   setting  This perf event specific resource setting defines overall per cpu limits of memory allowed for mapping by the user processes to execute performance monitoring  The setting essentially extends the RLIMIT MEMLOCK  11   limit  but only for memory regions mapped specifically for capturing monitored performance events and related data   For example  if a machine has eight cores and perf event mlock kb limit is set to 516 KiB  then a user process is provided with 516 KiB   8   4128 KiB of memory above the RLIMIT MEMLOCK limit  ulimit  l  for perf event mmap buffers  In particular  this means that  if the user wants to start two or more performance monitoring processes  the user is required to manually distribute the available 4128 KiB between the monitoring processes  for example  using the   mmap pages Perf record mode option  Otherwise  the first started performance monitoring process allocates all available 4128 KiB and the other processes will fail to proceed due to the lack of memory   RLIMIT MEMLOCK and perf event mlock kb resource constraints are ignored for processes with the CAP IPC LOCK capability  Thus  perf events Perf privileged users can be provided with memory above the constraints for perf events Perf performance monitoring purpose by providing the Perf executable with CAP IPC LOCK capability   Bibliography                   1    https   lwn net Articles 337493         2    http   man7 org linux man pages man2 perf event open 2 html        3    http   web eece maine edu  vweaver projects perf events         4    https   perf wiki kernel org index php Main Page        5    https   www kernel org doc html latest security credentials html        6    http   man7 org linux man pages man7 capabilities 7 html        7    http   man7 org linux man pages man2 ptrace 2 html        8    https   en wikipedia org wiki Hardware performance counter        9    https   en wikipedia org wiki Model specific register        10    http   man7 org linux man pages man5 acl 5 html        11    http   man7 org linux man pages man2 getrlimit 2 html        12    http   man7 org linux man pages man5 limits conf 5 html        13    https   sites google com site fullycapable        14    http   man7 org linux man pages man8 auditd 8 html        15    https   man7 org linux man pages man8 sudo 8 html        16    https   git kernel org pub scm libs libcap libcap git


linux a Random Number Generator RNG The software has two parts special hardware feature on your CPU or motherboard Hardware random number generators The hwrandom framework is software that makes use of a Introduction

Answer:
=================================
Hardware random number generators
=================================

Introduction
============

The hw_random framework is software that makes use of a
special hardware feature on your CPU or motherboard,
a Random Number Generator (RNG).  The software has two parts:
a core providing the /dev/hwrng character device and its
sysfs support, plus a hardware-specific driver that plugs
into that core.

To make the most effective use of these mechanisms, you
should download the support software as well.  Download the
latest version of the "rng-tools" package from:

	https://github.com/nhorman/rng-tools

Those tools use /dev/hwrng to fill the kernel entropy pool,
which is used internally and exported by the /dev/urandom and
/dev/random special files.

Theory of operation
===================

CHARACTER DEVICE.  Using the standard open()
and read() system calls, you can read random data from
the hardware RNG device.  This data is NOT CHECKED by any
fitness tests, and could potentially be bogus (if the
hardware is faulty or has been tampered with).  Data is only
output if the hardware "has-data" flag is set, but nevertheless
a security-conscious person would run fitness tests on the
data before assuming it is truly random.

The rng-tools package uses such tests in "rngd", and lets you
run them by hand with a "rngtest" utility.

/dev/hwrng is char device major 10, minor 183.

CLASS DEVICE.  There is a /sys/class/misc/hw_random node with
two unique attributes, "rng_available" and "rng_current".  The
"rng_available" attribute lists the hardware-specific drivers
available, while "rng_current" lists the one which is currently
connected to /dev/hwrng.  If your system has more than one
RNG available, you may change the one used by writing a name from
the list in "rng_available" into "rng_current".

==========================================================================

Hardware driver for Intel/AMD/VIA Random Number Generators (RNG)
	- Copyright 2000,2001 Jeff Garzik <jgarzik@pobox.com>
	- Copyright 2000,2001 Philipp Rumpf <prumpf@mandrakesoft.com>

About the Intel RNG hardware, from the firmware hub datasheet
=============================================================

The Firmware Hub integrates a Random Number Generator (RNG)
using thermal noise generated from inherently random quantum
mechanical properties of silicon. When not generating new random
bits the RNG circuitry will enter a low power state. Intel will
provide a binary software driver to give third party software
access to our RNG for use as a security feature. At this time,
the RNG is only to be used with a system in an OS-present state.

Intel RNG Driver notes
======================

FIXME: support poll(2)

.. note::

	request_mem_region was removed, for three reasons:

	1) Only one RNG is supported by this driver;
	2) The location used by the RNG is a fixed location in
	   MMIO-addressable memory;
	3) users with properly working BIOS e820 handling will always
	   have the region in which the RNG is located reserved, so
	   request_mem_region calls always fail for proper setups.
	   However, for people who use mem=XX, BIOS e820 information is
	   **not** in /proc/iomem, and request_mem_region(RNG_ADDR) can
	   succeed.

Driver details
==============

Based on:
	Intel 82802AB/82802AC Firmware Hub (FWH) Datasheet
	May 1999 Order Number: 290658-002 R

Intel 82802 Firmware Hub:
	Random Number Generator
	Programmer's Reference Manual
	December 1999 Order Number: 298029-001 R

Intel 82802 Firmware HUB Random Number Generator Driver
	Copyright (c) 2000 Matt Sottek <msottek@quiknet.com>

Special thanks to Matt Sottek.  I did the "guts", he
did the "brains" and all the testing.

Hardware random number generators                                    Introduction               The hw random framework is software that makes use of a special hardware feature on your CPU or motherboard  a Random Number Generator  RNG    The software has two parts  a core providing the  dev hwrng character device and its sysfs support  plus a hardware specific driver that plugs into that core   To make the most effective use of these mechanisms  you should download the support software as well   Download the latest version of the  rng tools  package from    https   github com nhorman rng tools  Those tools use  dev hwrng to fill the kernel entropy pool  which is used internally and exported by the  dev urandom and  dev random special files   Theory of operation                      CHARACTER DEVICE   Using the standard open   and read   system calls  you can read random data from the hardware RNG device   This data is NOT CHECKED by any fitness tests  and could potentially be bogus  if the hardware is faulty or has been tampered with    Data is only output if the hardware  has data  flag is set  but nevertheless a security conscious person would run fitness tests on the data before assuming it is truly random   The rng tools package uses such tests in  rngd   and lets you run them by hand with a  rngtest  utility    dev hwrng is char device major 10  minor 183   CLASS DEVICE   There is a  sys class misc hw random node with two unique attributes   rng available  and  rng current    The  rng available  attribute lists the hardware specific drivers available  while  rng current  lists the one which is currently connected to  dev hwrng   If your system has more than one RNG available  you may change the one used by writing a name from the list in  rng available  into  rng current                                                                                Hardware driver for Intel AMD VIA Random Number Generators  RNG     Copyright 2000 2001 Jeff Garzik  jgarzik pobox com     Copyright 2000 2001 Philipp Rumpf  prumpf mandrakesoft com    About the Intel RNG hardware  from the firmware hub datasheet                                                                The Firmware Hub integrates a Random Number Generator  RNG  using thermal noise generated from inherently random quantum mechanical properties of silicon  When not generating new random bits the RNG circuitry will enter a low power state  Intel will provide a binary software driver to give third party software access to our RNG for use as a security feature  At this time  the RNG is only to be used with a system in an OS present state   Intel RNG Driver notes                         FIXME  support poll 2      note     request mem region was removed  for three reasons    1  Only one RNG is supported by this driver   2  The location used by the RNG is a fixed location in     MMIO addressable memory   3  users with properly working BIOS e820 handling will always     have the region in which the RNG is located reserved  so     request mem region calls always fail for proper setups      However  for people who use mem XX  BIOS e820 information is       not   in  proc iomem  and request mem region RNG ADDR  can     succeed   Driver details                 Based on   Intel 82802AB 82802AC Firmware Hub  FWH  Datasheet  May 1999 Order Number  290658 002 R  Intel 82802 Firmware Hub   Random Number Generator  Programmer s Reference Manual  December 1999 Order Number  298029 001 R  Intel 82802 Firmware HUB Random Number Generator Driver  Copyright  c  2000 Matt Sottek  msottek quiknet com   Special thanks to Matt Sottek   I did the  guts   he did the  brains  and all the testing