IPC Utils Application Programming Interface (API): IPC Utils API Reference

  • Main Page
  • Related Pages

IPC Utils API Reference

ipcutils-a03

Modules

The IPC Utils product is made up of the following modules:

The Remote Command Message (RCM) package provides a client/server implementation for executing functions on a remote processor.

  • RCM Overview
  • RcmClient - Client Module
  • RcmServer - Server Module
Copyright 2012, Texas Instruments Incorporated


IPC Utils Application Programming Interface (API): Remote Command Message Overview

  • Main Page
  • Related Pages

Remote Command Message Overview

Modules

Remote Command Message - message based remote function execution

The Remote Command Message (RCM) package provides a client/server implementation for executing functions on a remote processor. The package contains the following modules.

  • RcmClient - Client Module
  • RcmServer - Server Module

This package provides modules for a client/server based implementation for executing functions on a remote processor. The IPC layer is based on messages. The application uses the RcmClient module to allocate a message, specify the remote function and its arguments, and then send the message to the server for execution. When the message returns, it contains the remote function's return values. The server is typically on a remote processor, but local server instances (on the same processor as the client) are also supported.

The following image provides an overview of a typical use case. An application running on the local cpu creates an RcmClient instance. Using the RcmClient instance handle, the application has access to all the necessary operations for executing a message on the remote server. The application must fill in the message with the remote function index, as supplied by the server, and the context needed by the remote function to execute. For higher level operations such as RPC, see the link ti.sdo.rpc.gen package which provides support for generating the stub and skeleton functions.

Diagram 1: RCM Overview

The RcmClient module is used to create instance objects. Each instance can send messages only to the server specified at create time. You create an instance for each server you want to send messages to. At create time the heap must be specified. The heap is used by the instance for allocating messages.

There are four types of execute commands:

  • synchronous blocking
  • synchronous non-blocking
  • synchronous deferred
  • asynchronous non-blocking

Here is an overview of the exec commands. See the RcmClient module for more details on each function.

  • RcmClient_exec() - synchronous blocking This function sends a message to the server and waits for the server to execute the message and to send the return message back to the client.
  • RcmClient_execNoWait() - synchronous non-blocking This function sends a message to the server but does not wait for the return message. Control returns to the caller as soon as the message has been delivered to the underlying transport. The server will execute the message and send the return message back to the client where it is placed in a mailbox. The client collects the return message with a call to RcmClient_waitUntilDone() which is a blocking call. This is useful when the client has more work to do while the remote function is executing. It is also efficient because it does not require a local callback thread.
  • RcmClient_execDpc() - synchronous deferred This function sends a message to the server and waits for the return message. When the server receives the message, it does not immediately execute it. Instead, it copies the message context into a local buffer and sends the message back to the client. Only after the message has been sent to the client, does the server execute the function. This is useful for server shutdown. This allows the client to regain ownership of the message and to return it to the heap and allows the server to shutdown without owning any resources allocated by the client.
  • RcmClient_execAsync() - asynchronous non-blocking This function sends a message to the server but does not wait for the return message. Control returns to the caller as in the synchronous non-blocking case above. The server will execute the message and send the return message back to the client for delivery to a callback thread. When the return message arrives, the callback thread will invoke an application callback to notify the application that the return message has arrived. This is the only asynchronous part of the sequence as the application will be preempted by the callback thread. It is the application's responsibility to periodically monitor a flag (set by the callback) to complete the message delivery.

RTSC Configuration

When using XDCtools to build your executable, use the following module to define the build time configuration options.

RCM Settings Module

Copyright 2012, Texas Instruments Incorporated


IPC Utils Application Programming Interface (API):

  • Main Page
  • Related Pages
disclaimer.html
IMPORTANT NOTICE
Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI's terms and conditions of sale supplied at the time of order acknowledgment.
TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI's standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed.
TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards.
TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of that third party, or a license from TI under the patents or other intellectual property of TI.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation.
Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements.
Mailing Address:
Texas Instruments
Post Office Box 655303
Dallas, Texas 75265
Copyright 2012, Texas Instruments Incorporated


IPC Utils Application Programming Interface (API): Graph Legend

  • Main Page
  • Related Pages

Graph Legend

This page explains how to interpret the graphs that are generated by doxygen.

Consider the following example:

/*! Invisible class because of truncation */
class Invisible { };

/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };

/* Class not documented with doxygen comments */
class Undocumented { };

/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };

/*! A template class */
template<class T> class Templ { };

/*! Class that is inherited using protected inheritance */
class ProtectedBase { };

/*! Class that is inherited using private inheritance */
class PrivateBase { };

/*! Class that is used by the Inherited class */
class Used { };

/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
                  protected ProtectedBase,
                  private PrivateBase,
                  public Undocumented,
                  public Templ<int>
{
  private:
    Used *m_usedClass;
};

This will result in the following graph:

The boxes in the above graph have the following meaning:

  • A filled gray box represents the struct or class for which the graph is generated.
  • A box with a black border denotes a documented struct or class.
  • A box with a grey border denotes an undocumented struct or class.
  • A box with a red border denotes a documented struct or class forwhich not all inheritance/containment relations are shown. A graph is truncated if it does not fit within the specified boundaries.

The arrows have the following meaning:

  • A dark blue arrow is used to visualize a public inheritance relation between two classes.
  • A dark green arrow is used for protected inheritance.
  • A dark red arrow is used for private inheritance.
  • A purple dashed arrow is used if a class is contained or used by another class. The arrow is labeled with the variable(s) through which the pointed class or struct is accessible.
  • A yellow dashed arrow denotes a relation between a template instance and the template class it was instantiated from. The arrow is labeled with the template parameters of the instance.
Copyright 2012, Texas Instruments Incorporated


IPC Utils Application Programming Interface (API): Page Index

  • Main Page
  • Related Pages

Related Pages

Here is a list of all related documentation pages:
  • Remote Command Message Overview
  • Disclaimer
Copyright 2012, Texas Instruments Incorporated