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 * During the generation of linker command files, the templates used to
213 * create these files examine several sources of information to determine
214 * the placement of named output sections into memory segments defined
215 * by the platform. The default placement, described below,
216 * uses information from the target and this platform's
217 * `{@link #codeMemory}`, `{@link #dataMemory}`, and
218 * `{@link #stackMemory}` configuration parameters.
219 *
220 * `sectMap` is used to override this default placement of
221 * output sections (".text", ".cinit", etc.) to a memory
222 * segment defined by the platform's memory map. For example, even if
223 * a platform's `codeMemory` parameter is defined to be "SRAM" and
224 * ".cinit" output sections are "code" sections, if the platform also
225 * defines the following `sectMap`, the section ".cinit" will be placed
226 * into a memory segment named "DDR2".
227 * @p(code) 228 * sectMap[] = [
229 * [".cinit", "DDR2"],
230 * ];
231 * @p 232 *
233 * @a(Note) If an output section has an entry in
234 * `{@link xdc.cfg.Program#sectMap Program.sectMap}`, that entry
235 * overrides the placement specified by this `sectMap`. A program's
236 * `sectMap` configuration always overrides the platform's `sectMap`
237 * settings.
238 *
239 * @a(Default Mapping) 240 * The default placement of a target's output sections into memory
241 * segments defined by the platform is determined by the following
242 * configuration parameters:
243 * @p(blist) 244 * - `{@link xdc.bld.ITarget#sectMap ITarget.sectMap}`
245 * used to map a named output section to either "code", "data",
246 * or "stack"
247 * - `{@link #codeMemory}`
248 * names a memory segment that will contain all "code"
249 * output sections
250 * - `{@link #dataMemory}`
251 * names a memory segment that will contain all "data"
252 * output sections
253 * - `{@link #stackMemory}`
254 * names a memory segment that will contain all "stack"
255 * output sections
256 * @p 257 *
258 * @see xdc.cfg.Program#sectMap
259 * @see xdc.bld.ITarget#sectMap
260 */
261 config string sectMap[string]; /* section name => memory segment */
262
263 /*!
264 * ======== getCpuDataSheet ========
265 * Get the Cpu data sheet object corresponding to specified cpu id.
266 *
267 * This function executes in either the Configuration object model
268 * or the Build object model.
269 *
270 * @param(cpuId) a string that corresponds to the platform-specific id
271 * of a CPU on this platform that runs executables.
272 *
273 * @a(returns) Returns an `{@link xdc.platform.ICpuDataSheet}`
274 * instance object that corresponds to the specified
275 * cpuId.
276 *
277 * @a(throws) `Error` exceptions are thrown for fatal errors.
278 */
279 function getCpuDataSheet(cpuId);
280 // xdc.platform.ICpuDataSheet.Instance getCpuDataSheet(string cpuId);
281
282 /*!
283 * ======== getCreateArgs ========
284 * DEPRECATED
285 * @_nodoc 286 *
287 * Get the value of the args parameter used to create this instance
288 *
289 * This function executes in either the Configuration object model
290 * or the Build object model.
291 *
292 * @a(returns) Returns the "args" object that passed to this
293 * module's create method when the instance was created.
294 *
295 * @a(throws) `Error` exceptions are thrown for fatal errors.
296 */
297 function getCreateArgs();
298 // any getCreateArgs();
299
300 /*!
301 * ======== getExeContext ========
302 * Get execution context object corresponding to the specified program.
303 *
304 * This is called before the program's configuration script runs to
305 * get the Cpu object that is assigned to the program's cpu field.
306 *
307 * Note: that the build script for the program is responsible for
308 * specifying the CPU; this is done by either implicitly naming the
309 * platform or explicitly naming a particular CPU on the platform
310 * (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
311 *
312 * This function executes in the Configuration object model.
313 *
314 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
315 * program being configured.
316 *
317 * This object contains the following properties that
318 * allows the platform to determine the appropriate Cpu
319 * object to return (if there is more than one):
320 * `prog.build.cpuId`,
321 * `prog.build.cpuArgs`,
322 * `prog.build.target`,
323 *
324 * @a(returns) Returns an `{@link xdc.platform.IExeContext}` instance
325 * object that corresponds to the CPU that will run the
326 * specified program.
327 *
328 * @a(throws) `Error` exceptions are thrown for fatal errors.
329 */
330 function getExeContext(prog);
331 // xdc.platform.IExeContext.Instance getExeContext(xdc.cfg.Program.Module prog);
332
333 /*!
334 * ======== getExecCmd ========
335 * Get the exec command used to run the program on this platform.
336 *
337 * This function is called after the program's configuration script runs
338 * and returns commands that are used to load and run the specified
339 * program. These commands are placed in a makefile that is included
340 * by the client package's generated makefile. Thus, the commands may
341 * refer to macros defined in this environment; e.g., `$(SHELL)` and
342 * `$(XDCROOT)`, etc.
343 *
344 * The special macro `$(1)` expands to test-specific arguments
345 * (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
346 * to the platform's exec command. Thus, all platforms that support
347 * arguments to their exec command, should embed "`$(1)`" within the
348 * command string at the appropriate place to have these arguments
349 * interpreted the exec command.
350 *
351 * For example, a platform that uses a shell script to run executables
352 * and allows options to be passed to the shell script might return
353 * the following string:
354 * @p(code) 355 * "$(SHELL) <exec_path> $(1) <exe_name>"
356 * @p 357 * where, `<exec_path>` is the absolute path to the platform's exec
358 * shell script, and `<prog_name>` is the name of the executable relative
359 * to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
360 *
361 * This function executes in the Configuration object model.
362 *
363 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
364 * program being configured.
365 *
366 * This object contains the following properties that
367 * allows the platform to determine the appropriate Cpu
368 * object to return (if there is more than one):
369 * `prog.build.cpuId`,
370 * `prog.build.cpuArgs`,
371 * `prog.build.target`
372 *
373 * @param(platPath) full path to the platform package for the program
374 *
375 * @a(returns) Returns a string of commands used to execute this
376 * program in the context of the XDC generated makefiles.
377 *
378 * @a(throws) `Error` exceptions are thrown for fatal errors.
379 */
380 function getExecCmd(prog, platPath);
381 // string getExecCmd(xdc.cfg.Program.Module prog, string platPath);
382
383 /*!
384 * ======== getLinkTemplate ========
385 * Get Linker Command file template used to link an executable.
386 *
387 * In the event that no template is provided by the program
388 * configuration script (see `{@link xdc.cfg.Program#linkTemplate}`),
389 * the template file identified by this method is used to generate the
390 * linker command file used to create the executable.
391 *
392 * This function executes in the Configuration object model and
393 * is called after the program configuration script runs. The template
394 * is expanded in the context of the Configuration Object Model.
395 *
396 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
397 * program being configured.
398 *
399 * This object contains the following properties that
400 * allows the platform to determine the appropriate link
401 * template to return:
402 * @p(blist) 403 * - `prog.build.cpuId`,
404 * - `prog.build.cpuArgs`,
405 * - `prog.build.target`
406 * @p 407 * @a(returns) Returns a path string to a template file or `null`. If
408 * `null`, no linker command file is generated; otherwise
409 * this path is relative to the package path.
410 *
411 * @a(throws) `Error` exceptions are thrown for fatal errors.
412 */
413 function getLinkTemplate(prog);
414 // string getLinkTemplate(prog);
415 }
416 /*
417 * @(#) xdc.platform; 1, 0, 1, 0,236; 12-18-2009 12:26:40; /db/ztree/library/trees/xdc/xdc-u16x/src/packages/
418 */
419