IARM Manager

The IARM Managers (iarmmgrs) component is a collection of daemon processes that run in the RDK middleware layer and expose platform subsystem capabilities to the rest of the software stack over the IARM Bus. Each manager registers itself on the bus under a well-known name, publishes events when platform state changes, and services RPC calls from peer processes. Together they provide a unified inter-process interface for device settings, system state tracking, manufacturer-specific operations, disk monitoring, and device update coordination.

At the device level, iarmmgrs acts as the bridge between platform hardware capabilities and the higher-level middleware stack. It ensures that audio and video output ports are configured correctly after boot and after HDMI hot-plug events, propagates power state transitions to hardware, manages HDCP authentication state, tracks firmware download progress, and provides other components with queryable snapshots of overall system readiness.

At the module level, each manager daemon is an independent process with its own IARM Bus identity. They interact through broadcast events and direct RPC calls, maintaining loose coupling while sharing a common system state model defined in sysMgr.h.

flowchart LR

%% Styles
classDef Apps stroke:#00B9F1,fill:#E6F7FD,stroke-width:2px;
classDef RDKMW stroke:#75D701,fill:#F1FFE6,stroke-width:2px;
classDef VL stroke:#808080,fill:#F2F2F2,stroke-width:2px;

%% Apps Layer
    subgraph Apps["Apps & Runtimes"]
        RDKUI["UI"]
        FBApps["Firebolt Apps"]
        WPE_RT["WPE Runtime"]
    end

%% Middleware
    subgraph RDKMW["RDK Core Middleware"]
        AM["App Manager"]
        Thunder["WPEFramework (Thunder)"]
        IARMBUS["IARM Bus Daemon"]
        subgraph IARMMGRS["iarmmgrs"]
            SYSMgr["SysMgr\n(System State)"]
            DSMgr["DSMgr\n(Device Settings)"]
            MFRMgr["MFRMgr\n(Manufacturer Lib)"]
            DISKMgr["DISKMgr\n(Disk Events)"]
            DevUpdateMgr["DeviceUpdateMgr\n(OTA Updates)"]
        end
        SYSMgr <-->|IARM Events / RPC| IARMBUS
        DSMgr <-->|IARM Events / RPC| IARMBUS
        MFRMgr <-->|IARM Events / RPC| IARMBUS
        DISKMgr <-->|IARM Events / RPC| IARMBUS
        DevUpdateMgr <-->|IARM Events / RPC| IARMBUS
        DSMgr -->|PowerController API| Thunder
    end

%% Vendor Layer
    subgraph VL["Vendor Layer"]
        DS_HAL["Device Settings HAL"]
        MFRLIB["MFR Library\n(dlopen)"]
    end

    Apps -->|Firebolt APIs| RDKMW
    DSMgr -->|DS APIs| DS_HAL
    MFRMgr -->|mfrGetSerializedData / mfrWriteImage| MFRLIB

Key Features & Responsibilities:

• System State Aggregation (SysMgr): Maintains a central, queryable snapshot of RDK system readiness states — including HDMI output status, HDCP state, firmware download progress, network IP assignment, NTP synchronization, and boot completion — and broadcasts state-change events over the IARM Bus.
• Device Settings Management (DSMgr): Manages audio and video output ports by applying persisted and EDID-negotiated resolutions after boot, HDMI hot-plug, and HDCP authentication. Also handles EAS (Emergency Alert System) audio mode changes and propagates AV port and LED states through the PowerController interface.
• Manufacturer Library Bridge (MFRMgr): Exposes vendor manufacturer library functions — including serialized data read/write, flash image write/verify, PDRI deletion, bank scrubbing, bootloader pattern, thermal monitoring, and CPU clock management — as IARM RPC calls by dynamically loading the MFR shared library at runtime via dlopen.
• Disk Event Management (DISKMgr): Connects to the IARM Bus, registers disk events, and runs a signal-guarded loop to report disk-related state changes to peer processes.
• Device Update Coordination (DeviceUpdateMgr): Monitors configured filesystem paths for device update packages, coordinates download and load operations, and broadcasts update status events over the IARM Bus.
• Power State Integration: DSMgr connects to the WPEFramework PowerController plugin to receive power state transitions, applying corresponding AV port enable/disable and front-panel LED configurations at each state transition.

