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] | 4
56 * | entry1 (0) | 4
57 * | ... |
58 * | entryN (0) | 4
59 * | |
60 * |-------------------------|
61 * | putWriteIndex (0) | 4
62 * | |
63 * |-------------------------|
64 * | getReadIndex (1) | 4
65 * | |
66 * |-------------------------|
67 * | entry0 (1) [Get] | 4
68 * | entry1 (1) | 4
69 * | ... |
70 * | entryN (1) | 4
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 addr;
103 Ptr message;
104 }
106 /*!
107 * ======== rovViewInfo ========
108 */
109 @Facet
110 metaonly config ViewInfo.Instance rovViewInfo =
111 ViewInfo.create({
112 viewMap: [
113 ['Basic',
114 {
115 type: ViewInfo.INSTANCE,
116 viewInitFxn: 'viewInitBasic',
117 structName: 'BasicView'
118 }
119 ],
120 ['Events',
121 {
122 type: ViewInfo.INSTANCE_DATA,
123 viewInitFxn: 'viewInitData',
124 structName: 'EventDataView'
125 }
126 ],
127 ]
128 });
130 /*!
131 * ======== close ========
132 * Close an opened instance
133 *
134 * Closing an instance will free local memory consumed by the opened
135 * instance. Instances that are opened should be closed before the
136 * instance is deleted.
137 *
138 * @param(handle) handle that is returned from an {@link #openByAddr}
139 */
140 Void close(Handle *handle);
142 /*! @_nodoc
143 * ======== notifyEventId ========
144 * Notify event ID for transport.
145 */
146 config UInt16 notifyEventId = 2;
148 /*! @_nodoc
149 * ======== numMsgs ========
150 * The maximum number of outstanding messages
151 *
152 * This number must be greater than 0 and a power of 2.
153 * If the transport reaches this threshold, it spins waiting for
154 * another message slot to be freed by the remote processor.
155 */
156 config UInt numMsgs = 4;
158 /*! @_nodoc
159 * ======== maxMsgSizeInBytes ========
160 * The maximum message size (in bytes) that is supported
161 */
162 config UInt maxMsgSizeInBytes = 128;
164 /*! @_nodoc
165 * ======== sharedMemReq ========
166 * Amount of shared memory required for creation of each instance
167 *
168 * @param(params) Pointer to the parameters that will be used in
169 * create.
170 *
171 * @a(returns) Number of MAUs needed to create the instance.
172 */
173 SizeT sharedMemReq(const Params *params);
175 /*! @_nodoc
176 * ======== sharedMemReqMeta ========
177 * Amount of shared memory required for creation of each instance
178 *
179 * @param(params) Pointer to the parameters that will be used in
180 * create.
181 *
182 * @a(returns) Size of shared memory in MAUs on local processor.
183 */
184 metaonly SizeT sharedMemReqMeta(const Params *params);
186 instance:
188 /*! @_nodoc
189 * ======== openFlag ========
190 * Set to 'true' by the open() call. No one else should touch this!
191 */
192 config Bool openFlag = false;
194 /*!
195 * ======== readAddr ========
196 * Physical address of the read address in shared memory
197 *
198 * This address should be specified in the local processor's memory
199 * space. It must point to the same physical write address of the
200 * remote processor its communicating with.
201 */
202 config Ptr readAddr = null;
204 /*!
205 * ======== writeAddr ========
206 * Physical address of the write address in shared memory
207 *
208 * This address should be specified in the local processor's memory
209 * space. It must point to the same physical read address of the
210 * remote processor its communicating with.
211 */
212 config Ptr writeAddr = null;
214 internal:
216 /*! The max index set to (numMsgs - 1) */
217 config UInt maxIndex;
219 /*!
220 * The message size calculated based on the target.
221 */
222 config UInt msgSize;
224 /*!
225 * ======== swiFxn ========
226 * This function takes the messages from the transport ListMP and
227 * calls MessageQ_put to send them to their destination queue.
228 * This function is posted by the NotifyFxn.
229 *
230 * @param(arg) argument for the function
231 */
232 Void swiFxn(UArg arg);
234 /*!
235 * ======== notifyFxn ========
236 * This is a callback function registered with Notify. It is called
237 * when a remote processor does a Notify_sendEvent(). It is executed
238 * at ISR level. It posts the instance Swi object to execute swiFxn.
239 *
240 * @param(procId) remote processor id
241 * @param(lineId) Notify line id
242 * @param(eventId) Notify event id
243 * @param(arg) argument for the function
244 * @param(payload) 32-bit payload value.
245 */
246 Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
247 UInt32 payload);
249 /* Instance State object */
250 struct Instance_State {
251 Ptr *putBuffer; /* buffer used to put message */
252 Bits32 *putReadIndex; /* ptr to readIndex for put buffer */
253 Bits32 *putWriteIndex; /* ptr to writeIndex for put buffer */
254 Ptr *getBuffer; /* buffer used to get message */
255 Bits32 *getReadIndex; /* ptr to readIndex for get buffer */
256 Bits32 *getWriteIndex; /* ptr to writeIndex for put buffer */
257 Swi.Object swiObj; /* Each instance has a swi */
258 SizeT allocSize; /* Shared memory allocated */
259 UInt16 remoteProcId; /* dst proc id */
260 UInt16 priority; /* priority to register */
261 };
262 }