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