IPC Implementation - C

Quick Example

The following is a minimal example for requesting the Cellular service data resource.

The example will trigger the following message sequence.

*   +------+                          +---------+
*   | user |                          | service |
*   +---+--+                          +----+----+
*       |     ipc_open_session_req         |
*       |--------------------------------->|
*       |     ipc_open_session_rsp         |
*       |<---------------------------------|
*       |     cellular_data_request_req    |
*       |--------------------------------->|
*       |     cellular_data_request_rsp    |
*       |<---------------------------------|
*       .                                  .
*       .                                  .

The code looks as follows. It is available in the demo actia-minimal-ipc-demo.

#define IPC_ID (A_IPC_GUEST_MIN_ID + 6)
#define IPC_OUTBOX_SIZE 10
#define IPC_INBOX_SIZE 15
A_IPC_STATIC_BUFFERS(ipc_buffers, IPC_INBOX_SIZE, IPC_OUTBOX_SIZE);

a_log_set_logger(a_log_stdout_logger);

int ret;
int epfd = epoll_create1(0);
struct epoll_event events[10];
int event_count;
int ipc_fd = 0;

a_ipc_handle *a_ipc = a_ipc_init(IPC_ID, &ipc_buffers);

A_IPC_MSG_ON_STACK(msg_buf, 256);

ipc_fd = a_ipc_get_fd(a_ipc);

events[0].events = EPOLLIN;
events[0].data.fd = ipc_fd;
ret = epoll_ctl(epfd, EPOLL_CTL_ADD, ipc_fd, events);
if (ret < 0) {
    perror("epoll_ctl ADD ipc_fd");
    return -1;
}

A_IPC_RESULT rc = a_ipc_init_ipc_open_session_req(msg_buf);
if (rc != A_IPC_RET_OK) {
    printf("Failed to create ipc open session request: %s\n", a_ipc_result_str(rc));
    return -2;
}
rc = a_ipc_send(a_ipc, A_SERVICE_ID_CELLULAR, msg_buf);
if (rc != A_IPC_RET_OK) {
    printf("Failed to send open session request: %s\n", a_ipc_result_str(rc));
    return -2;
}

int from;
bool run = true;
do {
    event_count = epoll_wait(epfd, events, a_membersof(events), -1);
    for (int i = 0; i < event_count; i++) {
        if (events[i].data.fd == ipc_fd) {
            rc = a_ipc_recv(a_ipc, &from, msg_buf);
            if (rc != 0) {
                printf("a_ipc_recv error: %d\n", rc);
                continue;
            }
            printf("Received msg type: %s\n",
                    a_ipc_msg_type_str(msg_buf->info.type));
            switch (msg_buf->info.type) {
             case A_IPC_MSG_IPC_OPEN_SESSION_RSP:
                a_ipc_init_cellular_data_request_req(msg_buf, 20);
                msg_buf->cellular_data_request_req.user.value = "demouser";
                msg_buf->cellular_data_request_req.user.length = strlen("demouser");

                rc = a_ipc_send(a_ipc, A_SERVICE_ID_CELLULAR, msg_buf);
                if (rc != A_IPC_RET_OK) {
                    printf("Failed to send open session request: %s\n", a_ipc_result_str(rc));
                    run = false;
                }
                break;
             case A_IPC_MSG_IPC_SESSION_CLOSED_IND:
                run = false;
                break;
             case A_IPC_MSG_CELLULAR_DATA_REQUEST_RSP:
                run = false;
                break;
            default:
                printf("Unknown command: %d\n", msg_buf->info.type);
                break;
            }
        }
    }
} while (run);

a_ipc_destroy(a_ipc);
return rc;

Note that production code should always check for errors and release resources when they are not needed anymore.

API

Initialization

The IPC framework is initialized by calling a_ipc_init() which returns a handle to the IPC instance. When done using IPC, the handle shall be destroyed using a_ipc_destroy().

The application needs to allocate inbox and outbox buffers and supply them to the a_ipc_init() call. This can be done with the macro A_IPC_STATIC_BUFFERS, which will allocate the buffers statically. (Static allocation is preferred when targeting smaller devices, such as the ACU6-Lite.)

