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.
139 */
140 config xdc.platform.IPlatform.Memory customMemoryMap[string];
141
142 /*!
143 * ======== renameMap ========
144 * A map for renaming memory objects.
145 *
146 * This map renames memory objects. If you do not want to change
147 * addresses in the default memory map, but you only want to rename the
148 * existing memory objects, you should use this parameter.
149 *
150 * This map and 'customMemoryMap' should not be used together because this
151 * map renames the default memory, but then 'customMemoryMap' replaces the
152 * default memory objects. The parameters 'codeMemory', 'dataMemory' and
153 * 'stackMemory' are not automatically reassigned to new names. It is the
154 * user's responsibility to set those parameters accordingly to
155 * 'renameMap'.
156 */
157 config string renameMap[string];
158
159 /*!
160 * ======== dataMemory ========
161 * The default segment for data sections.
162 *
163 * Each target has a section map with keys equal to the names of all
164 * sections that compiler and assembler for that target generate. The
165 * value for each key is either "code" or "data" or "stack". A linker
166 * template reads that map and puts all "data" sections in the segment
167 * defined by this configuration parameter.
168 *
169 * @see #codeMemory
170 * @see #stackMemory
171 */
172 config string dataMemory;
173
174 /*!
175 * ======== codeMemory ========
176 * The default segment for code sections.
177 *
178 * Each target has a section map with keys equal to the names of all
179 * sections that compiler and assembler for that target generate. The
180 * value for each key is either "code" or "data" or "stack". A linker
181 * template reads that map and puts all "code" sections in the segment
182 * defined by this configuration parameter.
183 *
184 * @see #dataMemory
185 * @see #stackMemory
186 */
187 config string codeMemory;
188
189 /*!
190 * ======== stackMemory ========
191 * The default segment for stack.
192 *
193 * Each target has a section map with keys equal to the names of all
194 * sections that compiler and assembler for that target generate. The
195 * value for each key is either "code" or "data" or "stack". A linker
196 * template reads that map and puts all "stack" sections in the segment
197 * defined by this configuration parameter.
198 *
199 * @see #dataMemory
200 * @see #codeMemory
201 */
202 config string stackMemory;
203
204 /*!
205 * ======== sectMap ========
206 * A mapping of linker output section names to memory segments.
207 *
208 * During the generation of linker command files, the templates used to
209 * create these files examine several sources of information to determine
210 * the placement of named output sections into memory segments defined
211 * by the platform. The default placement, described below,
212 * uses information from the target and this platform's
213 * `{@link #codeMemory}`, `{@link #dataMemory}`, and
214 * `{@link #stackMemory}` configuration parameters.
215 *
216 * `sectMap` is used to override this default placement of
217 * output sections (".text", ".cinit", etc.) to a memory
218 * segment defined by the platform's memory map. For example, even if
219 * a platform's `codeMemory` parameter is defined to be "SRAM" and
220 * ".cinit" output sections are "code" sections, if the platform also
221 * defines the following `sectMap`, the section ".cinit" will be placed
222 * into a memory segment named "DDR2".
223 * @p(code) 224 * sectMap[] = [
225 * [".cinit", "DDR2"],
226 * ];
227 * @p 228 *
229 * @a(Note) If an output section has an entry in
230 * `{@link xdc.cfg.Program#sectMap Program.sectMap}`, that entry
231 * overrides the placement specified by this `sectMap`. A program's
232 * `sectMap` configuration always overrides the platform's `sectMap`
233 * settings.
234 *
235 * @a(Default Mapping) 236 * The default placement of a target's output sections into memory
237 * segments defined by the platform is determined by the following
238 * configuration parameters:
239 * @p(blist) 240 * - `{@link xdc.bld.ITarget#sectMap ITarget.sectMap}`
241 * used to map a named output section to either "code", "data",
242 * or "stack"
243 * - `{@link #codeMemory}`
244 * names a memory segment that will contain all "code"
245 * output sections
246 * - `{@link #dataMemory}`
247 * names a memory segment that will contain all "data"
248 * output sections
249 * - `{@link #stackMemory}`
250 * names a memory segment that will contain all "stack"
251 * output sections
252 * @p 253 *
254 * @see xdc.cfg.Program#sectMap
255 * @see xdc.bld.ITarget#sectMap
256 */
257 config string sectMap[string]; /* section name => memory segment */
258
259 /*!
260 * ======== getCpuDataSheet ========
261 * Get the Cpu data sheet object corresponding to specified cpu id.
262 *
263 * This function executes in either the Configuration object model
264 * or the Build object model.
265 *
266 * @param(cpuId) a string that corresponds to the platform-specific id
267 * of a CPU on this platform that runs executables.
268 *
269 * @a(returns) Returns an `{@link xdc.platform.ICpuDataSheet}`
270 * instance object that corresponds to the specified
271 * cpuId.
272 *
273 * @a(throws) `Error` exceptions are thrown for fatal errors.
274 */
275 function getCpuDataSheet(cpuId);
276 // xdc.platform.ICpuDataSheet.Instance getCpuDataSheet(string cpuId);
277
278 /*!
279 * ======== getCreateArgs ========
280 * DEPRECATED
281 * @_nodoc 282 *
283 * Get the value of the args parameter used to create this instance
284 *
285 * This function executes in either the Configuration object model
286 * or the Build object model.
287 *
288 * @a(returns) Returns the "args" object that passed to this
289 * module's create method when the instance was created.
290 *
291 * @a(throws) `Error` exceptions are thrown for fatal errors.
292 */
293 function getCreateArgs();
294 // any getCreateArgs();
295
296 /*!
297 * ======== getExeContext ========
298 * Get execution context object corresponding to the specified program.
299 *
300 * This is called before the program's configuration script runs to
301 * get the Cpu object that is assigned to the program's cpu field.
302 *
303 * Note: that the build script for the program is responsible for
304 * specifying the CPU; this is done by either implicitly naming the
305 * platform or explicitly naming a particular CPU on the platform
306 * (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
307 *
308 * This function executes in the Configuration object model.
309 *
310 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
311 * program being configured.
312 *
313 * This object contains the following properties that
314 * allows the platform to determine the appropriate Cpu
315 * object to return (if there is more than one):
316 * `prog.build.cpuId`,
317 * `prog.build.cpuArgs`,
318 * `prog.build.target`,
319 *
320 * @a(returns) Returns an `{@link xdc.platform.IExeContext}` instance
321 * object that corresponds to the CPU that will run the
322 * specified program.
323 *
324 * @a(throws) `Error` exceptions are thrown for fatal errors.
325 */
326 function getExeContext(prog);
327 // xdc.platform.IExeContext.Instance getExeContext(xdc.cfg.Program.Module prog);
328
329 /*!
330 * ======== getExecCmd ========
331 * Get the exec command used to run the program on this platform.
332 *
333 * This function is called after the program's configuration script runs
334 * and returns commands that are used to load and run the specified
335 * program. These commands are placed in a makefile that is included
336 * by the client package's generated makefile. Thus, the commands may
337 * refer to macros defined in this environment; e.g., `$(SHELL)` and
338 * `$(XDCROOT)`, etc.
339 *
340 * The special macro `$(1)` expands to test-specific arguments
341 * (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
342 * to the platform's exec command. Thus, all platforms that support
343 * arguments to their exec command, should embed "`$(1)`" within the
344 * command string at the appropriate place to have these arguments
345 * interpreted the exec command.
346 *
347 * For example, a platform that uses a shell script to run executables
348 * and allows options to be passed to the shell script might return
349 * the following string:
350 * @p(code) 351 * "$(SHELL) <exec_path> $(1) <exe_name>"
352 * @p 353 * where, `<exec_path>` is the absolute path to the platform's exec
354 * shell script, and `<prog_name>` is the name of the executable relative
355 * to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
356 *
357 * This function executes in 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 Cpu
364 * object to return (if there is more than one):
365 * `prog.build.cpuId`,
366 * `prog.build.cpuArgs`,
367 * `prog.build.target`
368 *
369 * @param(platPath) full path to the platform package for the program
370 *
371 * @a(returns) Returns a string of commands used to execute this
372 * program in the context of the XDC generated makefiles.
373 *
374 * @a(throws) `Error` exceptions are thrown for fatal errors.
375 */
376 function getExecCmd(prog, platPath);
377 // string getExecCmd(xdc.cfg.Program.Module prog, string platPath);
378
379 /*!
380 * ======== getLinkTemplate ========
381 * Get Linker Command file template used to link an executable.
382 *
383 * In the event that no template is provided by the program
384 * configuration script (see `{@link xdc.cfg.Program#linkTemplate}`),
385 * the template file identified by this method is used to generate the
386 * linker command file used to create the executable.
387 *
388 * This function executes in the Configuration object model and
389 * is called after the program configuration script runs. The template
390 * is expanded in the context of the Configuration Object Model.
391 *
392 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
393 * program being configured.
394 *
395 * This object contains the following properties that
396 * allows the platform to determine the appropriate link
397 * template to return:
398 * @p(blist) 399 * - `prog.build.cpuId`,
400 * - `prog.build.cpuArgs`,
401 * - `prog.build.target`
402 * @p 403 * @a(returns) Returns a path string to a template file or `null`. If
404 * `null`, no linker command file is generated; otherwise
405 * this path is relative to the package path.
406 *
407 * @a(throws) `Error` exceptions are thrown for fatal errors.
408 */
409 function getLinkTemplate(prog);
410 // string getLinkTemplate(prog);
411 }
412 /*
413 * @(#) xdc.platform; 1, 0, 1, 0,289; 8-20-2010 17:20:52; /db/ztree/library/trees/xdc/xdc-v48x/src/packages/
414 */
415