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