-
Notifications
You must be signed in to change notification settings - Fork 1
docs: Replace Panel HAL placeholder with complete documentation (#374) #378
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+204
−11
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,25 +1,218 @@ | ||||||
| # Panel | ||||||
| # Panel HAL Interface | ||||||
|
|
||||||
| ## Overview | ||||||
|
|
||||||
| The Panel HAL provides a standardised interface to control and configure the display panel hardware on RDK platforms. It abstracts platform-specific display functions including resolution, panel type, picture quality parameters, white balance calibration, local dimming, factory configurations, and dynamic runtime controls such as picture modes and refresh rate management. | ||||||
|
|
||||||
| This HAL enables higher-level components to dynamically adjust video output parameters and factory tools to calibrate and validate panel hardware during manufacturing or service. | ||||||
|
|
||||||
| To declare the static feature set and ensure alignment between implementation and testing, each platform must provide a **HAL Feature Profile (HFP)** YAML file. This machine-readable profile specifies the supported capabilities of the Panel HAL implementation, including available picture modes, PQ parameters, dynamic range formats, and supported AV sources. It is essential for test suites, middleware negotiation, and runtime validation. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## References | ||||||
|
|
||||||
| !!! info References | ||||||
| !!! info "References" | ||||||
| ||| | ||||||
| |-|-| | ||||||
| |**Interface Definition**|[panel/current](https://github.com/rdkcentral/rdk-halif-aidl/tree/main/panel/current)| | ||||||
| |**API Documentation**| *TBD* | | ||||||
| |**Interface Definition**|[panel/current/com/rdk/hal/panel](https://github.com/rdkcentral/rdk-halif-aidl/tree/develop/panel/current/com/rdk/hal/panel)| | ||||||
| |**HAL Feature Profile**|[`hfp-panel.yaml`](https://github.com/rdkcentral/rdk-halif-aidl/blob/develop/panel/current/hfp-panel.yaml) – [Learn more](../../key_concepts/hal/hal_feature_profiles.md)| | ||||||
| |**HAL Interface Type**|[AIDL and Binder](../../../introduction/aidl_and_binder.md)| | ||||||
| |**VTS Tests**| TBC | | ||||||
| |**Reference Implementation - vComponent**|**TBD**| | ||||||
| |**Initialization Unit**|[systemd](../../../vsi/systemd/current/systemd.md) – **hal-panel.service**| | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Related Pages | ||||||
|
|
||||||
| !!! tip "Related Pages" | ||||||
| - TBC | ||||||
| * [HAL Feature Profile](../../key_concepts/hal/hal_feature_profiles.md) | ||||||
| * [HAL Interface Overview](../../key_concepts/hal/hal_interfaces.md) | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Functional Overview | ||||||
|
|
||||||
| The Panel HAL manages both static capabilities and dynamic runtime control of the display panel. It exposes: | ||||||
|
|
||||||
| * Panel hardware capabilities including resolution, physical size, panel type (LCD, OLED, QLED, Mini-LED), supported picture quality (PQ) parameters, refresh rates, and picture modes. | ||||||
| * Picture quality configuration, including brightness, contrast, saturation, hue, gamma, local dimming, and noise reduction. | ||||||
| * White balance calibration interfaces for 2-point and multi-point adjustments. | ||||||
| * Factory-level persistent storage of calibration data and test modes via `IFactoryPanel`. | ||||||
| * Dynamic control over panel enable/disable, picture modes, frame rate matching, and display fading. | ||||||
| * Event callbacks for real-time updates on video source, dynamic range, resolution, and refresh rate changes. | ||||||
|
|
||||||
| The corresponding [`hfp-panel.yaml`](https://github.com/rdkcentral/rdk-halif-aidl/tree/develop/panel/current/hfp-panel.yaml) file includes structured declarations for: | ||||||
|
|
||||||
| * `panelType`, `pixelWidth`, `heightCm`, etc. (from `Capabilities.aidl`, returned via `IPanelOutput.getCapabilities()`) | ||||||
| * `supportedPQParameters` (from `PQParameter.aidl`) | ||||||
| * `pqParameterCapabilities` (from `PQParameterCapabilities.aidl`) | ||||||
| * `pictureModeCapabilities` (from `Capabilities.aidl`) | ||||||
|
|
||||||
Ulrond marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| --- | ||||||
|
|
||||||
| ## Implementation Requirements | ||||||
|
|
||||||
| | # | Requirement | Comments | | ||||||
| | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | ||||||
Ulrond marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| | **HAL.PANEL.1** | The service shall expose accurate static capabilities including panel resolution, physical dimensions, and supported PQ parameters. | Enables adaptive client configurations | | ||||||
|
Comment on lines
+55
to
+57
|
||||||
| | **HAL.PANEL.2** | The service shall support setting and querying of picture quality parameters per picture mode, AV source, and dynamic range format. | Supports granular PQ control | | ||||||
| | **HAL.PANEL.3** | The service shall allow enabling/disabling panel output and backlight with no side effects. | | | ||||||
| | **HAL.PANEL.4** | The service shall provide asynchronous event callbacks for video source, picture mode, and refresh rate changes. | Ensures responsive UI/middleware updates | | ||||||
| | **HAL.PANEL.5** | The factory interface shall provide persistent storage of panel calibration including white balance, gamma tables, and local dimming settings. | Supports factory calibration and service | | ||||||
| | **HAL.PANEL.6** | The service shall support frame rate matching with panel refresh rate adjustments. | Enables smooth video playback synchronisation | | ||||||
| | **HAL.PANEL.7** | The service shall support local dimming zone control and test modes with timed duration. | Enables factory and diagnostic tests | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Interface Definitions | ||||||
|
|
||||||
| | AIDL File | Description | | ||||||
| | ----------------------------------- | ------------------------------------------------------------ | | ||||||
| | `Capabilities.aidl` | Defines panel capabilities and supported picture modes | | ||||||
| | `IFactoryPanel.aidl` | Factory interface for persistent configuration and tests | | ||||||
|
Comment on lines
+69
to
+72
|
||||||
| | `IPanelOutput.aidl` | Runtime panel output control interface | | ||||||
| | `IPanelOutputListener.aidl` | Event listener callbacks for panel state changes | | ||||||
| | `PQParameter.aidl` | Enumeration of supported picture quality parameters | | ||||||
| | `PQParameterCapabilities.aidl` | Capabilities per PQ parameter by picture mode and format | | ||||||
| | `PQParameterConfiguration.aidl` | Configuration value of PQ parameter for a mode/source/format | | ||||||
| | `PanelType.aidl` | Enumeration of panel types (LCD, OLED, etc.) | | ||||||
| | `PictureModeConfiguration.aidl` | Picture mode, video format, and AV source config | | ||||||
| | `WhiteBalance2PointSettings.aidl` | 2-point white balance calibration settings | | ||||||
| | `WhiteBalanceMultiPointSettings.aidl` | Multi-point white balance calibration arrays | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Initialization | ||||||
|
|
||||||
| The Panel HAL service is initialised early in the device boot process, registering itself with the system service manager under the name `"PanelOutput"`. Upon initialisation, it exposes static capabilities, factory interface, and supports client connections for runtime control. The event listener interface allows clients to subscribe for asynchronous updates. | ||||||
|
|
||||||
| Factory tools access `IFactoryPanel` for calibration data storage and test mode activation. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Product Customization | ||||||
|
|
||||||
| * Panels are uniquely identified via `panelId` stored persistently via factory interface. | ||||||
| * `Capabilities` parcelable exposes physical dimensions, panel type, supported PQ parameters, refresh rates, and supported picture modes. | ||||||
| * Supports multiple picture modes, dynamic ranges, and AV sources, allowing flexible client-specific configurations. | ||||||
| * Platforms may expose multiple simultaneous picture modes or limit to a single active mode depending on hardware capability. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## System Context | ||||||
|
|
||||||
| ```mermaid | ||||||
| flowchart TD | ||||||
| RDKClientComponent -->|Queries capabilities, sets PQ parameters| PanelOutput[PanelOutput HAL] | ||||||
| RDKClientComponent -->|Registers for events| Listener[IPanelOutputListener] | ||||||
| PanelOutput --> Factory[IFactoryPanel Interface] | ||||||
| Factory -->|Reads/writes calibration data| PersistentStorage | ||||||
| PanelOutput --> Hardware[Panel Hardware] | ||||||
| Hardware -->|Reports status| PanelOutput | ||||||
| Hardware -->|Applies settings| PanelOutput | ||||||
|
|
||||||
| classDef background fill:#121212,stroke:none,color:#E0E0E0; | ||||||
| classDef blue fill:#1565C0,stroke:#E0E0E0,stroke-width:2px,color:#E0E0E0; | ||||||
| classDef lightGrey fill:#616161,stroke:#E0E0E0,stroke-width:2px,color:#FFFFFF; | ||||||
| classDef wheat fill:#FFB74D,stroke:#424242,stroke-width:2px,color:#000000; | ||||||
| classDef green fill:#4CAF50,stroke:#E0E0E0,stroke-width:2px,color:#FFFFFF; | ||||||
| classDef default fill:#1E1E1E,stroke:#E0E0E0,stroke-width:1px,color:#E0E0E0; | ||||||
|
|
||||||
| RDKClientComponent:::blue | ||||||
| PanelOutput:::wheat | ||||||
| Listener:::wheat | ||||||
| Factory:::wheat | ||||||
| Hardware:::green | ||||||
| PersistentStorage:::green | ||||||
|
|
||||||
| ``` | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Resource Management | ||||||
|
|
||||||
| * Clients acquire handles via binder connection to `PanelOutput` service. | ||||||
| * Single or multiple clients can set PQ parameters scoped by picture mode/source/format. | ||||||
| * Factory calibration is accessed exclusively via the factory interface. | ||||||
| * Cleanup occurs on client disconnect, with persistent factory data unaffected. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Operation and Data Flow | ||||||
|
|
||||||
| * Client query `Capabilities` for supported picture modes and PQ parameters. | ||||||
|
||||||
| * Client query `Capabilities` for supported picture modes and PQ parameters. | |
| * Clients query `Capabilities` for supported picture modes and PQ parameters. |
Comment on lines
+185
to
+187
Copilot
AI
Apr 7, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Data Format / Protocol Support table also uses || at the start of each row, introducing an empty first column and risking broken rendering. Use a single leading | consistently.
Copilot
AI
Apr 7, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This later hfp-panel.yaml link also uses a GitHub /tree/ URL for a file. Use /blob/ (or a relative docs link) to avoid a broken link in the rendered documentation.
Suggested change
| Each platform must include a [hfp-panel.yaml](https://github.com/rdkcentral/rdk-halif-aidl/tree/develop/panel/current/hfp-panel.yaml) to define the platform-specific implementation of this HAL. It includes: | |
| Each platform must include a [hfp-panel.yaml](https://github.com/rdkcentral/rdk-halif-aidl/blob/develop/panel/current/hfp-panel.yaml) to define the platform-specific implementation of this HAL. It includes: |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The
hfp-panel.yamllink uses a GitHub/tree/URL which typically 404s for files (it should be/blob/). Update the URL so it points to the file content rather than a non-existent tree path.