/*
* Copyright (c) 2011-2013, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* * Neither the name of Texas Instruments Incorporated nor the names of
* its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
* ======== RcmClient.h ========
*
*/
/*!
* @file ti/grcm/RcmClient.h
*
* @brief Remote Command Message Client Module. An RcmClient is used
* for sending messages to an RcmServer for processing.
*
* @sa RcmServer.h
* @ref ti_grcm "RCM Overview"
*/
/*!
* @defgroup ti_grcm_RcmClient RcmClient
*
* @brief Remote Command Message Client Module. An RcmClient is used
* for sending messages to an RcmServer for processing.
*
* The RcmClient module is used to send messages to an RcmServer for
* processing. An RcmClient instance must be created which will
* communicate with a single RcmServer instance. An RcmServer instance
* can receive messages from many RcmClient instances but an RcmClient
* instance can send messages to only one RcmServer instance.
*
*
Error Handling
*
* Errors may be raised at various points in the execution flow of a
* single message. These are the types of errors raised by RCM:
* - RCM Errors
* - User Errors
* - Message Function Errors
* - Library Function Errors
*
* The following diagram illustrates the call flow and highlights the
* points at which errors can be raised.
*
* @image html ti/grcm/doc-files/ExecFlow.png "Diagram 1: Execution Flow"
*
* RCM errors are raised by the RCM implementation. For example, when
* calling RcmClient_exec(), it may raise an error if it
* is unable to send the message. This will be reported immediately to
* the caller, the server is never involved. This is highlighted in the
* diagram at point [A].
*
* RCM errors may also be raised by the RcmServer. Once RcmClient_exec()
* sends a message, it waits for the return message. When the server
* receives the message, it has to decode its type. If this fails, the
* server records this error in the message and sends it back to the
* client. This is highlighted at point [B] in the diagram. When
* RcmClient_exec() receives the return message, it inspects the status
* field and recognizes the error. It then raises an appropriate error
* to the caller.
*
* User errors are raised by RCM as a result of an invalid runtime
* condition. They are typically detected and raised by the server and
* then sent back to the client for processing. For example, when the
* server receives a message, it will lookup the function index in it's
* table and invoke the corresponding message function. If the index is
* invalid, this is detected by the server and reported as an error.
* The message function is never invoked. The message is returned to
* the client and RcmClient_exec() will raise the appropriate error.
* This error is raised at point [B] in the diagram.
*
* Message function errors are raised by the message function itself.
* This is highlighted at point [C] in the diagram. In the body of the
* message function, an error is encountered either when calling a
* framework function or when unmarshalling the arguments from the
* message payload. In both cases, the message function will abort and
* return an error value as its return value. The error value must be
* less than zero (< 0). When control returns to the server, it inspects
* the message function's return value. If the message was sent by
* RcmClient_exec(), then the server simply stores the return value in
* the message and returns it to the client. However, if the message was
* send by RcmClient_execCmd(), the behavior is slightly
* different. If the return value is < 0 (error condition), then the
* server behaves the same as for the RcmClient_exec() case. However,
* if there is no error, the server simply frees the message. The message
* is never returned to the client.
*
* Library functions errors are raised by the library functions invoked
* by the message function, highlighted at point [D] in the diagram. It
* is the responsibility of the message function to detect a library
* function error and to marshal the appropriate error code into the
* message payload. The message function must also return an error value
* (< 0) so that server can do proper error handing as described
* in the preceeding paragraph. It is the stub function's responsibility
* to unmarshal the error value from the message payload and take the
* appropriate action.
*
* Understanding the types of errors raised by RCM and where they are
* raised is important when writing the upper layer software. The following
* code fragment illustrates how to check for the errors discussed above.
* See Error Handling above.
*
* @code
* RcmClient_Message *msg;
*
* // send message
* status = RcmClient_exec(h, msg, &msg);
*
* // check for error
* switch (status) {
*
* case RcmClient_S_SUCCESS:
* // no error, all is well
* break;
*
* case RcmClient_E_EXECFAILED:
* // RCM error, unable to send message
* :
* break;
*
* case RcmClient_E_INVALIDFXNIDX:
* // user error, bad function index
* :
* break;
*
* case RcmClient_E_MSGFXNERROR:
* // decode message function error
* msgFxnErr = msg->result;
* :
* // decode library function error
* libFxnErr = msg->data[0];
* :
* break;
* }
*
* // free message if one was returned
* if (msg != NULL) {
* RcmClient_free(h, msg);
* msg = NULL;
* }
* @endcode
*
* The upper layer software begins by calling RcmClient_exec()
* to send the message to the server. If RCM encounters a transport error
* and is unable to send the message, an RcmClient_E_EXECFAILED error is
* returned.
*
* If the server encounters an error while decoding the message, say an
* invalid function index, the server returns the message and an
* RcmClient_E_INVALIDFXNIDX error is returned.
*
* If the message function or the library function encounter an error,
* the message is returned and an RcmClient_E_MSGFXNERROR error is
* returned. The upper layer software must decode the results field to
* see what error the message function returned. If the library function
* returned an error, its error code must be unmarshalled from the payload.
* This is illustrated by decoding the first word in the payload
* (msg->data[0]). The actual marshal format is implementation specific.
*
* The message function must return >=0 for success, <0 for error.
* Here is a very simple message function which simply turns on an LED.
*
* @code
* Int32 Led_On(UInt32 size, UInt32 *data)
* {
* Ptr led = ;
*
* *led = 1; // turn on LED
* return(0); // success
* }
* @endcode
*
* In this example, the message payload is not used. The message function
* does all the work, it just sets a bit in the LED control register, and
* returns success.
*
* This next example illustrates a very simple RPC style skel function.
* It unmarshalls two arguments and invokes the libraray function. If the
* library function succeeds, the message function returns 0, otherwise it
* returns -1 to indicate failure. In both cases, the library function's
* return value is marshalled into the payload. The calling stub function
* can umarshal the return value to get the library function's error code.
*
* @code
* Int32 MediaSkel_process(UInt32 size, UInt32 *data)
* {
* Int a, b, x;
* Int32 status = 0; // success
*
* // unmarshal args
* a = (Int)data[1];
* b = (Int)data[2];
*
* // invoke library function, returns >=0 on success
* x = Media_process(a, b);
*
* // marshal return value
* data[0] = (Int32)x;
*
* // return status
* return(x >= 0 ? 0 : -1);
* }
* @endcode
*
* @sa ti_grcm_RcmServer
* @ref ti_grcm "RCM Overview"
*/
#ifndef ti_grcm_RcmClient__include
#define ti_grcm_RcmClient__include
#include
/** @ingroup ti_grcm_RcmClient */
/*@{*/
#if defined (__cplusplus)
extern "C" {
#endif
/* -------- status codes --------*/
/*!
* @brief Success return code
*/
#define RcmClient_S_SUCCESS (0)
/*!
* @brief General failure return code
*/
#define RcmClient_E_FAIL (-1)
/*!
* @brief The client has not been configured for asynchronous notification
*
* In order to use the RcmClient_execAsync() function, the RcmClient
* must be configured with callbackNotification set to true in the
* instance create parameters.
*/
#define RcmClient_E_EXECASYNCNOTENABLED (-2)
/*!
* @brief The client was unable to send the command message to the server
*
* An IPC transport error occurred. The message was never sent to the server.
*/
#define RcmClient_E_EXECFAILED (-3)
/*!
* @brief A heap id must be provided in the create params
*
* When an RcmClient instance is created, a heap id must be given
* in the create params. This heap id must be registered with MessageQ
* before calling RcmClient_create().
*/
#define RcmClient_E_INVALIDHEAPID (-4)
/*!
* @brief Invalid function index
*
* An RcmClient_Message was sent to the server which contained a
* function index value (in the fxnIdx field) that was not found
* in the server's function table.
*/
#define RcmClient_E_INVALIDFXNIDX (-5)
/*!
* @brief Message function error
*
* There was an error encountered in either the message function or
* the library function invoked by the message function. The semantics
* of the error code are implementation dependent.
*/
#define RcmClient_E_MSGFXNERROR (-6)
/*!
* @brief An unknown error has been detected from the IPC layer
*
* Check the error log for additional information.
*/
#define RcmClient_E_IPCERROR (-7)
/*!
* @brief Failed to create the list object
*/
#define RcmClient_E_LISTCREATEFAILED (-8)
/*!
* @brief The expected reply message from the server was lost
*
* A command message was sent to the RcmServer but the reply
* message was not received. This is an internal error.
*/
#define RcmClient_E_LOSTMSG (-9)
/*!
* @brief Insufficient memory to allocate a message
*
* The message heap cannot allocate a buffer of the requested size.
* The reported size it the requested data size and the underlying
* message header size.
*/
#define RcmClient_E_MSGALLOCFAILED (-10)
/*!
* @brief The client message queue could not be created
*
* Each RcmClient instance must create its own message queue for
* receiving return messages from the RcmServer. The creation of
* this message queue failed, thus failing the RcmClient instance
* creation.
*/
#define RcmClient_E_MSGQCREATEFAILED (-11)
/*!
* @brief The server message queue could not be opened
*
* Each RcmClient instance must open the server's message queue.
* This error is raised when an internal error occurred while trying
* to open the server's message queue.
*/
#define RcmClient_E_MSGQOPENFAILED (-12)
/*!
* @brief The server returned an unknown error code
*
* The server encountered an error with the given message but
* the error code is not recognized by the client.
*/
#define RcmClient_E_SERVERERROR (-13)
/*!
* @brief The server specified in the create params was not found
*
* When creating an RcmClient instance, the specified server could not
* be found. This could occur if the server name is incorrect, or
* if the RcmClient instance is created before the RcmServer. In such an
* instance, the client can retry when the RcmServer is expected to
* have been created.
*/
#define RcmClient_E_SERVERNOTFOUND (-14)
/*!
* @brief The given symbol was not found in the server symbol table
*
* This error could occur if the symbol spelling is incorrect or
* if the RcmServer is still loading its symbol table.
*/
#define RcmClient_E_SYMBOLNOTFOUND (-15)
/*!
* @brief There is insufficient memory left in the heap
*/
#define RcmClient_E_NOMEMORY (-16)
/*!
* @brief The given job id was not found on the server
*
* When releasing a job id with a call to RcmClient_releaseJobId(),
* this error return value indicates that the given job id was not
* previously allocated with a call to RcmClient_acquireJobId().
*/
#define RcmClient_E_JOBIDNOTFOUND (-17)
/* -------- constants and types --------*/
/*!
* @brief Invalid function index
*/
#define RcmClient_INVALIDFXNIDX ((UInt32)(0xFFFFFFFF))
/*!
* @brief Invalid heap id
*/
#define RcmClient_INVALIDHEAPID ((UInt16)(0xFFFF))
/*!
* @brief Invalid message id
*/
#define RcmClient_INVALIDMSGID (0)
/*!
* @brief Default worker pool id
*
* The default worker pool is used to process all anonymous messages.
* When a new message is allocated, the pool id property is
* initialized to this value.
*/
#define RcmClient_DEFAULTPOOLID ((UInt16)(0x8000))
/*!
* @brief Invalid job stream id
*
* All discrete messages must have their jobId property set to this value.
* When a new message is allocated, the jobId property is initialized tothis value.
*/
#define RcmClient_DISCRETEJOBID (0)
/*!
* @brief RcmClient instance object handle
*/
typedef struct RcmClient_Object_tag *RcmClient_Handle;
/*!
* @brief Remote Command Message structure
*
* An RcmClient needs to fill in this message before sending it
* to the RcmServer for execution.
*/
typedef struct {
/*!
* @brief The worker pool id that will process this message.
*
* The message will be processed by a worker thread from the worker
* pool specified in this field. The default value is the default
* pool id.
*/
UInt16 poolId;
/*!
* @brief The job id associated with this message.
*
* All messages beloging to a job id must have this field set to
* that id. Use the value RcmClient_DISCRETEJOBID if the message
* does not belong to any job.
*/
UInt16 jobId;
/*!
* @brief The index of the remote function to execute.
*/
UInt32 fxnIdx;
/*!
* @brief The return value of the remote message function.
*/
Int32 result;
/*!
* @brief The size of the data buffer (in chars).
*
* This field should be considered as read-only. It is set by
* the call to the RcmClient_alloc() function.
*/
UInt32 dataSize;
/*!
* @brief The data buffer containing the message payload.
*
* The size of this field is dataSize chars. The space is allocated
* by the call to the RcmClient_alloc() function.
*/
UInt32 data[1];
} RcmClient_Message;
/*!
* @brief Callback function type
*
* When using callback notification, the application must supply a
* callback function of this type. The callback will be invoked with
* the pointer to the RcmClient_Message returned from the server and
* the application data pointer supplied in the call to RcmClient_execAsync().
*/
typedef Void (*RcmClient_CallbackFxn)(RcmClient_Message *, Ptr);
/*!
* @brief Instance create parameters
*/
typedef struct {
/*!
* @brief The heapId used by this instance for allocating messages
*
* If sending messages to a remote server, the specified heap must
* be compatible with the transport used for delivering messages
* to the remote processor.
*/
UInt16 heapId;
/*!
* @brief Asynchronous callback notification support
*
* When remote functions submitted with RcmClient_execAsync()
* complete, the given callback function is invoked. The callback
* function executes in the context of this RcmClient instance's
* callback server thread.
*
* This config param must be set to true when using RcmClient_execAsync()
* to execute remote functions.
*
* When set to false, the callback server thread is not created.
*/
Bool callbackNotification;
} RcmClient_Params;
/*!
* @brief Opaque client structure large enough to hold an instance object
*
* Use this structure to define an embedded RcmClient object.
*
* @sa RcmClient_construct
*/
typedef struct {
xdc_runtime_knl_GateThread_Struct _f1;
Ptr _f2;
Ptr _f3;
UInt16 _f4;
Ptr _f5;
UInt32 _f6;
Bool _f7;
UInt16 _f8;
Ptr _f9;
Ptr _f10;
Ptr _f11;
Ptr _f12;
} RcmClient_Struct;
/* -------- functions --------*/
/*
* ======== RcmClient_acquireJobId ========
*/
/*!
* @brief Get a job id from the server
*
* Acquire a unique job id from the server. The job id is used to associate
* messages with a common job id. The server will process all messages for
* a given job id in sequence.
*/
Int RcmClient_acquireJobId(
RcmClient_Handle handle,
UInt16 * jobId
);
/*
* ======== RcmClient_addSymbol ========
*/
/*!
* @brief Add a symbol and its address to the server table
*
* This function is used by the client to dynamically load a new
* function address into the server's function pointer table. The
* given address must be in the server's address space. The function
* must already be loaded into the server's memory.
*
* This function is useful when dynamically loading code onto the
* remote processor (as in the case of DLL's).
*
* @param[in] handle Handle to an instance object
*
* @param[in] name The function's name.
*
* @param[in] addr The function's address as specified in the
* remote processor's address space.
*
* @param[out] index The function's index value to be used in the
* RcmClient_Message.fxnIdx field.
*
* @retval RcmClient_S_SUCCESS Success
* @retval RcmClient_E_FAIL Failure
*/
Int RcmClient_addSymbol(
RcmClient_Handle handle,
String name,
Fxn addr,
UInt32 * index
);
/*
* ======== RcmClient_alloc ========
*/
/*!
* @brief Allocate a message from the heap configured for this instance
*
* When a message is allocated, the RcmClient instance is the owner
* of the message. All messages must be returned to the heap by
* calling RcmClient_free().
*
* During a call to all of the exec functions, the ownership of the
* message is temporarily transfered to the server. If the exec
* function returns an RcmClient_Message pointer, then ownership of
* the message is returned to the instance. For the other exec
* functions, the client acquires ownership of the return message
* by calling RcmClient_waitUntilDone().
*
* A message should not be accessed when ownership has been given
* away. Once ownership has been reacquired, the message can be
* either reused or returned to the heap.
*
* @param[in] handle Handle to an instance object
*
* @param[in] dataSize Specifies (in chars) how much space to allocate
* for the RcmClient_Message.data array. The actual memory allocated
* from the heap will be larger as it includes the size of the
* internal message header.
*
* @param[out] message A pointer to the allocated message or NULL on error.
*/
Int RcmClient_alloc(
RcmClient_Handle handle,
UInt32 dataSize,
RcmClient_Message ** message
);
/*
* ======== RcmClient_checkForError ========
*/
/*!
* @brief Check if an error message has been returned from the server
*
* When using RcmClient_execCmd() to send messages to the server, the
* message will be freed by the server unless an error occurs. In the
* case of an error, the message is returned to the client. Use this
* function to check for and to retrieve these error messages.
*
* Note that the latency of the return message is dependent on many
* system factors. In particular, the server's response time to processing
* a message will be a significant factor. It is possible to call
* RcmClient_execCmd() several times before any error message is returned.
* There is no way to know when all the messages have been processed.
*
* The return value of RcmClient_checkForError() is designed to mimic
* the return value of RcmClient_exec(). When an error message is returned
* to the caller, the return value of RcmClient_checkForError() will be
* the appropriate error code as if the error had occured during a call
* to RcmClient_exec(). For example, if a message is prepared with an
* incorrect function index, the return value from RcmClient_exec() would
* be RcmClient_E_INVALIDFXNIDX. However, the same message sent with
* RcmClient_execCmd() will not return an error, because the function does
* not wait for the return message. When the server receives the message
* and detects the function index error, it will return the message to
* the client on a special error queue. The subsequent call to
* RcmClient_checkForError() will pickup this error message and return
* with a status value of RcmClient_E_INVALIDFXNIDX, just as the call
* to RcmClient_exec() would have done.
*
* A return value of RcmClient_S_SUCCESS means there are no error messages.
* This function will never return a message and a success status code at
* the same time.
*
* When this function returns an error message, the caller must return
* the message to the heap by calling RcmClient_free().
*
* It is possible that RcmClient_checkForError() will return with an error
* but without an error message. This can happen when an internal error
* occurs in RcmClient_checkForError() before it has checked the error
* queue. In this case, an error is returned but the returnMsg argument
* will be set to NULL.
*
* @param[in] handle Handle to an instance object
*
* @param[out] returnMsg A pointer to the error message or NULL if there
* are no error messages in the queue.
*
* @retval RcmClient_S_SUCCESS
* @retval RcmClient_E_IPCERROR
* @retval RcmClient_E_INVALIDFXNIDX
* @retval RcmClient_E_MSGFXNERROR
* @retval RcmClient_E_SERVERERROR
*/
Int RcmClient_checkForError(
RcmClient_Handle handle,
RcmClient_Message ** returnMsg
);
/*
* ======== RcmClient_construct ========
*/
/*!
* @brief Initialize a new instance object inside the provided structure
*
* This function is the same as RcmClient_create() except that it does not
* allocate memory for the instance object. The instance object is
* constructed inside the provided structure. Call RcmClient_destruct()
* to finalize a constructed instance object.
*
* @param[in] structPtr A pointer to an allocated structure.
*
* @param[in] server The name of the server that messages will be sent to for
* executing commands. The name must be a system-wide unique name.
*
* @param[in] params The create params used to customize the instance object.
*
* @sa RcmClient_create
*/
Int RcmClient_construct(
RcmClient_Struct * structPtr,
String server,
const RcmClient_Params *params
);
/*
* ======== RcmClient_create ========
*/
/*!
* @brief Create an RcmClient instance
*
* The RcmClient instance is used by the application to send messages to
* an RcmServer for executing remote functions. A given
* instance can send messages only to the server it was configured
* for. If an application needs to send messages to multiple servers,
* then create an RcmClient instance for each server.
*
* The assigned server to this instance must already exist and be
* running before creating RcmClient instances which send messages to it.
*
* @param[in] server The name of the server that messages will be sent to for
* executing commands. The name must be a system-wide unique name.
*
* @param[in] params The create params used to customize the instance object.
*
* @param[out] handle An opaque handle to the created instance object.
*/
Int RcmClient_create(
String server,
const RcmClient_Params *params,
RcmClient_Handle * handle
);
/*
* ======== RcmClient_delete ========
*/
/*!
* @brief Delete an RcmClient instance
*
* @param[in,out] handlePtr Handle to the instance object to delete.
*/
Int RcmClient_delete(
RcmClient_Handle * handlePtr
);
/*
* ======== RcmClient_destruct ========
*/
/*!
* @brief Finalize the instance object inside the provided structure
*
* @param[in] structPtr A pointer to the structure containing the
* instance object to finalize.
*/
Int RcmClient_destruct(
RcmClient_Struct * structPtr
);
/*
* ======== RcmClient_exec ========
*/
/*!
* @brief Execute a command message on the server
*
* The message is sent to the server for processing. This call will
* block until the remote function has completed. When this function
* returns, the message will contain the return value of the remote
* function as well as a possibly modified context.
*
* After calling exec, the message can be either reused for another
* call to exec or it can be freed.
*
* @param[in] handle Handle to an instance object
*
* @param[in] cmdMsg Pointer to an RcmClient_Message structure.
*
* @param[out] returnMsg A pointer to the return message or NULL on
* error. The client must free this message. The return value of the
* message function is stored in the results field. The return value
* of the library function is marshalled into the data field.
*
* @retval RcmClient_S_SUCCESS
* @retval RcmClient_E_EXECFAILED
* @retval RcmClient_E_INVALIDFXNIDX
* @retval RcmClient_E_LOSTMSG
* @retval RcmClient_E_MSGFXNERROR
* @retval RcmClient_E_SERVERERROR
*/
Int RcmClient_exec(
RcmClient_Handle handle,
RcmClient_Message * cmdMsg,
RcmClient_Message ** returnMsg
);
/*
* ======== RcmClient_execAsync ========
*/
/*!
* @brief Execute a command message and use a callback for notification
*
* The message is sent to the server for execution, but this call does
* not wait for the remote function to execute. This call returns
* as soon as the message has been dispatched to the transport. Upon
* returning from this function, the ownership of the message has been
* lost; do not access the message at this time.
*
* When the remote function completes, the given callback function is
* invoked by this RcmClient instance's callback server thread. The
* callback function is used to asynchronously notify the client that
* the remote function has completed.
*
* The RcmClient instance must be create with callbackNotification
* set to true in order to use this function.
*
* @param[in] handle Handle to an instance object
*
* @param[in] cmdMsg Pointer to an RcmClient_Message structure.
*
* @param[in] callback A callback function pointer supplied by the
* application. It will be invoked by the callback server thread to
* notify the application that the remote function has completed.
*
* @param[in] appData A private data pointer supplied by the application.
* This allows the application to provide its own context when
* receiving the callback.
*/
Int RcmClient_execAsync(
RcmClient_Handle handle,
RcmClient_Message * cmdMsg,
RcmClient_CallbackFxn callback,
Ptr appData
);
/*
* ======== RcmClient_execCmd ========
*/
/*!
* @brief Execute a one-way command message on the server
*
* The message is sent to the server for processing but this function
* does not wait for the return message. This function is non-blocking.
* The server will processes the message and then free it, unless an
* error occurs. The return value from the remote function is discarded.
*
* If an error occurs on the server while processing the message, the server
* will return the message to the client. Use RcmClient_checkForError()
* to collect these return error messages.
*
* When this function returns, ownership of the message has been transfered
* to the server. Do not access the message after this function returns,
* it could cause cache inconsistencies or a memory access violation.
*
* @param[in] handle Handle to an instance object
*
* @param[in] cmdMsg Pointer to an RcmClient_Message structure.
*
* @retval RcmClient_S_SUCCESS
* @retval RcmClient_E_IPCERROR
*/
Int RcmClient_execCmd(
RcmClient_Handle handle,
RcmClient_Message * cmdMsg
);
/*
* ======== RcmClient_execDpc ========
*/
/*!
* @brief Execute a deferred procedure call on the server
*
* The return field of the message is not used.
*
* @param[in] handle Handle to an instance object
*
* @param[in] cmdMsg Pointer to an RcmClient_Message structure.
*
* @param[out] returnMsg A pointer to the return message or NULL
* on error. The client must free this message.
*/
Int RcmClient_execDpc(
RcmClient_Handle handle,
RcmClient_Message * cmdMsg,
RcmClient_Message ** returnMsg
);
/*
* ======== RcmClient_execNoWait ========
*/
/*!
* @brief Submit a command message to the server and return immediately
*
* The message is sent to the server for execution but this call does
* not wait for the remote function to execute. The call returns
* as soon as the message has been dispatched to the transport. Upon
* returning from this function, the ownership of the message has been
* lost; do not access the message at this time.
*
* Using this call to execute a remote message does not require a
* callback server thread. The application must call
* RcmClient_waitUntilDone() to get the return message from the remote
* function.
*
* @param[in] handle Handle to an instance object
*
* @param[in] cmdMsg A pointer to an RcmClient_Message structure.
*
* @param[out] msgId Pointer used for storing the message id. Use
* the message id in a call to RcmClient_WaitUntilDone() to retrieve
* the return value of the remote function.
*/
Int RcmClient_execNoWait(
RcmClient_Handle handle,
RcmClient_Message * cmdMsg,
UInt16 * msgId
);
/*
* ======== RcmClient_exit ========
*/
/*!
* @brief Finalize the RcmClient module
*
* This function is used to finalize the RcmClient module. Any resources
* acquired by RcmClient_init() will be released. Do not call any RcmClient
* functions after calling RcmClient_exit().
*
* This function must be serialized by the caller.
*/
Void RcmClient_exit(Void);
/*
* ======== RcmClient_free ========
*/
/*!
* @brief Free the given message
*
* @param[in] handle Handle to an instance object
*
* @param msg Pointer to an RcmClient_Message structure.
*/
Int RcmClient_free(
RcmClient_Handle handle,
RcmClient_Message * msg
);
/*
* ======== RcmClient_getSymbolIndex ========
*/
/*!
* @brief Return the function index from the server
*
* Query the server for the given function name and return its index.
* Use the index in the fxnIdx field of the RcmClient_Message struct.
*
* @param[in] handle Handle to an instance object
*
* @param[in] name The function's name.
*
* @param[out] index The function's index.
*/
Int RcmClient_getSymbolIndex(
RcmClient_Handle handle,
String name,
UInt32 * index
);
/*
* ======== RcmClient_init ========
*/
/*!
* @brief Initialize the RcmClient module
*
* This function is used to initialize the RcmClient module. Call this
* function before calling any other RcmClient function.
*
* This function must be serialized by the caller
*/
Void RcmClient_init(Void);
/*
* ======== RcmClient_Parmas_init ========
*/
/*!
* @brief Initialize the instance create params structure
*/
Void RcmClient_Params_init(
RcmClient_Params * params
);
/*
* ======== RcmClient_releaseJobId ========
*/
/*!
* @brief Return a job id to the server and release all resources
*
* @param[in] handle Handle to an instance object
*
* @param[in] jobId The job id to be released
*/
Int RcmClient_releaseJobId(
RcmClient_Handle handle,
UInt16 jobId
);
/*
* ======== RcmClient_removeSymbol ========
*/
/*!
* @brief Remove a symbol and from the server function table
*
* Useful when unloading a DLL from the server.
*
* @param[in] handle Handle to an instance object
*
* @param[in] name The function name.
*/
Int RcmClient_removeSymbol(
RcmClient_Handle handle,
String name
);
/*
* ======== RcmClient_waitUntilDone ========
*/
/*!
* @brief Block until the specified message has been executed
*
* This function will wait until the remote function invoked by the
* specified message has completed. Upon return from this call, the
* message will contain the return value and the return context of
* the remote function.
*
* @param[in] handle Handle to an instance object
*
* @param[in] msgId The message ID to wait for.
*
* @param[out] returnMsg A pointer to the return message or NULL
* on error. The client must free this message.
*/
Int RcmClient_waitUntilDone(
RcmClient_Handle handle,
UInt16 msgId,
RcmClient_Message ** returnMsg
);
#if defined (__cplusplus)
}
#endif /* defined (__cplusplus) */
/*@}*/
#endif /* ti_grcm_RcmClient__include */