Each peer must have a system-unique ID, which is used for addressing. IDs available to user applications are given by A_IPC_GUEST_MIN_ID and A_IPC_GUEST_MAX_ID (inclusive).

Each service provided by Actia has an ID (e.g. A_SERVICE_ID_CELLULAR).

The IPC framework interface is single-threaded, which means that calls to the framework must be done from the same calling thread. Note that it is possible to create multiple instances of IPC and use them from separate threads.

Messages

Each message is of a specific message type (msg->info.type), which in turn belongs to a message class.

A message is represented by an enum constant, for the type ID, and a struct. Refer to Data types for a description of the types that the message members can have.

An example message with its enum constant and struct:

A_IPC_MSG_RESOURCE_TRIGGER_RSP = 10

typedef struct {
    bool success;
    int counts[10];
    string message;
} a_ipc_msg_resource_trigger_rsp;

The sample below shows how to create a message and fill it with data

void my_function()
{
   A_IPC_MSG_ON_STACK(msg, 256);

   a_ipc_init_cellular_data_request_req(msg, 20);
   /* msg->info.type is now A_IPC_MSG_CELLULAR_DATA_REQUEST_REQ */

   msg->cellular_data_request_req.user.value = "demouser";
   msg->cellular_data_request_req.user.length = strlen("demouser");

   /* a_ipc_send(a_ipc, PEER_ID, msg); is often called here to
      send the message. */
}

The macros A_IPC_MSG_ON_STACK and A_IPC_STATIC_MSG create buffers of the given size and initializes the message metadata in the info member. Both make the given message an a_ipc_msg pointer.

The initialization is done using a_ipc_init_<msgtype>() and sets up the message buffer for the requested message type. If the message has dynamic length members (such as strings), the length to reserve for them in the buffer must be given.

A message buffer can be reused multiple times. One can change the values or change the message type by calling a_ipc_init_<msgtype>().

Sending messages

After initializing a message, it can simply be sent by a_ipc_send().

a_ipc_send(a_ipc, PEER_ID, msg);

Receiving messages

Messages are received into an inbox. a_ipc_recv() is used to fetch messages from the inbox. The msg parameter must point to a valid message buffer.

Since a_ipc_recv() is non-blocking, it might return A_IPC_RET_NO_MSG to indicate that no message has been received. Therefore, it’s recommended to use a_ipc_get_fd() to get the IPC file descriptor and listen for when it is ready for reading.

After receiving a message, the type (msg->info.type) can be used to determine how to interpret it and access the correct members. Always check that the return value is A_IPC_RET_OK or A_IPC_RET_SEND_ERROR before reading the message buffer.

A_IPC_STATIC_MSG(msg, 256);

int ipc_fd = a_ipc_get_fd();

/* epoll setup with ipc_fd */

while (true) {
   epoll_wait();

   int from;
   A_IPC_RESULT rc = a_ipc_recv(a_ipc, &from, msg);

   if (rc == A_IPC_RET_OK || rc == A_IPC_RET_SEND_ERROR) {
      switch (msg->info.type) {
         case A_IPC_MSG_CELLULAR_DATA_REQUEST_RSP:
            printf("Request resp: %d\n", msg->cellular_data_request_rsp.result);
            break;
      }
   }
}

Refer to the SDK demo applications for a full example of waiting for and receiving messages.

Data types

The generic message data types described in Data types is mapped into C language data types as follows:

Primitive types

Integers and booleans are stored as their corresponding C type, meaning a uint32 message parameter is stored as uint32_t

Strings

All strings should be NUL terminated, and strings in received or copied messages are always terminated. NUL-terminating input arguments is not needed, but recommended. Termination is added automatically.

Fixed length strings are represented as a char array of the strings length plus one.

Dynamic length strings is represented as a dynamic array of char with the difference that the length does not include the final NUL-termination.

Enumerations

Enumerations will have a corresponding C enumeration, so for example for ipc_send_error_reason there will be a a_ipc_enum_ipc_send_error_reason enum and its SEND_FAILED enumerator value will correspond to A_IPC_ENUM_IPC_SEND_ERROR_REASON_SEND_FAILED.

Structs

Internal structures will map to C structures, with name a_ipc_struct_foo. Nested members are handled just as direct message members.