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
37 package ti.sdo.ipc;
38
39 import xdc.runtime.Error;
40 import xdc.runtime.IHeap;
41 import xdc.rov.ViewInfo;
42
43 /*!
44 * ======== SharedRegion ========
45 * Shared memory manager and address translator.
46 *
47 * @p(html)
48 * This module has a common header that can be found in the {@link ti.ipc}
49 * package. Application code should include the common header file (not the
50 * RTSC-generated one):
51 *
52 * <PRE>#include <ti/ipc/SharedRegion.h></PRE>
53 *
54 * The RTSC module must be used in the application's RTSC configuration file
55 * (.cfg) if runtime APIs will be used in the application:
56 *
57 * <PRE>SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');</PRE>
58 *
59 * Documentation for all runtime APIs, instance configuration parameters,
60 * error codes macros and type definitions available to the application
61 * integrator can be found in the
62 * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
63 * for the IPC product. However, the documentation presented on this page
64 * should be referred to for information specific to the RTSC module, such as
65 * module configuration, Errors, and Asserts.
66 * @p
67 *
68 * The SharedRegion module is designed to be used in a multi-processor
69 * environment in which memory regions are shared and accessed
70 * across different processors. The module itself does not use any shared
71 * memory, because all module state is stored locally. SharedRegion
72 * APIs use the system gate for thread protection.
73 *
74 * This module creates and stores a local shared memory region table. The
75 * table contains the processor's view for every shared region in the system.
76 * The table must not contain any overlapping regions. Each processor's
77 * view of a particular shared memory region is determined by the region id.
78 * In cases where a processor cannot access a certain shared memory region,
79 * that shared memory region should be left invalid for that processor.
80 * Note: The {@link #numEntries} must be the same on all processors.
81 *
82 * Each shared region contains the following:
83 * @p(blist)
84 * -base: The base address
85 * -len: The length
86 * -name: The name of the region
87 * -isValid: Whether the region is valid
88 * -ownerProcId: The id of the processor which owns the region
89 * -cacheEnable: Whether the region is cacheable
90 * -cacheLineSize: The cache line size
91 * -createHeap: Whether a heap is created for the region.
92 * @p
93 *
94 * A region is added statically using the {@link #setEntryMeta} API.
95 * The length of a region must be the same across all processors.
96 * The owner of the region can be specified. If specified, the owner
97 * manages the shared region. It creates a HeapMemMP instance which spans
98 * the full size of the region. The other processors open the same HeapMemMP
99 * instance.
100 *
101 * An example of a SharedRegion configuration is as follows:
102 *
103 * @p(code)
104 *
105 * var SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');
106 * SharedRegion.setEntryMeta(0,
107 * { base: 0x80000000,
108 * len: 0x20000,
109 * ownerProcId: 0,
110 * isValid: true,
111 * cacheLineSize: 64,
112 * name: "DDR2",
113 * });
114 *
115 * @p
116 *
117 * The shared region table along with a shared region pointer (SRPtr)
118 * is used to do address translation at runtime. The shared region
119 * pointer is a 32-bit portable pointer composed of an id and offset.
120 * The most significant bits of a SRPtr are used for the id.
121 * The id corresponds to the index of the entry in the table.
122 * The offset is the offset from the base of the shared memory region.
123 * The number of entries in the table determines the number of bits to
124 * use for the id. Increasing the number of entries increases the
125 * range of ids but decreases the range of the offset.
126 *
127 * Note: Region 0 must be visible by all processors. Region 0 is used for
128 * synchonizing the processors, creating the default GateMP, and
129 * creating Notify and MessageQ transport instances. The HeapMemMP
130 * created in Region 0 is the length of the region minus memory
131 * reserved for creating these internal instances.
132 *
133 * Refer to the doxygen documentation for run-time API documenation.
134 *
135 */
136
137 module SharedRegion
138 {
139 /*!
140 * ======== RegionView ========
141 * @_nodoc
142 */
143 metaonly struct RegionView {
144 String base;
145 String end;
146 String len;
147 UInt16 ownerProcId;
148 Bool cacheEnable;
149 Bool isValid;
150 UInt16 cacheLineSize;
151 SizeT reservedSize;
152 Ptr heap;
153 String name;
154 };
155
156 /*!
157 * ======== rovViewInfo ========
158 * @_nodoc
159 */
160 @Facet
161 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
162 xdc.rov.ViewInfo.create({
163 viewMap: [
164 ['Regions',
165 {
166 type: xdc.rov.ViewInfo.MODULE_DATA,
167 viewInitFxn: 'viewInitRegions',
168 structName: 'RegionView'
169 }
170 ]
171 ]
172 });
173
174 /*!
175 * Definition of shared region pointer type
176 */
177 typedef Bits32 SRPtr;
178
179 /*!
180 * Assert raised when the id is larger than numEntries.
181 */
182 config xdc.runtime.Assert.Id A_idTooLarge =
183 {msg: "A_idTooLarge: id cannot be larger than numEntries"};
184
185 /*!
186 * Assert raised when an address is out of the range of the region id.
187 */
188 config xdc.runtime.Assert.Id A_addrOutOfRange =
189 {msg: "A_addrOutOfRange: Address is out of region id's range"};
190
191 /*!
192 * Assert raised when attempting to clear region 0
193 */
194 config xdc.runtime.Assert.Id A_region0Clear =
195 {msg: "A_region0Clear: Region 0 cannot be cleared"};
196
197 /*!
198 * Assert raised when region zero is invalid
199 */
200 config xdc.runtime.Assert.Id A_region0Invalid =
201 {msg: "A_region0Invalid: Region zero is invalid"};
202
203 /*!
204 * Assert raised when region is invalid
205 */
206 config xdc.runtime.Assert.Id A_regionInvalid =
207 {msg: "A_regionInvalid: Region is invalid"};
208
209 /*!
210 * Assert raised when the trying to reserve too much memory.
211 */
212 config xdc.runtime.Assert.Id A_reserveTooMuch =
213 {msg: "A_reserveTooMuch: Trying to reserve too much memory"};
214
215 /*!
216 * Assert raised when cache enabled but cache line size = 0.
217 */
218 config xdc.runtime.Assert.Id A_cacheLineSizeIsZero =
219 {msg: "A_cacheLineSizeIsZero: cache line size cannot be zero"};
220
221 /*!
222 * Assert raised when a new entry overlaps an existing one.
223 */
224 config xdc.runtime.Assert.Id A_overlap =
225 {msg: "A_overlap: Shared region overlaps"};
226
227 /*!
228 * Assert raised when a valid table entry already exists.
229 */
230 config xdc.runtime.Assert.Id A_alreadyExists =
231 {msg: "A_alreadyExists: Trying to overwrite an existing valid entry"};
232
233 /*!
234 * Assert raised when trying to use a heap for a region that has no heap
235 */
236 config xdc.runtime.Assert.Id A_noHeap =
237 {msg: "A_noHeap: Region has no heap"};
238
239 /*!
240 * ======== Entry ========
241 * Structure for specifying a region.
242 *
243 * Each region entry should not overlap with any other entry. The
244 * length of a region should be the same across all processors.
245 *
246 * During static configuration, the 'isValid' field can be set to 'false'
247 * to signify a partially completed entry. This should only be done
248 * if the base address of the entry is not known during static
249 * configuration. The entry can be completed and the
250 * 'isValid' field can be set to true at runtime.
251 *
252 * @field(base) The base address.
253 * @field(len) The length.
254 * @field(ownerProcId) MultiProc id of processor that manages region.
255 * @field(isValid) Whether the region is valid or not.
256 * @field(cacheEnable) Whether the region is cacheable.
257 * @field(cacheLineSize) The cache line size for the region.
258 * @field(createHeap) Whether a heap is created for the region.
259 * @field(name) The name associated with the region.
260 */
261 struct Entry {
262 Ptr base;
263 SizeT len;
264 UInt16 ownerProcId;
265 Bool isValid;
266 Bool cacheEnable;
267 SizeT cacheLineSize;
268 Bool createHeap;
269 String name;
270 };
271
272 /*! Specifies the invalid id */
273 const UInt16 INVALIDREGIONID = 0xFFFF;
274
275 /*! Specifies the default owner proc id */
276 const UInt16 DEFAULTOWNERID = ~0;
277
278 /*!
279 * Worst-case cache line size
280 *
281 * This is the default system cache line size for all modules.
282 * When a module puts structures in shared memory, this value is
283 * used to make sure items are aligned on a cache line boundary.
284 * If no cacheLineSize is specified for a region, it will use this
285 * value.
286 */
287 config SizeT cacheLineSize = 128;
288
289 /*!
290 * The number of shared region table entries.
291 *
292 * This value is used for calculating the number of bits for the offset.
293 * Note: This value must be the same across all processors in the system.
294 * Increasing this parameter will increase the footprint and
295 * the time for translating a pointer to a SRPtr.
296 */
297 config UInt16 numEntries = 4;
298
299 /*!
300 * Determines whether address translation is required.
301 *
302 * This configuration parameter should be set to 'false' if and only if all
303 * shared memory regions have the same base address for all processors.
304 * If 'false', it results in a fast {@link #getPtr} and {@link #getSRPtr},
305 * because a SRPtr is equivalent to a Ptr and no translation is done.
306 */
307 config Bool translate = true;
308
309 /*! @_nodoc
310 * Value that corresponds to NULL in SRPtr address space.
311 */
312 config SRPtr INVALIDSRPTR = 0xFFFFFFFF;
313
314 /*! @_nodoc
315 * ======== attach ========
316 * Opens a heap, for non-owner processors, for each SharedRegion.
317 *
318 * Function is called in Ipc_attach().
319 */
320 Int attach(UInt16 remoteProcId);
321
322 /*! @_nodoc
323 * ======== clearReservedMemory ========
324 * Clears the reserve memory for each region in the table.
325 */
326 Void clearReservedMemory();
327
328 /*!
329 * ======== getCacheLineSizeMeta ========
330 * Meta version of Ipc_getCacheLineSize
331 */
332 metaonly SizeT getCacheLineSizeMeta(UInt16 id);
333
334 /*! @_nodoc
335 * ======== getIdMeta ========
336 * Returns the region id for a given local address
337 *
338 * @param(addr) Address to retrieve the shared region pointer.
339 *
340 * @b(returns) region id
341 */
342 metaonly UInt16 getIdMeta(Ptr addr);
343
344 /*! @_nodoc
345 * ======== getPtrMeta ========
346 * Meta version of {@link #getPtr}
347 */
348 metaonly Ptr getPtrMeta(SRPtr srptr);
349
350 /*! @_nodoc
351 * ======== getPtrMeta$view ========
352 * ROV-time version of getPtrMeta
353 *
354 * @param(srptr) Shared region pointer.
355 *
356 * @b(returns) Pointer associated with shared region pointer.
357 */
358 metaonly Ptr getPtrMeta$view(SRPtr srptr);
359
360 /*! @_nodoc
361 * ======== getSRPtrMeta ========
362 * Meta version of {@link #getSRPtr}
363 */
364 metaonly SRPtr getSRPtrMeta(Ptr addr);
365
366 /*! @_nodoc
367 * ======== getSRPtrMeta$view ========
368 * ROV-time version of getSRPtrMeta
369 *
370 * @param(addr) Address to retrieve the shared region pointer.
371 *
372 * @b(returns) Shared region pointer.
373 */
374 metaonly SRPtr getSRPtrMeta$view(Ptr addr);
375
376 /*! @_nodoc
377 * ======== isCacheEnabledMeta ========
378 * Meta version of {@link #isCacheEnabled}
379 */
380 metaonly Bool isCacheEnabledMeta(UInt16 id);
381
382 /*! @_nodoc
383 * ======== reserveMemory ========
384 * Reserves the specified amount of memory from the specified region id.
385 *
386 * Must be called before Ipc_start(). The amount of memory reserved
387 * must be the same on all cores.
388 * The return pointer is the starting address that was reserved.
389 *
390 * @param(id) Region id.
391 * @param(size) Amount of memory to reserve.
392 *
393 * @b(returns) Starting address of memory reserved.
394 */
395 Ptr reserveMemory(UInt16 id, SizeT size);
396
397 /*!
398 * ======== setEntryMeta ========
399 * Sets the entry at the specified region id in the shared region table.
400 *
401 * The required parameters are base and len. All the other fields will
402 * get their default if not specified.
403 *
404 * @param(id) Region id.
405 * @param(entry) Entry fields about the region.
406 */
407 metaonly Void setEntryMeta(UInt16 id, Entry entry);
408
409 /*! @_nodoc
410 * ======== start ========
411 * Creates a heap by owner of region for each SharedRegion.
412 *
413 * Function is called by Ipc_start(). Requires that SharedRegion 0
414 * be valid before calling start().
415 */
416 Int start();
417
418
419 internal:
420
421 const UInt32 CREATED = 0x08111963;
422
423
424 struct Region {
425 Entry entry;
426 SizeT reservedSize;
427 IHeap.Handle heap;
428 };
429
430
431 metaonly config Entry entry[];
432
433
434 metaonly config UInt entryCount;
435
436
437 config UInt32 numOffsetBits;
438
439
440 config UInt32 offsetMask;
441
442 443 444 445 446 447 448 449 450
451 Int checkOverlap(Ptr base, SizeT len);
452
453 454 455 456 457
458 struct Module_State {
459 Region regions[];
460 };
461 }
462
463 464 465
466