Driver implementer’s API guide

The kernel offers a wide variety of interfaces to support the development of device drivers. This document is an only somewhat organized collection of some of those interfaces — it will hopefully get better over time! The available subsections can be seen below.

Table of contents

• Driver Model
  • Driver Binding
  • Bus Types
  • Device Driver Design Patterns
  • The Basic Device Structure
  • Devres - Managed Device Resource
  • Device Drivers
  • The Linux Kernel Device Model
  • Platform Devices and Drivers
  • Porting Drivers to the New Driver Model
• Driver Basics
  • Driver Entry and Exit points
  • Driver device table
  • Delaying and scheduling routines
  • Time and timer routines
  • High-resolution timers
  • Wait queues and Wake events
  • Internal Functions
  • Reference counting
  • Atomics
  • Kernel objects manipulation
  • Kernel utility functions
  • Device Resource Management
• Device drivers infrastructure
  • The Basic Device Driver-Model Structures
  • Device Drivers Base
  • Device Drivers DMA Management
  • Device drivers PnP support
  • Userspace IO devices
• ioctl based interfaces
  • Command number definitions
  • Interface versions
  • Return code
  • Timestamps
  • 32-bit compat mode
  • Information leaks
  • Subsystem abstractions
  • Alternatives to ioctl
• Early Userspace
  • Early userspace support
  • initramfs buffer format
• CPU and Device Power Management
  • CPU Idle Time Management
  • Device Power Management Basics
  • Suspend/Hibernation Notifiers
  • Device Power Management Data Types
• The Common Clk Framework
  • Introduction and interface split
  • Common data structures and api
  • Hardware clk implementations
  • Supporting your own clk hardware
  • Disabling clock gating of unused clocks
  • Locking
• Bus-Independent Device Accesses
  • Introduction
  • Memory Mapped IO
  • Port Space Accesses
  • __iomem pointer tokens
  • Differences between I/O access functions
  • Device memory mapping modes
  • Higher-level ioremap abstractions
  • Generalizing Access to System and I/O Memory
  • Public Functions Provided
• Buffer Sharing and Synchronization (dma-buf)
  • Shared DMA Buffers
  • Reservation Objects
  • DMA Fences
• Device links
  • Usage
  • Limitations
  • Examples
  • Alternatives
  • Implementation
  • State machine
  • API
• Component Helper for Aggregate Drivers
  • API
• Message-based devices
  • Fusion message devices
• InfiniBand and Remote DMA (RDMA) Interfaces
  • Introduction and Overview
  • InfiniBand core interfaces
  • RDMA Verbs transport library
  • Upper Layer Protocols
• Managing Ownership of the Framebuffer Aperture
  • aperture_remove_all_conflicting_devices()
  • devm_aperture_acquire_for_platform_device()
  • aperture_remove_conflicting_devices()
  • __aperture_remove_legacy_vga_devices()
  • aperture_remove_conflicting_pci_devices()
• Frame Buffer Library
  • Frame Buffer Memory
  • Frame Buffer Colormap
  • Frame Buffer Video Mode Database
  • Frame Buffer Macintosh Video Mode Database
  • Frame Buffer Fonts
• Voltage and current regulator API
  • Introduction
  • Consumer driver interface
  • Regulator driver interface
  • Machine interface
  • API reference
• Reset controller API
  • Introduction
  • Consumer driver interface
  • Reset controller driver interface
  • API reference
• Industrial I/O
  • Introduction
  • Core elements
  • Buffers
  • Triggers
  • Triggered Buffers
  • HW consumer
• Input Subsystem
  • Input core
  • Multitouch Library
  • Matrix keyboards/keypads
  • Sparse keymap support
• Linux USB API
  • The Linux-USB Host Side API
  • USB Gadget API for Linux
  • USB Anchors
  • USB bulk streams
  • USB core callbacks
  • USB DMA
  • USB Request Block (URB)
  • Power Management for USB
  • USB hotplugging
  • USB device persistence during system suspend
  • USB Error codes
  • Writing USB Device Drivers
  • Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
  • Writing a MUSB Glue Layer
  • USB Type-C connector class
  • API for USB Type-C Alternate Mode drivers
  • USB3 debug port
• Firewire (IEEE 1394) driver Interface Guide
  • Introduction and Overview
  • Firewire char device data structures
  • Firewire device probing and sysfs interfaces
  • Firewire core transaction interfaces
  • Firewire Isochronous I/O interfaces
• The Linux PCI driver implementer’s API guide
  • PCI Support Library
  • PCI Hotplug Support Library
  • PCI Peer-to-Peer DMA Support
