1 /*
2 * Copyright (c) 2011-2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*
33 * This is a little header file which doxygen parses to generate the main
34 * documentation page for the ti.rcm package.
35 */
37 /*!
38 * @page ti_rcm Remote Command Message Overview
39 *
40 * @section modules Modules
41 *
42 * Remote Command Message - message based remote function execution
43 *
44 * The Remote Command Message (RCM) package provides a client/server
45 * implementation for executing functions on a remote processor. The
46 * package contains the following modules.
47 * - @ref ti_rcm_RcmClient "RcmClient" - Client Module
48 * - @ref ti_rcm_RcmServer "RcmServer" - Server Module
49 *
50 * This package provides modules for a client/server based implementation
51 * for executing functions on a remote processor. The IPC layer is based
52 * on messages. The application uses the RcmClient module to allocate a
53 * message, specify the remote function and its arguments, and then send
54 * the message to the server for execution. When the message returns, it
55 * contains the remote function's return values. The server is typically
56 * on a remote processor, but local server instances (on the same processor
57 * as the client) are also supported.
58 *
59 * The following image provides an overview of a typical use case. An
60 * application running on the local cpu creates an RcmClient instance.
61 * Using the RcmClient instance handle, the application has access to all
62 * the necessary operations for executing a message on the remote server.
63 * The application must fill in the message with the remote function
64 * index, as supplied by the server, and the context needed by the remote
65 * function to execute. For higher level operations such as RPC, see the
66 * <tt>link ti.rpc.gen</tt> package which provides support for generating
67 * the stub and skeleton functions.
68 *
69 * @image html ti/rcm/doc-files/Overview.png "Diagram 1: RCM Overview"
70 *
71 * The RcmClient module is used to create instance objects. Each instance
72 * can send messages only to the server specified at create time. You
73 * create an instance for each server you want to send messages to. At
74 * create time the heap must be specified. The heap is used by the instance
75 * for allocating messages.
76 *
77 * There are four types of execute commands:
78 * - synchronous blocking
79 * - synchronous non-blocking
80 * - synchronous deferred
81 * - asynchronous non-blocking
82 *
83 * Here is an overview of the exec commands. See the
84 * @ref ti_rcm_RcmClient "RcmClient" module for more details on each
85 * function.
86 *
87 * - RcmClient_exec() - synchronous blocking
88 * This function sends a message to the server and waits for the server
89 * to execute the message and to send the return message back to the
90 * client.
91 *
92 * - RcmClient_execNoWait() - synchronous non-blocking
93 * This function sends a message to the server but does not wait for the
94 * return message. Control returns to the caller as soon as the message
95 * has been delivered to the underlying transport. The server will
96 * execute the message and send the return message back to the client
97 * where it is placed in a mailbox. The client collects the return message
98 * with a call to RcmClient_waitUntilDone() which is a blocking call.
99 * This is useful when the client has more work to do while the remote
100 * function is executing. It is also efficient because it does not require
101 * a local callback thread.
102 *
103 * - RcmClient_execDpc() - synchronous deferred
104 * This function sends a message to the server and waits for the return
105 * message. When the server receives the message, it does not immediately
106 * execute it. Instead, it copies the message context into a local buffer
107 * and sends the message back to the client. Only after the message has
108 * been sent to the client, does the server execute the function. This is
109 * useful for server shutdown. This allows the client to regain ownership
110 * of the message and to return it to the heap and allows the server to
111 * shutdown without owning any resources allocated by the client.
112 *
113 * - RcmClient_execAsync() - asynchronous non-blocking
114 * This function sends a message to the server but does not wait for the
115 * return message. Control returns to the caller as in the synchronous
116 * non-blocking case above. The server will execute the message and send
117 * the return message back to the client for delivery to a callback
118 * thread. When the return message arrives, the callback thread will
119 * invoke an application callback to notify the application that the
120 * return message has arrived. This is the only asynchronous part of the
121 * sequence as the application will be preempted by the callback thread.
122 * It is the application's responsibility to periodically monitor a flag
123 * (set by the callback) to complete the message delivery.
124 *
125 * <h2>RTSC Configuration</h2>
126 *
127 * When using XDCtools to build your executable, use the following module
128 * to define the build time configuration options.
129 *
130 * @rtsc(ti.rcm.Settings RCM Settings Module)
131 */