5285a12c11e7fa1b28d773c5e7ec1b269169b6f9
1 /*
2 * Copyright (c) 2012-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 * ======== TransportCirc.xdc ========
34 */
36 import ti.sysbios.knl.Swi;
38 import xdc.rov.ViewInfo;
40 /*!
41 * ======== TransportCirc ========
42 * Transport for MessageQ that uses a circular buffer.
43 *
44 * This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
45 * memory for passing messages between multiple processors.
46 *
47 * The transport utilizes shared memory in the manner indicated by the
48 * following diagram.
49 *
50 * @p(code)
51 *
52 * NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28
53 *
54 * sharedAddr -> --------------------------- bytes
55 * | entry0 (0) [Put] | msgSize
56 * | entry1 (0) | msgSize
57 * | ... |
58 * | entryN (0) | msgSize
59 * | |
60 * |-------------------------|
61 * | putWriteIndex (0) | 4
62 * | |
63 * |-------------------------|
64 * | getReadIndex (1) | 4
65 * | |
66 * |-------------------------|
67 * | entry0 (1) [Get] | msgSize
68 * | entry1 (1) | msgSize
69 * | ... |
70 * | entryN (1) | msgSize
71 * | |
72 * |-------------------------|
73 * | putWriteIndex (1) | 4
74 * | |
75 * |-------------------------|
76 * | getReadIndex (0) | 4
77 * | |
78 * |-------------------------|
79 *
80 *
81 * Legend:
82 * (0), (1) : belongs to the respective processor
83 * (N) : length of buffer
84 *
85 * @p
86 */
88 @InstanceFinalize
89 @InstanceInitError
91 module TransportCirc inherits ti.sdo.ipc.interfaces.IMessageQTransport
92 {
93 /*! @_nodoc */
94 metaonly struct BasicView {
95 String remoteProcName;
96 }
98 /*! @_nodoc */
99 metaonly struct EventDataView {
100 UInt index;
101 String buffer;
102 Ptr message;
103 }
105 /*!
106 * ======== rovViewInfo ========
107 */
108 @Facet
109 metaonly config ViewInfo.Instance rovViewInfo =
110 ViewInfo.create({
111 viewMap: [
112 ['Basic',
113 {
114 type: ViewInfo.INSTANCE,
115 viewInitFxn: 'viewInitBasic',
116 structName: 'BasicView'
117 }
118 ],
119 ['Events',
120 {
121 type: ViewInfo.INSTANCE_DATA,
122 viewInitFxn: 'viewInitData',
123 structName: 'EventDataView'
124 }
125 ],
126 ]
127 });
129 /*!
130 * ======== close ========
131 * Close an opened instance
132 *
133 * Closing an instance will free local memory consumed by the opened
134 * instance. Instances that are opened should be closed before the
135 * instance is deleted.
136 *
137 * @param(handle) handle that is returned from an {@link #openByAddr}
138 */
139 Void close(Handle *handle);
141 /*! @_nodoc
142 * ======== notifyEventId ========
143 * Notify event ID for transport.
144 */
145 config UInt16 notifyEventId = 2;
147 /*! @_nodoc
148 * ======== numMsgs ========
149 * The maximum number of outstanding messages
150 *
151 * This number must be greater than 0 and a power of 2.
152 * If the transport reaches this threshold, it spins waiting for
153 * another message slot to be freed by the remote processor.
154 */
155 config UInt numMsgs = 4;
157 /*! @_nodoc
158 * ======== maxMsgSizeInBytes ========
159 * The maximum message size (in bytes) that is supported
160 */
161 config UInt maxMsgSizeInBytes = 128;
163 /*! @_nodoc
164 * ======== sharedMemReq ========
165 * Amount of shared memory required for creation of each instance
166 *
167 * @param(params) Pointer to the parameters that will be used in
168 * create.
169 *
170 * @a(returns) Number of MAUs needed to create the instance.
171 */
172 SizeT sharedMemReq(const Params *params);
174 /*! @_nodoc
175 * ======== sharedMemReqMeta ========
176 * Amount of shared memory required for creation of each instance
177 *
178 * @param(params) Pointer to the parameters that will be used in
179 * create.
180 *
181 * @a(returns) Size of shared memory in MAUs on local processor.
182 */
183 metaonly SizeT sharedMemReqMeta(const Params *params);
185 instance:
187 /*! @_nodoc
188 * ======== openFlag ========
189 * Set to 'true' by the open() call. No one else should touch this!
190 */
191 config Bool openFlag = false;
193 /*!
194 * ======== readAddr ========
195 * Physical address of the read address in shared memory
196 *
197 * This address should be specified in the local processor's memory
198 * space. It must point to the same physical write address of the
199 * remote processor its communicating with.
200 */
201 config Ptr readAddr = null;
203 /*!
204 * ======== writeAddr ========
205 * Physical address of the write address in shared memory
206 *
207 * This address should be specified in the local processor's memory
208 * space. It must point to the same physical read address of the
209 * remote processor its communicating with.
210 */
211 config Ptr writeAddr = null;
213 /*!
214 * ======== swiPriority ========
215 * The priority of the Transport Swi object created
216 */
217 config UInt swiPriority = 1;
219 internal:
221 /*! The max index set to (numMsgs - 1) */
222 config UInt maxIndex;
224 /*!
225 * The message size calculated based on the target.
226 */
227 config UInt msgSize;
229 /*!
230 * ======== swiFxn ========
231 * This function takes the messages from the transport ListMP and
232 * calls MessageQ_put to send them to their destination queue.
233 * This function is posted by the NotifyFxn.
234 *
235 * @param(arg) argument for the function
236 */
237 Void swiFxn(UArg arg);
239 /*!
240 * ======== notifyFxn ========
241 * This is a callback function registered with Notify. It is called
242 * when a remote processor does a Notify_sendEvent(). It is executed
243 * at ISR level. It posts the instance Swi object to execute swiFxn.
244 *
245 * @param(procId) remote processor id
246 * @param(lineId) Notify line id
247 * @param(eventId) Notify event id
248 * @param(arg) argument for the function
249 * @param(payload) 32-bit payload value.
250 */
251 Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
252 UInt32 payload);
254 /* Instance State object */
255 struct Instance_State {
256 Ptr *putBuffer; /* buffer used to put message */
257 Bits32 *putReadIndex; /* ptr to readIndex for put buffer */
258 Bits32 *putWriteIndex; /* ptr to writeIndex for put buffer */
259 Ptr *getBuffer; /* buffer used to get message */
260 Bits32 *getReadIndex; /* ptr to readIndex for get buffer */
261 Bits32 *getWriteIndex; /* ptr to writeIndex for put buffer */
262 Swi.Object swiObj; /* Each instance has a swi */
263 SizeT allocSize; /* Shared memory allocated */
264 UInt16 remoteProcId; /* dst proc id */
265 UInt16 priority; /* priority to register */
266 };
267 }