Design

The component follows a process-per-manager design where each sub-manager runs as an independent daemon with its own IARM Bus connection. Each daemon follows a common three-phase lifecycle: Start() (IARM registration and hardware initialization), Loop() (steady-state event processing), and Stop() (resource release and bus disconnection). This pattern ensures that each manager can restart independently without disrupting the others.

Southbound interaction with hardware is abstracted through Device Settings APIs for audio and video port management, and through the WPEFramework PowerController plugin interface for power state transitions. The MFR manager takes an additional layer of indirection by resolving all vendor functions at runtime via dlopen, allowing the same daemon binary to work across different platform hardware.

Northbound communication is entirely through the IARM Bus. Peer processes and higher-level middleware components subscribe to published events or invoke RPC methods. This decouples the managers from their consumers and allows multiple subscribers to receive the same state-change notification simultaneously.

Power state transitions are handled in DSMgr through a dedicated connection to the WPEFramework PowerController plugin using the PowerController_Connect() API. A retry thread ensures connection resiliency at startup. Once connected, power state events are dispatched to a dedicated handler thread that applies the appropriate AV port enable/disable and LED state transitions.

DSMgr uses a GLib main loop (GMainLoop) as its steady-state event processing framework. HDMI hot-plug events and resolution setting operations are serialized through the main loop via g_timeout_add_seconds and pthread_cond_signal, preventing race conditions between concurrent display events.

Configuration state (such as resolution preferences and HDCP profile) is read from the persistent store under /opt/persistent/ds and from system properties at /etc/device.properties. The platform profile (TV or STB) and geographic region (EU or non-EU) are detected at startup from device.properties and govern default resolution fallback behavior.

graph TD

    subgraph IARMMgrs["iarmmgrs (Daemon Processes)"]

        subgraph SYSMgr_Block["SysMgr Process"]
            SYS_INIT["IARM_Bus_Init / Connect\nRegisterEvent / RegisterCall"]
            SYS_STATE["System State Store\n(systemStates struct)"]
            SYS_EVT["_sysEventHandler\n(IARM event listener)"]
            SYS_RPC["RPC Handlers\nGetSystemStates\nSetHDCPProfile / GetHDCPProfile\nSet/GetKeyCodeLoggingPref"]
        end

        subgraph DSMgr_Block["DSMgr Process"]
            DS_INIT["IARM_Bus_Init / Connect\nDS HAL Init\nPowerController_Connect"]
            DS_GLOOP["GLib Main Loop\n(event dispatch)"]
            DS_HPD_THR["HDMI HPD Thread"]
            DS_RESN_THR["Resolution Thread"]
            DS_PWR_THR["Power Event Handler Thread"]
            DS_EVT["_EventHandler\n(SysMgr + DSMgr events)"]
            DS_PWR_EVT["_PwrEventHandler\n(PowerController callback)"]
        end

        subgraph MFRMgr_Block["MFRMgr Process"]
            MFR_INIT["IARM_Bus_Init / Connect\nRegisterCall for all MFR APIs"]
            MFR_DL["dlopen(RDK_MFRLIB_NAME)\ndlsym per API function"]
        end

        subgraph DISKMgr_Block["DISKMgr Process"]
            DISK_INIT["IARM_Bus_Init / Connect\nRegisterEvent"]
            DISK_LOOP["Signal-based loop\n(SIGTERM / SIGINT)"]
        end

        subgraph DevUpdateMgr_Block["DeviceUpdateMgr Process"]
            DU_INIT["IARM_Bus_Init / Connect\ndeviceUpdateStart"]
            DU_LOOP["Folder-watch loop\ndeviceUpdateRun"]
        end
    end

    subgraph External["External Systems"]
        IARMBUS[("IARM Bus Daemon")]
        PWR_CTRL["WPEFramework\nPowerController Plugin"]
        DS_HAL_EXT["Device Settings HAL"]
        MFRLIB_EXT["MFR Shared Library"]
    end

    SYS_INIT --> IARMBUS
    DS_INIT --> IARMBUS
    MFR_INIT --> IARMBUS
    DISK_INIT --> IARMBUS
    DU_INIT --> IARMBUS

    DS_INIT --> PWR_CTRL
    DS_INIT --> DS_HAL_EXT
    DS_PWR_EVT --> DS_HAL_EXT
    MFR_DL --> MFRLIB_EXT

