diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 0bbfc6a..7de82df 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -24,4 +24,5 @@ - [HID EC Interface](specs/ec_interface/hid/README.md) - [HID Time and Alarm](specs/ec_interface/hid/HUTRR120-SystemWakeTimerAndRTC.md) - [HID Battery](specs/ec_interface/hid/HUTRR-DRAFT-Battery.md) + - [HID over eSPI PCC](specs/ec_interface/hid/hid_over_espi_pcc.md) - [eSPI PCC Specification](specs/ec_interface/espi/espi_pcc_draft.md) diff --git a/docs/src/specs/ec_interface/espi/espi_pcc_draft.md b/docs/src/specs/ec_interface/espi/espi_pcc_draft.md index 3cec54e..ae68109 100644 --- a/docs/src/specs/ec_interface/espi/espi_pcc_draft.md +++ b/docs/src/specs/ec_interface/espi/espi_pcc_draft.md @@ -4,9 +4,11 @@ The purpose of this document is to propose an update for the eSPI hardware interface that allows a more efficient and common interface to various eSPI hardware on x86 and ARM designs. -## Current ACPI EC eSPI Interface +## Legacy eSPI Communication -The current ACPI design is implemented with 3 I/O ports and two interrupt signals as defined below. +### Current ACPI EC Interface + +The current ACPI design exposes three register roles through two I/O port addresses, together with SCI and SMI signaling, as defined below. [12. ACPI Embedded Controller Interface Specification — ACPI Specification 6.5 documentation](https://uefi.org/specs/ACPI/6.5/12_Embedded_Controller_Interface_Specification.html) @@ -41,7 +43,7 @@ The current ACPI design is implemented with 3 I/O ports and two interrupt signal | BD_EC | 0x83 | | QR_EC | 0x84 | -## EC Operations +### EC Operations ### EC Write Flow @@ -74,6 +76,111 @@ The current ACPI design is implemented with 3 I/O ports and two interrupt signal > **Note:** The OEM defines the meaning of each event code and its corresponding **\_QXX** method. +### Legacy Architecture + +The operating system sees the legacy `EC_SC`/`EC_CMD` and `EC_DATA` I/O-port interface, normally at ports `0x66` and `0x62`. On an eSPI system, the host controller converts these I/O accesses into eSPI Peripheral Channel transactions. Battery, thermal, lid, button, and OEM-defined operations all share the same command/data mailbox and are globally serialized by the ACPI EC driver. + +```mermaid +flowchart LR + subgraph Host["Host / x86"] + BAT["Battery AML"] + THM["Thermal AML"] + LID["Lid / Button AML"] + OEM["OEM AML"] + DRV["ACPI EC Driver
Global transaction serialization"] + PORTS["Legacy EC I/O Ports
0x66: Command / Status
0x62: Data"] + + BAT --> DRV + THM --> DRV + LID --> DRV + OEM --> DRV + DRV --> PORTS + end + + subgraph PCH["PCH / SoC"] + DECODE["Legacy I/O Decode"] + ESPI["eSPI Controller"] + VWMAP["VWire to SCI/GPE Mapping"] + end + + subgraph EC["Embedded Controller"] + HIF["Legacy Host Interface
IBF / OBF / SCI_EVT"] + PARSER["Single Command Parser"] + ERAM["OEM EC RAM Map"] + TASKS["Battery / Thermal / Lid / OEM Tasks"] + EVENTS["Internal Event Queue"] + + HIF --> PARSER + PARSER --> ERAM + PARSER --> TASKS + TASKS --> EVENTS + EVENTS --> HIF + end + + PORTS --> DECODE + DECODE --> ESPI + ESPI -->|"eSPI Peripheral Channel
I/O read/write cycles"| HIF + HIF -->|"SCI VWire"| VWMAP + VWMAP -->|"SCI / GPE"| DRV +``` + +### Legacy Read Transaction + +```mermaid +sequenceDiagram + participant AML as ACPI AML + participant Driver as ACPI EC Driver + participant PCH as PCH eSPI Controller + participant EC as EC Host Interface + participant Subsystem as EC Subsystem + + AML->>Driver: Read EC field at address A + Driver->>Driver: Acquire global EC transaction lock + Driver->>EC: Poll EC_SC.IBF until clear + Driver->>PCH: OUT 0x66, RD_EC (0x80) + PCH->>EC: eSPI Peripheral I/O write + EC->>EC: Consume command and clear IBF + Driver->>EC: Poll EC_SC.IBF until clear + Driver->>PCH: OUT 0x62, address A + PCH->>EC: eSPI Peripheral I/O write + EC->>Subsystem: Read OEM-defined value at A + Subsystem-->>EC: Return one byte + EC->>EC: Place byte in output buffer and set OBF + Driver->>EC: Poll EC_SC.OBF until set + Driver->>PCH: IN 0x62 + PCH->>EC: eSPI Peripheral I/O read + EC-->>PCH: Return data byte + PCH-->>Driver: Complete IN instruction + Driver->>Driver: Release global EC transaction lock + Driver-->>AML: Return field value +``` + +### Legacy Unsolicited Event + +```mermaid +sequenceDiagram + participant Subsystem as EC Subsystem + participant EC as EC Host Interface + participant PCH as PCH / eSPI + participant Driver as ACPI EC Driver + participant AML as ACPI _Qxx Method + + Subsystem->>EC: Queue event code XX + EC->>EC: Set SCI_EVT + EC->>PCH: Assert SCI VWire + PCH->>Driver: Raise SCI / GPE + Driver->>EC: Write QR_EC (0x84) through 0x66 + EC-->>Driver: Return event code XX through 0x62 + Driver->>AML: Evaluate _QXX +``` + +The legacy transport has the following properties: + +- All EC subsystems share one command register and one data register. +- OEM-defined EC RAM ranges separate subsystem data logically, but do not provide independent transport ownership or concurrency. +- Reads and writes are byte-oriented and require repeated `IBF`/`OBF` handshakes. +- The EC queues unsolicited events internally, and the host retrieves them one at a time with `QR_EC`. + ## eSPI Features to Address The following is a list of issues with the current ACPI eSPI EC definition that we are seeking to address: @@ -137,7 +244,7 @@ On existing platforms recommendation is to use an I/O port for each of these. Ea ### Global Reset Register -Optional, an MMIO or I/O port register and mask that can be written to that traps into FW to initiate an in-band reset and reconfigures the eSPI config space back to defaults. Any pending transactions are lost, and the controller is in a fresh state. +Optional, an MMIO or I/O port register and mask that can be written to that traps into FW to initiate an in-band reset and reconfigures the eSPI config space back to defaults. Any pending transactions are lost, and the controller is in a fresh state. Generation changes and stale-message handling remain an [open question](#reset-and-stale-message-handling). ### VWire Channel @@ -151,11 +258,15 @@ Optional support for GPIO expansion via index 128-255 can be defined as well. Th ### Peripheral Channel -There can be multiple sub-channels exposed via a single peripheral channel. Each sub-channel must have a corresponding PCC table defining the channel details and the address of the MMIO region. For packet-based communication there must be two PCC tables defined: +There can be multiple logical sub-channels exposed over the single physical eSPI Peripheral Channel. Each logical sub-channel has a corresponding PCCT subspace that defines the channel details and shared-memory region. + +For a logical function that supports both host-initiated commands and platform-initiated notifications, define a Type 3/Type 4 pair: -**Type 3** – Initiator table to describe all the communication from the host to the device. +**Type 3** - An Initiator subspace. OSPM initiates the transaction by writing a request and ringing the doorbell. The platform may write the corresponding response into the same shared-memory region before setting Command Complete. -**Type 4** – Responder table to describe all the communication from the device to the host. +**Type 4** - A Responder subspace. The platform initiates an unsolicited notification, raises the Platform Interrupt, and waits for OSPM to acknowledge and release the region. + +A Type 3/Type 4 pair is a logical resource allocation, not an additional physical eSPI channel. A platform should allocate dedicated pairs where latency, isolation, independent reset, or security requires them. It is not necessary to allocate a pair to every EC subsystem. Related low-rate functions may share a logical pair or continue using the legacy EC or Type 0 interface. For legacy flat mapped memory space which just uses direct memory updates and is not packet based, this region can be directly accessed as MMIO or SystemMemory. Type 0 PCC region may also be used to describe the memory if a doorbell mechanism or more signaling is required. @@ -177,6 +288,8 @@ The sample separates the namespace device definition from the PCCT subspace reco | PCC Type 3 shared memory | 0xFEDC2000 | 0x400 | 1024-byte extended master subspace for OS-initiated bidirectional peripheral traffic. | | PCC Type 4 shared memory | 0xFEDC2400 | 0x400 | 1024-byte extended slave subspace for platform-initiated bidirectional peripheral traffic. | +The 1024-byte shared-memory sizes are illustrative. Supported region and message sizes depend on the resolution of [PCC Region Size versus eSPI Maximum Payload Size](#pcc-region-size-versus-espi-maximum-payload-size). + ### Sample SSDT Namespace Definition DefinitionBlock ("", "SSDT", 2, "OEMID", "ESPIPCC", 0x00000001) @@ -252,7 +365,7 @@ PCCT.Flags = 1  // Platform interrupt supported // Subspace ID 0: Extended PCC Master (Type 3) Type = 3 Length = sizeof (TYPE3_SUBSPACE) -PlatformInterrupt = \ +PlatformInterrupt = \
InterruptFlags = \ BaseAddress = 0x00000000FEDC2000 AddressLength = 0x0000000000000400  // 1024 bytes @@ -268,7 +381,7 @@ ErrorStatusMask = 0x00000002 // Subspace ID 1: Extended PCC Slave (Type 4) Type = 4 Length = sizeof (TYPE4_SUBSPACE) -PlatformInterrupt = \ +PlatformInterrupt = \
InterruptFlags = \ BaseAddress = 0x00000000FEDC2400 AddressLength = 0x0000000000000400  // 1024 bytes @@ -282,35 +395,374 @@ PlatformAckRegister = GAS(SystemMemory, 32, 0, DWord, 0xFEDC100C) PlatformAckPreserve = 0xFFFFFFFE PlatformAckWrite = 0x00000001 -## Sample PCC Type 3 and Type 4 Call Flows +## Proposed Recommendation + +The transport profiles in this document are function-neutral. Protocol-specific message formats and behavior are defined by separate overlays. HID is one possible use; see [HID over eSPI PCC](../hid/hid_over_espi_pcc.md). + +### Synchronous Type 3 Requests and Responses + +The recommended baseline uses Type 3 as a synchronous, bidirectional request/response subspace. Bidirectional means that the request and response use the same region during different ownership phases; it does not permit the host and platform to write the region concurrently. + +Type 4 is independent and is reserved for unsolicited platform notifications. A normal solicited response is returned through the Type 3 region that carried its request. + +The recommended eSPI implementation delivers each PCC Platform Interrupt with a target-to-controller eSPI Interrupt Event VWire. The host eSPI controller maps the configured VWire IRQ line to the GSI advertised in the PCCT entry. The PCCT interrupt flags must match the mapped interrupt's trigger mode and polarity. + +For a level-triggered interrupt, the PCCT Platform Interrupt Ack register must clear the PCC interrupt source and cause the EC to deassert the VWire. Because eSPI Peripheral and VWire traffic use independent channels, the implementation must ensure that the PCC message and Command Complete state are visible before asserting the VWire. + +```mermaid +flowchart LR + subgraph Host["Host"] + CLIENT["Function Driver"] + T3["Type 3 Shared Region"] + T4["Type 4 Notification Region"] + end + + subgraph EC["Embedded Controller"] + HANDLER["Type 3 Command Handler"] + FUNCTION["EC Function Implementation"] + EVENTQ["Private Notification Queue"] + PUBLISHER["Type 4 Publisher"] + end + + CLIENT -->|"1. Write request
2. Clear complete
3. Ring doorbell"| T3 + T3 -->|"Ownership transfers to EC"| HANDLER + HANDLER --> FUNCTION + FUNCTION --> HANDLER + HANDLER -->|"4. Write response
5. Set complete"| T3 + T3 -->|"6. Interrupt or polling
7. Read response"| CLIENT + + FUNCTION --> EVENTQ + EVENTQ --> PUBLISHER + PUBLISHER -->|"Write notification
Raise Platform Interrupt"| T4 + T4 -->|"Read and acknowledge"| CLIENT +``` + +The function driver submits one command and receives one result. Ownership transfer, memory ordering, interrupt delivery, and notification flow control are handled by the PCC transport implementation. Support for messages larger than one eSPI payload remains an [open question](#pcc-region-size-versus-espi-maximum-payload-size). + +### Synchronous Type 3 Transaction + +```mermaid +sequenceDiagram + participant Host as Host Driver + participant T3 as Type 3 Shared Region + participant EC as EC Command Handler + participant Function as EC Function + + Host->>T3: Check Command Complete = 1 + Note over Host,T3: Host owns the available region + Host->>T3: Write command and request payload + Host->>T3: Clear Command Complete + Host->>Host: Ensure request writes are visible + Note over Host,T3: Ownership transfers to EC + Host->>EC: Ring Type 3 doorbell + EC->>T3: Read request + EC->>Function: Execute operation + Function-->>EC: Return status and response data + EC->>T3: Write response into the same region + EC->>EC: Ensure response writes are visible + EC->>T3: Set Command Complete + Note over Host,T3: Ownership transfers back to host + EC-->>Host: Optional Type 3 Platform Interrupt + Host->>T3: Read response +``` + +For this profile, Type 3 Command Complete means that the requested operation has completed and the response is available. Only one Type 3 transaction is outstanding on a subspace, so a transaction identifier is not required. Timeout, error reporting, retry, and recovery behavior remain an [open question](#timeout-and-error-semantics). + +### Independent Type 4 Notification + +Type 4 carries platform-initiated traffic such as input events, GPIO events, sensor notifications, or function-specific state changes. It may operate while a Type 3 command is in progress. + +```mermaid +sequenceDiagram + participant Host as Host Driver + participant T3 as Type 3 + participant EC as EC + participant T4 as Type 4 + + Host->>T3: Submit request + T3->>EC: Doorbell + + par Process synchronous command + EC->>EC: Execute operation + EC->>T3: Write response and set complete + T3-->>Host: Optional completion interrupt + Host->>T3: Read response + and Publish unsolicited notification + EC->>T4: Wait for Type 4 availability + EC->>T4: Write notification and clear complete + T4-->>Host: Platform Interrupt + Host->>T4: Read notification + Host->>T4: Set complete and acknowledge interrupt + end +``` + +The platform must queue notifications internally while Type 4 is owned by OSPM. It must not overwrite an unacknowledged notification. Queue depth, overflow, ordering, and coalescing behavior remain an [open question](#notification-queue-semantics). + +### Logical Sub-channel Allocation + +The recommended design does not require one pair for every EC subsystem. It recommends dedicated pairs for functions whose latency, isolation, security, or independent reset requirements justify them. For example, a latency-sensitive input function can use a dedicated pair while battery, thermal, and fan functions share a generic EC pair or continue to use the legacy interface. + +```mermaid +flowchart TB + subgraph Host["Host Drivers"] + GH["Generic EC Driver"] + LH["Latency-sensitive Driver"] + end + + subgraph PCC["Logical PCC Sub-channels over one eSPI Peripheral Channel"] + G3["Generic EC Type 3"] + G4["Generic EC Type 4"] + L3["Dedicated Type 3"] + L4["Dedicated Type 4"] + end + + subgraph EC["EC Functions"] + GE["Battery / Thermal / Fan"] + LE["Latency-sensitive Function"] + end + + GH --> G3 --> GE + GE --> G4 --> GH + + LH --> L3 --> LE + LE --> L4 --> LH +``` + +Each pair consumes two PCCT subspaces, two shared-memory windows, Command Complete and doorbell state, and Type 4 interrupt-acknowledgment state. It does not consume another physical eSPI channel. Level-triggered Platform Interrupts may be shared when each subspace has a unique status and acknowledgment mask. The cost and availability of these resources on existing hardware remain an [open question](#pcc-resource-cost-and-in-market-device-capabilities). + +The sample 1024-byte Type 3 and Type 4 regions require 2048 bytes of addressable storage for one pair. A 512-byte-per-region profile may be used where memory is constrained. The selected region size and maximum message size must be advertised to software and must follow the resolution of [PCC Region Size versus eSPI Maximum Payload Size](#pcc-region-size-versus-espi-maximum-payload-size). + +### Shared-Pair Specialization + +A resource-constrained platform may specialize the recommended design by multiplexing multiple EC functions through one Type 3/Type 4 pair. The transport semantics remain unchanged: + +- Type 3 contains a synchronous request and its solicited response. +- Type 3 Command Complete means that the operation and response are complete. +- Type 4 contains unsolicited platform notifications. + +Only the logical allocation changes. The shared payload format must identify the target function and command namespace, and the host requires an EC PCC bus driver that dispatches requests and notifications to function-specific clients. + +```mermaid +flowchart LR + subgraph Host["Host"] + BUS["EC PCC Bus Driver"] + BAT["Battery Client"] + INPUT["Input Client"] + THM["Thermal Client"] + BAT --> BUS + INPUT --> BUS + THM --> BUS + end + + subgraph PCC["Recommended Synchronous Transport
Shared-Pair Specialization"] + T3["Shared Type 3
Request and Response"] + T4["Shared Type 4
Unsolicited Notifications"] + end + + subgraph EC["Embedded Controller"] + DISPATCH["Function Dispatcher"] + SCHED["Priority and Fairness Policy"] + FUNCTIONS["Battery / Input / Thermal Functions"] + DISPATCH --> SCHED --> FUNCTIONS + end + + BUS --> T3 --> DISPATCH + FUNCTIONS --> T4 --> BUS +``` + +This specialization reduces PCCT entries, shared-memory windows, and interrupt state, but all participating functions share the same Type 3 ownership token and Type 4 notification slot. The implementation must define scheduling priorities, quotas, and starvation prevention. A slow operation blocks other Type 3 users until its synchronous response is complete, so a latency-sensitive function may still require a dedicated pair. + +### Recommended Completion Semantics -PCC communication uses independent subspaces, shared memory, a doorbell protocol, platform notification, and completion/status registers. The following sample maps those mechanisms to the document’s Type 3 **PCC3** initiator channel and Type 4 **PCC4** platform-notification channel. +| Operation | Recommended behavior | +|---|---| +| Short read or query | Synchronous Type 3 request and response | +| Short write with status | Synchronous Type 3 request and response | +| Fire-and-forget write | Type 3 completes after the platform has safely consumed the data | +| Unsolicited platform event | Type 4 notification | +| Long-running operation, such as flash erase or image validation | Prefer a separate asynchronous command defined by the function protocol; see alternatives below | -CCC = Command Complete Check register +## Other Design Alternatives -### Initiator/Responder Call Flow: Host 🡪 eSPI Device +### Decoupled Type 3 Requests and Type 4 Responses + +In the decoupled model, Type 3 Command Complete means only that the platform validated and copied the request. The final solicited response is later published through Type 4. This permits the Type 3 region to be released before a long-running operation, such as flash erase, image validation, or delayed readiness, finishes, but it changes the transport interface from synchronous completion to asynchronous acceptance and completion. + +Because solicited responses and unsolicited notifications share Type 4 in this model, every Type 4 message requires an explicit message class and transaction identifier: + +| Type 4 message | Message class | Transaction identifier | +|---|---|---| +| Solicited response | Response | Copied from the corresponding Type 3 request | +| Unsolicited notification | Notification | Reserved notification value; no Type 3 request is referenced | + +The message class distinguishes the two flows without relying on whether a transaction identifier happens to match an outstanding request. A transaction identifier must not be reused while its request is pending. + +Because Type 3 Command Complete reports acceptance in this profile, a failure discovered after acceptance must be returned as an in-band status in the matching Type 4 Response. The Type 3 ACPI Error Status cannot report the final result after the Type 3 subspace has been released. + +```mermaid +flowchart LR + subgraph Host["Host"] + CLIENT["Function Driver"] + REQ["Type 3 Request Region"] + MSG["Type 4 Response / Notification Region"] + PENDING["Outstanding Transaction Table"] + + CLIENT --> REQ + CLIENT --> PENDING + MSG --> CLIENT + end + + subgraph EC["Embedded Controller"] + INTAKE["Type 3 Doorbell Handler"] + REQQ["Private Request Queue"] + WORKERS["Function Workers"] + MSGQ["Response / Notification Queue"] + PUB["Type 4 Publisher"] + + INTAKE -->|"Copy request"| REQQ + REQQ --> WORKERS + WORKERS --> MSGQ + MSGQ --> PUB + end + + REQ -->|"Doorbell"| INTAKE + INTAKE -->|"Set Type 3 complete
after copying"| REQ + PUB -->|"Write response or event"| MSG + PUB -->|"Platform Interrupt"| CLIENT + CLIENT -->|"Set Type 4 complete"| PUB +``` + +```mermaid +sequenceDiagram + participant Host as Host Driver + participant T3 as Type 3 Region + participant Intake as EC Doorbell Handler + participant Worker as EC Function Worker + participant T4 as Type 4 Region + + Host->>T3: Write request A, transaction 41 + Host->>T3: Clear Command Complete + Host->>Intake: Ring Type 3 doorbell + Intake->>T3: Read and copy request A + Intake->>Intake: Enqueue request A + Intake->>T3: Set Command Complete + + Note over Host,T3: Type 3 is available before request A finishes + + Host->>T3: Write request B, transaction 42 + Host->>Intake: Ring Type 3 doorbell + Intake->>T3: Copy request B and set complete + + Worker->>Worker: Process B quickly + Worker->>T4: Publish response B, transaction 42 + T4-->>Host: Platform Interrupt + Host->>T4: Read and correlate response 42 + Host->>T4: Set Command Complete + + Worker->>Worker: Finish request A + Worker->>T4: Publish response A, transaction 41 + T4-->>Host: Platform Interrupt + Host->>T4: Read and correlate response 41 + Host->>T4: Set Command Complete +``` + +This alternative requires message classes, transaction identifiers, request and response queues, queue-full behavior, acceptance and final-result timeouts, cancellation, reset generation handling, and response/notification scheduling. The unresolved correlation and cancellation rules are tracked under [Decoupled Request Lifecycle](#decoupled-request-lifecycle); generic queue, reset, timeout, and error rules are tracked in the corresponding open questions. This profile is appropriate when operations are long-running and concurrent acceptance provides measurable benefit. It should not be the default completion model for short commands. + +### Type 3-Only Interrupt-and-Pull + +Resource-constrained systems may omit Type 4. This profile uses a Type 3 subspace plus a dedicated notification interrupt. When the platform queues an unsolicited event, it asserts the notification interrupt, and OSPM issues a Type 3 request to retrieve the event. + +The notification interrupt is separate from the Type 3 command-completion indication. A platform can implement it with a dedicated eSPI Interrupt Event VWire that the host eSPI controller maps to a GSI. The notification GSI and its trigger and polarity configuration must be advertised to the consuming driver through the platform's ACPI device description. Its availability as a wake source depends on the transport's [power-state and wake behavior](#power-state-and-wake-behavior). ```mermaid sequenceDiagram - participant OSPM - participant EC as eSPI Controller / EC + participant Function as EC Function + participant EC as EC Transport + participant Host as Host Driver + participant T3 as Type 3 Region + + Function->>EC: Queue unsolicited event + EC-->>Host: Assert dedicated notification VWire/GSI + Host->>T3: Submit GET_PENDING_NOTIFICATION + T3->>EC: Doorbell + EC->>T3: Write next event and set complete + Host->>T3: Read event + EC-->>Host: Deassert notification VWire when queue is empty +``` + +For a level-triggered notification, the platform keeps the interrupt asserted while one or more events remain queued and deasserts it only after the host drains the queue. The binding must define acknowledgment behavior for other trigger modes. This profile saves one shared-memory region and the Type 4 acknowledgment state, but adds an interrupt-to-request-to-response round trip for every event. It is suitable for low-rate events, not high-rate input or sensor data. + +The response to `GET_PENDING_NOTIFICATION` requires an event-type discriminator so the function driver can interpret the returned payload. Event framing, queue arbitration, and interrupt behavior are tracked under [Type 3-Only Notification Retrieval](#type-3-only-notification-retrieval). + +### Design Comparison + +| Property | Legacy ACPI EC | Recommended synchronous PCC | Decoupled PCC | +|---|---|---|---| +| Request path | Ports `0x62`/`0x66` | Type 3 | Type 3 | +| Solicited response path | Legacy data register | Same Type 3 region | Type 4 | +| Unsolicited event path | SCI plus `QR_EC` | Type 4 | Type 4 | +| Completion meaning | Byte/transaction consumed | Operation and response complete | Request copied/accepted | +| Transaction ID required | No | No for one outstanding request | Yes | +| Blocking scope | All EC users | One logical sub-channel or all functions in the shared-pair specialization | Request intake only; Type 4 may still block | +| EC private queues | Event queue | Notification queue | Request and response queues | +| Host complexity | Legacy EC state machine | Synchronous command plus notification handler; shared specialization adds dispatch and fairness | Correlation and pending-request state | + +## Open Questions + +### PCC Region Size versus eSPI Maximum Payload Size + +Can the hardware expose a PCC region larger than the negotiated 64-, 128-, or 256-byte eSPI Maximum Payload Size and transfer the complete message through ordered transactions before signaling the doorbell, Command Complete, or Platform Interrupt? + +The profile must select one of these approaches: + +- Limit the PCC message and region size to the negotiated eSPI Maximum Payload Size. +- Define which protocol layer fragments and reassembles larger messages, which message classes may use it, and its ordering and error rules. +- Add a controller-managed staging or DMA mechanism with an explicit whole-message completion indication. + +### PCC Resource Cost and In-Market Device Capabilities + +Can in-market ECs and eSPI controllers expose a Type 3/Type 4 pair, including two shared-memory windows, signaling state, and a Type 4 interrupt acknowledgment path, without hardware changes? + +The specification must determine the typical SRAM and controller-resource cost, identify capabilities that software can discover, and define a compatible profile for devices that support only one region or the legacy interface. + +### Notification Queue Semantics + +Which notifications require lossless delivery, which may be coalesced or dropped, and what minimum queue depth is required while Type 4 is unavailable? + +The specification must define ordering, overflow indication and recovery, interrupt assertion and acknowledgment, and whether these rules are transport-wide or selected by each function overlay. + +### Reset and Stale Message Handling + +How are in-flight requests, responses, and notifications invalidated across a transport, controller, or function reset? + +The specification must define how software detects a new transport generation, when ownership returns to its initial state, and how both endpoints discard stale data from the previous generation. + +### Power-State and Wake Behavior + +Which PCC regions, doorbells, and interrupt paths remain available in each ACPI power state, and which notification GSIs can wake the system? + +The specification must define how transport availability and wake capability are advertised, including the required ordering between wake signaling and shared-memory visibility. + +### Timeout and Error Semantics + +What timeout applies to ownership acquisition, request completion, notification acknowledgment, and any asynchronous final response? + +The specification must define where each error is reported, which endpoint performs recovery, and when retry is safe or requires an idempotent operation. + +### Decoupled Request Lifecycle + +How does the decoupled profile allocate and reuse transaction identifiers, cancel accepted requests, and reject late responses from a previous reset generation? + +The specification must define identifier width and exhaustion behavior, cancellation races, response handling after timeout, and the relationship between acceptance timeout, final-result timeout, and transport reset. - OSPM->>EC: Wait PCC3 complete - OSPM->>EC: Clear PCC3 complete - OSPM->>EC: Write header + request - OSPM->>EC: Memory barrier - OSPM->>EC: Trigger Doorbell +### Type 3-Only Notification Retrieval - Note right of EC: Read PCC3 request +How are queued notifications framed and arbitrated when both event retrieval and ordinary commands use the same Type 3 subspace? - EC-->>OSPM: Set PCC3 complete - EC-->>OSPM: Wait PCC4 complete - EC-->>OSPM: Clear PCC4 complete - EC-->>OSPM: Write Header + Response - EC-->>OSPM: Trigger VWire/Interrupt +The specification must define the event-type discriminator, retrieval ordering, queue overflow behavior, interrupt acknowledgment or deassertion, and fairness between `GET_PENDING_NOTIFICATION` and ordinary requests. - Note left of OSPM: Notification PCC4 - Note left of OSPM: Process PCC4 response +## References - OSPM->>EC: Set PCC4 complete -``` \ No newline at end of file +- [ACPI 6.6, Chapter 14: Platform Communications Channel](https://uefi.org/specs/ACPI/6.6/14_Platform_Communications_Channel.html) +- [ACPI 6.5, Chapter 12: Embedded Controller Interface](https://uefi.org/specs/ACPI/6.5/12_Embedded_Controller_Interface_Specification.html) +- [eSPI Base Specification](https://www.intel.com/content/www/us/en/content-details/841852/enhanced-serial-peripheral-interface-espi-interface-base-specification-for-client-and-server-platforms.html) \ No newline at end of file diff --git a/docs/src/specs/ec_interface/hid/hid_over_espi_pcc.md b/docs/src/specs/ec_interface/hid/hid_over_espi_pcc.md new file mode 100644 index 0000000..3fc8904 --- /dev/null +++ b/docs/src/specs/ec_interface/hid/hid_over_espi_pcc.md @@ -0,0 +1,107 @@ +# HID over eSPI PCC + +## Scope + +This document defines a possible HID protocol overlay on the function-neutral [eSPI PCC transport](../espi/espi_pcc_draft.md). It maps HID operations onto the transport profiles defined by that specification without changing their ownership, signaling, or completion semantics. + +The eSPI PCC specification remains authoritative for: + +- Type 3 and Type 4 ownership and completion. +- Shared-memory and PCCT layout. +- VWire-to-GSI interrupt mapping. +- Logical sub-channel allocation. +- Payload-size, ordering, and hardware-resource requirements. + +This overlay defines only HID-specific message mapping and binding requirements. Generic PCC transport questions are tracked in the base specification. + +## HID Payload + +The PCC payload requires a HID header that identifies the HID message or command type, Report Type, Report ID, and payload length. Responses may also carry HID operation status distinct from transport-level PCC errors. The exact HID field layout and command values remain to be defined. + +Descriptor and large Feature Report transfer depends on the resolution of [PCC Region Size versus eSPI Maximum Payload Size](../espi/espi_pcc_draft.md#pcc-region-size-versus-espi-maximum-payload-size). + +## Recommended Synchronous Profile + +The recommended mapping uses synchronous Type 3 for HID requests and responses and independent Type 4 for unsolicited Input and Wake notifications. + +| HID operation | Type 3 request and response | Type 4 notification | +|---|---|---| +| Device and Report Descriptor discovery | Host requests a descriptor; EC returns it in the same Type 3 region | None | +| Get Input Report or Get Feature Report | Host supplies Report Type and Report ID; EC returns the current report | None | +| Set Output Report or Set Feature Report | Host supplies Report Type, Report ID, and report data; EC returns status | None | +| Input Report | None | EC publishes Report ID and report data | +| Reset | Host requests a logical HID reset and waits for completion | Optional device-initiated reset indication | +| Set Power ON, SLEEP, or OFF | Host sends the requested state; Command Complete provides transport completion | None | +| Wake | None | EC publishes a Wake notification while the device is in SLEEP | +| Get/Set Idle or Get/Set Protocol | Optional Type 3 commands for USB boot-device compatibility | None | + +### HID Binding Requirements + +The base transport specification tracks the generic [notification queue](../espi/espi_pcc_draft.md#notification-queue-semantics), [reset](../espi/espi_pcc_draft.md#reset-and-stale-message-handling), [power and wake](../espi/espi_pcc_draft.md#power-state-and-wake-behavior), and [timeout and error](../espi/espi_pcc_draft.md#timeout-and-error-semantics) questions. After those contracts are defined, the HID binding must: + +- Classify which HID reports require lossless delivery and which may be coalesced. +- Define HID descriptor, report, and protocol state after a transport-generation change. +- Map HID ON, SLEEP, OFF, and Wake behavior onto the transport's ACPI power-state and wake rules. +- Map HID operation failures and any operation-specific timeout requirements onto the transport status and recovery model. + +### Shared-Pair Specialization + +The Shared-Pair Specialization uses the same HID mapping but requires a Function ID in every request and notification. HID shares the Type 3 ownership token and Type 4 notification slot with other EC functions, creating head-of-line blocking and notification-scheduling risks. A latency-sensitive HID function may therefore require a dedicated pair. + +## Component Firmware Update + +HID firmware update should use the Microsoft Component Firmware Update (CFU) protocol rather than define a PCC-specific firmware-update command. The overlay transports CFU reports without redefining firmware-version discovery, offer and acceptance handling, component and segment identifiers, host tokens, content sequence numbers, per-block status, image validation results, or busy/readiness behavior. + +In the recommended synchronous profile, CFU Get Feature, Output Report, and associated response exchanges use Type 3. CFU content blocks are individually acknowledged; a firmware image is not represented as one long-running PCC transaction. + +The CFU `OFFER_NOTIFY_ON_READY` response may be delayed, but remains a solicited response. The synchronous profile therefore keeps Type 3 occupied until that response arrives. If delayed readiness must release Type 3, the decoupled profile carries it as a Type 4 Response with a transport transaction ID, not as an unsolicited Notification. + +CFU does not resolve the PCC transport questions. The binding must still define how each CFU HID report is encoded in the PCC HID payload. Whether a CFU report plus PCC framing fits in one transfer depends on [PCC Region Size versus eSPI Maximum Payload Size](../espi/espi_pcc_draft.md#pcc-region-size-versus-espi-maximum-payload-size). + +## Decoupled Type 3 and Type 4 Profile + +In the [decoupled profile](../espi/espi_pcc_draft.md#decoupled-type-3-requests-and-type-4-responses), Type 3 reports request acceptance while solicited responses and unsolicited notifications share Type 4. + +| HID operation | Type 3 path | Type 4 path | +|---|---|---| +| Descriptor discovery and Get Report | Request is accepted and assigned a transaction ID | Response carries the matching transaction ID and returned data | +| Set Report, Output Report, Reset, or Set Power | Request is accepted and assigned a transaction ID | Response carries final status when the operation completes | +| Input Report or Wake | None | Notification uses the Notification message class and reserved transaction-ID value | +| CFU HID report | Request acceptance releases Type 3 before processing finishes | Response uses the original transport transaction ID; CFU tokens and sequence numbers remain part of the CFU payload | + +### HID Binding Requirements + +The generic decoupled request lifecycle, timeout, error, reset, and Type 4 scheduling rules belong to the [base transport specification](../espi/espi_pcc_draft.md#decoupled-request-lifecycle). The HID binding must define only how HID semantics use those rules: + +- SLEEP and OFF operations need an explicit terminal-acceptance rule if no later HID Response is expected. +- CFU tokens and content sequence numbers must not replace the decoupled transport transaction ID. +- The binding must identify which HID operations may use decoupled completion instead of the recommended synchronous profile. + +## Type 3-Only Interrupt-and-Pull Profile + +The [Type 3-only profile](../espi/espi_pcc_draft.md#type-3-only-interrupt-and-pull) consists of a Type 3 subspace plus a dedicated notification interrupt. The notification interrupt is separate from Type 3 command completion and can be implemented with a dedicated eSPI Interrupt Event VWire mapped by the host controller to a GSI. The EC asserts it when a HID event is pending, and the host retrieves the event with a Type 3 request. + +| HID operation | Type 3 path | Event indication | +|---|---|---| +| Descriptor discovery, Get/Set Report, Reset, or Set Power | Synchronous request and response, as in the recommended profile | None | +| Input Report | Host sends `GET_PENDING_NOTIFICATION`; EC returns the next Input Report | EC asserts the dedicated notification VWire/GSI | +| Wake | Host sends `GET_PENDING_NOTIFICATION`; EC returns a Wake event | EC asserts the dedicated notification VWire/GSI | +| CFU HID report | Each CFU report uses a synchronous Type 3 request and response | Pending HID input cannot be retrieved while a CFU report occupies Type 3 | + +This profile resembles HID over I2C's interrupt followed by an Input Register read. + +### HID Binding Requirements + +The dedicated interrupt, ACPI advertisement, queue, event framing, and Type 3 arbitration rules belong to the [base transport specification](../espi/espi_pcc_draft.md#type-3-only-notification-retrieval). The HID binding must: + +- Assign HID event-type values for Input Report, Wake, and device-reset notifications. +- Define the HID payload returned by `GET_PENDING_NOTIFICATION`, including its event type, Report ID, and report data. + +The additional request/response round trip and single Type 3 ownership token make this profile unsuitable for high-rate touch, pen, or precision-touchpad traffic. + +## References + +- [eSPI PCC Specification](../espi/espi_pcc_draft.md) +- [USB Device Class Definition for Human Interface Devices, Version 1.11](https://www.usb.org/sites/default/files/hid1_11.pdf) +- [Microsoft HID over I2C Protocol Specification, Version 1.0](https://download.microsoft.com/download/7/D/D/7DD44BB7-2A7A-4505-AC1C-7227D3D96D5B/hid-over-i2c-protocol-spec-v1-0.docx) +- [Microsoft Component Firmware Update Protocol Specification](https://learn.microsoft.com/en-us/windows-hardware/drivers/cfu/cfu-specification)