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