Threading Model

• Threading Architecture: Multi-threaded (DSMgr); Single-threaded with event loop (SysMgr, MFRMgr, DISKMgr, DeviceUpdateMgr)
• Main Thread (DSMgr): Runs DSMgr_Start() for initialization then enters g_main_loop_run() for steady-state event dispatch.
• Worker Threads (DSMgr):
• HDMI/Resolution Thread (edsHDMIHPDThreadID, running _DSMgrResnThreadFunc): Monitors HDMI hot-plug and display events and applies EDID-negotiated or persisted video resolutions; waits on a condition variable until tune-ready or HDMI connection events arrive.
• Power Event Handler Thread (edsPwrEventHandlerThreadID, running dsMgrPwrEventHandlingThreadFunc): Drains the power event queue and executes AV port and LED state transitions for each power state change.
• PowerController Connection Thread (edsPwrConnectThreadID, running dsMgrPwrRetryEstablishConnThread): Retries PowerController_Connect() in a loop until the WPEFramework PowerController plugin is available, then detaches.
• Main Thread (SysMgr): Calls SYSMgr_Start() for IARM registration, then enters a heartbeat sleep loop in SYSMgr_Loop().
• Main Thread (MFRMgr): Calls MFRLib_Start() for IARM registration, then enters MFRLib_Loop().
• Synchronization: pthread_mutex_t / pthread_cond_t pairs protect the HDMI event state and resolution thread wakeup in DSMgr. A separate mutex (tdsPwrEventQueueMutexLock) guards the power event queue. SysMgr uses a single mutex (tMutexLock) to protect the systemStates structure and initialization flag. DeviceUpdateMgr uses std::mutex via RAII std::lock_guard.
• Async / Event Dispatch: IARM event callbacks are invoked on the IARM Bus thread; DSMgr uses pthread_cond_signal to hand off work to the HDMI/resolution thread, keeping the callback path short.

Prerequisites and Dependencies

• Build Dependencies: iarmbus, devicesettings, devicesettings-hal, rdk-logger, openssl, libsyswrapper, rfcapi, telemetry, boost, glib-2.0, dbus-1, yajl, curl, deepsleep-manager-headers, power-manager-headers, wpeframework-clientlibraries.
• Plugin Dependencies: wpeframework-powermanager — DSMgr connects to the PowerController plugin; dsmgr.service lists wpeframework-powermanager.service in After=.
• Device Services / HAL:
• Device Settings HAL for video and audio port management.
• MFR Library (resolved dynamically via dlopen at runtime using the path defined by RDK_MFRLIB_NAME).
• IARM Bus: All sub-managers register under their respective bus names: SYSMgr, DSMgr, MFRLib, DISKMgr, DeviceUpdateMgr.
• Systemd Services:
• sysmgr.service: Requires iarmbusd.service; starts after lighttpd.service and iarmbusd.service.
• dsmgr.service: Requires iarmbusd.service; starts after lighttpd.service, iarmbusd.service, sysmgr.service, and wpeframework-powermanager.service.
• mfrmgr.service: Requires iarmbusd.service; starts after iarmbusd.service and mfrlibapp.service.
• Configuration Files:
• /etc/device.properties — Platform profile and region detection (read at startup by rdkProfile.c and dsMgr.c).
• /etc/debug.ini or /opt/debug.ini — RDK Logger debug configuration (override path takes precedence).
• /opt/persistent/ds — Persistent device settings directory created by DSMgr service on start.
• /opt/.hdcp_profile_1 — HDCP profile persistence marker file managed by SysMgr.
• /opt/ddcDelay — Optional file controlling DDC retry count during HDMI resolution negotiation.
• /opt/deviceUpdateConfig.json, /mnt/nfs/env/deviceUpdateConfig.json, /etc/deviceUpdateConfig.json, or ./deviceUpdateConfig.json — Device Update Manager configuration: folder paths to monitor and download/load behavior (searched in that order).
• Startup Order: iarmbusd → sysmgr → wpeframework-powermanager → dsmgr; mfrlibapp → mfrmgr.

Component State Flow

Initialization to Active State

