Table of Contents
maxLevel 2

...

Overview

IARM-Bus is a platform agnostic Inter-process communication (IPC) interface. It allows applications to communicate with each other by sending Events or invoking Remote Procedure Calls. The common programming APIs offered by the RDK IARM-Bus interface is independent of the operating system or the underlying IPC mechanism.

Two applications connected to a same instance of IARM-Bus are able to exchange events or RPC calls. On a typical system, only one instance of IARM-Bus instance is needed. If desired, it is possible to have multiple IARM-Bus instances. However, applications connected to different buses will not be able to communicate with each other.

...

Bus Daemon

Each Bus Instance is managed by a single Bus Daemon Process. The Bus Daemon oversees the activities on the bus and manage common resources competed by all connected applications. Applications requesting a shared resource must firstly acquire Ownership from the Bus Daemon. Once it is done with the resource, it must release the ownership back to Bus Daemon so that other applications can use the resource. The IARM Bus Daemon offers standard APIs to request and release ownership of a resource. In Essence, a Bus Daemon itself is a regular applications connected to the IARM-Bus with special privileges. It is the only entity that has knowledge of all applications connected to the bus, and has the authority of granting or denying resources.

...

Well-Known Name

Each application that connected to the bus must identify itself with a unique name. This name is considered well-known in that it is used by other applications to send events or invoke RPC calls published by the application. The well-known name thus is considered part of the public API interface published by the application. The Bus daemon's well-known name is "Daemon".

An application's well-known name is only visible to the bus that it connects to. When concatenated with the IARM-bus name com.comcast.rdk.iarm.bus, it becomes the application's universally unique identifier.

...

Programming Guidelines

As explained above, IARM-Bus offers two basic functionalities:

...

We will use IR Manager's implementation to illustrate how to use IARM-Bus APIs to publish, send, receive and handle Events, as well as publish and invoke RPC Methods. 
This document explains the usage of IARM-Bus APIs by example. For a full API specification please refer to IARM's public header files or doxygen document.

...

How to Create, Send, and Receive Events

Declare Well-Known Name in Header File

...

        IARM_Result_t IARM_Bus_RegisterEventHandler(const char *ownerName, IARM_EventId_t eventId, IARM_EventHandler_t handler);

• Implement the handler.

...

How to Create and Invoke RPC Methods

Declare Well-Known Name in Header File

...

        IARM_Result_t IARM_Bus_Call(const char *ownerName, const char *methodName, void *arg, size_t argLen);

...

 Decouples Applications from IARM

The RPC methods exposed via IARM can be called by multiple applications, so they are also named Multiple-App APIs. In contract, the regular C functions that can only be invoked from within the same Linux process that implements the C functions are named Single-App APIs. Sometimes, it is desirable that the application is decoupled from such API difference. In this case, the developer should provide a generic API that can be linked to either a local C method or a RPC method at build time.
In our example, IR Manager exports RPC API "SetRepeatInterval". To invoke this method, the application executes:

...

 IRMgr_SetRepeatInterval(int newInterval) 
 {
     IARM_Bus_IRMgr_SetRepeatInterval_Param_t param;
     param.timeoutNewValue = 200;
     IARM_Bus_Call (
         IARM_BUS_IRMGR_NAME, /* Owner of the Method */
         IARM_BUS_IRMGR_API_SetRepeatInterval,/* Name of Method */
         (void )&param, / Parameter of Method */
         sizeof(param)); /* Length of the Parameter */ 
     )
 }

...

Short-Term Approach

To invoke the same API, application now calls IRMgr_SetRepeatInterval().
A quick approach to decouple application from IARM is to define the generic API IRMgr_SetRepeatInterval() as inline function. In our example, we would include this in the irMgr.h.

...

 In this approach, the application is decoupled from IARM. However, application cannot use the same API for Single-App version. This may be enough for most applications who at this point does not need a single-app version of the same API.

...

Long-Term Approach

If an application may use the same API's single-app version, the following changes are needed.
To invoke the same API, application now calls IRMgr_SetRepeatInterval(), which must be implemented as an actual function that has external linkage.

...

 static IARM_Result_t _SetRepeatInterval(void *arg)
 {
     /* First cast the argument to its target type */
     IARM_Bus_IRMgr_SetRepeatInterval_Param_t 
     *param = (IARM_Bus_IRMgr_SetRepeatInterval_Param_t *)arg; 
     IRMgr_SetRepeatInterval(parma->newInterval);
 } 

 Where Where IRMgr_SetRepeatInterval()changes the actual settings. 
Now, we have at our hands two implementations of a same generic API IRMgr_SetRepeatInterval:

 TheThe RPC Client / Multi App Version:

 IRMgr_SetRepeatInterval(int newInterval) 
 {
     IARM_Bus_IRMgr_SetRepeatInterval_Param_t param;
     param. timeoutNewValue = 200;
     IARM_Bus_Call (
         IARM_BUS_IRMGR_NAME, 			/* Owner of the Method */
         IARM_BUS_IRMGR_API_SetRepeatInterval,	/* Name of Method */
         (void )&param, 			/* Parameter of Method */
         sizeof(param)); 			/* Length of the Parameter */ 
     )
 }

...

 The application can then choose which implementation to link to at build time based on its needs. To use the multi-app version of API, the application links to libirMgrCli.so. To use the single-app version of the API, the application links to libirMgr.so. In either choice, the application is no longer coupled to IARM. The following diagrams demonstrate the linkage relationship between applications and the generic API.

...

Porting layer of IARM-Bus

Most IARM Applications are not Manager Components. Rather they are connected to IARM bus only to utilize the service provided by various IARM-Bus Managers. These applications can maximum their platform independency by interfacing to only the common APIs of the IARM Bus.

 Meanwhile, depending on the events being published or the dependency that an RPC method implementation may have, some part of an IARM Manager Component may be platform specific.
It is up to the developer of the manager component to craft out and abstract the platform specific portion of the manager implementation. In the IR Manager example we used, the manager receives IR signals from PIC drivers in different ways on different platforms. This difference is abstract to a PLAT_API interface defined in an internal header file plat.h, and allows most of IR Manager implementation to remain platform agnostic. 

...

Core IARM-Bus Manager Components

By default, the IARM-Bus has the following Manager Components. The published events and RPC methods from these manager components can be found in their public header files.
On a standard system, you should see the following 3 processes running before executing your own application.

ps -aef|grep Mgr*
 root 1042 1 0 00:00 ? 00:00:00 ./IARMDaemonMain
 root 1083 1 0 00:00 ? 00:00:00 ./irMgrMain
root 1117 1 0 00:00 ? 00:00:00 ./pwrMgrMainIARM 

Bus Daemon

Executable name is IARMDaemonMain. The IARM Bus Daemon is a Manager Component with special privileges. 

...

Executable name is pwrMgrMain. This manager monitors Power IR key events and react to power state changes based on RDK Power Management Specification. It dispatches Power Mode Change events to IARM-Bus. All listeners should releases resources when entering POWER OFF/STANDBY state and reacquire them when entering POWER ON state.

...

Troubleshooting

 Before you try out a new IARM-Application, please make sure the following components are properly running on your box:

...