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 * ======== IPlatform.xdc ========
14 *
15 */
16
17 package xdc.platform;
18
19 /*!
20 * ======== IPlatform ========
21 * Configuration-time interface to all platforms.
22 *
23 * This interface defines the elements that must be implemented by all
24 * "platform packages". All programs are built to execute on a platform
25 * and each program includes exactly one platform package (which defines
26 * the platform).
27 *
28 * Platform packages contain exactly one module named "Platform" which
29 * implements the `xdc.platform.IPlatform` interface defined here.
30 *
31 * Program configuration scripts may read (but not modify) the attributes
32 * provided by this interface from the global `Program` object; see
33 * `{@link xdc.cfg.Program#platform}`.
34 */
35 metaonlyinterface IPlatform
36 {
37 /*!
38 * ======== Board ========
39 * Board-level description.
40 */
41 struct Board {
42 string id; /*! unique id within the platform */
43 string boardName; /*! name of the board */
44 string boardFamily; /*! optional family name */
45 string boardRevision; /*! optional revision string */
46 };
47
48 /*!
49 * ======== Memory ========
50 * A named contiguous range of addresses.
51 *
52 * Memory structures are used in the description of the memory available
53 * from CPUs and platforms.
54 */
55 struct Memory {
56 string comment; /*! description of this block */
57 string name; /*! name of memory segment */
58 string space; /*! "code", "data", "code/data", etc... */
59 unsigned page; /*! page of memory segment */
60 unsigned base; /*! base address of memory segment */
61 unsigned len; /*! length of memory segment */
62 string access; /*! attributes of memory: "RWX" must be u.c.*/
63 };
64
65 /*! Type to be used for maps of Memory objects */
66 typedef Memory MemoryMap[string];
67
68 instance:
69 /*!
70 * ======== create ========
71 * Constructor for IPlatform instances.
72 *
73 * @param(name) the name of the platform instance being created
74 *
75 * This name is the suffix of the platform
76 * specification supplied in the build script after
77 * the platform name (and optional ':') prefix has
78 * been removed. So the platform instance name
79 * "joes.platform.foo:bar" results in the name "bar"
80 * and the name "joes.platform.foo" result in the name
81 * "".
82 *
83 * @param(args) deprecated parameter that should not be used in
84 * a platform instance implementation
85 *
86 */
87 create(string name, any args);
88
89 /*
90 * ======== memTab ========
91 * A mapping of memory names to external memory objects.
92 *
93 * This hash table is used to map linker memory region names ("EPROG",
94 * "EDATA", etc.) to `{@link xdc.platform.IPlatform#Memory}` objects.
95 * During generation of linker command files, for example, this table
96 * may be used to genenerate physical memory map declarations.
97 *
98 * Platforms with a fixed memory map can initialize this table
99 * "statically" in Platform.xdc using the following syntax:
100 * @p(code)
101 * override config xdc.platform.IPlatform.Memory memTab[string] = [
102 * ["PMEM", {name: "PMEM", base: 0x00000200, len: 0x0000FE00}],
103 * :
104 * ];
105 * @p
106 * Alternatively, platforms can initialize this table dynamically in
107 * the platform package's `init()` function (see `{@link xdc.IPackage}`)
108 * using the following syntax:
109 * @p(code)
110 * function init()
111 * {
112 * :
113 * this.memTab["PMEM"] = {name: "PMEM", base: 0x200, len: 0xFE00};
114 * :
115 * }
116 * @p
117 * @a(readonly) this parameter is set by the platform and read by
118 * program configuration scripts.
119 */
120 // config Memory memTab[string]; /* memory name => memory object */
121
122 /*!
123 * ======== externalMemoryMap ========
124 * A mapping of memory names to memory objects for external memory.
125 *
126 * This parameter defines the external portion of the platform's memory
127 * map.
128 */
129 readonlyconfig xdc.platform.IPlatform.Memory externalMemoryMap[string];
130
131 /*!
132 * ======== customMemoryMap ========
133 * A custom mapping of memory names to memory objects.
134 *
135 * This parameter allows platform instances to completely overwrite a
136 * default memory map based on the internal memory map coming from CPU's
137 * memory map and externalMemoryMap.
138 *
139 * Custom memory map must fit within the default memory map.
140 */
141 config xdc.platform.IPlatform.Memory customMemoryMap[string];
142
143 /*!
144 * ======== renameMap ========
145 * A map for renaming memory objects.
146 *
147 * This map renames memory objects. If you do not want to change
148 * addresses in the default memory map, but you only want to rename the
149 * existing memory objects, you should use this parameter.
150 *
151 * This map and 'customMemoryMap' should not be used together because this
152 * map renames the default memory, but then 'customMemoryMap' replaces the
153 * default memory objects. The parameters 'codeMemory', 'dataMemory' and
154 * 'stackMemory' are not automatically reassigned to new names. It is the
155 * user's responsibility to set those parameters accordingly to
156 * 'renameMap'.
157 */
158 config string renameMap[string];
159
160 /*!
161 * ======== dataMemory ========
162 * The default segment for data sections.
163 *
164 * Each target has a section map with keys equal to the names of all
165 * sections that compiler and assembler for that target generate. The
166 * value for each key is either "code" or "data" or "stack". A linker
167 * template reads that map and puts all "data" sections in the segment
168 * defined by this configuration parameter.
169 *
170 * @see #codeMemory
171 * @see #stackMemory
172 */
173 config string dataMemory;
174
175 /*!
176 * ======== codeMemory ========
177 * The default segment for code sections.
178 *
179 * Each target has a section map with keys equal to the names of all
180 * sections that compiler and assembler for that target generate. The
181 * value for each key is either "code" or "data" or "stack". A linker
182 * template reads that map and puts all "code" sections in the segment
183 * defined by this configuration parameter.
184 *
185 * @see #dataMemory
186 * @see #stackMemory
187 */
188 config string codeMemory;
189
190 /*!
191 * ======== stackMemory ========
192 * The default segment for stack.
193 *
194 * Each target has a section map with keys equal to the names of all
195 * sections that compiler and assembler for that target generate. The
196 * value for each key is either "code" or "data" or "stack". A linker
197 * template reads that map and puts all "stack" sections in the segment
198 * defined by this configuration parameter.
199 *
200 * @see #dataMemory
201 * @see #codeMemory
202 */
203 config string stackMemory;
204
205 /*!
206 * ======== sectMap ========
207 * A mapping of linker output section names to memory segments.
208 *
209 * This hash table is used to map a particular COFF output section
210 * (".text", ".stack", etc.) to a memory segment defined by this
211 * platform's memory map.
212 *
213 * This sectMap is referenced by linker command file templates during
214 * generation to create linker command files. The default allocation of
215 * sections is defined by matching ITarget.sectMap, and codeMemory and
216 * dataMemory parameters from a platform. Additionally, if
217 * Platform.sectMap is defined, it can override that default allocation
218 * for sections listed in Platform.sectMap. Finally, if a section has an
219 * entry in Program.sectMap, that entry overrides all other allocations.
220 */
221 config string sectMap[string]; /* section name => memory segment */
222
223 /*!
224 * ======== getCpuDataSheet ========
225 * Get the Cpu data sheet object corresponding to specified cpu id.
226 *
227 * This function executes in either the Configuration object model
228 * or the Build object model.
229 *
230 * @param(cpuId) a string that corresponds to the platform-specific id
231 * of a CPU on this platform that runs executables.
232 *
233 * @a(returns) Returns an `{@link xdc.platform.ICpuDataSheet}`
234 * instance object that corresponds to the specified
235 * cpuId.
236 *
237 * @a(throws) `Error` exceptions are thrown for fatal errors.
238 */
239 function getCpuDataSheet(cpuId);
240 // xdc.platform.ICpuDataSheet.Instance getCpuDataSheet(string cpuId);
241
242 /*!
243 * ======== getCreateArgs ========
244 * DEPRECATED
245 * @_nodoc 246 *
247 * Get the value of the args parameter used to create this instance
248 *
249 * This function executes in either the Configuration object model
250 * or the Build object model.
251 *
252 * @a(returns) Returns the "args" object that passed to this
253 * module's create method when the instance was created.
254 *
255 * @a(throws) `Error` exceptions are thrown for fatal errors.
256 */
257 function getCreateArgs();
258 // any getCreateArgs();
259
260 /*!
261 * ======== getExeContext ========
262 * Get execution context object corresponding to the specified program.
263 *
264 * This is called before the program's configuration script runs to
265 * get the Cpu object that is assigned to the program's cpu field.
266 *
267 * Note: that the build script for the program is responsible for
268 * specifying the CPU; this is done by either implicitly naming the
269 * platform or explicitly naming a particular CPU on the platform
270 * (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
271 *
272 * This function executes in the Configuration object model.
273 *
274 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
275 * program being configured.
276 *
277 * This object contains the following properties that
278 * allows the platform to determine the appropriate Cpu
279 * object to return (if there is more than one):
280 * `prog.build.cpuId`,
281 * `prog.build.cpuArgs`,
282 * `prog.build.target`,
283 *
284 * @a(returns) Returns an `{@link xdc.platform.IExeContext}` instance
285 * object that corresponds to the CPU that will run the
286 * specified program.
287 *
288 * @a(throws) `Error` exceptions are thrown for fatal errors.
289 */
290 function getExeContext(prog);
291 // xdc.platform.IExeContext.Instance getExeContext(xdc.cfg.Program.Module prog);
292
293 /*!
294 * ======== getExecCmd ========
295 * Get the exec command used to run the program on this platform.
296 *
297 * This function is called after the program's configuration script runs
298 * and returns commands that are used to load and run the specified
299 * program. These commands are placed in a makefile that is included
300 * by the client package's generated makefile. Thus, the commands may
301 * refer to macros defined in this environment; e.g., `$(SHELL)` and
302 * `$(XDCROOT)`, etc.
303 *
304 * The special macro `$(1)` expands to test-specific arguments
305 * (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
306 * to the platform's exec command. Thus, all platforms that support
307 * arguments to their exec command, should embed "`$(1)`" within the
308 * command string at the appropriate place to have these arguments
309 * interpreted the exec command.
310 *
311 * For example, a platform that uses a shell script to run executables
312 * and allows options to be passed to the shell script might return
313 * the following string:
314 * @p(code) 315 * "$(SHELL) <exec_path> $(1) <exe_name>"
316 * @p 317 * where, `<exec_path>` is the absolute path to the platform's exec
318 * shell script, and `<prog_name>` is the name of the executable relative
319 * to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
320 *
321 * This function executes in the Configuration object model.
322 *
323 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
324 * program being configured.
325 *
326 * This object contains the following properties that
327 * allows the platform to determine the appropriate Cpu
328 * object to return (if there is more than one):
329 * `prog.build.cpuId`,
330 * `prog.build.cpuArgs`,
331 * `prog.build.target`
332 *
333 * @param(platPath) full path to the platform package for the program
334 *
335 * @a(returns) Returns a string of commands used to execute this
336 * program in the context of the XDC generated makefiles.
337 *
338 * @a(throws) `Error` exceptions are thrown for fatal errors.
339 */
340 function getExecCmd(prog, platPath);
341 // string getExecCmd(xdc.cfg.Program.Module prog, string platPath);
342
343 /*!
344 * ======== getLinkTemplate ========
345 * Get Linker Command file template used to link an executable.
346 *
347 * In the event that no template is provided by the program
348 * configuration script (see `{@link xdc.cfg.Program#linkTemplate}`),
349 * the template file identified by this method is used to generate the
350 * linker command file used to create the executable.
351 *
352 * This function executes in the Configuration object model and
353 * is called after the program configuration script runs. The template
354 * is expanded in the context of the Configuration Object Model.
355 *
356 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
357 * program being configured.
358 *
359 * This object contains the following properties that
360 * allows the platform to determine the appropriate link
361 * template to return:
362 * @p(blist) 363 * - `prog.build.cpuId`,
364 * - `prog.build.cpuArgs`,
365 * - `prog.build.target`
366 * @p 367 * @a(returns) Returns a path string to a template file or `null`. If
368 * `null`, no linker command file is generated; otherwise
369 * this path is relative to the package path.
370 *
371 * @a(throws) `Error` exceptions are thrown for fatal errors.
372 */
373 function getLinkTemplate(prog);
374 // string getLinkTemplate(prog);
375 }
376 /*
377 * @(#) xdc.platform; 1, 0, 1, 0,207; 6-9-2009 20:09:02; /db/ztree/library/trees/xdc-t50x/src/packages/
378 */
379