Each manager daemon follows a Start → Loop → Stop lifecycle. SysMgr initializes first (as required by dsmgr.service ordering), registers its system state structure and RPC handlers on the IARM Bus, then enters a heartbeat loop. DSMgr starts after SysMgr and the PowerController plugin are available; it initializes the DS HAL, queries the current tune-ready state from SysMgr, spawns worker threads, sets the initial video port resolution, and enters the GLib main loop. MFRMgr registers all MFR RPC handlers on the IARM Bus without loading the MFR library upfront; each RPC handler resolves its corresponding symbol via dlopen on first call.

sequenceDiagram
    participant System as systemd
    participant SYSMgr as SysMgr
    participant DSMgr as DSMgr
    participant MFRMgr as MFRMgr
    participant IARM as IARM Bus (iarmbusd)
    participant DS as Device Settings HAL
    participant PWR as PowerController (Thunder)

    System->>SYSMgr: Start sysmgr.service
    SYSMgr->>IARM: IARM_Bus_Init / Connect
    SYSMgr->>IARM: RegisterEvent(SYSMGR_EVENT_MAX)
    SYSMgr->>IARM: RegisterCall(GetSystemStates, SetHDCPProfile, GetKeyCodeLoggingPref, ...)
    SYSMgr->>IARM: RegisterEventHandler(SYSMGR_EVENT_SYSTEMSTATE)
    SYSMgr-->>System: sd_notify READY=1

    System->>DSMgr: Start dsmgr.service
    DSMgr->>IARM: IARM_Bus_Init / Connect
    DSMgr->>DS: dsVideoPort / dsAudio HAL init
    DSMgr->>IARM: IARM_Bus_Call(SYSMgr, GetSystemStates)
    IARM-->>DSMgr: systemStates.TuneReadyStatus
    DSMgr->>PWR: PowerController_Init()
    DSMgr->>PWR: PowerController_Connect (retry thread, async)
    PWR-->>DSMgr: Connection established
    DSMgr->>DS: _SetVideoPortResolution (initial resolution apply)
    DSMgr-->>System: sd_notify READY=1

    System->>MFRMgr: Start mfrmgr.service
    MFRMgr->>IARM: IARM_Bus_Init / Connect
    MFRMgr->>IARM: RegisterCall(mfrGetManufacturerData, mfrWriteImage, ...)
    MFRMgr-->>System: sd_notify READY=1

    loop Runtime
        IARM-->>SYSMgr: SYSMGR_EVENT_SYSTEMSTATE (state updates from peers)
        IARM-->>DSMgr: DSMGR_EVENT_HDMI_HOTPLUG / DSMGR_EVENT_HDCP_STATUS
        PWR-->>DSMgr: _PwrEventHandler callback (power state change)
    end

    System->>SYSMgr: Stop
    SYSMgr->>IARM: IARM_Bus_Disconnect / IARM_Bus_Term

    System->>DSMgr: Stop
    DSMgr->>PWR: PowerController_Term
    DSMgr->>IARM: IARM_Bus_Disconnect / IARM_Bus_Term

Runtime State Changes

During normal operation, DSMgr responds to HDMI hot-plug events by re-evaluating the connected display’s EDID and applying a compatible resolution. HDCP authentication events update the HDCP state in SysMgr’s global state structure and trigger or suppress EDID dumps. Power state transitions from the PowerController plugin cause DSMgr to enable or disable AV ports and front-panel LEDs via the Device Settings HAL.

State Change Triggers:

• HDMI hot-plug (connect/disconnect): DSMgr re-negotiates video resolution and broadcasts the HDCP state update to SysMgr via IARM_Bus_BroadcastEvent.
• HDCP authentication success/failure: DSMgr broadcasts IARM_BUS_SYSMGR_SYSSTATE_HDCP_ENABLED and conditionally triggers resolution application or EDID dump.
• Power state transitions (ON / STANDBY / STANDBY_LIGHT_SLEEP / STANDBY_DEEP_SLEEP / OFF): DSMgr’s power event handler applies AV port enable/disable, LED state, and HAL power state recording.
• Tune Ready event: DSMgr applies the persisted audio mode and unblocks the resolution thread.
• EAS mode change: DSMgr forces stereo audio during EAS and restores the previous mode when EAS ends.

