Restructured the EC spec to include HID

[philgweber]

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.