• Compute Express Link
  • Compute Express Link Memory Devices
• Serial Peripheral Interface (SPI)
  • spi_statistics
  • spi_delay
  • spi_device
  • spi_driver
  • spi_unregister_driver()
  • module_spi_driver
  • spi_controller
  • spi_res
  • spi_transfer
  • spi_message
  • spi_message_init_with_transfers()
  • spi_is_bpw_supported()
  • spi_controller_xfer_timeout()
  • spi_replaced_transfers
  • spi_sync_transfer()
  • spi_write()
  • spi_read()
  • spi_w8r8()
  • spi_w8r16()
  • spi_w8r16be()
  • spi_board_info
  • spi_register_board_info()
  • __spi_register_driver()
  • spi_alloc_device()
  • spi_add_device()
  • spi_new_device()
  • spi_unregister_device()
  • spi_finalize_current_transfer()
  • spi_take_timestamp_pre()
  • spi_take_timestamp_post()
  • spi_get_next_queued_message()
  • spi_finalize_current_message()
  • spi_new_ancillary_device()
  • acpi_spi_count_resources()
  • acpi_spi_device_alloc()
  • spi_slave_abort()
  • __spi_alloc_controller()
  • __devm_spi_alloc_controller()
  • spi_register_controller()
  • devm_spi_register_controller()
  • spi_unregister_controller()
  • spi_split_transfers_maxsize()
  • spi_split_transfers_maxwords()
  • spi_setup()
  • spi_async()
  • spi_sync()
  • spi_sync_locked()
  • spi_bus_lock()
  • spi_bus_unlock()
  • spi_write_then_read()
• I²C and SMBus Subsystem
  • i2c_master_recv()
  • i2c_master_recv_dmasafe()
  • i2c_master_send()
  • i2c_master_send_dmasafe()
  • i2c_device_identity
  • i2c_driver_flags
  • i2c_driver
  • i2c_client
  • i2c_board_info
  • I2C_BOARD_INFO
  • i2c_algorithm
  • i2c_lock_operations
  • i2c_timings
  • i2c_bus_recovery_info
  • i2c_adapter_quirks
  • i2c_lock_bus()
  • i2c_trylock_bus()
  • i2c_unlock_bus()
  • i2c_mark_adapter_suspended()
  • i2c_mark_adapter_resumed()
  • i2c_check_quirks()
  • module_i2c_driver
  • builtin_i2c_driver
  • i2c_register_board_info()
  • i2c_verify_client()
  • i2c_new_client_device()
  • i2c_unregister_device()
  • i2c_find_device_by_fwnode()
  • i2c_new_dummy_device()
  • devm_i2c_new_dummy_device()
  • i2c_new_ancillary_device()
  • i2c_verify_adapter()
  • i2c_handle_smbus_host_notify()
  • i2c_add_adapter()
  • i2c_add_numbered_adapter()
  • i2c_del_adapter()
  • devm_i2c_add_adapter()
  • i2c_find_adapter_by_fwnode()
  • i2c_get_adapter_by_fwnode()
  • i2c_parse_fw_timings()
  • i2c_del_driver()
  • __i2c_transfer()
  • i2c_transfer()
  • i2c_transfer_buffer_flags()
  • i2c_get_device_id()
  • i2c_client_get_device_id()
  • i2c_get_dma_safe_msg_buf()
  • i2c_put_dma_safe_msg_buf()
  • i2c_smbus_pec()
  • i2c_smbus_read_byte()
  • i2c_smbus_write_byte()
  • i2c_smbus_read_byte_data()
  • i2c_smbus_write_byte_data()
  • i2c_smbus_read_word_data()
  • i2c_smbus_write_word_data()
  • i2c_smbus_read_block_data()
  • i2c_smbus_write_block_data()
  • i2c_smbus_xfer()
  • i2c_smbus_read_i2c_block_data_or_emulated()
  • i2c_new_smbus_alert_device()
• IPMB Driver for a Satellite MC
  • IPMB driver for Satellite MC
  • Load the IPMB driver
  • Instantiate the device
• The Linux IPMI Driver
  • Configuration
  • Basic Design
  • Addressing
  • Messages
  • The Upper Layer Interface (Message Handler)
  • The Lower Layer (SMI) Interface
  • The SI Driver
  • The SMBus Driver (SSIF)
  • The IPMI IPMB Driver
  • Other Pieces
  • Get the detailed info related with the IPMI device
  • Watchdog
  • Panic Timeouts
  • Poweroff
