lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/misc-devices/ad525x_dpot.rst
+57
View File
@@ -0,0 +1,57 @@
.. SPDX-License-Identifier: GPL-2.0
=============================
AD525x Digital Potentiometers
=============================
The ad525x_dpot driver exports a simple sysfs interface. This allows you to
work with the immediate resistance settings as well as update the saved startup
settings. Access to the factory programmed tolerance is also provided, but
interpretation of this settings is required by the end application according to
the specific part in use.
Files
=====
Each dpot device will have a set of eeprom, rdac, and tolerance files. How
many depends on the actual part you have, as will the range of allowed values.
The eeprom files are used to program the startup value of the device.
The rdac files are used to program the immediate value of the device.
The tolerance files are the read-only factory programmed tolerance settings
and may vary greatly on a part-by-part basis. For exact interpretation of
this field, please consult the datasheet for your part. This is presented
as a hex file for easier parsing.
Example
=======
Locate the device in your sysfs tree. This is probably easiest by going into
the common i2c directory and locating the device by the i2c slave address::
# ls /sys/bus/i2c/devices/
0-0022 0-0027 0-002f
So assuming the device in question is on the first i2c bus and has the slave
address of 0x2f, we descend (unrelated sysfs entries have been trimmed)::
# ls /sys/bus/i2c/devices/0-002f/
eeprom0 rdac0 tolerance0
You can use simple reads/writes to access these files::
# cd /sys/bus/i2c/devices/0-002f/
# cat eeprom0
0
# echo 10 > eeprom0
# cat eeprom0
10
# cat rdac0
5
# echo 3 > rdac0
# cat rdac0
3
linux-7.2.3/Documentation/misc-devices/amd-sbi.rst
+101
View File
@@ -0,0 +1,101 @@
.. SPDX-License-Identifier: GPL-2.0
=======================
AMD SIDE BAND interface
=======================
Some AMD Zen based processors supports system management
functionality via side-band interface (SBI) called
Advanced Platform Management Link (APML). APML is an I2C/I3C
based 2-wire processor target interface. APML is used to
communicate with the Remote Management Interface
(SB Remote Management Interface (SB-RMI)
and SB Temperature Sensor Interface (SB-TSI)).
More details on the interface can be found in chapter
"5 Advanced Platform Management Link (APML)" of the family/model PPR [1]_.
.. [1] https://docs.amd.com/v/u/en-US/55898_B1_pub_0_50
SBRMI device
============
apml_sbrmi driver under the drivers/misc/amd-sbi creates miscdevice
/dev/sbrmi-* to let user space programs run APML mailbox, CPUID,
MCAMSR and register xfer commands.
Register sets is common across APML protocols. IOCTL is providing synchronization
among protocols as transactions may create race condition.
.. code-block:: bash
$ ls -al /dev/sbrmi-3c
crw------- 1 root root 10, 53 Jul 10 11:13 /dev/sbrmi-3c
apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max,
current power consumption and managing power_cap.
Characteristics of the dev node:
* Differnet xfer protocols are defined:
* Mailbox
* CPUID
* MCA_MSR
* Register xfer
Access restrictions:
* Only root user is allowed to open the file.
* APML Mailbox messages and Register xfer access are read-write,
* CPUID and MCA_MSR access is read-only.
Driver IOCTLs
=============
.. c:macro:: SBRMI_IOCTL_MBOX_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
:doc: SBRMI_IOCTL_MBOX_CMD
.. c:macro:: SBRMI_IOCTL_CPUID_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
:doc: SBRMI_IOCTL_CPUID_CMD
.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
:doc: SBRMI_IOCTL_MCAMSR_CMD
.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
:doc: SBRMI_IOCTL_REG_XFER_CMD
User-space usage
================
To access side band interface from a C program.
First, user need to include the headers::
#include <uapi/misc/amd-apml.h>
Which defines the supported IOCTL and data structure to be passed
from the user space.
Next thing, open the device file, as follows::
int file;
file = open("/dev/sbrmi-*", O_RDWR);
if (file < 0) {
/* ERROR HANDLING */
exit(1);
}
The following IOCTLs are defined:
``#define SB_BASE_IOCTL_NR 0xF9``
``#define SBRMI_IOCTL_MBOX_CMD _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)``
``#define SBRMI_IOCTL_CPUID_CMD _IOWR(SB_BASE_IOCTL_NR, 1, struct apml_cpuid_msg)``
``#define SBRMI_IOCTL_MCAMSR_CMD _IOWR(SB_BASE_IOCTL_NR, 2, struct apml_mcamsr_msg)``
``#define SBRMI_IOCTL_REG_XFER_CMD _IOWR(SB_BASE_IOCTL_NR, 3, struct apml_reg_xfer_msg)``
User space C-APIs are made available by esmi_oob_library, hosted at
[2]_ which is provided by the E-SMS project [3]_.
.. [2] https://github.com/amd/esmi_oob_library
.. [3] https://www.amd.com/en/developer/e-sms.html
linux-7.2.3/Documentation/misc-devices/bh1770glc.rst
+135
View File
@@ -0,0 +1,135 @@
.. SPDX-License-Identifier: GPL-2.0
=======================
Kernel driver bh1770glc
=======================
Supported chips:
- ROHM BH1770GLC
- OSRAM SFH7770
Data sheet:
Not freely available
Author:
Samu Onkalo <samu.p.onkalo@nokia.com>
Description
-----------
BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
ALS and proximity parts operates on their own, but they shares common I2C
interface and interrupt logic. In principle they can run on their own,
but ALS side results are used to estimate reliability of the proximity sensor.
ALS produces 16 bit lux values. The chip contains interrupt logic to produce
low and high threshold interrupts.
Proximity part contains IR-led driver up to 3 IR leds. The chip measures
amount of reflected IR light and produces proximity result. Resolution is
8 bit. Driver supports only one channel. Driver uses ALS results to estimate
reliability of the proximity results. Thus ALS is always running while
proximity detection is needed.
Driver uses threshold interrupts to avoid need for polling the values.
Proximity low interrupt doesn't exists in the chip. This is simulated
by using a delayed work. As long as there is proximity threshold above
interrupts the delayed work is pushed forward. So, when proximity level goes
below the threshold value, there is no interrupt and the delayed work will
finally run. This is handled as no proximity indication.
Chip state is controlled via runtime pm framework when enabled in config.
Calibscale factor is used to hide differences between the chips. By default
value set to neutral state meaning factor of 1.00. To get proper values,
calibrated source of light is needed as a reference. Calibscale factor is set
so that measurement produces about the expected lux value.
SYSFS
-----
chip_id
RO - shows detected chip type and version
power_state
RW - enable / disable chip
Uses counting logic
- 1 enables the chip
- 0 disables the chip
lux0_input
RO - measured lux value
sysfs_notify called when threshold interrupt occurs
lux0_sensor_range
RO - lux0_input max value
lux0_rate
RW - measurement rate in Hz
lux0_rate_avail
RO - supported measurement rates
lux0_thresh_above_value
RW - HI level threshold value
All results above the value
trigs an interrupt. 65535 (i.e. sensor_range) disables the above
interrupt.
lux0_thresh_below_value
RW - LO level threshold value
All results below the value
trigs an interrupt. 0 disables the below interrupt.
lux0_calibscale
RW - calibration value
Set to neutral value by default.
Output results are multiplied with calibscale / calibscale_default
value.
lux0_calibscale_default
RO - neutral calibration value
prox0_raw
RO - measured proximity value
sysfs_notify called when threshold interrupt occurs
prox0_sensor_range
RO - prox0_raw max value
prox0_raw_en
RW - enable / disable proximity
Uses counting logic
- 1 enables the proximity
- 0 disables the proximity
prox0_thresh_above_count
RW - number of proximity interrupts needed before triggering the event
prox0_rate_above
RW - Measurement rate (in Hz) when the level is above threshold
i.e. when proximity on has been reported.
prox0_rate_below
RW - Measurement rate (in Hz) when the level is below threshold
i.e. when proximity off has been reported.
prox0_rate_avail
RO - Supported proximity measurement rates in Hz
prox0_thresh_above0_value
RW - threshold level which trigs proximity events.
Filtered by persistence filter (prox0_thresh_above_count)
prox0_thresh_above1_value
RW - threshold level which trigs event immediately
linux-7.2.3/Documentation/misc-devices/c2port.rst
+94
View File
@@ -0,0 +1,94 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
===============
C2 port support
===============
(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
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.
Overview
--------
This driver implements the support for Linux of Silicon Labs (Silabs)
C2 Interface used for in-system programming of micro controllers.
By using this driver you can reprogram the in-system flash without EC2
or EC3 debug adapter. This solution is also useful in those systems
where the micro controller is connected via special GPIOs pins.
References
----------
The C2 Interface main references are at (https://www.silabs.com)
Silicon Laboratories site], see:
- AN127: FLASH Programming via the C2 Interface at
https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf
- C2 Specification at
https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults
however it implements a two wire serial communication protocol (bit
banging) designed to enable in-system programming, debugging, and
boundary-scan testing on low pin-count Silicon Labs devices. Currently
this code supports only flash programming but extensions are easy to
add.
Using the driver
----------------
Once the driver is loaded you can use sysfs support to get C2port's
info or read/write in-system flash::
# ls /sys/class/c2port/c2port0/
access flash_block_size flash_erase rev_id
dev_id flash_blocks_num flash_size subsystem/
flash_access flash_data reset uevent
Initially the C2port access is disabled since you hardware may have
such lines multiplexed with other devices so, to get access to the
C2port, you need the command::
# echo 1 > /sys/class/c2port/c2port0/access
after that you should read the device ID and revision ID of the
connected micro controller::
# cat /sys/class/c2port/c2port0/dev_id
8
# cat /sys/class/c2port/c2port0/rev_id
1
However, for security reasons, the in-system flash access in not
enabled yet, to do so you need the command::
# echo 1 > /sys/class/c2port/c2port0/flash_access
After that you can read the whole flash::
# cat /sys/class/c2port/c2port0/flash_data > image
erase it::
# echo 1 > /sys/class/c2port/c2port0/flash_erase
and write it::
# cat image > /sys/class/c2port/c2port0/flash_data
after writing you have to reset the device to execute the new code::
# echo 1 > /sys/class/c2port/c2port0/reset
linux-7.2.3/Documentation/misc-devices/dw-xdata-pcie.rst
+64
View File
@@ -0,0 +1,64 @@
.. SPDX-License-Identifier: GPL-2.0
===========================================================================
Driver for Synopsys DesignWare PCIe traffic generator (also known as xData)
===========================================================================
Supported chips:
Synopsys DesignWare PCIe prototype solution
Datasheet:
Not freely available
Author:
Gustavo Pimentel <gustavo.pimentel@synopsys.com>
Description
-----------
This driver should be used as a host-side (Root Complex) driver and Synopsys
DesignWare prototype that includes this IP.
The dw-xdata-pcie driver can be used to enable/disable PCIe traffic
generator in either direction (mutual exclusion) besides allowing the
PCIe link performance analysis.
The interaction with this driver is done through the module parameter and
can be changed in runtime. The driver outputs the requested command state
information to ``/var/log/kern.log`` or dmesg.
Example
-------
Write TLPs traffic generation - Root Complex to Endpoint direction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generate traffic::
# echo 1 > /sys/class/misc/dw-xdata-pcie.0/write
Get link throughput in MB/s::
# cat /sys/class/misc/dw-xdata-pcie.0/write
204
Stop traffic in any direction::
# echo 0 > /sys/class/misc/dw-xdata-pcie.0/write
Read TLPs traffic generation - Endpoint to Root Complex direction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generate traffic::
# echo 1 > /sys/class/misc/dw-xdata-pcie.0/read
Get link throughput in MB/s::
# cat /sys/class/misc/dw-xdata-pcie.0/read
199
Stop traffic in any direction::
# echo 0 > /sys/class/misc/dw-xdata-pcie.0/read
linux-7.2.3/Documentation/misc-devices/ibmvmc.rst
+227
View File
@@ -0,0 +1,227 @@
.. SPDX-License-Identifier: GPL-2.0+
======================================================
IBM Virtual Management Channel Kernel Driver (IBMVMC)
======================================================
:Authors:
Dave Engebretsen <engebret@us.ibm.com>,
Adam Reznechek <adreznec@linux.vnet.ibm.com>,
Steven Royer <seroyer@linux.vnet.ibm.com>,
Bryant G. Ly <bryantly@linux.vnet.ibm.com>,
Introduction
============
Note: Knowledge of virtualization technology is required to understand
this document.
A good reference document would be:
https://openpowerfoundation.org/wp-content/uploads/2016/05/LoPAPR_DRAFT_v11_24March2016_cmt1.pdf
The Virtual Management Channel (VMC) is a logical device which provides an
interface between the hypervisor and a management partition. This interface
is like a message passing interface. This management partition is intended
to provide an alternative to systems that use a Hardware Management
Console (HMC) - based system management.
The primary hardware management solution that is developed by IBM relies
on an appliance server named the Hardware Management Console (HMC),
packaged as an external tower or rack-mounted personal computer. In a
Power Systems environment, a single HMC can manage multiple POWER
processor-based systems.
Management Application
----------------------
In the management partition, a management application exists which enables
a system administrator to configure the system’s partitioning
characteristics via a command line interface (CLI) or Representational
State Transfer Application (REST API's).
The management application runs on a Linux logical partition on a
POWER8 or newer processor-based server that is virtualized by PowerVM.
System configuration, maintenance, and control functions which
traditionally require an HMC can be implemented in the management
application using a combination of HMC to hypervisor interfaces and
existing operating system methods. This tool provides a subset of the
functions implemented by the HMC and enables basic partition configuration.
The set of HMC to hypervisor messages supported by the management
application component are passed to the hypervisor over a VMC interface,
which is defined below.
The VMC enables the management partition to provide basic partitioning
functions:
- Logical Partitioning Configuration
- Start, and stop actions for individual partitions
- Display of partition status
- Management of virtual Ethernet
- Management of virtual Storage
- Basic system management
Virtual Management Channel (VMC)
--------------------------------
A logical device, called the Virtual Management Channel (VMC), is defined
for communicating between the management application and the hypervisor. It
basically creates the pipes that enable virtualization management
software. This device is presented to a designated management partition as
a virtual device.
This communication device uses Command/Response Queue (CRQ) and the
Remote Direct Memory Access (RDMA) interfaces. A three-way handshake is
defined that must take place to establish that both the hypervisor and
management partition sides of the channel are running prior to
sending/receiving any of the protocol messages.
This driver also utilizes Transport Event CRQs. CRQ messages are sent
when the hypervisor detects one of the peer partitions has abnormally
terminated, or one side has called H_FREE_CRQ to close their CRQ.
Two new classes of CRQ messages are introduced for the VMC device. VMC
Administrative messages are used for each partition using the VMC to
communicate capabilities to their partner. HMC Interface messages are used
for the actual flow of HMC messages between the management partition and
the hypervisor. As most HMC messages far exceed the size of a CRQ buffer,
a virtual DMA (RMDA) of the HMC message data is done prior to each HMC
Interface CRQ message. Only the management partition drives RDMA
operations; hypervisors never directly cause the movement of message data.
Terminology
-----------
RDMA
Remote Direct Memory Access is DMA transfer from the server to its
client or from the server to its partner partition. DMA refers
to both physical I/O to and from memory operations and to memory
to memory move operations.
CRQ
Command/Response Queue a facility which is used to communicate
between partner partitions. Transport events which are signaled
from the hypervisor to partition are also reported in this queue.
Example Management Partition VMC Driver Interface
=================================================
This section provides an example for the management application
implementation where a device driver is used to interface to the VMC
device. This driver consists of a new device, for example /dev/ibmvmc,
which provides interfaces to open, close, read, write, and perform
ioctl’s against the VMC device.
VMC Interface Initialization
----------------------------
The device driver is responsible for initializing the VMC when the driver
is loaded. It first creates and initializes the CRQ. Next, an exchange of
VMC capabilities is performed to indicate the code version and number of
resources available in both the management partition and the hypervisor.
Finally, the hypervisor requests that the management partition create an
initial pool of VMC buffers, one buffer for each possible HMC connection,
which will be used for management application session initialization.
Prior to completion of this initialization sequence, the device returns
EBUSY to open() calls. EIO is returned for all open() failures.
::
Management Partition Hypervisor
CRQ INIT
---------------------------------------->
CRQ INIT COMPLETE
<----------------------------------------
CAPABILITIES
---------------------------------------->
CAPABILITIES RESPONSE
<----------------------------------------
ADD BUFFER (HMC IDX=0,1,..) _
<---------------------------------------- |
ADD BUFFER RESPONSE | - Perform # HMCs Iterations
----------------------------------------> -
VMC Interface Open
------------------
After the basic VMC channel has been initialized, an HMC session level
connection can be established. The application layer performs an open() to
the VMC device and executes an ioctl() against it, indicating the HMC ID
(32 bytes of data) for this session. If the VMC device is in an invalid
state, EIO will be returned for the ioctl(). The device driver creates a
new HMC session value (ranging from 1 to 255) and HMC index value (starting
at index 0 and ranging to 254) for this HMC ID. The driver then does an
RDMA of the HMC ID to the hypervisor, and then sends an Interface Open
message to the hypervisor to establish the session over the VMC. After the
hypervisor receives this information, it sends Add Buffer messages to the
management partition to seed an initial pool of buffers for the new HMC
connection. Finally, the hypervisor sends an Interface Open Response
message, to indicate that it is ready for normal runtime messaging. The
following illustrates this VMC flow:
::
Management Partition Hypervisor
RDMA HMC ID
---------------------------------------->
Interface Open
---------------------------------------->
Add Buffer _
<---------------------------------------- |
Add Buffer Response | - Perform N Iterations
----------------------------------------> -
Interface Open Response
<----------------------------------------
VMC Interface Runtime
---------------------
During normal runtime, the management application and the hypervisor
exchange HMC messages via the Signal VMC message and RDMA operations. When
sending data to the hypervisor, the management application performs a
write() to the VMC device, and the driver RDMA’s the data to the hypervisor
and then sends a Signal Message. If a write() is attempted before VMC
device buffers have been made available by the hypervisor, or no buffers
are currently available, EBUSY is returned in response to the write(). A
write() will return EIO for all other errors, such as an invalid device
state. When the hypervisor sends a message to the management, the data is
put into a VMC buffer and an Signal Message is sent to the VMC driver in
the management partition. The driver RDMA’s the buffer into the partition
and passes the data up to the appropriate management application via a
read() to the VMC device. The read() request blocks if there is no buffer
available to read. The management application may use select() to wait for
the VMC device to become ready with data to read.
::
Management Partition Hypervisor
MSG RDMA
---------------------------------------->
SIGNAL MSG
---------------------------------------->
SIGNAL MSG
<----------------------------------------
MSG RDMA
<----------------------------------------
VMC Interface Close
-------------------
HMC session level connections are closed by the management partition when
the application layer performs a close() against the device. This action
results in an Interface Close message flowing to the hypervisor, which
causes the session to be terminated. The device driver must free any
storage allocated for buffers for this HMC connection.
::
Management Partition Hypervisor
INTERFACE CLOSE
---------------------------------------->
INTERFACE CLOSE RESPONSE
<----------------------------------------
Additional Information
======================
For more information on the documentation for CRQ Messages, VMC Messages,
HMC interface Buffers, and signal messages please refer to the Linux on
Power Architecture Platform Reference. Section F.
linux-7.2.3/Documentation/misc-devices/ics932s401.rst
+36
View File
@@ -0,0 +1,36 @@
========================
Kernel driver ics932s401
========================
Supported chips:
* IDT ICS932S401
Prefix: 'ics932s401'
Addresses scanned: I2C 0x69
Datasheet: Publicly available at the IDT website
Author: Darrick J. Wong
Description
-----------
This driver implements support for the IDT ICS932S401 chip family.
This chip has 4 clock outputs--a base clock for the CPU (which is likely
multiplied to get the real CPU clock), a system clock, a PCI clock, a USB
clock, and a reference clock. The driver reports selected and actual
frequency. If spread spectrum mode is enabled, the driver also reports by what
percent the clock signal is being spread, which should be between 0 and -0.5%.
All frequencies are reported in KHz.
The ICS932S401 monitors all inputs continuously. The driver will not read
the registers more often than once every other second.
Special Features
----------------
The clocks could be reprogrammed to increase system speed. I will not help you
do this, as you risk damaging your system!
linux-7.2.3/Documentation/misc-devices/index.rst
+30
View File
@@ -0,0 +1,30 @@
.. SPDX-License-Identifier: GPL-2.0
============================================
Assorted Miscellaneous Devices Documentation
============================================
This documentation contains information for assorted devices that do not
fit into other categories.
.. toctree::
:caption: Table of contents
:maxdepth: 2
ad525x_dpot
amd-sbi
bh1770glc
c2port
dw-xdata-pcie
ibmvmc
ics932s401
isl29003
lis3lv02d
max6875
mrvl_cn10k_dpi
oxsemi-tornado
pci-endpoint-test
spear-pcie-gadget
tps6594-pfsm
uacce
xilinx_sdfec
linux-7.2.3/Documentation/misc-devices/isl29003.rst
+75
View File
@@ -0,0 +1,75 @@
======================
Kernel driver isl29003
======================
Supported chips:
* Intersil ISL29003
Prefix: 'isl29003'
Addresses scanned: none
Datasheet:
http://www.intersil.com/data/fn/fn7464.pdf
Author: Daniel Mack <daniel@caiaq.de>
Description
-----------
The ISL29003 is an integrated light sensor with a 16-bit integrating type
ADC, I2C user programmable lux range select for optimized counts/lux, and
I2C multi-function control and monitoring capabilities. The internal ADC
provides 16-bit resolution while rejecting 50Hz and 60Hz flicker caused by
artificial light sources.
The driver allows to set the lux range, the bit resolution, the operational
mode (see below) and the power state of device and can read the current lux
value, of course.
Detection
---------
The ISL29003 does not have an ID register which could be used to identify
it, so the detection routine will just try to read from the configured I2C
address and consider the device to be present as soon as it ACKs the
transfer.
Sysfs entries
-------------
range:
== ===========================
0: 0 lux to 1000 lux (default)
1: 0 lux to 4000 lux
2: 0 lux to 16,000 lux
3: 0 lux to 64,000 lux
== ===========================
resolution:
== =====================
0: 2^16 cycles (default)
1: 2^12 cycles
2: 2^8 cycles
3: 2^4 cycles
== =====================
mode:
== =================================================
0: diode1's current (unsigned 16bit) (default)
1: diode1's current (unsigned 16bit)
2: difference between diodes (l1 - l2, signed 15bit)
== =================================================
power_state:
== =================================================
0: device is disabled (default)
1: device is enabled
== =================================================
lux (read only):
returns the value from the last sensor reading
linux-7.2.3/Documentation/misc-devices/lis3lv02d.rst
+99
View File
@@ -0,0 +1,99 @@
=======================
Kernel driver lis3lv02d
=======================
Supported chips:
* STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision)
* STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and
LIS331DLH (16 bits)
Authors:
- Yan Burman <burman.yan@gmail.com>
- Eric Piel <eric.piel@tremplin-utc.net>
Description
-----------
This driver provides support for the accelerometer found in various HP laptops
sporting the feature officially called "HP Mobile Data Protection System 3D" or
"HP 3D DriveGuard". It detects automatically laptops with this sensor. Known
models (full list can be found in drivers/platform/x86/hp_accel.c) will have
their axis automatically oriented on standard way (eg: you can directly play
neverball). The accelerometer data is readable via
/sys/devices/faux/lis3lv02d. Reported values are scaled
to mg values (1/1000th of earth gravity).
Sysfs attributes under /sys/devices/faux/lis3lv02d/:
position
- 3D position that the accelerometer reports. Format: "(x,y,z)"
rate
- read reports the sampling rate of the accelerometer device in HZ.
write changes sampling rate of the accelerometer device.
Only values which are supported by HW are accepted.
selftest
- performs selftest for the chip as specified by chip manufacturer.
This driver also provides an absolute input class device, allowing
the laptop to act as a pinball machine-esque joystick. Joystick device can be
calibrated. Joystick device can be in two different modes.
By default output values are scaled between -32768 .. 32767. In joystick raw
mode, joystick and sysfs position entry have the same scale. There can be
small difference due to input system fuzziness feature.
Events are also available as input event device.
Selftest is meant only for hardware diagnostic purposes. It is not meant to be
used during normal operations. Position data is not corrupted during selftest
but interrupt behaviour is not guaranteed to work reliably. In test mode, the
sensing element is internally moved little bit. Selftest measures difference
between normal mode and test mode. Chip specifications tell the acceptance
limit for each type of the chip. Limits are provided via platform data
to allow adjustment of the limits without a change to the actual driver.
Seltest returns either "OK x y z" or "FAIL x y z" where x, y and z are
measured difference between modes. Axes are not remapped in selftest mode.
Measurement values are provided to help HW diagnostic applications to make
final decision.
On HP laptops, if the led infrastructure is activated, support for a led
indicating disk protection will be provided as /sys/class/leds/hp::hddprotect.
Another feature of the driver is misc device called "freefall" that
acts similar to /dev/rtc and reacts on free-fall interrupts received
from the device. It supports blocking operations, poll/select and
fasync operation modes. You must read 1 bytes from the device. The
result is number of free-fall interrupts since the last successful
read (or 255 if number of interrupts would not fit). See the freefall.c
file for an example on using the device.
Axes orientation
----------------
For better compatibility between the various laptops. The values reported by
the accelerometer are converted into a "standard" organisation of the axes
(aka "can play neverball out of the box"):
* When the laptop is horizontal the position reported is about 0 for X and Y
and a positive value for Z
* If the left side is elevated, X increases (becomes positive)
* If the front side (where the touchpad is) is elevated, Y decreases
(becomes negative)
* If the laptop is put upside-down, Z becomes negative
If your laptop model is not recognized (cf "dmesg"), you can send an
email to the maintainer to add it to the database. When reporting a new
laptop, please include the output of "dmidecode" plus the value of
/sys/devices/faux/lis3lv02d/position in these four cases.
Q&A
---
Q: How do I safely simulate freefall? I have an HP "portable
workstation" which has about 3.5kg and a plastic case, so letting it
fall to the ground is out of question...
A: The sensor is pretty sensitive, so your hands can do it. Lift it
into free space, follow the fall with your hands for like 10
centimeters. That should be enough to trigger the detection.
linux-7.2.3/Documentation/misc-devices/max6875.rst
+136
View File
@@ -0,0 +1,136 @@
=====================
Kernel driver max6875
=====================
Supported chips:
* Maxim MAX6874, MAX6875
Prefix: 'max6875'
Addresses scanned: None (see below)
Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
Author: Ben Gardner <bgardner@wabtec.com>
Description
-----------
The Maxim MAX6875 is an EEPROM-programmable power-supply sequencer/supervisor.
It provides timed outputs that can be used as a watchdog, if properly wired.
It also provides 512 bytes of user EEPROM.
At reset, the MAX6875 reads the configuration EEPROM into its configuration
registers. The chip then begins to operate according to the values in the
registers.
The Maxim MAX6874 is a similar, mostly compatible device, with more inputs
and outputs:
=========== === === ====
- vin gpi vout
=========== === === ====
MAX6874 6 4 8
MAX6875 4 3 5
=========== === === ====
See the datasheet for more information.
Sysfs entries
-------------
eeprom - 512 bytes of user-defined EEPROM space.
General Remarks
---------------
Valid addresses for the MAX6875 are 0x50 and 0x52.
Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56.
The driver does not probe any address, so you explicitly instantiate the
devices.
Example::
$ modprobe max6875
$ echo max6875 0x50 > /sys/bus/i2c/devices/i2c-0/new_device
The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple
addresses. For example, for address 0x50, it also reserves 0x51.
The even-address instance is called 'max6875', the odd one is 'dummy'.
Programming the chip using i2c-dev
----------------------------------
Use the i2c-dev interface to access and program the chips.
Reads and writes are performed differently depending on the address range.
The configuration registers are at addresses 0x00 - 0x45.
Use i2c_smbus_write_byte_data() to write a register and
i2c_smbus_read_byte_data() to read a register.
The command is the register number.
Examples:
To write a 1 to register 0x45::
i2c_smbus_write_byte_data(fd, 0x45, 1);
To read register 0x45::
value = i2c_smbus_read_byte_data(fd, 0x45);
The configuration EEPROM is at addresses 0x8000 - 0x8045.
The user EEPROM is at addresses 0x8100 - 0x82ff.
Use i2c_smbus_write_word_data() to write a byte to EEPROM.
The command is the upper byte of the address: 0x80, 0x81, or 0x82.
The data word is the lower part of the address or'd with data << 8::
cmd = address >> 8;
val = (address & 0xff) | (data << 8);
Example:
To write 0x5a to address 0x8003::
i2c_smbus_write_word_data(fd, 0x80, 0x5a03);
Reading data from the EEPROM is a little more complicated.
Use i2c_smbus_write_byte_data() to set the read address and then
i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data.
Example:
To read data starting at offset 0x8100, first set the address::
i2c_smbus_write_byte_data(fd, 0x81, 0x00);
And then read the data::
value = i2c_smbus_read_byte(fd);
or::
count = i2c_smbus_read_i2c_block_data(fd, 0x84, 16, buffer);
The block read should read 16 bytes.
0x84 is the block read command.
See the datasheet for more details.
linux-7.2.3/Documentation/misc-devices/mrvl_cn10k_dpi.rst
+52
View File
@@ -0,0 +1,52 @@
.. SPDX-License-Identifier: GPL-2.0
===============================================
Marvell CN10K DMA packet interface (DPI) driver
===============================================
Overview
========
DPI is a DMA packet interface hardware block in Marvell's CN10K silicon.
DPI hardware comprises a physical function (PF), its virtual functions,
mailbox logic, and a set of DMA engines & DMA command queues.
DPI PF function is an administrative function which services the mailbox
requests from its VF functions and provisions DMA engine resources to
it's VF functions.
mrvl_cn10k_dpi.ko misc driver loads on DPI PF device and services the
mailbox commands submitted by the VF devices and accordingly initializes
the DMA engines and VF device's DMA command queues. Also, driver creates
/dev/mrvl-cn10k-dpi node to set DMA engine and PEM (PCIe interface) port
attributes like fifo length, molr, mps & mrrs.
DPI PF driver is just an administrative driver to setup its VF device's
queues and provisions the hardware resources, it cannot initiate any
DMA operations. Only VF devices are provisioned with DMA capabilities.
Driver location
===============
drivers/misc/mrvl_cn10k_dpi.c
Driver IOCTLs
=============
:c:macro:`DPI_MPS_MRRS_CFG`
ioctl that sets max payload size & max read request size parameters of
a pem port to which DMA engines are wired.
:c:macro:`DPI_ENGINE_CFG`
ioctl that sets DMA engine's fifo sizes & max outstanding load request
thresholds.
User space code example
=======================
DPI VF devices are probed and accessed from user space applications using
vfio-pci driver. Below is a sample dpi dma application to demonstrate on
how applications use mailbox and ioctl services from DPI PF kernel driver.
https://github.com/MarvellEmbeddedProcessors/dpi-sample-app
linux-7.2.3/Documentation/misc-devices/oxsemi-tornado.rst
+107
View File
@@ -0,0 +1,107 @@
.. SPDX-License-Identifier: GPL-2.0
====================================================================
Notes on Oxford Semiconductor PCIe (Tornado) 950 serial port devices
====================================================================
Oxford Semiconductor PCIe (Tornado) 950 serial port devices are driven
by a fixed 62.5MHz clock input derived from the 100MHz PCI Express clock.
The baud rate produced by the baud generator is obtained from this input
frequency by dividing it by the clock prescaler, which can be set to any
value from 1 to 63.875 in increments of 0.125, and then the usual 16-bit
divisor is used as with the original 8250, to divide the frequency by a
value from 1 to 65535. Finally a programmable oversampling rate is used
that can take any value from 4 to 16 to divide the frequency further and
determine the actual baud rate used. Baud rates from 15625000bps down
to 0.933bps can be obtained this way.
By default the oversampling rate is set to 16 and the clock prescaler is
set to 33.875, meaning that the frequency to be used as the reference
for the usual 16-bit divisor is 115313.653, which is close enough to the
frequency of 115200 used by the original 8250 for the same values to be
used for the divisor to obtain the requested baud rates by software that
is unaware of the extra clock controls available.
The oversampling rate is programmed with the TCR register and the clock
prescaler is programmed with the CPR/CPR2 register pair [OX200]_ [OX952]_
[OX954]_ [OX958]_. To switch away from the default value of 33.875 for
the prescaler the enhanced mode has to be explicitly enabled though, by
setting bit 4 of the EFR. In that mode setting bit 7 in the MCR enables
the prescaler or otherwise it is bypassed as if the value of 1 was used.
Additionally writing any value to CPR clears CPR2 for compatibility with
old software written for older conventional PCI Oxford Semiconductor
devices that do not have the extra prescaler's 9th bit in CPR2, so the
CPR/CPR2 register pair has to be programmed in the right order.
By using these parameters rates from 15625000bps down to 1bps can be
obtained, with either exact or highly-accurate actual bit rates for
standard and many non-standard rates.
Here are the figures for the standard and some non-standard baud rates
(including those quoted in Oxford Semiconductor documentation), giving
the requested rate (r), the actual rate yielded (a) and its deviation
from the requested rate (d), and the values of the oversampling rate
(tcr), the clock prescaler (cpr) and the divisor (div) produced by the
new ``get_divisor`` handler:
::
r: 15625000, a: 15625000.00, d: 0.0000%, tcr: 4, cpr: 1.000, div: 1
r: 12500000, a: 12500000.00, d: 0.0000%, tcr: 5, cpr: 1.000, div: 1
r: 10416666, a: 10416666.67, d: 0.0000%, tcr: 6, cpr: 1.000, div: 1
r: 8928571, a: 8928571.43, d: 0.0000%, tcr: 7, cpr: 1.000, div: 1
r: 7812500, a: 7812500.00, d: 0.0000%, tcr: 8, cpr: 1.000, div: 1
r: 4000000, a: 4000000.00, d: 0.0000%, tcr: 5, cpr: 3.125, div: 1
r: 3686400, a: 3676470.59, d: -0.2694%, tcr: 8, cpr: 2.125, div: 1
r: 3500000, a: 3496503.50, d: -0.0999%, tcr: 13, cpr: 1.375, div: 1
r: 3000000, a: 2976190.48, d: -0.7937%, tcr: 14, cpr: 1.500, div: 1
r: 2500000, a: 2500000.00, d: 0.0000%, tcr: 10, cpr: 2.500, div: 1
r: 2000000, a: 2000000.00, d: 0.0000%, tcr: 10, cpr: 3.125, div: 1
r: 1843200, a: 1838235.29, d: -0.2694%, tcr: 16, cpr: 2.125, div: 1
r: 1500000, a: 1492537.31, d: -0.4975%, tcr: 5, cpr: 8.375, div: 1
r: 1152000, a: 1152073.73, d: 0.0064%, tcr: 14, cpr: 3.875, div: 1
r: 921600, a: 919117.65, d: -0.2694%, tcr: 16, cpr: 2.125, div: 2
r: 576000, a: 576036.87, d: 0.0064%, tcr: 14, cpr: 3.875, div: 2
r: 460800, a: 460829.49, d: 0.0064%, tcr: 7, cpr: 3.875, div: 5
r: 230400, a: 230414.75, d: 0.0064%, tcr: 14, cpr: 3.875, div: 5
r: 115200, a: 115207.37, d: 0.0064%, tcr: 14, cpr: 1.250, div: 31
r: 57600, a: 57603.69, d: 0.0064%, tcr: 8, cpr: 3.875, div: 35
r: 38400, a: 38402.46, d: 0.0064%, tcr: 14, cpr: 3.875, div: 30
r: 19200, a: 19201.23, d: 0.0064%, tcr: 8, cpr: 3.875, div: 105
r: 9600, a: 9600.06, d: 0.0006%, tcr: 9, cpr: 1.125, div: 643
r: 4800, a: 4799.98, d: -0.0004%, tcr: 7, cpr: 2.875, div: 647
r: 2400, a: 2400.02, d: 0.0008%, tcr: 9, cpr: 2.250, div: 1286
r: 1200, a: 1200.00, d: 0.0000%, tcr: 14, cpr: 2.875, div: 1294
r: 300, a: 300.00, d: 0.0000%, tcr: 11, cpr: 2.625, div: 7215
r: 200, a: 200.00, d: 0.0000%, tcr: 16, cpr: 1.250, div: 15625
r: 150, a: 150.00, d: 0.0000%, tcr: 13, cpr: 2.250, div: 14245
r: 134, a: 134.00, d: 0.0000%, tcr: 11, cpr: 2.625, div: 16153
r: 110, a: 110.00, d: 0.0000%, tcr: 12, cpr: 1.000, div: 47348
r: 75, a: 75.00, d: 0.0000%, tcr: 4, cpr: 5.875, div: 35461
r: 50, a: 50.00, d: 0.0000%, tcr: 16, cpr: 1.250, div: 62500
r: 25, a: 25.00, d: 0.0000%, tcr: 16, cpr: 2.500, div: 62500
r: 4, a: 4.00, d: 0.0000%, tcr: 16, cpr: 20.000, div: 48828
r: 2, a: 2.00, d: 0.0000%, tcr: 16, cpr: 40.000, div: 48828
r: 1, a: 1.00, d: 0.0000%, tcr: 16, cpr: 63.875, div: 61154
With the baud base set to 15625000 and the unsigned 16-bit UART_DIV_MAX
limitation imposed by ``serial8250_get_baud_rate`` standard baud rates
below 300bps become unavailable in the regular way, e.g. the rate of
200bps requires the baud base to be divided by 78125 and that is beyond
the unsigned 16-bit range.
Maciej W. Rozycki <macro@orcam.me.uk>
.. [OX200] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor,
Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65
.. [OX952] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port",
Oxford Semiconductor, Inc., DS-0046, Mar 06 08, Section "950 Mode",
p. 20
.. [OX954] "OXPCIe954 PCI Express Bridge to Quad Serial Port", Oxford
Semiconductor, Inc., DS-0047, Feb 08, Section "950 Mode", p. 20
.. [OX958] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford
Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20
linux-7.2.3/Documentation/misc-devices/pci-endpoint-test.rst
+56
View File
@@ -0,0 +1,56 @@
.. SPDX-License-Identifier: GPL-2.0
=====================================
Driver for PCI Endpoint Test Function
=====================================
This driver should be used as a host side driver if the root complex is
connected to a configurable PCI endpoint running ``pci_epf_test`` function
driver configured according to [1]_.
The "pci_endpoint_test" driver can be used to perform the following tests.
The PCI driver for the test device performs the following tests:
#) verifying addresses programmed in BAR
#) raise legacy IRQ
#) raise MSI IRQ
#) raise MSI-X IRQ
#) read data
#) write data
#) copy data
This misc driver creates /dev/pci-endpoint-test.<num> for every
``pci_epf_test`` function connected to the root complex and "ioctls"
should be used to perform the above tests.
ioctl
-----
PCITEST_BAR:
Tests the BAR. The number of the BAR to be tested
should be passed as argument.
PCITEST_LEGACY_IRQ:
Tests legacy IRQ
PCITEST_MSI:
Tests message signalled interrupts. The MSI number
to be tested should be passed as argument.
PCITEST_MSIX:
Tests message signalled interrupts. The MSI-X number
to be tested should be passed as argument.
PCITEST_SET_IRQTYPE:
Changes driver IRQ type configuration. The IRQ type
should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X).
PCITEST_GET_IRQTYPE:
Gets driver IRQ type configuration.
PCITEST_WRITE:
Perform write tests. The size of the buffer should be passed
as argument.
PCITEST_READ:
Perform read tests. The size of the buffer should be passed
as argument.
PCITEST_COPY:
Perform read tests. The size of the buffer should be passed
as argument.
.. [1] Documentation/PCI/endpoint/function/binding/pci-test.rst
linux-7.2.3/Documentation/misc-devices/spear-pcie-gadget.rst
+170
View File
@@ -0,0 +1,170 @@
.. SPDX-License-Identifier: GPL-2.0
========================
Spear PCIe Gadget Driver
========================
Author
======
Pratyush Anand (pratyush.anand@gmail.com)
Location
========
driver/misc/spear13xx_pcie_gadget.c
Supported Chip:
===============
SPEAr1300
SPEAr1310
Menuconfig option:
==================
Device Drivers
Misc devices
PCIe gadget support for SPEAr13XX platform
purpose
=======
This driver has several nodes which can be read/written by configfs interface.
Its main purpose is to configure selected dual mode PCIe controller as device
and then program its various registers to configure it as a particular device
type. This driver can be used to show spear's PCIe device capability.
Description of different nodes:
===============================
read behavior of nodes:
-----------------------
=============== ==============================================================
link gives ltssm status.
int_type type of supported interrupt
no_of_msi zero if MSI is not enabled by host. A positive value is the
number of MSI vector granted.
vendor_id returns programmed vendor id (hex)
device_id returns programmed device id(hex)
bar0_size: returns size of bar0 in hex.
bar0_address returns address of bar0 mapped area in hex.
bar0_rw_offset returns offset of bar0 for which bar0_data will return value.
bar0_data returns data at bar0_rw_offset.
=============== ==============================================================
write behavior of nodes:
------------------------
=============== ================================================================
link write UP to enable ltsmm DOWN to disable
int_type write interrupt type to be configured and (int_type could be
INTA, MSI or NO_INT). Select MSI only when you have programmed
no_of_msi node.
no_of_msi number of MSI vector needed.
inta write 1 to assert INTA and 0 to de-assert.
send_msi write MSI vector to be sent.
vendor_id write vendor id(hex) to be programmed.
device_id write device id(hex) to be programmed.
bar0_size write size of bar0 in hex. default bar0 size is 1000 (hex)
bytes.
bar0_address write address of bar0 mapped area in hex. (default mapping of
bar0 is SYSRAM1(E0800000). Always program bar size before bar
address. Kernel might modify bar size and address for alignment,
so read back bar size and address after writing to cross check.
bar0_rw_offset write offset of bar0 for which bar0_data will write value.
bar0_data write data to be written at bar0_rw_offset.
=============== ================================================================
Node programming example
========================
Program all PCIe registers in such a way that when this device is connected
to the PCIe host, then host sees this device as 1MB RAM.
::
#mount -t configfs none /Config
For nth PCIe Device Controller::
# cd /config/pcie_gadget.n/
Now you have all the nodes in this directory.
program vendor id as 0x104a::
# echo 104A >> vendor_id
program device id as 0xCD80::
# echo CD80 >> device_id
program BAR0 size as 1MB::
# echo 100000 >> bar0_size
check for programmed bar0 size::
# cat bar0_size
Program BAR0 Address as DDR (0x2100000). This is the physical address of
memory, which is to be made visible to PCIe host. Similarly any other peripheral
can also be made visible to PCIe host. E.g., if you program base address of UART
as BAR0 address then when this device will be connected to a host, it will be
visible as UART.
::
# echo 2100000 >> bar0_address
program interrupt type : INTA::
# echo INTA >> int_type
go for link up now::
# echo UP >> link
It will have to be insured that, once link up is done on gadget, then only host
is initialized and start to search PCIe devices on its port.
::
/*wait till link is up*/
# cat link
Wait till it returns UP.
To assert INTA::
# echo 1 >> inta
To de-assert INTA::
# echo 0 >> inta
if MSI is to be used as interrupt, program no of msi vector needed (say4)::
# echo 4 >> no_of_msi
select MSI as interrupt type::
# echo MSI >> int_type
go for link up now::
# echo UP >> link
wait till link is up::
# cat link
An application can repetitively read this node till link is found UP. It can
sleep between two read.
wait till msi is enabled::
# cat no_of_msi
Should return 4 (number of requested MSI vector)
to send msi vector 2::
# echo 2 >> send_msi
# cd -
linux-7.2.3/Documentation/misc-devices/tps6594-pfsm.rst
+87
View File
@@ -0,0 +1,87 @@
.. SPDX-License-Identifier: GPL-2.0
=====================================
Texas Instruments TPS6594 PFSM driver
=====================================
Author: Julien Panis (jpanis@baylibre.com)
Overview
========
Strictly speaking, PFSM (Pre-configurable Finite State Machine) is not
hardware. It is a piece of code.
The TPS6594 PMIC (Power Management IC) integrates a state machine which
manages operational modes. Depending on the current operational mode,
some voltage domains remain energized while others can be off.
The PFSM driver can be used to trigger transitions between configured
states. It also provides R/W access to the device registers.
Supported chips
---------------
- tps6594-q1
- tps6593-q1
- lp8764-q1
Driver location
===============
drivers/misc/tps6594-pfsm.c
Driver type definitions
=======================
include/uapi/linux/tps6594_pfsm.h
Driver IOCTLs
=============
:c:macro:`PMIC_GOTO_STANDBY`
All device resources are powered down. The processor is off, and
no voltage domains are energized.
:c:macro:`PMIC_GOTO_LP_STANDBY`
The digital and analog functions of the PMIC, which are not
required to be always-on, are turned off (low-power).
:c:macro:`PMIC_UPDATE_PGM`
Triggers a firmware update.
:c:macro:`PMIC_SET_ACTIVE_STATE`
One of the operational modes.
The PMICs are fully functional and supply power to all PDN loads.
All voltage domains are energized in both MCU and Main processor
sections.
:c:macro:`PMIC_SET_MCU_ONLY_STATE`
One of the operational modes.
Only the power resources assigned to the MCU Safety Island are on.
:c:macro:`PMIC_SET_RETENTION_STATE`
One of the operational modes.
Depending on the triggers set, some DDR/GPIO voltage domains can
remain energized, while all other domains are off to minimize
total system power.
Driver usage
============
See available PFSMs::
# ls /dev/pfsm*
Dump the registers of pages 0 and 1::
# hexdump -C /dev/pfsm-0-0x48
See PFSM events::
# cat /proc/interrupts
Userspace code example
----------------------
samples/pfsm/pfsm-wakeup.c
linux-7.2.3/Documentation/misc-devices/uacce.rst
+179
View File
@@ -0,0 +1,179 @@
.. SPDX-License-Identifier: GPL-2.0
Uacce (Unified/User-space-access-intended Accelerator Framework)
================================================================
Introduction
------------
Uacce (Unified/User-space-access-intended Accelerator Framework) targets to
provide Shared Virtual Addressing (SVA) between accelerators and processes.
So accelerator can access any data structure of the main cpu.
This differs from the data sharing between cpu and io device, which share
only data content rather than address.
Because of the unified address, hardware and user space of process can
share the same virtual address in the communication.
Uacce takes the hardware accelerator as a heterogeneous processor, while
IOMMU share the same CPU page tables and as a result the same translation
from va to pa.
::
__________________________ __________________________
| | | |
| User application (CPU) | | Hardware Accelerator |
|__________________________| |__________________________|
| |
| va | va
V V
__________ __________
| | | |
| MMU | | IOMMU |
|__________| |__________|
| |
| |
V pa V pa
_______________________________________
| |
| Memory |
|_______________________________________|
Architecture
------------
Uacce is the kernel module, taking charge of iommu and address sharing.
The user drivers and libraries are called WarpDrive.
The uacce device, built around the IOMMU SVA API, can access multiple
address spaces, including the one without PASID.
A virtual concept, queue, is used for the communication. It provides a
FIFO-like interface. And it maintains a unified address space between the
application and all involved hardware.
::
___________________ ________________
| | user API | |
| WarpDrive library | ------------> | user driver |
|___________________| |________________|
| |
| |
| queue fd |
| |
| |
v |
___________________ _________ |
| | | | | mmap memory
| Other framework | | uacce | | r/w interface
| crypto/nic/others | |_________| |
|___________________| |
| | |
| register | register |
| | |
| | |
| _________________ __________ |
| | | | | |
------------- | Device Driver | | IOMMU | |
|_________________| |__________| |
| |
| V
| ___________________
| | |
-------------------------- | Device(Hardware) |
|___________________|
How does it work
----------------
Uacce uses mmap and IOMMU to play the trick.
Uacce creates a chrdev for every device registered to it. New queue is
created when user application open the chrdev. The file descriptor is used
as the user handle of the queue.
The accelerator device present itself as an Uacce object, which exports as
a chrdev to the user space. The user application communicates with the
hardware by ioctl (as control path) or share memory (as data path).
The control path to the hardware is via file operation, while data path is
via mmap space of the queue fd.
The queue file address space:
::
/**
* enum uacce_qfrt: qfrt type
* @UACCE_QFRT_MMIO: device mmio region
* @UACCE_QFRT_DUS: device user share region
*/
enum uacce_qfrt {
UACCE_QFRT_MMIO = 0,
UACCE_QFRT_DUS = 1,
};
All regions are optional and differ from device type to type.
Each region can be mmapped only once, otherwise -EEXIST returns.
The device mmio region is mapped to the hardware mmio space. It is generally
used for doorbell or other notification to the hardware. It is not fast enough
as data channel.
The device user share region is used for share data buffer between user process
and device.
The Uacce register API
----------------------
The register API is defined in uacce.h.
::
struct uacce_interface {
char name[UACCE_MAX_NAME_SIZE];
unsigned int flags;
const struct uacce_ops *ops;
};
According to the IOMMU capability, uacce_interface flags can be:
::
/**
* UACCE Device flags:
* UACCE_DEV_SVA: Shared Virtual Addresses
* Support PASID
* Support device page faults (PCI PRI or SMMU Stall)
*/
#define UACCE_DEV_SVA BIT(0)
struct uacce_device *uacce_alloc(struct device *parent,
struct uacce_interface *interface);
int uacce_register(struct uacce_device *uacce);
void uacce_remove(struct uacce_device *uacce);
uacce_register results can be:
a. If uacce module is not compiled, ERR_PTR(-ENODEV)
b. Succeed with the desired flags
c. Succeed with the negotiated flags, for example
uacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA
So user driver need check return value as well as the negotiated uacce->flags.
The user driver
---------------
The queue file mmap space will need a user driver to wrap the communication
protocol. Uacce provides some attributes in sysfs for the user driver to
match the right accelerator accordingly.
More details in Documentation/ABI/testing/sysfs-driver-uacce.
linux-7.2.3/Documentation/misc-devices/xilinx_sdfec.rst
+292
View File
@@ -0,0 +1,292 @@
.. SPDX-License-Identifier: GPL-2.0+
====================
Xilinx SD-FEC Driver
====================
Overview
========
This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs.
.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122
.. with trademark sign
For a full description of SD-FEC core features, see the `SD-FEC Product Guide (PG256) <https://www.xilinx.com/cgi-bin/docs/ipdoc?c=sd_fec;v=latest;d=pg256-sdfec-integrated-block.pdf>`_
This driver supports the following features:
- Retrieval of the Integrated Block configuration and status information
- Configuration of LDPC codes
- Configuration of Turbo decoding
- Monitoring errors
Missing features, known issues, and limitations of the SD-FEC driver are as
follows:
- Only allows a single open file handler to any instance of the driver at any time
- Reset of the SD-FEC Integrated Block is not controlled by this driver
- Does not support shared LDPC code table wraparound
The device tree entry is described in:
`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.yaml>`_
Modes of Operation
------------------
The driver works with the SD-FEC core in two modes of operation:
- Run-time configuration
- Programmable Logic (PL) initialization
Run-time Configuration
~~~~~~~~~~~~~~~~~~~~~~
For Run-time configuration the role of driver is to allow the software application to do the following:
- Load the configuration parameters for either Turbo decode or LDPC encode or decode
- Activate the SD-FEC core
- Monitor the SD-FEC core for errors
- Retrieve the status and configuration of the SD-FEC core
Programmable Logic (PL) Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For PL initialization, supporting logic loads configuration parameters for either
the Turbo decode or LDPC encode or decode. The role of the driver is to allow
the software application to do the following:
- Activate the SD-FEC core
- Monitor the SD-FEC core for errors
- Retrieve the status and configuration of the SD-FEC core
Driver Structure
================
The driver provides a platform device where the ``probe`` and ``remove``
operations are provided.
- probe: Updates configuration register with device-tree entries plus determines the current activate state of the core, for example, is the core bypassed or has the core been started.
The driver defines the following driver file operations to provide user
application interfaces:
- open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time
- release: Allows another file descriptor to be open, that is after current file descriptor is closed
- poll: Provides a method to monitor for SD-FEC Error events
- unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core:
- :c:macro:`XSDFEC_START_DEV`
- :c:macro:`XSDFEC_STOP_DEV`
- :c:macro:`XSDFEC_GET_STATUS`
- :c:macro:`XSDFEC_SET_IRQ`
- :c:macro:`XSDFEC_SET_TURBO`
- :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
- :c:macro:`XSDFEC_GET_CONFIG`
- :c:macro:`XSDFEC_SET_ORDER`
- :c:macro:`XSDFEC_SET_BYPASS`
- :c:macro:`XSDFEC_IS_ACTIVE`
- :c:macro:`XSDFEC_CLEAR_STATS`
- :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`
Driver Usage
============
Overview
--------
After opening the driver, the user should find out what operations need to be
performed to configure and activate the SD-FEC core and determine the
configuration of the driver.
The following outlines the flow the user should perform:
- Determine Configuration
- Set the order, if not already configured as desired
- Set Turbo decode, LPDC encode or decode parameters, depending on how the
SD-FEC core is configured plus if the SD-FEC has not been configured for PL
initialization
- Enable interrupts, if not already enabled
- Bypass the SD-FEC core, if required
- Start the SD-FEC core if not already started
- Get the SD-FEC core status
- Monitor for interrupts
- Stop the SD-FEC core
Note: When monitoring for interrupts if a critical error is detected where a reset is required, the driver will be required to load the default configuration.
Determine Configuration
-----------------------
Determine the configuration of the SD-FEC core by using the ioctl
:c:macro:`XSDFEC_GET_CONFIG`.
Set the Order
-------------
Setting the order determines how the order of Blocks can change from input to output.
Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER`
Setting the order can only be done if the following restrictions are met:
- The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
Add LDPC Codes
--------------
The following steps indicate how to add LDPC codes to the SD-FEC core:
- Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code.
- Set the SC, QA, and LA table offsets for the LPDC parameters and the parameters in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
- Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
- Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
- For the applied LPDC Code Parameter use the function :c:func:`xsdfec_calculate_shared_ldpc_table_entry_size` to calculate the size of shared LPDC code tables. This allows the user to determine the shared table usage so when selecting the table offsets for the next LDPC code parameters unused table areas can be selected.
- Repeat for each LDPC code parameter.
Adding LDPC codes can only be done if the following restrictions are met:
- The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as LDPC
- The ``code_wr_protect`` of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates that write protection is not enabled
- The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not started
Set Turbo Decode
----------------
Configuring the Turbo decode parameters is done by using the ioctl :c:macro:`XSDFEC_SET_TURBO` using auto-generated parameters to fill the :c:type:`struct xsdfec_turbo <xsdfec_turbo>` for the desired Turbo code.
Adding Turbo decode can only be done if the following restrictions are met:
- The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO
- The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
Enable Interrupts
-----------------
Enabling or disabling interrupts is done by using the ioctl :c:macro:`XSDFEC_SET_IRQ`. The members of the parameter passed, :c:type:`struct xsdfec_irq <xsdfec_irq>`, to the ioctl are used to set and clear different categories of interrupts. The category of interrupt is controlled as following:
- ``enable_isr`` controls the ``tlast`` interrupts
- ``enable_ecc_isr`` controls the ECC interrupts
If the ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO then the enabling ECC errors is not required.
Bypass the SD-FEC
-----------------
Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS`
Bypassing the SD-FEC can only be done if the following restrictions are met:
- The ``state`` member of :c:type:`struct xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
Start the SD-FEC core
---------------------
Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV`
Get SD-FEC Status
-----------------
Get the SD-FEC status of the device by using the ioctl :c:macro:`XSDFEC_GET_STATUS`, which will fill the :c:type:`struct xsdfec_status <xsdfec_status>`
Monitor for Interrupts
----------------------
- Use the poll system call to monitor for an interrupt. The poll system call waits for an interrupt to wake it up or times out if no interrupt occurs.
- On return Poll ``revents`` will indicate whether stats and/or state have been updated
- ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm
- ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm
- Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS`
- For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
- For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
- Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS`
- For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required
- Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS`
If a critical error is detected where a reset is required. The application is required to call the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`, after the reset and it is not required to call the ioctl :c:macro:`XSDFEC_STOP_DEV`
Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS`
Stop the SD-FEC Core
---------------------
Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV`
Set the Default Configuration
-----------------------------
Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver.
Limitations
-----------
Users should not duplicate SD-FEC device file handlers, for example fork() or dup() a process that has a created an SD-FEC file handler.
Driver IOCTLs
==============
.. c:macro:: XSDFEC_START_DEV
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_START_DEV
.. c:macro:: XSDFEC_STOP_DEV
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_STOP_DEV
.. c:macro:: XSDFEC_GET_STATUS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_GET_STATUS
.. c:macro:: XSDFEC_SET_IRQ
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_SET_IRQ
.. c:macro:: XSDFEC_SET_TURBO
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_SET_TURBO
.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_ADD_LDPC_CODE_PARAMS
.. c:macro:: XSDFEC_GET_CONFIG
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_GET_CONFIG
.. c:macro:: XSDFEC_SET_ORDER
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_SET_ORDER
.. c:macro:: XSDFEC_SET_BYPASS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_SET_BYPASS
.. c:macro:: XSDFEC_IS_ACTIVE
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_IS_ACTIVE
.. c:macro:: XSDFEC_CLEAR_STATS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_CLEAR_STATS
.. c:macro:: XSDFEC_GET_STATS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_GET_STATS
.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:doc: XSDFEC_SET_DEFAULT_CONFIG
Driver Type Definitions
=======================
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
:internal: