From 061e71781dec9464994f17ca03abafe63c9792e7 Mon Sep 17 00:00:00 2001
From: akanda200_comcast <Anand_Kandasamy@comcast.com>
Date: Fri, 5 Dec 2025 05:27:37 -0500
Subject: [PATCH] Add ARCHITECTURE.md and PRODUCT.md documentation

- Add comprehensive architecture documentation describing the layered design
- Add product documentation detailing features, use cases, and integration
- Include component descriptions, communication flows, and design patterns
- Document API usage examples and extension points
---
 ARCHITECTURE.md | 223 +++++++++++++++++++++++++++++++++++++++++++
 PRODUCT.md      | 246 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 469 insertions(+)
 create mode 100644 ARCHITECTURE.md
 create mode 100644 PRODUCT.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 00000000..6ad5756b
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,223 @@
+# HDMI-CEC Library Architecture
+
+## Overview
+
+The HDMI-CEC library is a C++ implementation for managing HDMI Consumer Electronics Control (CEC) protocol communications on RDK (Reference Design Kit) platforms. This library provides a layered architecture that abstracts hardware-specific CEC driver implementations and offers high-level APIs for CEC message processing.
+
+## High-Level Architecture
+
+The library follows a three-layer architecture:
+
+```
+┌─────────────────────────────────────────────────────┐
+│          Application Layer                          │
+│  (Uses Connection & MessageProcessor APIs)          │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│          CCEC Layer (Core CEC Logic)                │
+│  - Connection Management                            │
+│  - Message Encoding/Decoding                        │
+│  - Bus Communication                                │
+│  - Frame Processing                                 │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│          OSAL Layer                                 │
+│  (OS Abstraction - Threading, Synchronization)      │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│          Driver Layer                               │
+│  (Hardware-specific CEC Driver Interface)           │
+└─────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. OSAL (OS Abstraction Layer)
+
+**Location:** `osal/`
+
+Provides platform-independent synchronization primitives and utilities:
+
+- **Thread**: POSIX thread wrapper for concurrent execution
+- **Mutex**: Mutual exclusion for thread-safe operations
+- **ConditionVariable**: Thread synchronization mechanism
+- **EventQueue**: Thread-safe event queue for asynchronous processing
+- **Runnable/Stoppable**: Interfaces for thread lifecycle management
+
+**Key Features:**
+- Platform abstraction for portability
+- Thread-safe container implementations
+- Exception-based error handling
+
+### 2. CCEC (Core CEC Implementation)
+
+**Location:** `ccec/`
+
+The main CEC protocol implementation with several key subsystems:
+
+#### 2.1 Connection Management
+
+**Classes:** `Connection`, `Bus`
+
+- **Connection**: Primary API for applications to access the CEC bus
+  - Manages logical addresses (source/destination)
+  - Provides send/receive operations for CEC frames
+  - Supports both synchronous and asynchronous messaging
+  - Implements frame listener registration
+
+- **Bus**: Singleton managing the physical CEC bus
+  - Routes frames between connections and the driver
+  - Manages frame listeners
+  - Handles polling and device discovery
+  - Thread-safe operation using OSAL primitives
+
+#### 2.2 Message Processing
+
+**Classes:** `MessageEncoder`, `MessageDecoder`, `MessageProcessor`
+
+- **MessageEncoder**: Converts high-level message objects to raw CEC frames
+- **MessageDecoder**: Parses raw CEC frames into message objects
+- **MessageProcessor**: Base class with virtual methods for processing specific CEC messages
+  - Implements visitor pattern for message handling
+  - Applications extend this to handle specific message types
+  - Default implementation discards messages (acts as filter)
+
+**Supported Message Types:**
+- Active Source / Inactive Source
+- Image View On / Text View On
+- Standby, Power Status
+- Routing Control (Set Stream Path, Routing Change, etc.)
+- OSD Name, Vendor Commands
+- Device capabilities (CEC Version, Physical Address)
+
+#### 2.3 Frame and Data Management
+
+**Classes:** `CECFrame`, `Header`, `OpCode`, `Operands`
+
+- **CECFrame**: Raw byte buffer representing complete CEC messages
+  - Header block (initiator/destination addresses)
+  - OpCode block (message type)
+  - Operand block (message parameters)
+
+- **Header**: Encapsulates source and destination logical addresses
+- **OpCode**: Defines all CEC operation codes
+- **Operands**: Container for message-specific parameters
+
+#### 2.4 Driver Interface
+
+**Classes:** `Driver`, `DriverImpl`
+
+- **Driver**: Abstract interface for hardware CEC driver
+  - `open()`, `close()`: Resource management
+  - `read()`, `write()`: Frame I/O operations
+  - `poll()`: Device presence detection
+  - Singleton pattern for system-wide access
+
+- **DriverImpl**: Concrete implementation
+  - Callbacks for asynchronous receive/transmit
+  - Incoming frame queue management
+  - State machine for driver lifecycle (CLOSED/OPENING/OPENED/CLOSING)
+  - ACK/NACK handling (SENT_AND_ACKD, SENT_FAILED, SENT_BUT_NOT_ACKD)
+
+#### 2.5 Host Integration
+
+**Interface:** `Host.hpp`
+
+C-compatible API for platform-specific host implementations:
+
+- Device status monitoring (power state, connection, OSD name)
+- Policy management (TV/STB power control)
+- Callback mechanisms for host notifications
+- Error code definitions
+
+## Communication Flow
+
+### Sending Messages
+
+```
+Application
+    ↓ creates Message object
+MessageEncoder
+    ↓ encode to CECFrame
+Connection
+    ↓ send() or sendAsync()
+Bus
+    ↓ queue and route
+Driver
+    ↓ transmit to hardware
+CEC Bus
+```
+
+### Receiving Messages
+
+```
+CEC Bus
+    ↓ hardware interrupt
+Driver (DriverReceiveCallback)
+    ↓ enqueue CECFrame
+Bus
+    ↓ notify listeners
+FrameListener(s)
+    ↓ filter and process
+MessageDecoder
+    ↓ decode to Message object
+MessageProcessor
+    ↓ process() method
+Application
+```
+
+## Design Patterns
+
+1. **Singleton Pattern**: `Bus`, `Driver` - ensures single instance per system
+2. **Observer Pattern**: `FrameListener`, `FrameFilter` - event notification
+3. **Factory Pattern**: Message creation through encoder/decoder
+4. **Strategy Pattern**: `MessageProcessor` - pluggable message handling
+5. **Template Pattern**: OSAL abstractions for platform independence
+
+## Thread Safety
+
+- All public APIs are thread-safe using OSAL Mutex
+- Bus uses internal locking for listener management
+- Driver callbacks execute on separate threads
+- EventQueue provides thread-safe message queuing
+- Asynchronous operations recommended to avoid blocking
+
+## Build System
+
+- **Autotools-based**: `configure.ac`, `Makefile.am`
+- **Dependencies**: glib-2.0 (≥0.10.28)
+- **Subdirectories**: cfg, osal, ccec, tests
+- **Output**: Shared libraries for OSAL and CCEC components
+- **Build scripts**: `build.sh`, `rdk_build.sh` for RDK integration
+
+## Testing
+
+**Location:** `tests/`
+
+- **BasicTest.cpp**: Fundamental API validation
+- **CECCmdTest.cpp**: Command processing tests
+- **CECMonitor.cpp**: Bus monitoring utility
+
+## Key Design Decisions
+
+1. **Asynchronous-First**: Library prioritizes async operations due to CEC's inherent latency and unreliable device responses
+2. **Layered Abstraction**: OSAL enables portability across platforms
+3. **Type-Safe Messages**: C++ classes for each message type prevent errors
+4. **Extensible Processing**: Virtual methods allow custom message handling
+5. **Exception-Based Errors**: Uses exceptions for error propagation in critical paths
+
+## Extension Points
+
+Applications can extend the library by:
+
+1. Implementing custom `MessageProcessor` subclasses
+2. Creating custom `FrameListener` implementations
+3. Implementing platform-specific `Driver` backends
+4. Extending host integration callbacks
+
+## Version
+
+Current version: 1.0.7 (as per CHANGELOG.md)
diff --git a/PRODUCT.md b/PRODUCT.md
new file mode 100644
index 00000000..50485884
--- /dev/null
+++ b/PRODUCT.md
@@ -0,0 +1,246 @@
+# HDMI-CEC Library Product Documentation
+
+## Product Overview
+
+The HDMI-CEC library is a comprehensive C++ software library that enables RDK-based devices to communicate using the HDMI Consumer Electronics Control (CEC) protocol. CEC allows devices connected via HDMI to control one another without the need for multiple remote controls, enabling a unified home entertainment experience.
+
+This library provides both low-level frame manipulation and high-level message-oriented APIs, making it suitable for integrating CEC functionality into set-top boxes, TVs, audio receivers, and other HDMI-connected consumer electronics devices.
+
+## Key Features
+
+### 1. Comprehensive CEC Protocol Support
+
+The library implements the full HDMI-CEC 1.4 specification, supporting all standard CEC messages:
+
+**Power Management:**
+- Active Source / Inactive Source
+- Image View On / Text View On
+- Standby control
+- Power status reporting
+
+**Device Discovery & Addressing:**
+- Physical address reporting
+- Logical address allocation
+- Device polling
+- OSD name management
+
+**Routing Control:**
+- Set Stream Path
+- Routing Change
+- Routing Information
+- Request Active Source
+
+**Audio Control (ARC/eARC):**
+- Initiate/Terminate Audio Return Channel (ARC)
+- System Audio Mode control
+- Audio status reporting
+- Volume control commands
+
+**User Interface Commands:**
+- Remote control button pass-through (User Control Pressed/Released)
+- Menu navigation
+- OSD string display
+
+**Device Information:**
+- CEC version reporting
+- Vendor ID exchange
+- Device capabilities query
+- Feature support reporting
+
+**Timer & Recording:**
+- Timer programming
+- Recording control
+- Deck control and status
+
+### 2. Dual API Layers
+
+#### High-Level Message API
+
+Applications work with strongly-typed C++ message objects rather than raw bytes:
+
+```cpp
+// Send an Active Source message
+CECFrame frame = MessageEncoder().encode(
+    Header(LogicalAddress(TUNER_1), LogicalAddress(TV)),
+    ActiveSource(PhysicalAddress(1, 0, 0, 0))
+);
+Connection(LogicalAddress(TUNER_1)).send(frame);
+```
+
+**Benefits:**
+- Type-safe message construction
+- Compile-time validation
+- Self-documenting code
+- Reduced integration errors
+
+#### Low-Level Frame API
+
+Direct access to CEC frame bytes for specialized use cases:
+- Custom message implementation
+- Protocol debugging
+- Bus monitoring
+- Performance optimization
+
+### 3. Asynchronous Communication Model
+
+The library is designed for asynchronous operation, acknowledging the real-world challenges of CEC:
+
+- **Non-blocking sends**: Applications don't wait for acknowledgments
+- **Event-driven reception**: Listener pattern for incoming messages
+- **Configurable timeouts**: Handle unresponsive devices gracefully
+- **Queue management**: Automatic frame queuing during bus contention
+
+**Rationale:** CEC devices often have variable response times or may ignore messages entirely. Asynchronous APIs prevent application blocking and enable responsive user experiences.
+
+### 4. Extensible Message Processing
+
+Applications customize behavior by extending the `MessageProcessor` class:
+
+```cpp
+class MyDeviceController : public MessageProcessor {
+public:
+    void process(const ActiveSource &msg, const Header &header) override {
+        // Custom handling for Active Source messages
+        if (msg.physicalAddress == myAddress) {
+            switchToInput();
+        }
+    }
+    
+    void process(const Standby &msg, const Header &header) override {
+        // Handle standby requests
+        enterPowerSaveMode();
+    }
+};
+```
+
+Supports selective message handling - only override methods for messages of interest.
+
+### 5. Multi-Connection Architecture
+
+Multiple logical connections can coexist on the same physical CEC bus:
+
+- **Logical address management**: Each connection represents a CEC device role
+- **Message filtering**: Connections receive only relevant frames
+- **Independent listeners**: Different components can monitor specific message types
+- **Bus arbitration**: Automatic coordination of simultaneous sends
+
+### 6. Thread-Safe Operations
+
+Built on a robust OS abstraction layer (OSAL):
+
+- **Mutex protection**: All public APIs are thread-safe
+- **Event queues**: Thread-safe message buffering
+- **Condition variables**: Efficient thread synchronization
+- **No deadlocks**: Careful lock ordering and timeout mechanisms
+
+### 7. Platform Abstraction
+
+The OSAL layer ensures portability across different RDK platforms:
+
+- **Thread management**: Platform-independent threading
+- **Synchronization primitives**: Mutexes, condition variables
+- **Event handling**: Asynchronous event delivery
+- **Minimal dependencies**: Only requires glib-2.0 (≥0.10.28)
+
+### 8. Bus Monitoring & Debugging
+
+Built-in tools for development and troubleshooting:
+
+- **CECMonitor**: Real-time CEC bus traffic monitoring
+- **Frame logging**: Detailed message tracing
+- **State introspection**: Query connection and device status
+- **Test utilities**: Validation and conformance testing
+
+## Use Cases
+
+### Smart TV Integration
+- Automatically switch to active source input
+- Control STB/DVD player power and playback
+- Display device OSD names in source selection
+- Handle remote control commands from connected devices
+
+### Set-Top Box (STB) Implementation
+- Signal content availability (Active Source)
+- Power on/off TV when STB powers up/down
+- Forward user commands to TV
+- Support ARC for audio output
+
+### Audio/Video Receiver (AVR)
+- System Audio Control implementation
+- HDMI switching based on Active Source
+- Volume control integration
+- ARC audio routing
+
+### Device Testing & Validation
+- CEC protocol conformance testing
+- Interoperability verification
+- Bus analysis and debugging
+- Performance benchmarking
+
+## Integration Points
+
+### Application Layer
+Applications integrate by:
+1. Creating `Connection` objects for each logical device role
+2. Extending `MessageProcessor` for custom message handling
+3. Registering `FrameListener` objects for event notifications
+4. Calling `send()` or `sendAsync()` to transmit messages
+
+### Platform/Hardware Layer
+Platform vendors provide:
+1. Hardware driver implementation conforming to `Driver` interface
+2. Host module implementation for device-specific behavior
+3. Physical address configuration
+4. Device type and capabilities definition
+
+### Build Integration
+- Autotools-based build system
+- pkg-config support for dependency management
+- Separate libraries for OSAL and CCEC layers
+- Header installation for downstream projects
+
+## Configuration
+
+The library supports runtime configuration through the host interface:
+
+- **Device policies**: Control automatic power-off behavior
+- **Logical addresses**: Configure device roles and addresses
+- **Physical addresses**: Set HDMI topology position
+- **Feature flags**: Enable/disable specific CEC capabilities
+
+## Benefits
+
+1. **Accelerated Development**: Pre-built CEC stack reduces time-to-market
+2. **Compliance**: Implements HDMI-CEC specification correctly
+3. **Reliability**: Handles edge cases and error conditions
+4. **Maintainability**: Clean API separation and extensive documentation
+5. **Flexibility**: Supports both simple and advanced use cases
+6. **Testability**: Built-in debugging and monitoring tools
+7. **Portability**: Runs across RDK platforms with minimal changes
+
+## Example Applications
+
+The library includes practical examples:
+
+- **BasicTest**: Demonstrates fundamental API usage
+- **CECMonitor**: Real-time bus monitoring and message decoding
+- **CECCmdTest**: Interactive command-line CEC message sender
+
+These serve as both learning tools and starting points for custom applications.
+
+## Limitations & Considerations
+
+- **Bus timing**: CEC has inherent latency; design for asynchronous operation
+- **Device compatibility**: Not all devices fully implement CEC specification
+- **Single bus**: Typically one CEC bus per HDMI infrastructure
+- **No guarantees**: CEC messages may be ignored or NACK'd by receivers
+- **Platform-specific**: Requires platform driver implementation
+
+## Version & Support
+
+**Current Version:** 1.0.7  
+**License:** Apache License 2.0  
+**Maintained By:** RDK Management  
+**Repository:** github.com/rdkcentral/hdmicec
+
+For contributions, bug reports, and feature requests, see CONTRIBUTING.md.