• I3C subsystem
  • I3C protocol
  • I3C device driver API
  • I3C master controller driver API
• Generic System Interconnect Subsystem
  • Introduction
  • Terminology
  • Interconnect providers
  • Interconnect consumers
  • Interconnect debugfs interfaces
• Device Frequency Scaling
  • Introduction
  • API
• High Speed Synchronous Serial Interface (HSI)
  • Introduction
  • HSI Subsystem in Linux
  • hsi-char Device
  • The kernel HSI API
• Error Detection And Correction (EDAC) Devices
  • Main Concepts used at the EDAC subsystem
  • Memory Controllers
  • PCI Controllers
  • EDAC Blocks
  • Heterogeneous system support
• SCSI Interfaces Guide
  • Introduction
  • SCSI upper layer
  • SCSI mid layer
  • SCSI lower layer
• libATA Developer’s Guide
  • Introduction
  • libata Driver API
  • Error handling
  • libata Library
  • libata Core Internals
  • libata SCSI translation/emulation
  • ATA errors and exceptions
  • ata_piix Internals
  • sata_sil Internals
  • Thanks
• target and iSCSI Interfaces Guide
  • Introduction and Overview
  • Target core device interfaces
  • Target core transport interfaces
  • Target-supported userspace I/O
  • iSCSI helper functions
  • iSCSI boot information
  • iSCSI TCP interfaces
• The Common Mailbox Framework
  • Controller Driver (See include/linux/mailbox_controller.h)
  • Client Driver (See include/linux/mailbox_client.h)
• MTD NAND Driver Programming Interface
  • Introduction
  • Known Bugs And Assumptions
  • Documentation hints
  • Basic board driver
  • Advanced board driver functions
  • Filesystem support
  • Tools
  • Constants
  • Structures
  • Public Functions Provided
  • Internal Functions Provided
  • Credits
• Parallel Port Devices
  • parport_register_driver
  • module_parport_driver
  • parport_yield()
  • parport_yield_blocking()
  • parport_wait_event()
  • parport_wait_peripheral()
  • parport_negotiate()
  • parport_write()
  • parport_read()
  • parport_set_timeout()
  • __parport_register_driver()
  • parport_unregister_driver()
  • parport_get_port()
  • parport_put_port()
  • parport_register_port()
  • parport_announce_port()
  • parport_remove_port()
  • parport_register_dev_model()
  • parport_unregister_device()
  • parport_find_number()
  • parport_find_base()
  • parport_claim()
  • parport_claim_or_block()
  • parport_release()
  • parport_open()
  • parport_close()
• 16x50 UART Driver
  • serial8250_get_port()
  • serial8250_suspend_port()
  • serial8250_resume_port()
  • serial8250_register_8250_port()
  • serial8250_unregister_port()
• Pulse-Width Modulation (PWM)
  • pwm_polarity
  • pwm_args
  • pwm_device
  • pwm_get_state()
  • pwm_init_state()
  • pwm_get_relative_duty_cycle()
  • pwm_set_relative_duty_cycle()
  • pwm_capture
  • pwm_ops
  • pwm_chip
  • pwm_config()
  • pwm_enable()
  • pwm_disable()
  • pwm_set_chip_data()
  • pwm_get_chip_data()
  • pwmchip_add()
  • pwmchip_remove()
  • pwm_request_from_chip()
  • pwm_apply_might_sleep()
  • pwm_adjust_config()
  • pwm_get()
  • pwm_put()
  • devm_pwm_get()
  • devm_fwnode_pwm_get()
• Intel(R) Management Engine Interface (Intel(R) MEI)
  • Introduction
  • Intel MEI Driver
  • IOCTLs:
  • Supported Chipsets
  • Intel(R) Management Engine (ME) Client bus API
  • Intel(R) Active Management Technology (Intel AMT)
• Memory Technology Device (MTD)
  • Upgrading BIOS using spi-intel
  • NAND Error-correction Code
  • SPI NOR framework
• MMC/SD/SDIO card support
  • SD and MMC Block Device Attributes
  • SD and MMC Device Partitions
  • MMC Asynchronous Request
  • MMC tools introduction
• Non-Volatile Memory Device (NVDIMM)
  • LIBNVDIMM: Non-Volatile Devices
  • BTT - Block Translation Table
  • NVDIMM Security
  • NVDIMM Runtime Firmware Activation
• W1: Dallas’ 1-wire bus
  • W1 API internal to the kernel
• The Linux RapidIO Subsystem
  • Introduction
  • Sysfs entries
  • RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
  • RapidIO subsystem mport character device driver (rio_mport_cdev.c)
  • RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
