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 package xdc.platform;
17
18 /*!
19 * ======== IPlatform ========
20 * Configuration-time interface to all platforms.
21 *
22 * This interface defines the elements that must be implemented by all
23 * "platform packages". All programs are built to execute on a platform
24 * and each program includes exactly one platform package (which defines
25 * the platform).
26 *
27 * Platform packages contain exactly one module named "Platform" which
28 * implements the `xdc.platform.IPlatform` interface defined here.
29 *
30 * Program configuration scripts may read (but not modify) the attributes
31 * provided by this interface from the global `Program` object; see
32 * `{@link xdc.cfg.Program#platform}`.
33 */
34 metaonlyinterface IPlatform
35 {
36 /*!
37 * ======== Board ========
38 * Board-level description.
39 */
40 struct Board {
41 string id; /*! unique id within the platform */
42 string boardName; /*! name of the board */
43 string boardFamily; /*! optional family name */
44 string boardRevision; /*! optional revision string */
45 };
46
47 /*!
48 * ======== Memory ========
49 * A named contiguous range of addresses.
50 *
51 * Memory structures are used in the description of the memory available
52 * from CPUs and platforms.
53 */
54 struct Memory {
55 string comment; /*! description of this block */
56 string name; /*! name of memory segment */
57 string space; /*! "code", "data", "code/data", etc.... */
58 unsigned page; /*! page of memory segment */
59 unsigned base; /*! base address of memory segment */
60 unsigned len; /*! length of memory segment */
61 string access; /*! attributes of memory: "RWX" */
62 };
63
64 /*! Type to be used for maps of Memory objects */
65 typedef Memory MemoryMap[string];
66
67 instance:
68 /*!
69 * ======== create ========
70 * Constructor for IPlatform instances.
71 *
72 * @param(name) the name of the platform instance being created
73 *
74 * This name is the suffix of the platform
75 * specification supplied in the build script after
76 * the platform name (and optional ':') prefix has
77 * been removed. So the platform instance name
78 * "joes.platform.foo:bar" results in the name "bar"
79 * and the name "joes.platform.foo" result in the name
80 * "".
81 *
82 * @param(args) deprecated parameter that should not be used in
83 * a platform instance implementation
84 *
85 */
86 create(string name, any args);
87
88 /*
89 * ======== memTab ========
90 * A mapping of memory names to external memory objects.
91 *
92 * This hash table is used to map linker memory region names ("EPROG",
93 * "EDATA", etc.) to `{@link xdc.platform.IPlatform#Memory}` objects.
94 * During generation of linker command files, for example, this table
95 * may be used to genenerate physical memory map declarations.
96 *
97 * Platforms with a fixed memory map can initialize this table
98 * "statically" in Platform.xdc using the following syntax:
99 * @p(code)
100 * override config xdc.platform.IPlatform.Memory memTab[string] = [
101 * ["PMEM", {name: "PMEM", base: 0x00000200, len: 0x0000FE00}],
102 * :
103 * ];
104 * @p
105 * Alternatively, platforms can initialize this table dynamically in
106 * the platform package's `init()` function (see `{@link xdc.IPackage}`)
107 * using the following syntax:
108 * @p(code)
109 * function init()
110 * {
111 * :
112 * this.memTab["PMEM"] = {name: "PMEM", base: 0x200, len: 0xFE00};
113 * :
114 * }
115 * @p
116 * @a(readonly) this parameter is set by the platform and read by
117 * program configuration scripts.
118 */
119 // config Memory memTab[string]; /* memory name => memory object */
120
121 /*!
122 * ======== externalMemoryMap ========
123 * A mapping of memory names to memory objects for external memory.
124 *
125 * This parameter defines the external portion of the platform's memory
126 * map.
127 */
128 readonlyconfig xdc.platform.IPlatform.Memory externalMemoryMap[string];
129
130 /*!
131 * ======== customMemoryMap ========
132 * A custom mapping of memory names to memory objects.
133 *
134 * This parameter allows platform instances to completely overwrite a
135 * default memory map based on the internal memory map coming from CPU's
136 * memory map and externalMemoryMap.
137 *
138 * Custom memory map must fit within the default memory map, unless the
139 * verification of the fit is disabled (see `{@link xdc.platform}`).
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 * During the generation of linker command files, the templates used to
210 * create these files examine several sources of information to determine
211 * the placement of named output sections into memory segments defined
212 * by the platform. The default placement, described below,
213 * uses information from the target and this platform's
214 * `{@link #codeMemory}`, `{@link #dataMemory}`, and
215 * `{@link #stackMemory}` configuration parameters.
216 *
217 * `sectMap` is used to override this default placement of
218 * output sections (".text", ".cinit", etc.) to a memory
219 * segment defined by the platform's memory map. For example, even if
220 * a platform's `codeMemory` parameter is defined to be "SRAM" and
221 * ".cinit" output sections are "code" sections, if the platform also
222 * defines the following `sectMap`, the section ".cinit" will be placed
223 * into a memory segment named "DDR2".
224 * @p(code) 225 * sectMap[] = [
226 * [".cinit", "DDR2"],
227 * ];
228 * @p 229 *
230 * @a(Note) If an output section has an entry in
231 * `{@link xdc.cfg.Program#sectMap Program.sectMap}`, that entry
232 * overrides the placement specified by this `sectMap`. A program's
233 * `sectMap` configuration always overrides the platform's `sectMap`
234 * settings.
235 *
236 * @a(Default Mapping) 237 * The default placement of a target's output sections into memory
238 * segments defined by the platform is determined by the following
239 * configuration parameters:
240 * @p(blist) 241 * - `{@link xdc.bld.ITarget#sectMap ITarget.sectMap}`
242 * used to map a named output section to either "code", "data",
243 * or "stack"
244 * - `{@link #codeMemory}`
245 * names a memory segment that will contain all "code"
246 * output sections
247 * - `{@link #dataMemory}`
248 * names a memory segment that will contain all "data"
249 * output sections
250 * - `{@link #stackMemory}`
251 * names a memory segment that will contain all "stack"
252 * output sections
253 * @p 254 *
255 * @see xdc.cfg.Program#sectMap
256 * @see xdc.bld.ITarget#sectMap
257 */
258 config string sectMap[string]; /* section name => memory segment */
259
260 /*!
261 * ======== peripherals ========
262 * @_nodoc 263 *
264 * A map of peripherals available on a platform instance
265 *
266 * The map contains peripherals from an
267 * `{@link xdc.platform.ICpuDataSheet}` instance available as
268 * `{@link xdc.cfg.Program#cpu.attrs}`, and peripherals defined in this
269 * platform instance. The map is initialized by the platform instance,
270 * and in multicore platforms the instance must add only peripherals
271 * available to the CPU for which an executable is being built.
272 */
273 //config IPeripheral.Instance peripherals[string];
274
275 /*!
276 * ======== getCpuDataSheet ========
277 * Get the Cpu data sheet object corresponding to specified cpu id.
278 *
279 * This function executes in either the Configuration object model
280 * or the Build object model.
281 *
282 * @param(cpuId) a string that corresponds to the platform-specific id
283 * of a CPU on this platform that runs executables.
284 *
285 * @a(returns) Returns an `{@link xdc.platform.ICpuDataSheet}`
286 * instance object that corresponds to the specified
287 * cpuId.
288 *
289 * @a(throws) `Error` exceptions are thrown for fatal errors.
290 */
291 function getCpuDataSheet(cpuId);
292 // xdc.platform.ICpuDataSheet.Instance getCpuDataSheet(string cpuId);
293
294 /*!
295 * ======== getCreateArgs ========
296 * DEPRECATED
297 * @_nodoc 298 *
299 * Get the value of the args parameter used to create this instance
300 *
301 * This function executes in either the Configuration object model
302 * or the Build object model.
303 *
304 * @a(returns) Returns the "args" object that passed to this
305 * module's create method when the instance was created.
306 *
307 * @a(throws) `Error` exceptions are thrown for fatal errors.
308 */
309 function getCreateArgs();
310 // any getCreateArgs();
311
312 /*!
313 * ======== getExeContext ========
314 * Get execution context object corresponding to the specified program.
315 *
316 * This is called before the program's configuration script runs to
317 * get the Cpu object that is assigned to the program's cpu field.
318 *
319 * Note: that the build script for the program is responsible for
320 * specifying the CPU; this is done by either implicitly naming the
321 * platform or explicitly naming a particular CPU on the platform
322 * (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
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 * @a(returns) Returns an `{@link xdc.platform.IExeContext}` instance
337 * object that corresponds to the CPU that will run the
338 * specified program.
339 *
340 * @a(throws) `Error` exceptions are thrown for fatal errors.
341 */
342 function getExeContext(prog);
343 // xdc.platform.IExeContext.Instance getExeContext(xdc.cfg.Program.Module prog);
344
345 /*!
346 * ======== getExecCmd ========
347 * Get the exec command used to run the program on this platform.
348 *
349 * This function is called after the program's configuration script runs
350 * and returns commands that are used to load and run the specified
351 * program. These commands are placed in a makefile that is included
352 * by the client package's generated makefile. Thus, the commands may
353 * refer to macros defined in this environment; e.g., `$(SHELL)` and
354 * `$(XDCROOT)`, etc.
355 *
356 * The special macro `$(1)` expands to test-specific arguments
357 * (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
358 * to the platform's exec command. Thus, all platforms that support
359 * arguments to their exec command, should embed "`$(1)`" within the
360 * command string at the appropriate place to have these arguments
361 * interpreted by the exec command.
362 *
363 * For example, a platform that uses a shell script to run executables
364 * and allows options to be passed to the shell script might return
365 * the following string:
366 * @p(code) 367 * "$(SHELL) <exec_path> $(1) <exe_name>"
368 * @p 369 * where, `<exec_path>` is the absolute path to the platform's exec
370 * shell script, and `<prog_name>` is the name of the executable relative
371 * to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
372 *
373 * This function executes in the Configuration object model.
374 *
375 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
376 * program being configured.
377 *
378 * This object contains the following properties that
379 * allows the platform to determine the appropriate Cpu
380 * object to return (if there is more than one):
381 * `prog.build.cpuId`,
382 * `prog.build.cpuArgs`,
383 * `prog.build.target`
384 *
385 * @param(platPath) full path to the platform package for the program
386 *
387 * @a(returns) Returns a string of commands used to execute this
388 * program in the context of the XDC generated makefiles.
389 *
390 * @a(throws) `Error` exceptions are thrown for fatal errors.
391 */
392 function getExecCmd(prog, platPath);
393 // string getExecCmd(xdc.cfg.Program.Module prog, string platPath);
394
395 /*!
396 * ======== getLinkTemplate ========
397 * Get Linker Command file template used to link an executable.
398 *
399 * In the event that no template is provided by the program
400 * configuration script (see `{@link xdc.cfg.Program#linkTemplate}`),
401 * the template file identified by this method is used to generate the
402 * linker command file used to create the executable.
403 *
404 * This function executes in the Configuration object model and
405 * is called after the program configuration script runs. The template
406 * is expanded in the context of the Configuration Object Model.
407 *
408 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
409 * program being configured.
410 *
411 * This object contains the following properties that
412 * allows the platform to determine the appropriate link
413 * template to return:
414 * @p(blist) 415 * - `prog.build.cpuId`,
416 * - `prog.build.cpuArgs`,
417 * - `prog.build.target`
418 * @p 419 * @a(returns) Returns a path string to a template file or `null`. If
420 * `null`, no linker command file is generated; otherwise
421 * this path is relative to the package path.
422 *
423 * @a(throws) `Error` exceptions are thrown for fatal errors.
424 */
425 function getLinkTemplate(prog);
426 // string getLinkTemplate(prog);
427 }
428 /*
429 * @(#) xdc.platform; 1, 0, 1, 0,360; 11-16-2011 10:59:57; /db/ztree/library/trees/xdc/xdc-y13x/src/packages/
430 */
431