1 2 3 4 5 6 7 8 9
10 11 12 13 14 15
16
17 /*!
18 * ======== IMessageQTransport ========
19 * Interface for the transports used by MessageQ
20 *
21 * The transport implementations have to register with
22 * {@link ti.sdo.ipc.MessageQ}. This is done via the
23 * {@link ti.sdo.ipc.MessageQ#registerTransport} function.
24 *
25 * If transports need additional processing during startup,
26 * there are multiple hook points to run start-up code that
27 * the transport implementation can use.
28 */
29
30 interface IMessageQTransport
31 {
32 /*!
33 * Transport return values
34 *
35 * @p(blist)
36 * -{@link #S_SUCCESS}: Operation was successful
37 * -{@link #E_FAIL}: Operation resulted in a failure
38 * -{@link #E_ERROR}: Operation resulted in an error.
39 * @p
40 */
41 enum Status {
42 S_SUCCESS = 0,
43 E_FAIL = -1,
44 E_ERROR = -2
45 };
46
47 /*!
48 * Reason for error function being called
49 *
50 * First field in the {@link #errFxn}
51 */
52 enum Reason {
53 Reason_FAILEDPUT,
54 Reason_INTERNALERR,
55 Reason_PHYSICALERR,
56 Reason_FAILEDALLOC
57 };
58
59 /*!
60 * Asynchronous error function for the transport module
61 */
62 config ErrFxn errFxn = null;
63
64 /*!
65 * Typedef for transport error callback function.
66 *
67 * First parameter: Why the error function is being called.
68 *
69 * Second parameter: Handle of transport that had the error. NULL denotes
70 * that it is a system error, not a specific transport.
71 *
72 * Third parameter: Pointer to the message. This is only valid for
73 * {@link #Reason_FAILEDPUT}.
74 *
75 * Fourth parameter: Transport specific information. Refer to individual
76 * transports for more details.
77 */
78 typedef Void (*ErrFxn)(Reason, Handle, Ptr, UArg);
79
80 /*!
81 * ======== setErrFxn ========
82 * Sets the asynchronous error function for the transport module
83 *
84 * This API allows the user to set the function that will be called in
85 * case of an asynchronous error by the transport.
86 *
87 * @param(errFxn) Function that is called when an asynchronous
88 * error occurs.
89 */
90 Void setErrFxn(ErrFxn errFxn);
91
92 instance:
93
94 /*!
95 * Which priority messages should this transport manage.
96 */
97 config UInt priority = 0;
98
99 /*!
100 * ======== create ========
101 * Create a Transport instance
102 *
103 * This function creates a transport instance. The transport is
104 * responsible for registering with MessageQ via the
105 * {@link ti.sdo.ipc.MessageQ#registerTransport} API.
106 *
107 * @param(procId) Remote processor id that this instance
108 * will communicate with.
109 */
110 create(UInt16 procId);
111
112 /*!
113 * ======== getStatus ========
114 * Status of a Transport instance
115 *
116 * This function returns the status of the transport instance.
117 *
118 * @b(returns) Returns status of Transport instance
119 */
120 Int getStatus();
121
122 /*!
123 * ======== put ========
124 * Put the message to the remote processor
125 *
126 * If the transport can accept the message, it returns TRUE. Accepting
127 * a message does not mean that it is transmitted. It simply means that
128 * the transport should be able to send the message. If the actual transfer
129 * fails, the transport calls the {@#ErrFxn} (assuming it is set up via the
130 * {@#setErrFxn} API. If the {@#ErrFxn} is not set, the message is dropped.
131 * (also...should an error be raised or just System_printf?).
132 *
133 * If the transport cannot send the message, it returns FALSE and a
134 * filled in Error_Block. The caller still owns the message.
135 *
136 * @param(msg) Pointer the message to be sent
137 *
138 * @b(returns) TRUE denotes acceptance of the message to
139 * be sent. FALSE denotes the message could not be
140 * sent.
141 */
142 Bool put(Ptr msg);
143
144 /*!
145 * ======== Control ========
146 * Send a control command to the transport instance
147 *
148 * This is function allows transport to specify control commands. Refer
149 * to individual transport implementions for more details.
150 *
151 * @param(cmd) Requested command
152 * @param(cmdArgs) Accompanying field for the command. This is
153 * command specific.
154 *
155 * @b(returns) TRUE denotes acceptance of the command. FALSE
156 * denotes failure of the command.
157 */
158 Bool control(UInt cmd, UArg cmdArg);
159 }