RDKDEV-1424 Add HDMICEC Documentation#60
Open
gourivarma3 wants to merge 1 commit into
Open
Conversation
Add detailed documentation for HDMI CEC library including features, design, and configuration.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a comprehensive top-level README documenting the HDMI CEC middleware library in the RDK stack, covering architecture, threading model, initialization/state flows, HAL integration, and runtime configuration.
Changes:
- Introduces new
README.mdwith detailed component overview, design notes, and module breakdown. - Adds multiple Mermaid diagrams for system positioning, internal architecture, and call flows.
- Documents build/runtime dependencies and configuration (e.g., log level via
/tmp/cec_log_enabled).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| #### Initialization to Active State | ||
|
|
||
| The HDMI CEC library initialization begins when an application calls LibCCEC::getInstance() which creates the singleton instance and implicitly starts the Bus singleton. The Bus constructor automatically launches reader and writer threads that immediately begin running. The application then calls LibCCEC::init() to mark the library as initialized and optionally calls Bus::start() to open the driver. When the driver opens via DriverImpl::open(), it calls HdmiCecOpen() and registers receive and transmit callbacks. For source devices, the HAL performs logical address discovery during HdmiCecOpen(). The application creates Connection instances which register FrameListener objects with the Bus to begin receiving frames. |
Comment on lines
+194
to
+207
| App->>LibCCEC: getInstance() | ||
| LibCEC->>LibCEC: Create singleton | ||
| LibCEC->>Bus: getInstance() | ||
| Bus->>Bus: Constructor | ||
| Bus->>Reader: Create and start thread | ||
| Bus->>Writer: Create and start thread | ||
| Note over Reader,Writer: Threads running, waiting for driver | ||
|
|
||
| App->>LibCCEC: init(name) | ||
| LibCCEC->>LibCCEC: Set initialized flag | ||
| LibCCEC-->>App: Initialized | ||
|
|
||
| App->>Bus: start() | ||
| Bus->>Driver: open() |
Comment on lines
+353
to
+357
| Writer->>Writer: Dequeue frame | ||
| Writer->>Driver: writeAsync(frame) | ||
| Driver->>Driver: Lock mutex, check status | ||
| Driver->>HAL: HdmiCecTxAsync(handle, buf, len) | ||
| HAL-->>Driver: Queued status |
|
|
||
| - **Worker Threads**: | ||
| - _Bus Reader Thread_: Continuously polls Driver.read() to receive incoming CEC frames. When a frame arrives, it locks the reader mutex and iterates through all registered FrameListener instances, invoking their notify() method synchronously. Owns the frame dispatch logic. | ||
| - _Bus Writer Thread_: Processes an EventQueue of outgoing CECFrame pointers. Dequeues frames, invokes Driver.write() or Driver.writeAsync(), and handles transmission errors. Uses condition variables for efficient waiting when the queue is empty. |
|
|
||
| - **Build Dependencies**: | ||
| - virtual/vendor-hdmicec-hal: Vendor-specific HAL implementation that the library wraps. This is the primary interface to hardware and is directly called throughout DriverImpl. | ||
| - glib-2.0 (>= 0.10.28): Provides core data structures and utilities used across the library codebase. |
|
|
||
| ### Prerequisites & Dependencies | ||
|
|
||
| The HDMI CEC library is designed as a standalone middleware library with minimal external dependencies. It requires a vendor-specific HAL implementation to interface with hardware and uses glib for basic utilities. The library does not directly depend on IARM, Device Settings, or Thunder framework components - these are used by applications that consume the library, not by the library itself. Build-time dependencies are limited to essential libraries that are actually invoked in the library source code. |
Comment on lines
+273
to
+290
| App->>LibCEC: getInstance() | ||
| Note over LibCEC: First call creates singleton | ||
| LibCEC->>Bus: getInstance() | ||
| Note over Bus: Constructor starts threads | ||
| LibCEC-->>App: libCCEC reference | ||
|
|
||
| App->>LibCEC: init("component") | ||
| LibCEC->>LibCEC: Check initialized flag | ||
| alt Not yet initialized | ||
| LibCEC->>LibCEC: Set initialized = true | ||
| LibCEC->>LibCEC: Set log prefix | ||
| end | ||
| LibCEC-->>App: Initialized | ||
|
|
||
| App->>Bus: start() | ||
| Bus->>Driver: getInstance() | ||
| Driver->>Driver: Create singleton | ||
| Bus->>Driver: open() |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Added documentation for HDMI CEC library including features, design, and configuration.
I have read the CLA Document and I hereby sign the CLA