Context Switching Scenarios:

• On receiving IARM_BUS_SYS_MODE_EAS, DSMgr switches audio output to stereo regardless of the persisted setting; it restores the saved mode upon EAS exit.
• On transitioning to POWER_STATE_STANDBY_DEEP_SLEEP, DSMgr’s power event handler responds by disabling video output ports and AV paths via the Device Settings HAL, coordinated through the PowerController plugin callback.

Call Flows

Initialization Call Flow

sequenceDiagram
    participant Systemd as systemd
    participant DSMgr as DSMgr (dsMgrMain)
    participant IARM as IARM Bus
    participant SYSMgr as SysMgr
    participant DS as Device Settings HAL
    participant PWR as PowerController

    Systemd->>DSMgr: fork / exec dsMgrMain
    DSMgr->>DSMgr: rdk_logger_init(debug.ini)
    DSMgr->>IARM: IARM_Bus_Init("DSMgr")
    IARM-->>DSMgr: Success
    DSMgr->>IARM: IARM_Bus_Connect
    DSMgr->>IARM: RegisterEventHandler(SYSMgr, SYSTEMSTATE)
    DSMgr->>IARM: RegisterEventHandler(DSMgr, HDMI_HOTPLUG / HDCP_STATUS)
    DSMgr->>IARM: RegisterCall(SysModeChange, SetStandbyVideoState, ...)
    DSMgr->>SYSMgr: IARM_Bus_Call(GetSystemStates)
    SYSMgr-->>DSMgr: systemStates.TuneReadyStatus
    DSMgr->>DS: dsVideoPort / dsDisplay / dsAudio init
    DSMgr->>DSMgr: setupPlatformConfig (detect EU/non-EU via device.properties)
    DSMgr->>PWR: PowerController_Init()
    DSMgr->>PWR: PowerController_Connect (retry thread, async)
    DSMgr->>DS: _SetVideoPortResolution (EDID-negotiated or persisted, via resolution thread)
    DSMgr-->>Systemd: sd_notify READY=1

Request Processing Call Flow

The following shows how DSMgr processes an HDMI hot-plug connect event and applies the appropriate output resolution.

sequenceDiagram
    participant HAL as HDMI HPD Driver
    participant IARM as IARM Bus
    participant DSMgr as DSMgr _EventHandler
    participant ResnThread as Resolution Thread
    participant DS as Device Settings HAL
    participant SYSMgr as SysMgr

    HAL->>IARM: IARM_BUS_DSMGR_EVENT_HDMI_HOTPLUG (connected)
    IARM->>DSMgr: _EventHandler callback
    DSMgr->>DSMgr: setBGColor(dsVIDEO_BGCOLOR_NONE)
    DSMgr->>ResnThread: pthread_cond_signal (unblock)
    ResnThread->>DS: _dsGetVideoPort(HDMI)
    ResnThread->>DS: _dsIsDisplayConnected
    DS-->>ResnThread: connected = true
    ResnThread->>DS: _dsGetEDID (edidData)
    DS-->>ResnThread: supported resolution list
    ResnThread->>DS: _dsSetResolution (best supported resolution)
    DS-->>ResnThread: dsERR_NONE
    ResnThread->>SYSMgr: IARM_Bus_BroadcastEvent(SYSMGR_SYSSTATE_HDMI_OUT, state=1)

Internal Modules

Component Interactions

Interaction Matrix

Events Published

IPC Flow Patterns

Primary Request / Response Flow:

IARM RPC calls are dispatched by the bus daemon to the registered handler function within the target manager process. The handler executes synchronously, reads or modifies the relevant hardware or state, and returns an IARM_Result_t status code that is relayed back to the caller.

sequenceDiagram
    participant Client as Client Process
    participant IARM as IARM Bus
    participant SYSMgr as SysMgr

    Client->>IARM: IARM_Bus_Call("SYSMgr", "GetSystemStates", param)
    IARM->>SYSMgr: Dispatch _GetSystemStates(arg)
    SYSMgr->>SYSMgr: Copy systemStates struct to param (mutex-protected)
    SYSMgr-->>IARM: IARM_RESULT_SUCCESS
    IARM-->>Client: Return populated param (system state snapshot)

Event Notification Flow:

