Restructured the EC spec to include HID by philgweber · Pull Request #41 · OpenDevicePartnership/odp-embedded-controller

philgweber · 2026-08-28T19:03:20Z

Updated overview documents and added structure for Legacy, FFA and HID support.

Copilot

Pull request overview

This PR restructures the Embedded Controller (EC) interface specification documentation to explicitly separate Legacy ACPI, FF-A (secure-world) ACPI flows, and direct HID-based interfaces, adding initial HID usage-table drafts and Waratah descriptor sources.

Changes:

Added a new top-level EC interface spec README with a protocol/stack overview and architecture diagram.
Added new structured spec content under legacy/, ffa/, hid/, and espi/ (including HID HUTRR draft docs and .wara descriptor sources).
Updated several FF-A docs to fix image paths and adjusted headings/formatting; removed the old ec_interface.md stub.

Reviewed changes

Copilot reviewed 12 out of 22 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
docs/src/specs/ec_interface/README.md	New top-level entry point for the restructured EC interface spec (Legacy / FF-A / HID).
docs/src/specs/ec_interface/legacy/README.md	New Legacy ACPI EC background and adoption guidance.
docs/src/specs/ec_interface/hid/README.md	New HID EC interface overview with links to draft HUTRR docs.
docs/src/specs/ec_interface/hid/HUTRR120-SystemWakeTimerAndRTC.md	Added HID usage-table draft for RTC & System Wake Timer.
docs/src/specs/ec_interface/hid/HUTRR-DRAFT-Battery.md	Added HID usage-table draft for Control Method Battery.
docs/src/specs/ec_interface/hid/hid-tad.wara	Added Waratah source for time/alarm (wake timer + RTC) descriptors (currently contains invalid markup/sections).
docs/src/specs/ec_interface/hid/hid-battery.wara	Added Waratah source for Control Method Battery descriptors (currently contains invalid syntax markers).
docs/src/specs/ec_interface/ffa/README.md	Retitled/reformatted FF-A overview and fixed image paths.
docs/src/specs/ec_interface/ffa/ucsi.md	Fixed image paths to shared media directory.
docs/src/specs/ec_interface/ffa/battery.md	Reformatted note block (markdown cleanup).
docs/src/specs/ec_interface/ffa/acpi-sample.md	Fixed image path and caption for notification flow diagram.
docs/src/specs/ec_interface/ffa/time-alarm.md	Added FF-A Time and Alarm service page.
docs/src/specs/ec_interface/ffa/thermal.md	Added FF-A Thermal Zone + Fan service page.
docs/src/specs/ec_interface/ffa/power.md	Added FF-A Power service stub.
docs/src/specs/ec_interface/ffa/oem.md	Added FF-A OEM service stub.
docs/src/specs/ec_interface/ffa/manufacturing.md	Added FF-A Manufacturing service stub.
docs/src/specs/ec_interface/ffa/management.md	Added FF-A firmware management/service discovery documentation.
docs/src/specs/ec_interface/ffa/input.md	Added FF-A input management documentation and example ACPI snippets.
docs/src/specs/ec_interface/ffa/debug.md	Added FF-A debug service documentation and shared-memory example.
docs/src/specs/ec_interface/espi/espi_pcc_draft.md	Added draft proposal for eSPI interface updates based on ACPI PCC.
docs/src/specs/ec_interface/ec_interface.md	Removed old top-level stub page (now replaced by the new structured README).

Suppressed comments (4)

docs/src/specs/ec_interface/hid/hid-battery.wara:525

More trailing *** markers on section headers here will break parsing; remove/convert them consistently throughout the file.

            [[applicationCollection.featureReport.logicalCollection.variableItem]] *** Static
            usage = [0x85, 0x83] # Design Capacity
            logicalValueRange = [-1, 0x7FFFFFFF]

            [[applicationCollection.featureReport.logicalCollection.variableItem]]  *** Static

docs/src/specs/ec_interface/hid/hid-battery.wara:533

More trailing ** Static markers on section headers here are not comments and will break Waratah parsing.

            [[applicationCollection.featureReport.logicalCollection.logicalCollection]] ** Static
            usage = ['Battery System', 'Battery Technology']

              [[applicationCollection.featureReport.logicalCollection.logicalCollection.arrayItem]] ** Static
              usageRange = ['Battery System', 'Primary Battery Technology', 'Secondary Battery Technology']

docs/src/specs/ec_interface/hid/hid-battery.wara:539

