metaonly interface xdc.platform.IPlatform
index URL

Configuration-time interface to all platforms

This interface defines the elements that must be implemented by all "platform packages". All programs are built to execute on a platform and each program includes exactly one platform package (which defines the platform). [ more ... ]
XDCspec summary sourced in xdc/platform/IPlatform.xdc
metaonly interface IPlatform {  ...
instance:  ...
XDCspec declarations sourced in xdc/platform/IPlatform.xdc
package xdc.platform;
 
metaonly interface IPlatform {
module-wide constants & types
    typedef IPlatform.Memory MemoryMap// Type to be used for maps of Memory objects[string];
    metaonly struct Board// Board-level description {
        String id// unique id within the platform;
        String boardName// name of the board;
        String boardFamily// optional family name;
        String boardRevision// optional revision string;
    };
    metaonly struct Memory// A named contiguous range of addresses {
        String comment// description of this block;
        String name// name of memory segment;
        String space// "code", "data", "code/data", etc...;
        UInt page// page of memory segment;
        UInt base// base address of memory segment;
        UInt len// length of memory segment;
        String access// attributes of memory: "RWX";
    };
 
instance:
per-instance config parameters
    config String codeMemory// The default segment for code sections;
    config IPlatform.Memory customMemoryMap// A custom mapping of memory names to memory objects[string];
    config String dataMemory// The default segment for data sections;
    readonly config IPlatform.Memory externalMemoryMap// A mapping of memory names to memory objects for external memory[string];
    config String renameMap// A map for renaming memory objects[string];
    config String sectMap// A mapping of linker output section names to memory segments[string];
    config String stackMemory// The default segment for stack;
per-instance creation
    create// Create an instance-object(String name, Any args);
per-instance functions
    function getCpuDataSheet// Get the Cpu data sheet object corresponding to specified cpu id(cpuId);
    function getExeContext// Get execution context object corresponding to the specified program(prog);
    function getExecCmd// Get the exec command used to run the program on this platform(prog, platPath);
    function getLinkTemplate// Get Linker Command file template used to link an executable(prog);
}
DETAILS
This interface defines the elements that must be implemented by all "platform packages". All programs are built to execute on a platform and each program includes exactly one platform package (which defines the platform).
Platform packages contain exactly one module named "Platform" which implements the xdc.platform.IPlatform interface defined here.
Program configuration scripts may read (but not modify) the attributes provided by this interface from the global Program object; see xdc.cfg.Program.platform.
typedef IPlatform.MemoryMap
index URL

Type to be used for maps of Memory objects

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
typedef IPlatform.Memory MemoryMap[string];
struct IPlatform.Board
index URL

Board-level description

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
metaonly struct Board {
    String id;
    // unique id within the platform
    String boardName;
    // name of the board
    String boardFamily;
    // optional family name
    String boardRevision;
    // optional revision string
};
struct IPlatform.Memory
index URL

A named contiguous range of addresses

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
metaonly struct Memory {
    String comment;
    // description of this block
    String name;
    // name of memory segment
    String space;
    // "code", "data", "code/data", etc...
    UInt page;
    // page of memory segment
    UInt base;
    // base address of memory segment
    UInt len;
    // length of memory segment
    String access;
    // attributes of memory: "RWX"
};
DETAILS
Memory structures are used in the description of the memory available from CPUs and platforms.
config IPlatform.codeMemory  // instance
index URL

The default segment for code sections

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config String codeMemory;
DETAILS
Each target has a section map with keys equal to the names of all sections that compiler and assembler for that target generate. The value for each key is either "code" or "data" or "stack". A linker template reads that map and puts all "code" sections in the segment defined by this configuration parameter.
SEE
dataMemory, stackMemory
config IPlatform.customMemoryMap  // instance
index URL

A custom mapping of memory names to memory objects

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config IPlatform.Memory customMemoryMap[string];
DETAILS
This parameter allows platform instances to completely overwrite a default memory map based on the internal memory map coming from CPU's memory map and externalMemoryMap.
Custom memory map must fit within the default memory map.
config IPlatform.dataMemory  // instance
index URL

The default segment for data sections

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config String dataMemory;
DETAILS
Each target has a section map with keys equal to the names of all sections that compiler and assembler for that target generate. The value for each key is either "code" or "data" or "stack". A linker template reads that map and puts all "data" sections in the segment defined by this configuration parameter.
SEE
codeMemory, stackMemory
config IPlatform.externalMemoryMap  // instance
index URL

A mapping of memory names to memory objects for external memory

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
readonly config IPlatform.Memory externalMemoryMap[string];
DETAILS
This parameter defines the external portion of the platform's memory map.
config IPlatform.renameMap  // instance
index URL

A map for renaming memory objects

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config String renameMap[string];
DETAILS
This map renames memory objects. If you do not want to change addresses in the default memory map, but you only want to rename the existing memory objects, you should use this parameter.
This map and 'customMemoryMap' should not be used together because this map renames the default memory, but then 'customMemoryMap' replaces the default memory objects. The parameters 'codeMemory', 'dataMemory' and 'stackMemory' are not automatically reassigned to new names. It is the user's responsibility to set those parameters accordingly to 'renameMap'.
config IPlatform.sectMap  // instance
index URL

A mapping of linker output section names to memory segments

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config String sectMap[string];
DETAILS
During the generation of linker command files, the templates used to create these files examine several sources of information to determine the placement of named output sections into memory segments defined by the platform. The default placement, described below, uses information from the target and this platform's codeMemory, dataMemory, and stackMemory configuration parameters.
sectMap is used to override this default placement of output sections (".text", ".cinit", etc.) to a memory segment defined by the platform's memory map. For example, even if a platform's codeMemory parameter is defined to be "SRAM" and ".cinit" output sections are "code" sections, if the platform also defines the following sectMap, the section ".cinit" will be placed into a memory segment named "DDR2".
      sectMap[] = [
          [".cinit", "DDR2"],
      ];
