User-Space EC Interface (cdev) — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs General information for driver authors Useful support libraries Bus-level documentation Subsystem-specific APIs Linux 802.11 Driver Developer’s Guide ACPI Support Kernel driver lp855x The Common Clk Framework Confidential Computing Console Drivers Crypto Drivers DMAEngine documentation The Linux kernel dpll subsystem Error Detection And Correction (EDAC) Devices Extcon Device Subsystem Linux Firmware API FPGA Subsystem Frame Buffer Library Managing Ownership of the Framebuffer Aperture Generic Counter Interface Generic Radix Page Table General Purpose Input/Output (GPIO) High Speed Synchronous Serial Interface (HSI) The Linux Hardware Timestamping Engine (HTE) Recoverable Hardware Error Tracking in vmcoreinfo I 2 C and SMBus Subsystem Industrial I/O InfiniBand and Remote DMA (RDMA) Interfaces Input Subsystem Generic System Interconnect Subsystem IPMB Driver for a Satellite MC The Linux IPMI Driver The Intel Silicon Security Engine Interface (Intel SSEI) libATA Developer’s Guide The Common Mailbox Framework RAID Media subsystem kernel internal API Intel(R) Management Engine Interface (Intel(R) MEI) Memory Controller drivers Message-based devices Miscellaneous Devices Parallel Port Devices 16x50 UART Driver Pulse-Width Modulation (PWM) MMC/SD/SDIO card support Memory Technology Device (MTD) MTD NAND Driver Programming Interface Near Field Communication NTB Drivers Non-Volatile Memory Device (NVDIMM) NVMEM Subsystem PARPORT interface documentation Generic PHY Framework PINCTRL (PIN CONTROL) subsystem PLDM Firmware Flash Update Library PPS - Pulse Per Second PTP hardware clock infrastructure for Linux Pulse Width Modulation (PWM) interface Power Sequencing API Voltage and current regulator API Reset controller API rfkill - RF kill switch support Writing s390 channel device drivers SCSI Interfaces Guide Support for Serial devices SM501 Driver SoundWire Documentation Serial Peripheral Interface (SPI) Steal Governor Introduction Core idea Workload considerations Module Parameters Reasons for CONFIG_STEAL_GOVERNOR=m Surface System Aggregator Module (SSAM) Linux Switchtec Support Sync File API Guide target and iSCSI Interfaces Guide TEE (Trusted Execution Environment) driver API Thermal TTY WBRF - Wifi Band RFI Mitigations WMI Driver API Xilinx FPGA Writing Device Drivers for Zorro Devices Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source User-Space EC Interface (cdev) ¶ The surface_aggregator_cdev module provides a misc-device for the SSAM controller to allow for a (more or less) direct connection from user-space to the SAM EC.
It is intended to be used for development and debugging, and therefore should not be used or relied upon in any other way. Note that this module is not loaded automatically, but instead must be loaded manually. The provided interface is accessible through the /dev/surface/aggregator device-file. All functionality of this interface is provided via IOCTLs. These IOCTLs and their respective input/output parameter structs are defined in include/uapi/linux/surface_aggregator/cdev.h .
A small python library and scripts for accessing this interface can be found at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam . Receiving Events ¶ Events can be received by reading from the device-file. The are represented by the struct ssam_cdev_event datatype. Before events are available to be read, however, the desired notifiers must be registered via the SSAM_CDEV_NOTIF_REGISTER IOCTL.
Notifiers are, in essence, callbacks, called when the EC sends an event. They are, in this interface, associated with a specific target category and device-file-instance. They forward any event of this category to the buffer of the corresponding instance, from which it can then be read. Notifiers themselves do not enable events on the EC. Thus, it may additionally be necessary to enable events via the SSAM_CDEV_EVENT_ENABLE IOCTL.
While notifiers work per-client (i.e. per-device-file-instance), events are enabled globally, for the EC and all of its clients (regardless of userspace or non-userspace). The SSAM_CDEV_EVENT_ENABLE and SSAM_CDEV_EVENT_DISABLE IOCTLs take care of reference counting the events, such that an event is enabled as long as there is a client that has requested it. Note that enabled events are not automatically disabled once the client instance is closed.
Therefore any client process (or group of processes) should balance their event enable calls with the corresponding event disable calls. It is, however, perfectly valid to enable and disable events on different client instances. For example, it is valid to set up notifiers and read events on client instance A , enable those events on instance B (note that these will also be received by A since events are enabled/disabled globally), and after no more events are desired, disable the previously enabled events via instance C .
Controller IOCTLs ¶ The following IOCTLs are provided: Controller IOCTLs ¶ Type Number Direction Name Description 0xA5 1 WR REQUEST Perform synchronous SAM request. 0xA5 2 W NOTIF_REGISTER Register event notifier. 0xA5 3 W NOTIF_UNREGISTER Unregister event notifier. 0xA5 4 W EVENT_ENABLE Enable event source. 0xA5 5 W EVENT_DISABLE Disable event source. SSAM_CDEV_REQUEST ¶ Defined as _IOWR(0xA5, 1, struct ssam_cdev_request) .
Executes a synchronous SAM request. The request specification is passed in as argument of type struct ssam_cdev_request , which is then written to/modified by the IOCTL to return status and result of the request. Request payload data must be allocated separately and is passed in via the payload.data and payload.length members. If a response is required, the response buffer must be allocated by the caller and passed in via the response.data member.
The response.length member must be set to the capacity of this buffer, or if no response is required, zero. Upon completion of the request, the call will write the response to the response buffer (if its capacity allows it) and overwrite the length field with the actual size of the response, in bytes. Additionally, if the request has a response, this must be indicated via the request flags, as is done with in-kernel requests.
Request flags can be set via the flags member and the values correspond to the values found in enum ssam_cdev_request_flags . Finally, the status of the request itself is returned in the status member (a negative errno value indicating failure). Note that failure indication of the IOCTL is separated from failure indication of the request: The IOCTL returns a negative status code if anything failed during setup of the request ( -EFAULT ) or if the provided argument or any of its fields are invalid ( -EINVAL ).
In this case, the status value of the request argument may be set, providing more detail on what went wrong (e.g. -ENOMEM for out-of-memory), but this value may also be zero. The IOCTL will return with a zero status code in case the request has been set up, submitted, and completed (i.e. handed back to user-space) successfully from inside the IOCTL, but the request status member may still be negative in case the actual execution of the request failed after it has been submitted.
A full definition of the argument struct is provided below. SSAM_CDEV_NOTIF_REGISTER ¶ Defined as _IOW(0xA5, 2
The rest of this page is on the live site.