Repository navigation
HAL Delivery & Versioning Standard Operating Procedure (SOP)
To eliminate ambiguity, every HAL is managed as a self-contained component. All code, documentation, and metadata reside within the same versioned subdirectory. This ensures that the Latest Version is always distinct from Legacy snapshots, allowing vendors to consume code in a stable, production-like environment.
Note on Migration: A full review to the current directory structure is underway to align with this componentised model. All existing HALs will be migrated into this versioned subdirectory format to ensure global consistency across the repository.
We utilize a two-tier numbering scheme based on the maturity of the interface. Metadata files within each folder act as the Single Source of Truth.
| Phase | Versioning | Meaning for Stakeholders |
|---|---|---|
| Development | 0.1, 0.2, 0.3 ... | Active iteration phases. Follows the "14+5" cycle. |
| Formal Release | 1, 2, 3, 4 ... | Production baselines. Follows Google numbering schemes. |
- 🟢 GREEN: Baseline complete. SoC vendors start/continue implementation.
- 🟡 AMBER: Review window active or feedback being integrated. High-priority focus.
- 🔴 RED: Significant issues or foundational drafting. Not ready for external review.
To drive velocity and set simple expectations, all HAL updates move through a strictly time-boxed lifecycle.
- Action: The Pull Request is published to reviewers (SoC Vendors, VTS, RTAB, Architecture, MW), everyone comments directly on the reviews.
- Expectation: All technical feedback must be submitted within 14 calendar days.
- Policy: Silence equals consent. If no feedback is provided within the window, the component moves to Phase B as "accepted."
Immediately following the 14-day review, the component enters a 5-business-day finalization sprint:
- Days 1–3 (Implementation): The HAL Lead triages feedback and implements required changes.
- Day 4 (Sanity Check): The updated component is re-shared for a final 24-hour verification. No new feature requests are permitted.
-
Day 5 (The Merge): The
metadata.yamlis updated to GREEN, the folder is "locked," and the code is merged.
- HAL Lead: Final decision authority on feedback. Drives the 5-day resolution window.
- SoC Vendors: Must provide feasibility feedback during the 14-day window. They consume GREEN baselines as production-ready.
- Middleware (MW) Team: The HAL is the Control Plane. MW must react and adapt to the HAL definition once it reaches AMBER/GREEN status.
- Architecture & RTAB: Ensure high-level system alignment and provide visibility for stakeholders above the engineer level.
- Production Snapshots: The Git repository serves as a live production environment. Vendors can "pin" their builds to a specific version directory to ensure stability.
- Automated Status: The .yaml files allow for an automated dashboard to present the RAG status of the entire HAL suite, providing a clear picture for executive-level management.
- Load Monitoring: Review command load is managed ensuring the feedback loop is driven differently to avoid "too slow" delivery.
This is a "Short-term Pain, Long-term Gain" strategy. To get from a confused state to a high-velocity production model, we need to draw a line in the sand.
We will execute this in two distinct stages: the Review Liquidation (3 weeks) and the Structural Migration (1 week).
Objective: Close all "Zombie" review requests and push as many HALs as possible to a Green (0.x) state.
- Week 1: Triage & Ownership. Assign every outstanding issue to a specific owner
- Week 2: The "Hammer" Week. Force decisions on all pending feedback. If a stakeholder hasn't responded by the end of this week, their input is waived.
- Week 3: Final Resolution. Apply the 5-Day Resolution logic to the entire backlog. Any feedback that isn't implemented now is moved to a future version.
Objective: Physically move the code and documentation into the new self-contained versioned structure.
-
Directory Setup: Create the
0.xsubdirectories for every component. -
Artifact Migration: Move
src/,docs/into their respective versioned folders. -
Metadata Injection: Drop the
metadata.yamlinto every folder. - Baseline Flip: Formally flip the RAG status of the components to Green (0.x).
Once the repo is restructured and the backlog is clear, we present the "New World Order" to the stakeholders.
The Message to Stakeholders: "We have cleared the legacy review backlog. The repository has been restructured for production stability. Moving forward, we are operating on a strict 14+5 day delivery cycle. If it is in a versioned folder and marked Green in the manifest, it is ready for implementation."
Baseline: New Architectural Era (0.100.x)
SoC vendors can behind to implement.
| HAL Component | New Version | Status |
|---|---|---|
| Video Decoder | 0.100.0 | Release Candidate 1, Clear Playback |
| Video Sink | 0.100.0 | Release Candidate 1, Clear Playback |
| Audio Decoder | 0.100.0 | Release Candidate 1, Clear Playback |
| Audio Sink | 0.100.0 | Release Candidate 1, Clear Playback |
| AV Clock | 0.100.0 | Release Candidate 1 |
| HDMI CEC | 0.100.0 | Release Candidate 1 |
| HDMI Input | 0.100.0* | Release Candidate 1 |
| HDMI Output | 0.100.0 | Release Candidate 1 |
| Composite Input | 0.100.0 | Release Candidate 1 |
| HAL Component | New Version | Status |
|---|---|---|
| Indicator | 0.100.0 | Release Candidate 1 |
| Panel | 0.100.0 | Release Candidate 1 (Multi-View Changes Required) |
| Motion | 0.100.0 | Release Candidate 1 |
| Thermal | 0.100.0 | Release Candidate 1 |
| Device Info | 0.100.0 | Release Candidate 1 |
Feature complete. Within the 14+5 Day Review Window. Implementation for early access only.
| HAL Component | Target Version | Key Requirement |
|---|---|---|
| AV Buffer | 0.100.0 | Encrypted buffer discussion required with DRM / SVP inputs |
| Audio Mixer | 0.100.0 | Under Review On PR |
| Broadcast | 0.100.1 | Under Review On PR |
| FFV | 0.100.0 | Under Review On PR |
| Deep Sleep | 0.100.0 | Feedback Loop review required from current platform experiences |
| Plane Control | 0.100.0 | Re-review required |
| Boot | 0.100.0 | Release Candidate 1, Migrate name to RebootReason |
| Flash | 0.100.0 | Release Candidate 1, Migrate name to Image |
| OEM System Interfaces | Target Era | Status |
|---|---|---|
| Graphics Libraries | 0.100.x | Standard Linux Feature, OpenGLES /Vulcan etc. Documentation Required |
| Bluetooth | 0.100.x | Standard Linux Feature, Documentation Required |
| WPA Supplicant | 0.100.x | Standard Linux Feature, Documentation Required |
| File System | 0.100.x | Standard Linux Feature, Layout documentation and usage standards need reviewing |
| Abstract File System | 0.100.x | Standard Linux Feature, Documentation Required, DMCrypt, eCrypFS etc |
| Linux Input | 0.100.x | Standard Linux Feature, Documentation Required |
| Kernel | 0.100.x | Standard Linux Feature, Strategy Required, Use current kernels |
Further Inputs required
| HAL Component | Target Era | Status |
|---|---|---|
| DRM | 0.100.x | HAL Interface Requirements Gathering |
| Crypto | 0.100.x | HAL Interface Requirements Gathering |
Here is the template for FFV, incorporating the new status, the "14+5" tracking, and the specific technical requirements for Far-Field Voice.
component: ffv
version: 0.100.1
generation: 100
status: AMBER
# Timeline Tracking (14+5 Rule)
lifecycle:
review_started: 2026-02-13
review_deadline: 2026-02-27 # 14 Calendar Days
target_green_date: 2026-03-06 # +5 Business Days for resolution
hal_lead: "Your Name/ID"
# High-Level Architecture
scope:
- Multi-mic array topology support (up to 8 channels)
- Hardware-offloaded Beamforming & AEC (Acoustic Echo Cancellation)
- Wake-word Engine (WWE) integration path
- Low-power "Always-on" buffer management
# Stakeholder Visibility
reviewers:
- Audio_MW
- Voice_Assistant_Team
- VTS_Testing
# Automated Dashboard Metadata
impact:
breaking_change: true # Signals Reintegration Required (0.x.0/0.x.1 transition)
multi_view_sync: false
# Documentation References
links:
spec: "./docs/FFV_Interface_Spec.md"