1 2 3 4 5 6 7 8 9 10 11
12 13 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 metaonly interface 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 Bool cacheable; /*! Is this block cacheable? */
63 Any cacheAttrs; /*! Device specific MMU attributes */
64 };
65
66 /*! Type to be used for maps of Memory objects */
67 typedef Memory MemoryMap[string];
68
69 instance:
70 /*!
71 * ======== create ========
72 * Constructor for IPlatform instances.
73 *
74 * @param(name) the name of the platform instance being created
75 *
76 * This name is the suffix of the platform
77 * specification supplied in the build script after
78 * the platform name (and optional ':') prefix has
79 * been removed. So the platform instance name
80 * "joes.platform.foo:bar" results in the name "bar"
81 * and the name "joes.platform.foo" result in the name
82 * "".
83 */
84 create(string name);
85
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
117
118
119 /*!
120 * ======== externalMemoryMap ========
121 * A mapping of memory names to memory objects for external memory.
122 *
123 * This parameter defines the external portion of the platform's memory
124 * map.
125 */
126 readonly config xdc.platform.IPlatform.Memory externalMemoryMap[string];
127
128 /*!
129 * ======== customMemoryMap ========
130 * A custom mapping of memory names to memory objects.
131 *
132 * This parameter allows platform instances to completely overwrite a
133 * default memory map based on the internal memory map coming from CPU's
134 * memory map and externalMemoryMap.
135 *
136 * Custom memory map must fit within the default memory map, unless the
137 * verification of the fit is disabled (see `{@link xdc.platform}`).
138 */
139 config xdc.platform.IPlatform.Memory customMemoryMap[string];
140
141 /*!
142 * ======== renameMap ========
143 * A map for renaming memory objects.
144 *
145 * This map renames memory objects. If you do not want to change
146 * addresses in the default memory map, but you only want to rename the
147 * existing memory objects, you should use this parameter.
148 *
149 * This map and `customMemoryMap` should not be used together because this
150 * map renames the default memory, but then `customMemoryMap` replaces the
151 * default memory objects. The parameters `codeMemory`, `dataMemory` and
152 * `stackMemory` are not automatically reassigned to new names. It is the
153 * user's responsibility to set those parameters accordingly to
154 * `renameMap`.
155 */
156 config string renameMap[string];
157
158 /*!
159 * ======== dataMemory ========
160 * The default segment for data sections.
161 *
162 * Each target has a section map with keys equal to the names of all
163 * sections that compiler and assembler for that target generate. The
164 * value for each key is either "code" or "data" or "stack". A linker
165 * template reads that map and puts all "data" sections in the segment
166 * defined by this configuration parameter.
167 *
168 * @see #codeMemory
169 * @see #stackMemory
170 */
171 config string dataMemory;
172
173 /*!
174 * ======== codeMemory ========
175 * The default segment for code sections.
176 *
177 * Each target has a section map with keys equal to the names of all
178 * sections that compiler and assembler for that target generate. The
179 * value for each key is either "code" or "data" or "stack". A linker
180 * template reads that map and puts all "code" sections in the segment
181 * defined by this configuration parameter.
182 *
183 * @see #dataMemory
184 * @see #stackMemory
185 */
186 config string codeMemory;
187
188 /*!
189 * ======== stackMemory ========
190 * The default segment for stack.
191 *
192 * Each target has a section map with keys equal to the names of all
193 * sections that compiler and assembler for that target generate. The
194 * value for each key is either "code" or "data" or "stack". A linker
195 * template reads that map and puts all "stack" sections in the segment
196 * defined by this configuration parameter.
197 *
198 * @see #dataMemory
199 * @see #codeMemory
200 */
201 config string stackMemory;
202
203 /*!
204 * ======== sectMap ========
205 * A mapping of linker output section names to memory segments.
206 *
207 * During the generation of linker command files, the templates used to
208 * create these files examine several sources of information to determine
209 * the placement of named output sections into memory segments defined
210 * by the platform. The default placement, described below,
211 * uses information from the target and this platform's
212 * `{@link #codeMemory}`, `{@link #dataMemory}`, and
213 * `{@link #stackMemory}` configuration parameters.
214 *
215 * `sectMap` is used to override this default placement of
216 * output sections (".text", ".cinit", etc.) to a memory
217 * segment defined by the platform's memory map. For example, even if
218 * a platform's `codeMemory` parameter is defined to be "SRAM" and
219 * ".cinit" output sections are "code" sections, if the platform also
220 * defines the following `sectMap`, the section ".cinit" will be placed
221 * into a memory segment named "DDR2".
222 * @p(code)
223 * sectMap[] = [
224 * [".cinit", "DDR2"],
225 * ];
226 * @p
227 *
228 * @a(Note) If an output section has an entry in
229 * `{@link xdc.cfg.Program#sectMap Program.sectMap}`, that entry
230 * overrides the placement specified by this `sectMap`. A program's
231 * `sectMap` configuration always overrides the platform's `sectMap`
232 * settings.
233 *
234 * @a(Default Mapping)
235 * The default placement of a target's output sections into memory
236 * segments defined by the platform is determined by the following
237 * configuration parameters:
238 * @p(blist)
239 * - `{@link xdc.bld.ITarget#sectMap ITarget.sectMap}`
240 * used to map a named output section to either "code", "data",
241 * or "stack"
242 * - `{@link #codeMemory}`
243 * names a memory segment that will contain all "code"
244 * output sections
245 * - `{@link #dataMemory}`
246 * names a memory segment that will contain all "data"
247 * output sections
248 * - `{@link #stackMemory}`
249 * names a memory segment that will contain all "stack"
250 * output sections
251 * @p
252 *
253 * @see xdc.cfg.Program#sectMap
254 * @see xdc.bld.ITarget#sectMap
255 */
256 config string sectMap[string];
257
258 /*!
259 * ======== peripherals ========
260 * @_nodoc
261 *
262 * A map of peripherals available on a platform instance
263 *
264 * The map contains peripherals from an
265 * `{@link xdc.platform.ICpuDataSheet}` instance available as
266 * `{@link xdc.cfg.Program#cpu.attrs}`, and peripherals defined in this
267 * platform instance. The map is initialized by the platform instance,
268 * and in multicore platforms the instance must add only peripherals
269 * available to the CPU for which an executable is being built.
270 */
271 config IPeripheral.Instance peripherals[string];
272
273 /*!
274 * ======== getCpuDataSheet ========
275 * Get the Cpu data sheet object corresponding to specified cpu id.
276 *
277 * This function executes in either the Configuration object model
278 * or the Build object model.
279 *
280 * @param(cpuId) a string that corresponds to the platform-specific id
281 * of a CPU on this platform that runs executables.
282 *
283 * @a(returns) Returns an `{@link xdc.platform.ICpuDataSheet}`
284 * instance object that corresponds to the specified
285 * cpuId.
286 *
287 * @a(throws) `Error` exceptions are thrown for fatal errors.
288 */
289 function getCpuDataSheet(cpuId);
290
291
292 /*!
293 * ======== getCreateArgs ========
294 * DEPRECATED
295 * @_nodoc
296 *
297 * Get the value of the args parameter used to create this instance
298 *
299 * This function executes in either the Configuration object model
300 * or the Build object model.
301 *
302 * @a(returns) Returns the "args" object that passed to this
303 * module's create method when the instance was created.
304 *
305 * @a(throws) `Error` exceptions are thrown for fatal errors.
306 */
307 function getCreateArgs();
308
309
310 /*!
311 * ======== getExeContext ========
312 * Get execution context object corresponding to the specified program.
313 *
314 * This is called before the program's configuration script runs to
315 * get the Cpu object that is assigned to the program's cpu field.
316 *
317 * Note: that the build script for the program is responsible for
318 * specifying the CPU; this is done by either implicitly naming the
319 * platform or explicitly naming a particular CPU on the platform
320 * (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
321 *
322 * This function executes in the Configuration object model.
323 *
324 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
325 * program being configured.
326 *
327 * This object contains the following properties that
328 * allows the platform to determine the appropriate Cpu
329 * object to return (if there is more than one):
330 * `prog.build.cpuId`,
331 * `prog.build.cpuArgs`,
332 * `prog.build.target`,
333 *
334 * @a(returns) Returns an `{@link xdc.platform.IExeContext}` instance
335 * object that corresponds to the CPU that will run the
336 * specified program.
337 *
338 * @a(throws) `Error` exceptions are thrown for fatal errors.
339 */
340 function getExeContext(prog);
341
342
343 /*!
344 * ======== getExecCmd ========
345 * Get the exec command used to run the program on this platform.
346 *
347 * This function is called after the program's configuration script runs
348 * and returns commands that are used to load and run the specified
349 * program. These commands are placed in a makefile that is included
350 * by the client package's generated makefile. Thus, the commands may
351 * refer to macros defined in this environment; e.g., `$(SHELL)` and
352 * `$(XDCROOT)`, etc.
353 *
354 * The special macro `$(1)` expands to test-specific arguments
355 * (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
356 * to the platform's exec command. Thus, all platforms that support
357 * arguments to their exec command, should embed "`$(1)`" within the
358 * command string at the appropriate place to have these arguments
359 * interpreted by the exec command.
360 *
361 * For example, a platform that uses a shell script to run executables
362 * and allows options to be passed to the shell script might return
363 * the following string:
364 * @p(code)
365 * "$(SHELL) <exec_path> $(1) <exe_name>"
366 * @p
367 * where, `<exec_path>` is the absolute path to the platform's exec
368 * shell script, and `<prog_name>` is the name of the executable relative
369 * to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
370 *
371 * This function executes in the Configuration object model.
372 *
373 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
374 * program being configured.
375 *
376 * This object contains the following properties that
377 * allows the platform to determine the appropriate Cpu
378 * object to return (if there is more than one):
379 * `prog.build.cpuId`,
380 * `prog.build.cpuArgs`,
381 * `prog.build.target`
382 *
383 * @param(platPath) full path to the platform package for the program
384 *
385 * @a(returns) Returns a string of commands used to execute this
386 * program in the context of the XDC generated makefiles.
387 *
388 * @a(throws) `Error` exceptions are thrown for fatal errors.
389 */
390 function getExecCmd(prog, platPath);
391
392
393 /*!
394 * ======== getLinkTemplate ========
395 * Get Linker Command file template used to link an executable.
396 *
397 * In the event that no template is provided by the program
398 * configuration script (see `{@link xdc.cfg.Program#linkTemplate}`),
399 * the template file identified by this method is used to generate the
400 * linker command file used to create the executable.
401 *
402 * This function executes in the Configuration object model and
403 * is called after the program configuration script runs. The template
404 * is expanded in the context of the Configuration Object Model.
405 *
406 * @param(prog) the `{@link xdc.cfg.Program}` object representing the
407 * program being configured.
408 *
409 * This object contains the following properties that
410 * allows the platform to determine the appropriate link
411 * template to return:
412 * @p(blist)
413 * - `prog.build.cpuId`,
414 * - `prog.build.cpuArgs`,
415 * - `prog.build.target`
416 * @p
417 * @a(returns) Returns a path string to a template file or `null`. If
418 * `null`, no linker command file is generated; otherwise
419 * this path is relative to the package path.
420 *
421 * @a(throws) `Error` exceptions are thrown for fatal errors.
422 */
423 function getLinkTemplate(prog);
424
425 }
426 427 428
429