Skip to content

Commit b0f14fd

Browse files
UlrondUlrond
authored
Merge pull request #378 from rdkcentral/feature/374-panel-hal-documentation
docs: Replace Panel HAL placeholder with complete documentation (#374)
2 parents 8ab4217 + 341d95f commit b0f14fd

File tree

1 file changed

+204
-11
lines changed

1 file changed

+204
-11
lines changed

‎docs/halif/panel/current/panel.md‎

Lines changed: 204 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,218 @@
1-
# Panel
1+
# Panel HAL Interface
2+
3+
## Overview
4+
5+
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.
6+
7+
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.
8+
9+
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.
10+
11+
---
212

313
## References
414

5-
!!! info References
15+
!!! info "References"
616
|||
717
|-|-|
8-
|**Interface Definition**|[panel/current](https://github.com/rdkcentral/rdk-halif-aidl/tree/main/panel/current)|
9-
|**API Documentation**| *TBD* |
18+
|**Interface Definition**|[panel/current/com/rdk/hal/panel](https://github.com/rdkcentral/rdk-halif-aidl/tree/develop/panel/current/com/rdk/hal/panel)|
19+
|**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)|
1020
|**HAL Interface Type**|[AIDL and Binder](../../../introduction/aidl_and_binder.md)|
11-
|**VTS Tests**| TBC |
12-
|**Reference Implementation - vComponent**|**TBD**|
21+
|**Initialization Unit**|[systemd](../../../vsi/systemd/current/systemd.md) – **hal-panel.service**|
22+
23+
---
1324

1425
## Related Pages
1526

1627
!!! tip "Related Pages"
17-
- TBC
28+
* [HAL Feature Profile](../../key_concepts/hal/hal_feature_profiles.md)
29+
* [HAL Interface Overview](../../key_concepts/hal/hal_interfaces.md)
30+
31+
---
32+
33+
## Functional Overview
34+
35+
The Panel HAL manages both static capabilities and dynamic runtime control of the display panel. It exposes:
36+
37+
* Panel hardware capabilities including resolution, physical size, panel type (LCD, OLED, QLED, Mini-LED), supported picture quality (PQ) parameters, refresh rates, and picture modes.
38+
* Picture quality configuration, including brightness, contrast, saturation, hue, gamma, local dimming, and noise reduction.
39+
* White balance calibration interfaces for 2-point and multi-point adjustments.
40+
* Factory-level persistent storage of calibration data and test modes via `IFactoryPanel`.
41+
* Dynamic control over panel enable/disable, picture modes, frame rate matching, and display fading.
42+
* Event callbacks for real-time updates on video source, dynamic range, resolution, and refresh rate changes.
43+
44+
The corresponding [`hfp-panel.yaml`](https://github.com/rdkcentral/rdk-halif-aidl/tree/develop/panel/current/hfp-panel.yaml) file includes structured declarations for:
45+
46+
* `panelType`, `pixelWidth`, `heightCm`, etc. (from `Capabilities.aidl`, returned via `IPanelOutput.getCapabilities()`)
47+
* `supportedPQParameters` (from `PQParameter.aidl`)
48+
* `pqParameterCapabilities` (from `PQParameterCapabilities.aidl`)
49+
* `pictureModeCapabilities` (from `Capabilities.aidl`)
50+
51+
---
52+
53+
## Implementation Requirements
54+
55+
| # | Requirement | Comments |
56+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
57+
| **HAL.PANEL.1** | The service shall expose accurate static capabilities including panel resolution, physical dimensions, and supported PQ parameters. | Enables adaptive client configurations |
58+
| **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 |
59+
| **HAL.PANEL.3** | The service shall allow enabling/disabling panel output and backlight with no side effects. | |
60+
| **HAL.PANEL.4** | The service shall provide asynchronous event callbacks for video source, picture mode, and refresh rate changes. | Ensures responsive UI/middleware updates |
61+
| **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 |
62+
| **HAL.PANEL.6** | The service shall support frame rate matching with panel refresh rate adjustments. | Enables smooth video playback synchronisation |
63+
| **HAL.PANEL.7** | The service shall support local dimming zone control and test modes with timed duration. | Enables factory and diagnostic tests |
64+
65+
---
66+
67+
## Interface Definitions
68+
69+
| AIDL File | Description |
70+
| ----------------------------------- | ------------------------------------------------------------ |
71+
| `Capabilities.aidl` | Defines panel capabilities and supported picture modes |
72+
| `IFactoryPanel.aidl` | Factory interface for persistent configuration and tests |
73+
| `IPanelOutput.aidl` | Runtime panel output control interface |
74+
| `IPanelOutputListener.aidl` | Event listener callbacks for panel state changes |
75+
| `PQParameter.aidl` | Enumeration of supported picture quality parameters |
76+
| `PQParameterCapabilities.aidl` | Capabilities per PQ parameter by picture mode and format |
77+
| `PQParameterConfiguration.aidl` | Configuration value of PQ parameter for a mode/source/format |
78+
| `PanelType.aidl` | Enumeration of panel types (LCD, OLED, etc.) |
79+
| `PictureModeConfiguration.aidl` | Picture mode, video format, and AV source config |
80+
| `WhiteBalance2PointSettings.aidl` | 2-point white balance calibration settings |
81+
| `WhiteBalanceMultiPointSettings.aidl` | Multi-point white balance calibration arrays |
82+
83+
---
84+
85+
## Initialization
86+
87+
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.
88+
89+
Factory tools access `IFactoryPanel` for calibration data storage and test mode activation.
90+
91+
---
92+
93+
## Product Customization
94+
95+
* Panels are uniquely identified via `panelId` stored persistently via factory interface.
96+
* `Capabilities` parcelable exposes physical dimensions, panel type, supported PQ parameters, refresh rates, and supported picture modes.
97+
* Supports multiple picture modes, dynamic ranges, and AV sources, allowing flexible client-specific configurations.
98+
* Platforms may expose multiple simultaneous picture modes or limit to a single active mode depending on hardware capability.
99+
100+
---
101+
102+
## System Context
103+
104+
```mermaid
105+
flowchart TD
106+
RDKClientComponent -->|Queries capabilities, sets PQ parameters| PanelOutput[PanelOutput HAL]
107+
RDKClientComponent -->|Registers for events| Listener[IPanelOutputListener]
108+
PanelOutput --> Factory[IFactoryPanel Interface]
109+
Factory -->|Reads/writes calibration data| PersistentStorage
110+
PanelOutput --> Hardware[Panel Hardware]
111+
Hardware -->|Reports status| PanelOutput
112+
Hardware -->|Applies settings| PanelOutput
113+
114+
classDef background fill:#121212,stroke:none,color:#E0E0E0;
115+
classDef blue fill:#1565C0,stroke:#E0E0E0,stroke-width:2px,color:#E0E0E0;
116+
classDef lightGrey fill:#616161,stroke:#E0E0E0,stroke-width:2px,color:#FFFFFF;
117+
classDef wheat fill:#FFB74D,stroke:#424242,stroke-width:2px,color:#000000;
118+
classDef green fill:#4CAF50,stroke:#E0E0E0,stroke-width:2px,color:#FFFFFF;
119+
classDef default fill:#1E1E1E,stroke:#E0E0E0,stroke-width:1px,color:#E0E0E0;
120+
121+
RDKClientComponent:::blue
122+
PanelOutput:::wheat
123+
Listener:::wheat
124+
Factory:::wheat
125+
Hardware:::green
126+
PersistentStorage:::green
127+
128+
```
129+
130+
---
131+
132+
## Resource Management
133+
134+
* Clients acquire handles via binder connection to `PanelOutput` service.
135+
* Single or multiple clients can set PQ parameters scoped by picture mode/source/format.
136+
* Factory calibration is accessed exclusively via the factory interface.
137+
* Cleanup occurs on client disconnect, with persistent factory data unaffected.
138+
139+
---
140+
141+
## Operation and Data Flow
142+
143+
* Client query `Capabilities` for supported picture modes and PQ parameters.
144+
* Picture mode configurations and PQ parameters are set via `setPictureModes()` and `setPQParameters()`.
145+
* The panel output enable state controls display and backlight.
146+
* Frame rate matching adjusts panel refresh rate dynamically to match video content.
147+
* White balance and gamma settings are adjusted either dynamically or via factory calibration data.
148+
* Local dimming zones can be controlled and tested for factory diagnostics.
149+
150+
---
151+
152+
## Modes of Operation
153+
154+
* Runtime picture modes configurable by client with dynamic range and AV source scoping.
155+
* Factory calibration mode accessed exclusively through factory interface.
156+
* Frame rate matching mode enabled/disabled by client.
157+
158+
---
159+
160+
## Event Handling
161+
162+
* Event callbacks include:
163+
164+
* `onPictureModeChanged`
165+
* `onVideoSourceChanged`
166+
* `onVideoFormatChanged`
167+
* `onVideoFrameRateChanged`
168+
* `onVideoResolutionChanged`
169+
* `onRefreshRateChanged`
170+
* Clients register listener interface to receive asynchronous events.
171+
172+
---
173+
174+
## State Machine / Lifecycle
175+
176+
* Typical states: `ENABLED`, `DISABLED`
177+
* Transitions triggered via `setEnabled()`
178+
* Picture modes and PQ parameters are set during `ENABLED` state
179+
* Factory interface operates independently of runtime state
180+
181+
---
182+
183+
## Data Format / Protocol Support
184+
185+
| Format | Use Case | Support Level |
186+
| ------------- | ----------------------- | ------------- |
187+
| Picture Modes | Video display presets | Mandatory |
188+
| PQ Parameters | Picture quality control | Mandatory |
189+
| White Balance | Color calibration | Mandatory |
190+
191+
---
192+
193+
## Platform Capabilities
194+
195+
* Supports a range of panel types: LCD, OLED, QLED, Mini LED.
196+
* Supports multiple refresh rates and frame rate matching.
197+
* Supports local dimming with zone control and test modes.
198+
* Supports advanced PQ parameters including AI PQ engine and noise reduction.
199+
200+
---
201+
202+
## HAL Feature Profile Integration
203+
204+
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:
205+
206+
* Static capabilities such as panel dimensions, panel type, and refresh rates.
207+
* Lists of supported PQ parameters and picture modes.
208+
* Capabilities of each PQ parameter per picture mode, AV source, and dynamic range.
209+
* Declared as includes or structured sections aligned with the AIDL interfaces.
18210

19-
## 🚧 Document Under Construction
211+
These files are machine-readable and used for:
20212

21-
This document serves as a **placeholder**.
213+
* Platform validation via test automation.
214+
* Runtime feature gating in middleware.
215+
* Reference values for functions like `getCapabilities()`.
22216

23-
The content is **not yet released** and is currently **under construction**.
217+
> See the [HAL Feature Profile documentation](../../key_concepts/hal/hal_feature_profiles.md) for full details and schema format.
24218
25-
Please check back later for updates.

0 commit comments

Comments
 (0)