Upon detecting a hardware or IARM event, the manager processes the event data and broadcasts a new event over the IARM Bus. All processes that have registered a handler for that event on that bus name receive the notification.

sequenceDiagram
    participant HDCP_HAL as DS HAL (HDCP Driver)
    participant IARM as IARM Bus
    participant DSMgr as DSMgr _EventHandler
    participant SYSMgr as SysMgr
    participant Other as Other Subscribers

    HDCP_HAL->>IARM: IARM_BUS_DSMGR_EVENT_HDCP_STATUS (authenticated)
    IARM->>DSMgr: _EventHandler callback
    DSMgr->>DSMgr: bHDCPAuthenticated = true, trigger resolution apply
    DSMgr->>IARM: IARM_Bus_BroadcastEvent("SYSMgr", SYSTEMSTATE, HDCP_ENABLED=1)
    IARM->>SYSMgr: _sysEventHandler (update systemStates.hdcp_enabled)
    IARM->>Other: Deliver SYSTEMSTATE event to all registered subscribersd

Implementation Details

Major HAL APIs Integration

Key Implementation Logic

• State / Lifecycle Management: SysMgr holds the systemStates structure as a single in-memory store, protected by tMutexLock. State fields are initialized to zero at startup (except hdcp_enabled.state which defaults to 1) and updated by _sysEventHandler as peers broadcast state transitions. DSMgr tracks HDMI connection state, HDCP authentication state (bHDCPAuthenticated), and tune-ready flag (iTuneReady) as module-level statics.
• Core SysMgr state: sysmgr/sysMgr.c
• DSMgr connection and HDCP tracking: dsmgr/dsMgr.c
• Power state machine: dsmgr/dsMgrPwrEventListener.c
• Event Processing: IARM event callbacks (_sysEventHandler in SysMgr, _EventHandler in DSMgr, _PwrEventHandler in DSMgr’s power listener) execute on the IARM Bus dispatch thread. DSMgr uses pthread_cond_signal to wake its resolution and HDMI threads, keeping callback processing minimal. Power events are queued (pwrEventQueue) and drained on the dedicated power event handler thread to decouple event receipt from hardware operation.
• Error Handling Strategy: Each IARM call return value is checked against IARM_RESULT_SUCCESS. Failures are logged via RDK Logger macros (INT_ERROR, INT_INFO). DS API errors during resolution negotiation cause DSMgr to fall back through a prioritized resolution list (2160p → 1080p → 1080i → 720p → 576p → 480p, region-dependent) before defaulting to 720p. MFRMgr returns IARM_RESULT_INVALID_STATE when the MFR library symbol cannot be resolved. Persistent retries are applied exclusively to the PowerController plugin connection; other IARM RPC failures are handled through logging and error code propagation.
• Logging & Diagnostics: Each manager uses the RDK Logger framework when RDK_LOGGER_ENABLED is defined at build time, falling back to printf otherwise.
• RDK Logger module names: LOG.RDK.DSMGR (DSMgr), LOG.RDK.MFRMGR (MFRMgr).
• DSMgr emits a heartbeat log message every 300 seconds via a GLib timer callback (heartbeatMsg).
• Debug configuration is read from /opt/debug.ini if present, otherwise from /etc/debug.ini.

Configuration

Key Configuration Files

Key Configuration Parameters

Runtime Configuration

The DDC retry count can be adjusted at runtime without recompilation:

# Set HDMI DDC retry count to 10 iterations (takes effect on next DSMgr start)
echo "10" > /opt/ddcDelay

The debug log verbosity can be overridden at runtime:

# Place a modified debug.ini to override the system default
cp /etc/debug.ini /opt/debug.ini
# Edit /opt/debug.ini to set desired module log levels
# Changes take effect on next manager restart

Configuration Persistence

• Resolution and audio mode selections are persisted by the Device Settings HAL layer in the /opt/persistent/ds directory and restored by DSMgr on the next initialization.
• The HDCP profile selection is persisted by SysMgr as a filesystem marker file (/opt/.hdcp_profile_1).
• The key code logging preference is maintained as a runtime in-memory flag in SysMgr (keyLogStatus) and resets to the default enabled state on each startup.
• All compile-time feature flags are embedded in the binary at build time and take effect when the binary is deployed.