1 /*
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12 /*
13 * ======== Utils.xdc ========
14 */
15
16 package xdc.platform;
17
18 /*!
19 * ======== Utils ========
20 * Misc platform utilities
21 */
22 metaonlymodule Utils
23 {
24 /*!
25 * ======== addPeripheralsMap ========
26 * Create a map of all peripherals available on a device.
27 *
28 * The config parameter `peripherals` is by default undefined in an
29 * `{@link xdc.platform.ICpuDataSheet}` instance. This function gathers
30 * all instance configuration parameters that are of the type
31 * `{@link xdc.platform.IPeripheral}` into the map `peripherals`.
32 *
33 * @param(cds) an `{@link xdc.platform.ICpuDataSheet}` instance
34 *
35 */
36 Void addPeripheralsMap(ICpuDataSheet.Instance cds);
37
38 /*!
39 * ======== assembleMemoryMap ========
40 * Combine the device and the external memory map into a platform map
41 *
42 * This function combines memory maps and also applies memory map name
43 * changes requested through renameMap.
44 *
45 * @param(cpu) an `xdc.platform.IExeContext` object
46 *
47 * @param(plat) a platform instance
48 *
49 * @param(noCheck) if true, and a custom memory map is defined, the
50 * function does not check if the custom memory map fits
51 * into the available physical memory
52 *
53 * @a(returns) platform memory map
54 */
55 function assembleMemoryMap(cpu, plat, noCheck);
56
57 /*!
58 * ======== assemblePeripheralsMap ========
59 * Create a map of all peripherals available on a platform.
60 *
61 * The config parameter `peripherals` is by default undefined in an
62 * `{@link xdc.platform.IPlatform}` instance. This function gathers
63 * all peripherals defined in an `{@link xdc.platform.ICpuDataSheet}`
64 * instance available as `{@link xdc.cfg.Program#cpu.attrs}`, and adds
65 * peripherals defined in this platform instance. By providing a list
66 * of config parameter names, the instance can add only listed
67 * peripherals instead of adding all available ones.
68 *
69 * @param(inst) an `xdc.platform.IPlatform` instance
70 * @param(cds) an `xdc.platform.ICpuDataSheet` instance
71 * @param(names) an optional list of names of `IPeripheral` parameters
72 *
73 */
74 Void assemblePeripheralsMap(ICpuDataSheet.Instance cds,
75 IPlatform.Instance inst, String names[] = []);
76
77 /*!
78 * ======== checkDefaults ========
79 * Check if dataMemory, codeMemory and stackMemory are set correctly
80 *
81 * The `xdc.platform.IPlatform` instance parameters 'dataMemory',
82 * 'codeMemory', and 'stackMemory' are strings. This function verifies
83 * that those strings correspond to names of the memory objects in the
84 * supplied memory map.
85 *
86 * @param(inst) an `xdc.platform.IPlatform` instance
87 *
88 * @param(memMap) a map of `xdc.platform.IPlatform.Memory` objects
89 *
90 * @a(returns) 'true' if checked parameters are valid, 'false'
91 * otherwise
92 */
93 function checkDefaults(inst, memMap);
94
95 /*!
96 * ======== checkFit ========
97 * Check if a memory map fits into available physical memory
98 *
99 * A custom memory map segment can be spread over multiple physical
100 * memories or multiple custom memory map segments can be located in
101 * one physical memory. However, code/data restrictions must be followed.
102 * A custom memory segment with the parameter 'space' set to "code/data",
103 * which is the default value if the parameter was not specified, can fit
104 * only into "code/data" physical memories. Custom memory segments with
105 * 'space' set to "code" can fit into "code" and "code/data" memories, and
106 * custom memory segments with 'space' set to "data" can fit into "data"
107 * and "code/data" physical memories.
108 *
109 * @param(realMemMap) a map of `xdc.platform.IPlatform.Memory`
110 * objects containing physical memory map as
111 * defined in datasheets for the device and the
112 * platform
113 *
114 * @param(customMemMap) a map of `xdc.platform.IPlatform.Memory`
115 * objects containing user defined memory map,
116 * which must fit within boundaries of 'realMemMap'
117 *
118 * @a(returns) 'true', if customMemMap fits within realMemMap,
119 * and 'false' otherwise
120 */
121 function checkFit(realMemMap, customMemMap);
122
123 /*!
124 * ======== checkOverlap ========
125 * Check if there is an overlap among memory objects in a memory map
126 *
127 * @param(memMap) a map of `xdc.platform.IPlatform.Memory` objects
128 *
129 * @a(returns) a string with names of Memory objects that overlap
130 */
131 function checkOverlap(memMap);
132
133 /*!
134 * ======== getCpuDataSheet ========
135 * Get the specified cpu data sheet object
136 *
137 * @param(cpuDesc) an `xdc.platform.IExeContext.Cpu` object identifying
138 * the CPU device
139 *
140 * @a(returns) an `xdc.platform.ICpuDataSheet.Instance` object that
141 * corresponds to the specified cpuDesc
142 *
143 * @a(throws) `Error` exceptions are thrown for fatal errors
144 */
145 function getCpuDataSheet(cpuDesc);
146 }
147
148 /*
149 * @(#) xdc.platform; 1, 0, 1, 0,324; 4-29-2011 10:51:43; /db/ztree/library/trees/xdc/xdc-x03x/src/packages/
150 */
151