IPC API  3.40.00.06
RcmClient.h
Go to the documentation of this file.
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 
34 /*
35  * ======== RcmClient.h ========
36  *
37  */
38 
237 #ifndef ti_grcm_RcmClient__include
238 #define ti_grcm_RcmClient__include
239 
240 #include <xdc/runtime/knl/GateThread.h>
241 
242 
245 
246 #if defined (__cplusplus)
247 extern "C" {
248 #endif
249 
250 
251 /* -------- status codes --------*/
252 
256 #define RcmClient_S_SUCCESS (0)
257 
261 #define RcmClient_E_FAIL (-1)
262 
270 #define RcmClient_E_EXECASYNCNOTENABLED (-2)
271 
277 #define RcmClient_E_EXECFAILED (-3)
278 
286 #define RcmClient_E_INVALIDHEAPID (-4)
287 
295 #define RcmClient_E_INVALIDFXNIDX (-5)
296 
304 #define RcmClient_E_MSGFXNERROR (-6)
305 
311 #define RcmClient_E_IPCERROR (-7)
312 
316 #define RcmClient_E_LISTCREATEFAILED (-8)
317 
324 #define RcmClient_E_LOSTMSG (-9)
325 
333 #define RcmClient_E_MSGALLOCFAILED (-10)
334 
343 #define RcmClient_E_MSGQCREATEFAILED (-11)
344 
352 #define RcmClient_E_MSGQOPENFAILED (-12)
353 
360 #define RcmClient_E_SERVERERROR (-13)
361 
371 #define RcmClient_E_SERVERNOTFOUND (-14)
372 
379 #define RcmClient_E_SYMBOLNOTFOUND (-15)
380 
384 #define RcmClient_E_NOMEMORY (-16)
385 
393 #define RcmClient_E_JOBIDNOTFOUND (-17)
394 
395 
396 /* -------- constants and types --------*/
397 
401 #define RcmClient_INVALIDFXNIDX ((UInt32)(0xFFFFFFFF))
402 
406 #define RcmClient_INVALIDHEAPID ((UInt16)(0xFFFF))
407 
411 #define RcmClient_INVALIDMSGID (0)
412 
420 #define RcmClient_DEFAULTPOOLID ((UInt16)(0x8000))
421 
428 #define RcmClient_DISCRETEJOBID (0)
429 
433 typedef struct RcmClient_Object_tag *RcmClient_Handle;
434 
441 typedef struct {
449  UInt16 poolId;
450 
458  UInt16 jobId;
459 
463  UInt32 fxnIdx;
464 
468  Int32 result;
469 
476  UInt32 dataSize;
477 
484  UInt32 data[1];
485 
487 
496 typedef Void (*RcmClient_CallbackFxn)(RcmClient_Message *, Ptr);
497 
501 typedef struct {
509  UInt16 heapId;
510 
525 
527 
535 typedef struct {
536  xdc_runtime_knl_GateThread_Struct _f1;
537  Ptr _f2;
538  Ptr _f3;
539  UInt16 _f4;
540  Ptr _f5;
541  UInt32 _f6;
542  Bool _f7;
543  UInt16 _f8;
544  Ptr _f9;
545  Ptr _f10;
546  Ptr _f11;
547  Ptr _f12;
549 
550 
551 /* -------- functions --------*/
552 
553 /*
554  * ======== RcmClient_acquireJobId ========
555  */
564  RcmClient_Handle handle,
565  UInt16 * jobId
566  );
567 
568 /*
569  * ======== RcmClient_addSymbol ========
570  */
596  RcmClient_Handle handle,
597  String name,
598  Fxn addr,
599  UInt32 * index
600  );
601 
602 /*
603  * ======== RcmClient_alloc ========
604  */
632 Int RcmClient_alloc(
633  RcmClient_Handle handle,
634  UInt32 dataSize,
635  RcmClient_Message ** message
636  );
637 
638 /*
639  * ======== RcmClient_checkForError ========
640  */
695  RcmClient_Handle handle,
696  RcmClient_Message ** returnMsg
697  );
698 
699 /*
700  * ======== RcmClient_construct ========
701  */
720  RcmClient_Struct * structPtr,
721  String server,
722  const RcmClient_Params *params
723  );
724 
725 /*
726  * ======== RcmClient_create ========
727  */
747 Int RcmClient_create(
748  String server,
749  const RcmClient_Params *params,
750  RcmClient_Handle * handle
751  );
752 
753 /*
754  * ======== RcmClient_delete ========
755  */
761 Int RcmClient_delete(
762  RcmClient_Handle * handlePtr
763  );
764 
765 /*
766  * ======== RcmClient_destruct ========
767  */
775  RcmClient_Struct * structPtr
776  );
777 
778 /*
779  * ======== RcmClient_exec ========
780  */
808 Int RcmClient_exec(
809  RcmClient_Handle handle,
810  RcmClient_Message * cmdMsg,
811  RcmClient_Message ** returnMsg
812  );
813 
814 /*
815  * ======== RcmClient_execAsync ========
816  */
847  RcmClient_Handle handle,
848  RcmClient_Message * cmdMsg,
849  RcmClient_CallbackFxn callback,
850  Ptr appData
851  );
852 
853 /*
854  * ======== RcmClient_execCmd ========
855  */
880  RcmClient_Handle handle,
881  RcmClient_Message * cmdMsg
882  );
883 
884 /*
885  * ======== RcmClient_execDpc ========
886  */
900  RcmClient_Handle handle,
901  RcmClient_Message * cmdMsg,
902  RcmClient_Message ** returnMsg
903  );
904 
905 /*
906  * ======== RcmClient_execNoWait ========
907  */
931  RcmClient_Handle handle,
932  RcmClient_Message * cmdMsg,
933  UInt16 * msgId
934  );
935 
936 /*
937  * ======== RcmClient_exit ========
938  */
948 Void RcmClient_exit(Void);
949 
950 /*
951  * ======== RcmClient_free ========
952  */
960 Int RcmClient_free(
961  RcmClient_Handle handle,
962  RcmClient_Message * msg
963  );
964 
965 /*
966  * ======== RcmClient_getSymbolIndex ========
967  */
981  RcmClient_Handle handle,
982  String name,
983  UInt32 * index
984  );
985 
986 /*
987  * ======== RcmClient_init ========
988  */
997 Void RcmClient_init(Void);
998 
999 /*
1000  * ======== RcmClient_Parmas_init ========
1001  */
1006  RcmClient_Params * params
1007  );
1008 
1009 /*
1010  * ======== RcmClient_releaseJobId ========
1011  */
1020  RcmClient_Handle handle,
1021  UInt16 jobId
1022  );
1023 
1024 /*
1025  * ======== RcmClient_removeSymbol ========
1026  */
1037  RcmClient_Handle handle,
1038  String name
1039  );
1040 
1041 /*
1042  * ======== RcmClient_waitUntilDone ========
1043  */
1060  RcmClient_Handle handle,
1061  UInt16 msgId,
1062  RcmClient_Message ** returnMsg
1063  );
1064 
1065 
1066 #if defined (__cplusplus)
1067 }
1068 #endif /* defined (__cplusplus) */
1069 
1072 #endif /* ti_grcm_RcmClient__include */
UInt16 jobId
The job id associated with this message.
Definition: RcmClient.h:458
Ptr _f5
Definition: RcmClient.h:540
Int RcmClient_execAsync(RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_CallbackFxn callback, Ptr appData)
Execute a command message and use a callback for notification.
Bool callbackNotification
Asynchronous callback notification support.
Definition: RcmClient.h:524
Int RcmClient_execNoWait(RcmClient_Handle handle, RcmClient_Message *cmdMsg, UInt16 *msgId)
Submit a command message to the server and return immediately.
Int RcmClient_construct(RcmClient_Struct *structPtr, String server, const RcmClient_Params *params)
Initialize a new instance object inside the provided structure.
Int RcmClient_execCmd(RcmClient_Handle handle, RcmClient_Message *cmdMsg)
Execute a one-way command message on the server.
Int RcmClient_releaseJobId(RcmClient_Handle handle, UInt16 jobId)
Return a job id to the server and release all resources.
Int RcmClient_exec(RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_Message **returnMsg)
Execute a command message on the server.
UInt32 dataSize
The size of the data buffer (in chars).
Definition: RcmClient.h:476
Ptr _f3
Definition: RcmClient.h:538
Ptr _f12
Definition: RcmClient.h:547
struct RcmClient_Object_tag * RcmClient_Handle
RcmClient instance object handle.
Definition: RcmClient.h:433
Void RcmClient_init(Void)
Initialize the RcmClient module.
Void(* RcmClient_CallbackFxn)(RcmClient_Message *, Ptr)
Callback function type.
Definition: RcmClient.h:496
Int RcmClient_checkForError(RcmClient_Handle handle, RcmClient_Message **returnMsg)
Check if an error message has been returned from the server.
Int RcmClient_create(String server, const RcmClient_Params *params, RcmClient_Handle *handle)
Create an RcmClient instance.
UInt32 _f6
Definition: RcmClient.h:541
Int RcmClient_delete(RcmClient_Handle *handlePtr)
Delete an RcmClient instance.
Instance create parameters.
Definition: RcmClient.h:501
Ptr _f10
Definition: RcmClient.h:545
UInt16 _f8
Definition: RcmClient.h:543
Ptr _f11
Definition: RcmClient.h:546
Void RcmClient_Params_init(RcmClient_Params *params)
Initialize the instance create params structure.
Int RcmClient_waitUntilDone(RcmClient_Handle handle, UInt16 msgId, RcmClient_Message **returnMsg)
Block until the specified message has been executed.
Remote Command Message structure.
Definition: RcmClient.h:441
Opaque client structure large enough to hold an instance object.
Definition: RcmClient.h:535
Int RcmClient_free(RcmClient_Handle handle, RcmClient_Message *msg)
Free the given message.
Int RcmClient_acquireJobId(RcmClient_Handle handle, UInt16 *jobId)
Get a job id from the server.
Int RcmClient_alloc(RcmClient_Handle handle, UInt32 dataSize, RcmClient_Message **message)
Allocate a message from the heap configured for this instance.
UInt16 poolId
The worker pool id that will process this message.
Definition: RcmClient.h:449
Int RcmClient_addSymbol(RcmClient_Handle handle, String name, Fxn addr, UInt32 *index)
Add a symbol and its address to the server table.
UInt16 _f4
Definition: RcmClient.h:539
Ptr _f2
Definition: RcmClient.h:537
UInt16 heapId
The heapId used by this instance for allocating messages.
Definition: RcmClient.h:509
Int RcmClient_getSymbolIndex(RcmClient_Handle handle, String name, UInt32 *index)
Return the function index from the server.
Ptr _f9
Definition: RcmClient.h:544
Int32 result
The return value of the remote message function.
Definition: RcmClient.h:468
Int RcmClient_removeSymbol(RcmClient_Handle handle, String name)
Remove a symbol and from the server function table.
Int RcmClient_destruct(RcmClient_Struct *structPtr)
Finalize the instance object inside the provided structure.
Void RcmClient_exit(Void)
Finalize the RcmClient module.
xdc_runtime_knl_GateThread_Struct _f1
Definition: RcmClient.h:536
UInt32 fxnIdx
The index of the remote function to execute.
Definition: RcmClient.h:463
Bool _f7
Definition: RcmClient.h:542
Int RcmClient_execDpc(RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_Message **returnMsg)
Execute a deferred procedure call on the server.
Copyright 2015, Texas Instruments Incorporated