Re: [RFC PATCH 3/4] Documentation: espi: add subsystem overview and MAINTAINERS entry

On 8/4/2026 10:09 PM, Randy Dunlap wrote:
> 
> 
> On 8/4/26 4:52 AM, Krishnamoorthi M wrote:
>> Add a driver-api overview of the eSPI subsystem and a MAINTAINERS entry
>> covering the subsystem files.
>>
>> The document describes the architecture, how to write a controller driver
>> and a slave driver, the per-channel APIs (Peripheral, Virtual Wire, OOB,
>> Flash), the alert mechanism flow, and the event notification model. An
>> API Reference section renders kernel-doc from the exported symbols.
>>
>> Signed-off-by: Krishnamoorthi M <[email protected]>
>> ---
>>   Documentation/driver-api/espi.rst  | 213 +++++++++++++++++++++++++++++
>>   Documentation/driver-api/index.rst |   1 +
>>   MAINTAINERS                        |   8 ++
>>   3 files changed, 222 insertions(+)
>>   create mode 100644 Documentation/driver-api/espi.rst
>>
>> diff --git a/Documentation/driver-api/espi.rst b/Documentation/driver-api/espi.rst
>> new file mode 100644
>> index 000000000000..60a3187edb05
>> --- /dev/null
>> +++ b/Documentation/driver-api/espi.rst
>> @@ -0,0 +1,213 @@
>> +.. SPDX-License-Identifier: GPL-2.0-or-later
>> +
>> +===========================================
>> +eSPI (Enhanced Serial Peripheral Interface)
>> +===========================================
>> +
>> +Introduction
>> +============
>> +
>> +eSPI is a bus defined by Intel that replaces the legacy LPC bus. Unlike
>> +SPI it is a structured, capability-negotiated, message-oriented protocol
>> +with four logically independent channels (Peripheral, Virtual Wire, OOB,
>> +Flash) over a shared physical link, and asynchronous target-to-controller
>> +events, so it is modelled as its own bus type rather than an extension of
>> +the SPI subsystem.
>> +
>> +Architecture
>> +============
>> +
>> +* ``struct espi_controller`` - host controller, created with
>> +  espi_controller_alloc() and registered with espi_controller_register().
>> +  It is not itself a device on espi_bus_type.
>> +* ``struct espi_device`` - a target on the bus, matched to a
>> +  ``struct espi_driver`` via its modalias.
>> +* ``struct espi_controller_ops`` - the optional hardware-op table; the
>> +  channel API returns -EOPNOTSUPP for ops a controller does not provide.
>> +
>> +Writing a controller driver
>> +===========================
>> +
>> +A controller driver allocates and registers a controller from its
>> +``probe()`` function::
>> +
>> +    ctrl = espi_controller_alloc(&pdev->dev, sizeof(*priv));
>> +    if (IS_ERR(ctrl))
>> +        return PTR_ERR(ctrl);
>> +
>> +    priv = espi_controller_get_devdata(ctrl);
>> +    ctrl->ops = &my_espi_ops;
>> +    ctrl->max_targets = 1;
>> +
>> +    /* populate ctrl->caps from hardware capability registers */
>> +    ctrl->caps.supported_channels = ESPI_CHANNEL_ALL;
>> +    ctrl->caps.max_freq_mhz       = 33;
>> +    ctrl->caps.io_mode            = ESPI_IO_MODE_SINGLE;
>> +
>> +    ret = espi_controller_register(ctrl);
>> +    if (ret)
>> +        goto err_put;
>> +
>> +After registration the controller calls espi_new_device() for each
>> +target enumerated from firmware (ACPI or device tree)::
>> +
>> +    struct espi_board_info info = {
>> +        .type = "my-ec",
>> +        .cs   = 0,
>> +    };
>> +    edev = espi_new_device(ctrl, &info);
>> +
>> +On removal::
>> +
>> +    espi_remove_device(edev);
>> +    espi_controller_unregister(ctrl);
>> +    espi_controller_put(ctrl);
>> +
>> +Writing a slave driver
>> +======================
>> +
>> +A slave driver declares a device ID table and a ``struct espi_driver``::
>> +
>> +    static const struct espi_device_id my_ec_ids[] = {
>> +        { "my-ec", 0 },
>> +        { }
>> +    };
>> +    MODULE_DEVICE_TABLE(espi, my_ec_ids);
>> +
>> +    static int my_ec_probe(struct espi_device *edev)
>> +    {
>> +        /* register for hardware events */
>> +        nb->notifier_call = my_ec_event;
>> +        espi_register_notifier(edev->ctrl, nb);
>> +        return 0;
>> +    }
>> +
>> +    static void my_ec_remove(struct espi_device *edev)
>> +    {
>> +        espi_unregister_notifier(edev->ctrl, nb);
>> +    }
>> +
>> +    static struct espi_driver my_ec_driver = {
>> +        .driver   = { .name = "my-ec" },
>> +        .id_table = my_ec_ids,
>> +        .probe    = my_ec_probe,
>> +        .remove   = my_ec_remove,
>> +    };
>> +    module_espi_driver(my_ec_driver);
>> +
>> +Channel-independent commands
>> +============================
>> +
>> +espi_get_configuration(), espi_set_configuration(), espi_inband_reset()
>> +and espi_get_status(). GET_STATUS is optional: controllers whose hardware
>> +does not implement the wire command leave .get_status unset.
>> +
>> +Capability negotiation and channel management
>> +=============================================
>> +
>> +At boot the controller driver reads the target's capability registers via
>> +espi_get_configuration(), negotiates link parameters (I/O mode, clock
>> +frequency, CRC) via espi_set_configuration(), then enables each channel
>> +with espi_enable_channel(). espi_channel_is_enabled() may be called at
>> +any time to query the current state. Channels may be disabled individually
>> +with espi_disable_channel(), for example before an in-band reset.
>> +
>> +Channel APIs
>> +============
>> +
>> +Peripheral channel
>> +------------------
>> +
>> +Carries I/O and memory cycles between the host and target endpoints.
>> +
>> +* espi_periph_io_read() / espi_periph_io_write() — 16-bit I/O port
>> +  access; ``width`` is the access size in bytes (1, 2, or 4).
>> +* espi_periph_mem_read() / espi_periph_mem_write() — 32-bit memory
>> +  mapped access.
>> +
>> +Virtual Wire channel
>> +--------------------
>> +
>> +Carries logical signal state (power sequencing, SMI#, SCI#, IRQs) as
>> +indexed wire groups. Each group carries up to four wire values with
>> +individual valid bits.
>> +
>> +* espi_vwire_get() — read a wire group from the target.
>> +* espi_vwire_put() — send a PUT_VIRTUAL_WIRE command to the target.
>> +  Named after the eSPI PUT_VW wire command, not a reference-count
>> +  release.
>> +
>> +Wire changes from the target generate an ``ESPI_EVENT_VWIRE_CHANGED``
>> +event delivered through the notifier chain.
>> +
>> +OOB channel
>> +-----------
>> +
>> +Tunnels SMBus/I2C messages between the host and target out-of-band
>> +processor (BMC, EC). Messages are exchanged as opaque byte buffers with
>> +a tag field for matching requests to responses.
>> +
>> +* espi_oob_send() / espi_oob_recv()
>> +
>> +Incoming OOB messages generate an ``ESPI_EVENT_OOB_RECEIVED`` event.
>> +
>> +Flash Access channel
>> +--------------------
>> +
>> +Provides access to a SPI flash device attached to the target. The target
>> +acts as a proxy for flash read, write, and erase operations.
>> +
>> +* espi_flash_read() / espi_flash_write() / espi_flash_erase()
>> +
>> +Alert mechanism
>> +===============
>> +
>> +When the target has upstream data pending it asserts ``ALERT#``. The
>> +controller's hard-IRQ handler acknowledges the interrupt and defers
>> +processing to a threaded IRQ or workqueue. From that process context the
>> +controller driver calls espi_handle_alert(), which acquires the
>> +controller lock and dispatches to ``ops->handle_alert``. The hardware
>> +callback reads the target's status register (GET_STATUS), identifies the
>> +pending channel, and calls espi_notify_event() to deliver the appropriate
>> +``ESPI_EVENT_*`` to all registered slave driver notifiers::
>> +
>> +    ALERT# asserted by target
>> +          |
>> +          v
>> +    hard-IRQ handler (controller driver)
>> +          |
>> +          v
>> +    threaded IRQ / workqueue
>> +          |
>> +          v
>> +    espi_handle_alert(ctrl)          [espi-core.c]
>> +          |
>> +          v
>> +    ops->handle_alert(ctrl)          [controller driver]
>> +          | reads GET_STATUS, decodes channel
>> +          v
>> +    espi_notify_event(ctrl, &event)  [espi-slave.c]
>> +          |
>> +          v
>> +    slave driver notifier callback
>> +
>> +espi_handle_alert() must always be called from process context; it must
>> +never be called from a hard-IRQ handler.
>> +
>> +Events and concurrency
>> +======================
>> +
>> +Hardware events (Virtual Wire changes, OOB messages, Peripheral channel
>> +completions, channel state changes) are delivered through a per-controller
>> +blocking notifier chain (espi_register_notifier()/espi_notify_event()).
>> +Callbacks run in process context; controllers deliver events from a
>> +threaded IRQ or workqueue, never from hardirq and never while holding the
>> +controller lock.
>> +
>> +API Reference
>> +=============
>> +
>> +.. kernel-doc:: include/linux/espi/espi.h
>> +
> 
> Describe each of these:
> 
> WARNING: ../include/linux/espi/espi.h:176 struct member 'setup' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'cleanup' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'get_configuration' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'set_configuration' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'inband_reset' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'get_status' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'enable_channel' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'disable_channel' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'periph_io_read' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'periph_io_write' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'periph_mem_read' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'periph_mem_write' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'vwire_get' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'vwire_put' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'oob_send' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'oob_recv' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'flash_read' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'flash_write' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'flash_erase' not described in 'espi_controller_ops'
> WARNING: ../include/linux/espi/espi.h:176 struct member 'handle_alert' not described in 'espi_controller_ops'
> 
> 
> or don't use "/**" for that struct's comment header.

Noted. Will add descriptions for all struct espi_controller_ops members 
in v2.

Thanks,
Krishna
> 
>> +.. kernel-doc:: drivers/espi/espi-slave.c
>> +   :export:
> 
>