• Writing s390 channel device drivers
  • Introduction
  • The css bus
  • The ccw bus
  • The ccwgroup bus
  • Generic interfaces
• VME Device Drivers
  • Driver registration
  • Resource management
  • Master windows
  • Slave windows
  • DMA channels
  • Interrupts
  • Location monitors
  • Slot Detection
  • Bus Detection
  • VME API
• Linux 802.11 Driver Developer’s Guide
  • Introduction
  • cfg80211 subsystem
  • mac80211 subsystem (basics)
  • mac80211 subsystem (advanced)
• The Userspace I/O HOWTO
  • About this document
  • About UIO
  • Writing your own kernel module
  • Writing a driver in userspace
  • Generic PCI UIO driver
  • Generic Hyper-V UIO driver
  • Further information
• Linux Firmware API
  • Introduction
  • Firmware API core features
  • UEFI Support
  • request_firmware API
  • Firmware Upload API
  • Other Firmware Interfaces
• PINCTRL (PIN CONTROL) subsystem
  • Top-level interface
  • Pin groups
  • Pin configuration
  • Interaction with the GPIO subsystem
  • PINMUX interfaces
  • What is pinmuxing?
  • Pinmux conventions
  • Pinmux drivers
  • Pin control interaction with the GPIO subsystem
  • GPIO mode pitfalls
  • Board/machine configuration
  • Complex mappings
  • Pin control requests from drivers
  • Drivers needing both pin control and GPIOs
  • System pin control hogging
  • Runtime pinmuxing
  • Debugfs files
• General Purpose Input/Output (GPIO)
  • Introduction
  • Using GPIO Lines in Linux
  • GPIO Driver Interface
  • GPIO Descriptor Consumer Interface
  • GPIO Mappings
  • Subsystem drivers using GPIO
  • Legacy GPIO Interfaces
  • A driver for a selfmade cheap BT8xx based PCI GPIO-card (bt8xxgpio)
  • Core
  • ACPI support
  • Device tree support
  • Device-managed API
  • sysfs helpers
• RAID
  • MD Cluster
  • RAID 4/5/6 cache
  • Partial Parity Log
• Media subsystem kernel internal API
  • 1. Media Subsystem Profile
  • 2. Video4Linux devices
  • 3. Digital TV (DVB) devices
  • 4. Remote Controller devices
  • 5. Media Controller devices
  • 6. CEC Kernel Support
  • 7. Pixel data transmitter and receiver drivers
  • 8. Writing camera sensor drivers
  • 9. Media driver-specific documentation
• Miscellaneous Devices
  • misc_register()
  • misc_deregister()
• Near Field Communication
  • HCI backend for NFC Core
  • Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip
• DMAEngine documentation
  • DMAEngine development documentation
  • DMAEngine client documentation
  • DMA Test documentation
  • PXA DMA documentation
• Linux kernel SLIMbus support
  • Overview
• SoundWire Documentation
  • SoundWire Subsystem Summary
  • Audio Stream in SoundWire
  • SoundWire Error Handling
  • SoundWire Locking
• Thermal
  • CPU cooling APIs How To
  • CPU Idle Cooling
  • Generic Thermal Sysfs driver How To
  • Power allocator governor tunables
  • Kernel driver exynos_tmu
  • Exynos Emulation Mode
  • Kernel driver nouveau
  • Kernel driver: x86_pkg_temp_thermal
  • Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface
• FPGA Subsystem
  • Introduction
  • FPGA Manager
  • FPGA Bridge
  • FPGA Region
  • In-kernel API for FPGA Programming
• ACPI Support
  • Linuxized ACPICA - Introduction to ACPICA Release Automation
  • ACPI Scan Handlers
• Auxiliary Bus
  • When Should the Auxiliary Bus Be Used
  • Auxiliary Device Creation
  • Auxiliary Drivers
  • Example Usage
• Kernel driver lp855x
  • Description
  • Platform data for lp855x
• Kernel Connector
  • Connector interfaces
  • Protocol description
  • Reliability
  • Userspace usage
  • Code samples
• Console Drivers
  • Notes for developers
  • Guidelines for console driver writers
• Dell Systems Management Base Driver
  • Overview
  • System Management Interrupt
  • Host Control Action
  • Host Control SMI Type
• EISA bus support
  • Bus root driver
  • Driver
  • Device
  • Misc stuff
  • Kernel parameters
  • Random notes
  • Thanks
• ISA Drivers
• ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz>
  • Interface /proc/isapnp
  • Interface /proc/bus/isapnp