NOTE
If an output section has an entry in Program.sectMap, that entry overrides the placement specified by this sectMap. A program's sectMap configuration always overrides the platform's sectMap settings.
DEFAULT MAPPING
The default placement of a target's output sections into memory segments defined by the platform is determined by the following configuration parameters:
  • ITarget.sectMap used to map a named output section to either "code", "data", or "stack"
  • codeMemory names a memory segment that will contain all "code" output sections
  • dataMemory names a memory segment that will contain all "data" output sections
  • stackMemory names a memory segment that will contain all "stack" output sections
SEE
xdc.cfg.Program.sectMap, xdc.bld.ITarget.sectMap
config IPlatform.stackMemory  // instance
index URL

The default segment for stack

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
config String stackMemory;
DETAILS
Each target has a section map with keys equal to the names of all sections that compiler and assembler for that target generate. The value for each key is either "code" or "data" or "stack". A linker template reads that map and puts all "stack" sections in the segment defined by this configuration parameter.
SEE
dataMemory, codeMemory
Instance Creation
index URL

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
create(String name, Any args);
// Create an instance-object
ARGUMENTS
name — the name of the platform instance being created
This name is the suffix of the platform specification supplied in the build script after the platform name (and optional ':') prefix has been removed. So the platform instance name "joes.platform.foo:bar" results in the name "bar" and the name "joes.platform.foo" result in the name "".
args — deprecated parameter that should not be used in a platform instance implementation
IPlatform.getCpuDataSheet()  // instance
index URL

Get the Cpu data sheet object corresponding to specified cpu id

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
function getCpuDataSheet(cpuId);
ARGUMENTS
cpuId — a string that corresponds to the platform-specific id of a CPU on this platform that runs executables.
DETAILS
This function executes in either the Configuration object model or the Build object model.
RETURNS
Returns an xdc.platform.ICpuDataSheet instance object that corresponds to the specified cpuId.
THROWS
Error exceptions are thrown for fatal errors.
IPlatform.getExeContext()  // instance
index URL

Get execution context object corresponding to the specified program

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
function getExeContext(prog);
ARGUMENTS
prog — the xdc.cfg.Program object representing the program being configured.
This object contains the following properties that allows the platform to determine the appropriate Cpu object to return (if there is more than one): prog.build.cpuId, prog.build.cpuArgs, prog.build.target,
DETAILS
This is called before the program's configuration script runs to get the Cpu object that is assigned to the program's cpu field.
Note: that the build script for the program is responsible for specifying the CPU; this is done by either implicitly naming the platform or explicitly naming a particular CPU on the platform (see xdc.bld.Executable.Attrs.cpuId).
This function executes in the Configuration object model.
RETURNS
Returns an xdc.platform.IExeContext instance object that corresponds to the CPU that will run the specified program.
THROWS
Error exceptions are thrown for fatal errors.
IPlatform.getExecCmd()  // instance
index URL

Get the exec command used to run the program on this platform

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
function getExecCmd(prog, platPath);
ARGUMENTS
prog — the xdc.cfg.Program object representing the program being configured.
This object contains the following properties that allows the platform to determine the appropriate Cpu object to return (if there is more than one): prog.build.cpuId, prog.build.cpuArgs, prog.build.target
platPath — full path to the platform package for the program
DETAILS
This function is called after the program's configuration script runs and returns commands that are used to load and run the specified program. These commands are placed in a makefile that is included by the client package's generated makefile. Thus, the commands may refer to macros defined in this environment; e.g., $(SHELL) and $(XDCROOT), etc.
The special macro $(1) expands to test-specific arguments (xdc.bld.Test.attrs.execArgs) that are passed from the test to the platform's exec command. Thus, all platforms that support arguments to their exec command, should embed "$(1)" within the command string at the appropriate place to have these arguments interpreted the exec command.
For example, a platform that uses a shell script to run executables and allows options to be passed to the shell script might return the following string:
	    "$(SHELL) <exec_path> $(1) <exe_name>"
where, <exec_path> is the absolute path to the platform's exec shell script, and <prog_name> is the name of the executable relative to the package's base directory (i.e., xdc.cfg.Program.name).
This function executes in the Configuration object model.
RETURNS
Returns a string of commands used to execute this program in the context of the XDC generated makefiles.
THROWS
Error exceptions are thrown for fatal errors.
IPlatform.getLinkTemplate()  // instance
index URL

Get Linker Command file template used to link an executable

XDCspec declarations sourced in xdc/platform/IPlatform.xdc
function getLinkTemplate(prog);
ARGUMENTS
prog — the xdc.cfg.Program object representing the program being configured.
This object contains the following properties that allows the platform to determine the appropriate link template to return:
  • prog.build.cpuId,
  • prog.build.cpuArgs,
  • prog.build.target
DETAILS
In the event that no template is provided by the program configuration script (see xdc.cfg.Program.linkTemplate), the template file identified by this method is used to generate the linker command file used to create the executable.
This function executes in the Configuration object model and is called after the program configuration script runs. The template is expanded in the context of the Configuration Object Model.
RETURNS
Returns a path string to a template file or null. If null, no linker command file is generated; otherwise this path is relative to the package path.
THROWS
Error exceptions are thrown for fatal errors.
generated on Tue, 24 Aug 2010 15:39:19 GMT