Additional trailing ** Static marker here breaks parsing; remove it (and apply the same cleanup to the other headers below that use **/******).

            [[applicationCollection.featureReport.logicalCollection.variableItem]] ** Static
            usage = [0x84, 0x40] # Config Voltage / ACPI Design Voltage
            logicalValueRange = [-1, 0x7FFFFFFF]

            [[applicationCollection.featureReport.logicalCollection.variableItem]] ** Static

docs/src/specs/ec_interface/hid/hid-battery.wara:547

More trailing ** / ****** markers on section headers here are not comments and will break parsing; remove them (and apply the same cleanup to the remaining occurrences below).

            [[applicationCollection.featureReport.logicalCollection.variableItem]]  ** Static
            usage = ['Battery System', 'Design Capacity Low']
            logicalValueRange = [0, 0x7FFFFFFF]

            [[applicationCollection.featureReport.logicalCollection.variableItem]]  ****** Dynamic maybe move to Status

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Repair the restructured mdBook navigation and local image links. Clean up the HID descriptor sources so they remain valid Waratah/TOML and correct the reviewed report types and documentation text. Assisted-by: GitHub Copilot:gpt-5.6-sol Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jerrysxie · 2026-08-28T19:54:49Z

+
+An MMIO or I/O port that can be read which returns the global status of the eSPI based on the definition of the eSPI controller.
+
+<img src="espi_media/media/image1.png" style="width:6.5in;height:1.75069in" />


This graphic element is not there.

jerrysxie · 2026-08-28T19:56:41Z

@@ -0,0 +1,679 @@
+Request #:        HUTRR TBD


These looks a bit funky in markdown, is the source MS word document?

Yeah I need to clean this up a bit it was a Word doc originally and did an auto convert. Was just trying to get all the information in here since stuff has been on random SharePoint and spread all over.

jerrysxie · 2026-08-28T20:36:07Z

+| 5 | Wait for completion using the platform interrupt when available; otherwise poll the Type 3 completion bit in **GSTA** using the PCCT nominal latency and maximum access rate. | Read data to local buffer to process and mark as completed. |
+
+#### Type 3 Sequence Summary
+


This is looking malformed. Maybe a mermaid diagram (AI generated) would help here?

sequenceDiagram participant OSPM participant EC as eSPI Controller / EC OSPM->>OSPM: Lock PCC3 OSPM->>EC: Write header and request OSPM->>OSPM: Memory barrier OSPM->>EC: DB00 = 1 activate EC Note over EC: Validate and execute eSPI request EC-->>OSPM: Response in PCC4 EC-->>OSPM: Completion interrupt or status deactivate EC OSPM->>OSPM: Populate and read barrier OSPM->>EC: Clear completion and trigger NP_AVAIL OSPM->>EC: Trigger VWire for host notification

Loading

Is the last 2 transition correct? In flow chat, OSPM is sending VWire to EC, but shouldn't it be the other way around?

jerrysxie · 2026-08-28T20:38:52Z

+#### 
+
+#### Type 4 Sequence Summary
+


Mermaid diagram would help here as well:

sequenceDiagram participant EC as eSPI Controller / EC participant OSPM EC->>EC: Wait for PCC4 to become free EC->>EC: Write header and notification EC->>OSPM: Publish status and interrupt activate OSPM Note over OSPM: Validate and consume PCC4 OSPM-->>EC: AK00 = 1 deactivate OSPM EC->>EC: Clear notification and free PCC4

Loading

Restructured the EC spec to include HID

fe4a8be

philgweber self-assigned this Aug 28, 2026

Copilot AI lite review requested due to automatic review settings August 28, 2026 19:03

philgweber requested a review from a team as a code owner August 28, 2026 19:03

philgweber requested review from kat-perez, kurtjd, maxperga-msft and rogurr August 28, 2026 19:03

Copilot started reviewing on behalf of philgweber August 28, 2026 19:03 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

philgweber requested a review from jerrysxie August 28, 2026 19:37

jerrysxie reviewed Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

Restructured the EC spec to include HID - #41

Restructured the EC spec to include HID#41
philgweber wants to merge 2 commits into
OpenDevicePartnership:mainfrom
philgweber:main

philgweber commented Aug 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jerrysxie Aug 28, 2026

Uh oh!

jerrysxie Aug 28, 2026

Uh oh!

philgweber Aug 28, 2026

Uh oh!

jerrysxie Aug 28, 2026 •

edited

Loading

Uh oh!

jerrysxie Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		An MMIO or I/O port that can be read which returns the global status of the eSPI based on the definition of the eSPI controller.

		<img src="espi_media/media/image1.png" style="width:6.5in;height:1.75069in" />

		\| 5 \| Wait for completion using the platform interrupt when available; otherwise poll the Type 3 completion bit in GSTA using the PCCT nominal latency and maximum access rate. \| Read data to local buffer to process and mark as completed. \|

		#### Type 3 Sequence Summary

Uh oh!

Conversation

philgweber commented Aug 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jerrysxie Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

jerrysxie Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

philgweber Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

jerrysxie Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jerrysxie Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jerrysxie Aug 28, 2026 •

edited

Loading