• The io_mapping functions
  • API
• Ordering I/O writes to memory-mapped addresses
• Generic Counter Interface
  • Introduction
  • Theory
  • Paradigm
  • Driver API
  • Driver Implementation
  • Subsystem Architecture
  • Sysfs Interface
  • Counter Character Device
• Memory Controller drivers
  • TI EMIF SDRAM Controller Driver
  • GPMC (General Purpose Memory Controller)
• MEN Chameleon Bus
  • Introduction
  • Architecture
  • Resource handling
  • Writing an MCB driver
• NTB Drivers
  • NTB Core Driver (ntb)
  • NTB Client Drivers
  • NTB Hardware Drivers
• NVMEM Subsystem
  • 1. Introduction
  • 2. Registering/Unregistering the NVMEM provider
  • 3. NVMEM cell based consumer APIs
  • 4. Direct NVMEM device based consumer APIs
  • 5. Releasing a reference to the NVMEM
  • 6. Userspace binary interface
  • 7. DeviceTree Binding
  • 8. NVMEM layouts
• PARPORT interface documentation
  • Global functions
  • PORT FUNCTIONS
• PPS - Pulse Per Second
  • Overview
  • RFC considerations
  • PPS with USB to serial devices
  • Coding example
  • SYSFS support
  • Testing the PPS support
  • Generators
• PTP hardware clock infrastructure for Linux
  • PTP hardware clock kernel API
  • PTP hardware clock user space API
  • Writing clock drivers
  • Supported hardware
• Generic PHY Framework
  • PHY subsystem
  • Samsung USB 2.0 PHY adaptation layer
• Pulse Width Modulation (PWM) interface
  • Identifying PWMs
  • Using PWMs
  • Using PWMs with the sysfs interface
  • Implementing a PWM driver
  • Locking
  • Helpers
• PLDM Firmware Flash Update Library
  • PLDM Firmware file format overview
  • Driver-specific callbacks
• Overview of the pldmfw library
  • Parsing the PLDM file
  • Performing a flash update
• rfkill - RF kill switch support
  • Introduction
  • Implementation details
  • Kernel API
  • Userspace support
• Support for Serial devices
  • Low Level Serial API
  • Serial drivers
• SM501 Driver
  • Core
  • Resources
  • Configuration
• Surface System Aggregator Module (SSAM)
  • Overview
  • Writing Client Drivers
  • Client Driver Documentation
  • Surface Serial Hub Protocol
  • Core Driver Internals
• Linux Switchtec Support
  • Interface
  • Userspace Interface
  • Non-Transparent Bridge (NTB) Driver
• Sync File API Guide
  • in-fences and out-fences
  • Creating Sync Files
  • Receiving Sync Files from Userspace
• TTY
  • TTY structures
  • Writing TTY Driver
  • Other Documentation
• VFIO Mediated devices
  • Virtual Function I/O (VFIO) Mediated devices[1]
  • Registration Interfaces
  • Mediated Device Management Interface Through sysfs
  • Translation APIs for Mediated Devices
  • References
• VFIO - “Virtual Function I/O”
  • Groups, Devices, and IOMMUs
  • VFIO Usage Example
  • IOMMUFD and vfio_iommu_type1
  • VFIO Device cdev
  • Device cdev Example
  • VFIO User API
  • VFIO bus driver API
  • PPC64 sPAPR implementation note
• Acceptance criteria for vfio-pci device specific driver variants
  • Overview
• Virtio
  • Virtio on Linux
  • Writing Virtio Drivers
• Xilinx FPGA
  • Xilinx Zynq MPSoC EEMI Documentation
• Xillybus driver for generic FPGA interface
  • Introduction
  • Usage
  • Internals
• Writing Device Drivers for Zorro Devices
  • Introduction
  • Probing for Zorro Devices
  • Zorro Resources
  • Accessing the Zorro Address Space
  • References
• The Linux Hardware Timestamping Engine (HTE)
  • The HTE Subsystem
  • HTE Tegra Provider
• WMI Driver API
  • wmi_device
  • wmi_driver
  • wmi_driver_register
  • module_wmi_driver
  • set_required_buffer_size()
  • wmi_instance_count()
  • wmidev_instance_count()
  • wmi_evaluate_method()
  • wmidev_evaluate_method()
  • wmi_query_block()
  • wmidev_block_query()
  • wmi_set_block()
  • wmi_install_notify_handler()
  • wmi_remove_notify_handler()
  • wmi_get_event_data()
  • wmi_has_guid()
  • wmi_get_acpi_device_uid()
  • wmi_driver_unregister()