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 * ======== TransportShmCirc.xdc ================
34 */
35
36 import ti.sdo.utils.MultiProc;
37 import ti.sdo.ipc.Ipc;
38 import ti.sysbios.knl.Swi;
39
40 import xdc.rov.ViewInfo;
41
42 /*!
43 * ======== TransportShmCirc ========
44 * Transport for MessageQ that uses a circular buffer to queue messages
45 *
46 * This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
47 * memory for passing messages between multiple processors.
48 *
49 * The transport implements a queue using a circular buffer in the manner
50 * indicated by the following diagram.
51 *
52 * @p(code)
53 *
54 * NOTE: Processors '0' and '1' correspond to the processors with lower and
55 * higher MultiProc ids, respectively
56 *
57 * sharedAddr -> --------------------------- bytes
58 * | entry0 (0) [Put] | 4
59 * | entry1 (0) | 4
60 * | ... |
61 * | entryN (0) | 4
62 * | [align to cache size] |
63 * |-------------------------|
64 * | putWriteIndex (0) | 4
65 * | [align to cache size] |
66 * |-------------------------|
67 * | putReadIndex (0) | 4
68 * | [align to cache size] |
69 * |-------------------------|
70 * | entry0 (1) [Get] | 4
71 * | entry1 (1) | 4
72 * | ... |
73 * | entryN (1) | 4
74 * | [align to cache size] |
75 * |-------------------------|
76 * | getWriteIndex (1) | 4
77 * | [align to cache size] |
78 * |-------------------------|
79 * | getReadIndex (1) | 4
80 * | [align to cache size] |
81 * |-------------------------|
82 *
83 *
84 * Legend:
85 * (0), (1) : Memory that belongs to the proc with lower and higher
86 * MultiProc.id, respectively
87 * |----| : Cache line boundary
88 *
89 * @p
90 */
91
92 @InstanceFinalize
93 @InstanceInitError
94
95 module TransportShmCirc inherits ti.sdo.ipc.interfaces.IMessageQTransport
96 {
97 /*! @_nodoc */
98 metaonly struct BasicView {
99 String remoteProcName;
100 Bool cacheEnabled;
101 }
102
103 /*! @_nodoc */
104 metaonly struct EventDataView {
105 UInt index;
106 String buffer;
107 Ptr addr;
108 Ptr message;
109 }
110
111 /*!
112 * ======== rovViewInfo ========
113 */
114 @Facet
115 metaonly config ViewInfo.Instance rovViewInfo =
116 ViewInfo.create({
117 viewMap: [
118 ['Basic',
119 {
120 type: ViewInfo.INSTANCE,
121 viewInitFxn: 'viewInitBasic',
122 structName: 'BasicView'
123 }
124 ],
125 ['Events',
126 {
127 type: ViewInfo.INSTANCE_DATA,
128 viewInitFxn: 'viewInitData',
129 structName: 'EventDataView'
130 }
131 ],
132 ]
133 });
134
135
136 /*!
137 * @_nodoc
138 * Determines whether the put() call unconditionally does a Cache_wbInv of
139 * the message before sending a notification to the remote core.
140 * The default value of 'true' allows us to skip the additional step of
141 * checking whether cache is enabled for the message.
142 *
143 * This should be set to 'false' when it is optimal to perform this
144 * check. This may be OPTIMAL when sending a message that is allocated
145 * from a shared region whose cacheFlag is 'false' and when the write-back
146 * cache operation is expensive.
147 */
148 config Bool alwaysWriteBackMsg = true;
149
150 /*!
151 * ======== enableStats ========
152 * Enable statistics for sending an event
153 *
154 * If this parameter is to 'TRUE' and 'waitClear' is also set to
155 * TRUE when calling (@link #sendEvent(), then the module keeps
156 * track of the number of times the processor spins waiting for
157 * an empty slot and the max amount of time it waits.
158 */
159 config Bool enableStats = false;
160
161 /*!
162 * ======== notifyEventId ========
163 * Notify event ID for transport.
164 */
165 config UInt16 notifyEventId = 2;
166
167 /*!
168 * ======== numMsgs ========
169 * The number of messages or slots in the circular buffer
170 *
171 * This is use to determine the size of the put and get buffers.
172 * Each eventEntry is two 32bits wide, therefore the total size
173 * of each circular buffer is [numMsgs * sizeof(eventEntry)].
174 * The total size of each buffer must be a multiple of the
175 * the cache line size. For example, if the cacheLineSize = 128
176 * then numMsgs could be 16, 32, etc...
177 */
178 config UInt numMsgs = 32;
179
180 /*! @_nodoc
181 * ======== sharedMemReq ========
182 * Amount of shared memory required for creation of each instance
183 *
184 * @param(params) Pointer to parameters that will be used in the
185 * create
186 *
187 * @a(returns) Number of MAUs in shared memory needed to create
188 * the instance.
189 */
190 SizeT sharedMemReq(const Params *params);
191
192 instance:
193
194 /*!
195 * ======== sharedAddr ========
196 * Address in shared memory where this instance will be placed
197 *
198 * Use {@link #sharedMemReq} to determine the amount of shared memory
199 * required.
200 */
201 config Ptr sharedAddr = null;
202
203 internal:
204
205 /*! The max index set to (numMsgs - 1) */
206 config UInt maxIndex;
207
208 /*!
209 * The modulo index value. Set to (numMsgs / 4).
210 * Used in the isr for doing cache_wb of readIndex.
211 */
212 config UInt modIndex;
213
214 /*!
215 * ======== swiFxn ========
216 */
217 Void swiFxn(UArg arg);
218
219 /*!
220 * ======== notifyFxn ========
221 */
222 Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
223 UInt32 payload);
224
225 /*! Instance state structure */
226 struct Instance_State {
227 Ptr *putBuffer; /* buffer used to put events */
228 Bits32 *putReadIndex; /* ptr to readIndex for put buffer */
229 Bits32 *putWriteIndex; /* ptr to writeIndex for put buffer */
230 Ptr *getBuffer; /* buffer used to get events */
231 Bits32 *getReadIndex; /* ptr to readIndex for get buffer */
232 Bits32 *getWriteIndex; /* ptr to writeIndex for put buffer */
233 SizeT opCacheSize; /* optimized cache size for wb/inv */
234 UInt16 regionId; /* the shared region id */
235 UInt16 remoteProcId; /* dst proc id */
236 Bool cacheEnabled; /* set by param or SharedRegion */
237 UInt16 priority; /* priority to register */
238 Swi.Object swiObj; /* Each instance has a swi */
239 Ipc.ObjType objType; /* Static/Dynamic? open/creator? */
240 }
241 }