diff options
Diffstat (limited to 'Documentation/misc-devices')
| -rw-r--r-- | Documentation/misc-devices/eeprom.rst (renamed from Documentation/misc-devices/eeprom) | 43 | ||||
| -rw-r--r-- | Documentation/misc-devices/ics932s401.rst (renamed from Documentation/misc-devices/ics932s401) | 7 | ||||
| -rw-r--r-- | Documentation/misc-devices/index.rst | 6 | ||||
| -rw-r--r-- | Documentation/misc-devices/isl29003.rst (renamed from Documentation/misc-devices/isl29003) | 15 | ||||
| -rw-r--r-- | Documentation/misc-devices/lis3lv02d.rst (renamed from Documentation/misc-devices/lis3lv02d) | 20 | ||||
| -rw-r--r-- | Documentation/misc-devices/max6875.rst (renamed from Documentation/misc-devices/max6875) | 52 | ||||
| -rw-r--r-- | Documentation/misc-devices/mei/mei-client-bus.txt | 141 | ||||
| -rw-r--r-- | Documentation/misc-devices/mei/mei.txt | 266 | ||||
| -rw-r--r-- | Documentation/misc-devices/xilinx_sdfec.rst | 291 |
9 files changed, 396 insertions, 445 deletions
diff --git a/Documentation/misc-devices/eeprom b/Documentation/misc-devices/eeprom.rst index ba692011f221..008249675ccc 100644 --- a/Documentation/misc-devices/eeprom +++ b/Documentation/misc-devices/eeprom.rst @@ -1,11 +1,17 @@ +==================== Kernel driver eeprom ==================== Supported chips: + * Any EEPROM chip in the designated address range + Prefix: 'eeprom' + Addresses scanned: I2C 0x50 - 0x57 + Datasheets: Publicly available from: + Atmel (www.atmel.com), Catalyst (www.catsemi.com), Fairchild (www.fairchildsemi.com), @@ -16,7 +22,9 @@ Supported chips: Xicor (www.xicor.com), and others. - Chip Size (bits) Address + ========= ============= ============================================ + Chip Size (bits) Address + ========= ============= ============================================ 24C01 1K 0x50 (shadows at 0x51 - 0x57) 24C01A 1K 0x50 - 0x57 (Typical device on DIMMs) 24C02 2K 0x50 - 0x57 @@ -24,7 +32,7 @@ Supported chips: (additional data at 0x51, 0x53, 0x55, 0x57) 24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52, 0x53, 0x55, 0x56, 0x57) - 24C16 16K 0x50 (additional data at 0x51 - 0x57) + 24C16 16K 0x50 (additional data at 0x51 - 0x57) Sony 2K 0x57 Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37 @@ -33,14 +41,15 @@ Supported chips: Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37 Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37 ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37 + ========= ============= ============================================ Authors: - Frodo Looijaard <[email protected]>, - Philip Edelbrock <[email protected]>, - Jean Delvare <[email protected]>, - Greg Kroah-Hartman <[email protected]>, - IBM Corp. + - Frodo Looijaard <[email protected]>, + - Philip Edelbrock <[email protected]>, + - Jean Delvare <[email protected]>, + - Greg Kroah-Hartman <[email protected]>, + - IBM Corp. Description ----------- @@ -74,23 +83,25 @@ this address will write protect the memory array permanently, and the device will no longer respond at the 0x30-37 address. The eeprom driver does not support this register. -Lacking functionality: +Lacking functionality +--------------------- * Full support for larger devices (24C04, 24C08, 24C16). These are not -typically found on a PC. These devices will appear as separate devices at -multiple addresses. + typically found on a PC. These devices will appear as separate devices at + multiple addresses. * Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512). -These devices require two-byte address fields and are not supported. + These devices require two-byte address fields and are not supported. * Enable Writing. Again, no technical reason why not, but making it easy -to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy -to disable the DIMMs (potentially preventing the computer from booting) -until the values are restored somehow. + to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy + to disable the DIMMs (potentially preventing the computer from booting) + until the values are restored somehow. -Use: +Use +--- After inserting the module (and any other required SMBus/i2c modules), you -should have some EEPROM directories in /sys/bus/i2c/devices/* of names such +should have some EEPROM directories in ``/sys/bus/i2c/devices/*`` of names such as "0-0050". Inside each of these is a series of files, the eeprom file contains the binary data from EEPROM. diff --git a/Documentation/misc-devices/ics932s401 b/Documentation/misc-devices/ics932s401.rst index bdac67ff6e3f..613ee54a9c21 100644 --- a/Documentation/misc-devices/ics932s401 +++ b/Documentation/misc-devices/ics932s401.rst @@ -1,10 +1,15 @@ +======================== Kernel driver ics932s401 -====================== +======================== Supported chips: + * IDT ICS932S401 + Prefix: 'ics932s401' + Addresses scanned: I2C 0x69 + Datasheet: Publicly available at the IDT website Author: Darrick J. Wong diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index dfd1f45a3127..f11c5daeada5 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -14,4 +14,10 @@ fit into other categories. .. toctree:: :maxdepth: 2 + eeprom ibmvmc + ics932s401 + isl29003 + lis3lv02d + max6875 + xilinx_sdfec diff --git a/Documentation/misc-devices/isl29003 b/Documentation/misc-devices/isl29003.rst index 80b952fd32ff..0cc38aed6c00 100644 --- a/Documentation/misc-devices/isl29003 +++ b/Documentation/misc-devices/isl29003.rst @@ -1,10 +1,15 @@ +====================== Kernel driver isl29003 -===================== +====================== Supported chips: + * Intersil ISL29003 + Prefix: 'isl29003' + Addresses scanned: none + Datasheet: http://www.intersil.com/data/fn/fn7464.pdf @@ -37,25 +42,33 @@ 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 diff --git a/Documentation/misc-devices/lis3lv02d b/Documentation/misc-devices/lis3lv02d.rst index f89960a0ff95..959bd2b822cf 100644 --- a/Documentation/misc-devices/lis3lv02d +++ b/Documentation/misc-devices/lis3lv02d.rst @@ -1,3 +1,4 @@ +======================= Kernel driver lis3lv02d ======================= @@ -8,8 +9,8 @@ Supported chips: LIS331DLH (16 bits) Authors: - Yan Burman <[email protected]> - Eric Piel <[email protected]> + - Yan Burman <[email protected]> + - Eric Piel <[email protected]> Description @@ -25,11 +26,15 @@ neverball). The accelerometer data is readable via to mg values (1/1000th of earth gravity). Sysfs attributes under /sys/devices/platform/lis3lv02d/: -position - 3D position that the accelerometer reports. Format: "(x,y,z)" -rate - read reports the sampling rate of the accelerometer device in HZ. + +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. +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 @@ -69,11 +74,12 @@ 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 + 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) + (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 diff --git a/Documentation/misc-devices/max6875 b/Documentation/misc-devices/max6875.rst index 2f2bd0b17b5d..ad419ac22a5b 100644 --- a/Documentation/misc-devices/max6875 +++ b/Documentation/misc-devices/max6875.rst @@ -1,12 +1,16 @@ +===================== 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 + + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf Author: Ben Gardner <[email protected]> @@ -24,9 +28,13 @@ registers. The Maxim MAX6874 is a similar, mostly compatible device, with more inputs and outputs: - vin gpi vout + +=========== === === ==== +- vin gpi vout +=========== === === ==== MAX6874 6 4 8 MAX6875 4 3 5 +=========== === === ==== See the datasheet for more information. @@ -41,13 +49,16 @@ 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 +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. @@ -58,52 +69,67 @@ 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: + +To write a 1 to register 0x45:: + i2c_smbus_write_byte_data(fd, 0x45, 1); -To read register 0x45: +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. +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: + +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: + +To read data starting at offset 0x8100, first set the address:: + i2c_smbus_write_byte_data(fd, 0x81, 0x00); -And then read the data +And then read the data:: + value = i2c_smbus_read_byte(fd); - or +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. diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/misc-devices/mei/mei-client-bus.txt deleted file mode 100644 index 743be4ec8989..000000000000 --- a/Documentation/misc-devices/mei/mei-client-bus.txt +++ /dev/null @@ -1,141 +0,0 @@ -Intel(R) Management Engine (ME) Client bus API -============================================== - - -Rationale -========= - -MEI misc character device is useful for dedicated applications to send and receive -data to the many FW appliance found in Intel's ME from the user space. -However for some of the ME functionalities it make sense to leverage existing software -stack and expose them through existing kernel subsystems. - -In order to plug seamlessly into the kernel device driver model we add kernel virtual -bus abstraction on top of the MEI driver. This allows implementing linux kernel drivers -for the various MEI features as a stand alone entities found in their respective subsystem. -Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to -the existing code. - - -MEI CL bus API -============== - -A driver implementation for an MEI Client is very similar to existing bus -based device drivers. The driver registers itself as an MEI CL bus driver through -the mei_cl_driver structure: - -struct mei_cl_driver { - struct device_driver driver; - const char *name; - - const struct mei_cl_device_id *id_table; - - int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id); - int (*remove)(struct mei_cl_device *dev); -}; - -struct mei_cl_id { - char name[MEI_NAME_SIZE]; - kernel_ulong_t driver_info; -}; - -The mei_cl_id structure allows the driver to bind itself against a device name. - -To actually register a driver on the ME Client bus one must call the mei_cl_add_driver() -API. This is typically called at module init time. - -Once registered on the ME Client bus, a driver will typically try to do some I/O on -this bus and this should be done through the mei_cl_send() and mei_cl_recv() -routines. The latter is synchronous (blocks and sleeps until data shows up). -In order for drivers to be notified of pending events waiting for them (e.g. -an Rx event) they can register an event handler through the -mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event -will trigger an event handler call and the driver implementation is supposed -to call mei_recv() from the event handler in order to fetch the pending -received buffers. - - -Example -======= - -As a theoretical example let's pretend the ME comes with a "contact" NFC IP. -The driver init and exit routines for this device would look like: - -#define CONTACT_DRIVER_NAME "contact" - -static struct mei_cl_device_id contact_mei_cl_tbl[] = { - { CONTACT_DRIVER_NAME, }, - - /* required last entry */ - { } -}; -MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl); - -static struct mei_cl_driver contact_driver = { - .id_table = contact_mei_tbl, - .name = CONTACT_DRIVER_NAME, - - .probe = contact_probe, - .remove = contact_remove, -}; - -static int contact_init(void) -{ - int r; - - r = mei_cl_driver_register(&contact_driver); - if (r) { - pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n"); - return r; - } - - return 0; -} - -static void __exit contact_exit(void) -{ - mei_cl_driver_unregister(&contact_driver); -} - -module_init(contact_init); -module_exit(contact_exit); - -And the driver's simplified probe routine would look like that: - -int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) -{ - struct contact_driver *contact; - - [...] - mei_cl_enable_device(dev); - - mei_cl_register_event_cb(dev, contact_event_cb, contact); - - return 0; -} - -In the probe routine the driver first enable the MEI device and then registers -an ME bus event handler which is as close as it can get to registering a -threaded IRQ handler. -The handler implementation will typically call some I/O routine depending on -the pending events: - -#define MAX_NFC_PAYLOAD 128 - -static void contact_event_cb(struct mei_cl_device *dev, u32 events, - void *context) -{ - struct contact_driver *contact = context; - - if (events & BIT(MEI_EVENT_RX)) { - u8 payload[MAX_NFC_PAYLOAD]; - int payload_size; - - payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD); - if (payload_size <= 0) - return; - - /* Hook to the NFC subsystem */ - nfc_hci_recv_frame(contact->hdev, payload, payload_size); - } -} diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt deleted file mode 100644 index 2b80a0cd621f..000000000000 --- a/Documentation/misc-devices/mei/mei.txt +++ /dev/null @@ -1,266 +0,0 @@ -Intel(R) Management Engine Interface (Intel(R) MEI) -=================================================== - -Introduction -============ - -The Intel Management Engine (Intel ME) is an isolated and protected computing -resource (Co-processor) residing inside certain Intel chipsets. The Intel ME -provides support for computer/IT management features. The feature set -depends on the Intel chipset SKU. - -The Intel Management Engine Interface (Intel MEI, previously known as HECI) -is the interface between the Host and Intel ME. This interface is exposed -to the host as a PCI device. The Intel MEI Driver is in charge of the -communication channel between a host application and the Intel ME feature. - -Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and -each client has its own protocol. The protocol is message-based with a -header and payload up to 512 bytes. - -Prominent usage of the Intel ME Interface is to communicate with Intel(R) -Active Management Technology (Intel AMT) implemented in firmware running on -the Intel ME. - -Intel AMT provides the ability to manage a host remotely out-of-band (OOB) -even when the operating system running on the host processor has crashed or -is in a sleep state. - -Some examples of Intel AMT usage are: - - Monitoring hardware state and platform components - - Remote power off/on (useful for green computing or overnight IT - maintenance) - - OS updates - - Storage of useful platform information such as software assets - - Built-in hardware KVM - - Selective network isolation of Ethernet and IP protocol flows based - on policies set by a remote management console - - IDE device redirection from remote management console - -Intel AMT (OOB) communication is based on SOAP (deprecated -starting with Release 6.0) over HTTP/S or WS-Management protocol over -HTTP/S that are received from a remote management console application. - -For more information about Intel AMT: -http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - - -Intel MEI Driver -================ - -The driver exposes a misc device called /dev/mei. - -An application maintains communication with an Intel ME feature while -/dev/mei is open. The binding to a specific feature is performed by calling -MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID. -The number of instances of an Intel ME feature that can be opened -at the same time depends on the Intel ME feature, but most of the -features allow only a single instance. - -The Intel AMT Host Interface (Intel AMTHI) feature supports multiple -simultaneous user connected applications. The Intel MEI driver -handles this internally by maintaining request queues for the applications. - -The driver is transparent to data that are passed between firmware feature -and host application. - -Because some of the Intel ME features can change the system -configuration, the driver by default allows only a privileged -user to access it. - -A code snippet for an application communicating with Intel AMTHI client: - - struct mei_connect_client_data data; - fd = open(MEI_DEVICE); - - data.d.in_client_uuid = AMTHI_UUID; - - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data); - - printf("Ver=%d, MaxLen=%ld\n", - data.d.in_client_uuid.protocol_version, - data.d.in_client_uuid.max_msg_length); - - [...] - - write(fd, amthi_req_data, amthi_req_data_len); - - [...] - - read(fd, &amthi_res_data, amthi_res_data_len); - - [...] - close(fd); - - -IOCTL -===== - -The Intel MEI Driver supports the following IOCTL commands: - IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client). - - usage: - struct mei_connect_client_data clientData; - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData); - - inputs: - mei_connect_client_data struct contain the following - input field: - - in_client_uuid - UUID of the FW Feature that needs - to connect to. - outputs: - out_client_properties - Client Properties: MTU and Protocol Version. - - error returns: - EINVAL Wrong IOCTL Number - ENODEV Device or Connection is not initialized or ready. - (e.g. Wrong UUID) - ENOMEM Unable to allocate memory to client internal data. - EFAULT Fatal Error (e.g. Unable to access user input data) - EBUSY Connection Already Open - - Notes: - max_msg_length (MTU) in client properties describes the maximum - data that can be sent or received. (e.g. if MTU=2K, can send - requests up to bytes 2k and received responses up to 2k bytes). - - IOCTL_MEI_NOTIFY_SET: enable or disable event notifications - - Usage: - uint32_t enable; - ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable); - - Inputs: - uint32_t enable = 1; - or - uint32_t enable[disable] = 0; - - Error returns: - EINVAL Wrong IOCTL Number - ENODEV Device is not initialized or the client not connected - ENOMEM Unable to allocate memory to client internal data. - EFAULT Fatal Error (e.g. Unable to access user input data) - EOPNOTSUPP if the device doesn't support the feature - - Notes: - The client must be connected in order to enable notification events - - - IOCTL_MEI_NOTIFY_GET : retrieve event - - Usage: - uint32_t event; - ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event); - - Outputs: - 1 - if an event is pending - 0 - if there is no even pending - - Error returns: - EINVAL Wrong IOCTL Number - ENODEV Device is not initialized or the client not connected - ENOMEM Unable to allocate memory to client internal data. - EFAULT Fatal Error (e.g. Unable to access user input data) - EOPNOTSUPP if the device doesn't support the feature - - Notes: - The client must be connected and event notification has to be enabled - in order to receive an event - - -Intel ME Applications -===================== - - 1) Intel Local Management Service (Intel LMS) - - Applications running locally on the platform communicate with Intel AMT Release - 2.0 and later releases in the same way that network applications do via SOAP - over HTTP (deprecated starting with Release 6.0) or with WS-Management over - SOAP over HTTP. This means that some Intel AMT features can be accessed from a - local application using the same network interface as a remote application - communicating with Intel AMT over the network. - - When a local application sends a message addressed to the local Intel AMT host - name, the Intel LMS, which listens for traffic directed to the host name, - intercepts the message and routes it to the Intel MEI. - For more information: - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "About Intel AMT" => "Local Access" - - For downloading Intel LMS: - http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ - - The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS - firmware feature using a defined UUID and then communicates with the feature - using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol). - The protocol is used to maintain multiple sessions with Intel AMT from a - single application. - - See the protocol specification in the Intel AMT Software Development Kit (SDK) - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)" - => "Information for Intel(R) vPro(TM) Gateway Developers" - => "Description of the Intel AMT Port Forwarding (APF) Protocol" - - 2) Intel AMT Remote configuration using a Local Agent - - A Local Agent enables IT personnel to configure Intel AMT out-of-the-box - without requiring installing additional data to enable setup. The remote - configuration process may involve an ISV-developed remote configuration - agent that runs on the host. - For more information: - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "Setup and Configuration of Intel AMT" => - "SDK Tools Supporting Setup and Configuration" => - "Using the Local Agent Sample" - - An open source Intel AMT configuration utility, implementing a local agent - that accesses the Intel MEI driver, can be found here: - http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ - - -Intel AMT OS Health Watchdog -============================ - -The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog. -Whenever the OS hangs or crashes, Intel AMT will send an event -to any subscriber to this event. This mechanism means that -IT knows when a platform crashes even when there is a hard failure on the host. - -The Intel AMT Watchdog is composed of two parts: - 1) Firmware feature - receives the heartbeats - and sends an event when the heartbeats stop. - 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature, - configures the watchdog and sends the heartbeats. - -The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure -the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the -watchdog is 120 seconds. - -If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate -on the me client bus and watchdog devices won't be exposed. - - -Supported Chipsets -================== - -7 Series Chipset Family -6 Series Chipset Family -5 Series Chipset Family -4 Series Chipset Family -Mobile 4 Series Chipset Family -ICH9 -82946GZ/GL -82G35 Express -82Q963/Q965 -82P965/G965 -Mobile PM965/GM965 -Mobile GME965/GLE960 -82Q35 Express -82G33/G31/P35/P31 Express -82Q33 Express -82X38/X48 Express - ---- diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst new file mode 100644 index 000000000000..2245fcfa224d --- /dev/null +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -0,0 +1,291 @@ +.. 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.txt <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.txt>`_ + + +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 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: |