TMS320C6000 Assembly Language Tools v 6.1. User's Guide

Description of the Object Formats

11.11.4

Texas Instruments SDSMAC Object Format (-t Option)

The Texas Instruments SDSMAC (TI-Tagged) object format supports 16-bit addresses, including

start-of-file record, data records, and end-of-file record. Each data records consists of a series of small

fields and is signified by a tag character:

Tag Character

Description

Followed by the program identifier

Followed by a checksum

Followed by a dummy checksum (ignored)

Followed by a 16-bit load address

Followed by a data word (four characters)

Identifies the end of a data record

Followed by a data byte (two characters)

Figure 11-9 illustrates the tag characters and fields in TI-Tagged object format.

Figure 11-9. TI-Tagged Object Format

Start-of-file

Load

record

address

Program

Tag characters

identifier

K000COFFTOTI90000BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7EF3DF

BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7EE37F

Data

records

BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7F245F

End-of-file

Data

record

words

Checksum

If any data fields appear before the first address, the first field is assigned address 0000h. Address fields

may be expressed but not required for any data byte. The checksum field, preceded by the tag character

7, is the 2s complement of the sum of the 8-bit ASCII values of characters, beginning with the first tag

character and ending with the checksum tag character (7 or 8). The end-of-file record is a colon ( : ).

Hex Conversion Utility Description

253

Description of the Object Formats

11.11.5

TI-TXT Hex Format (--ti_txt Option)

The TI-TXT hex format supports 16-bit hexadecimal data. It consists of section start addresses, data byte,

and an end-of-file character. These restrictions apply:

• The number of sections is unlimited.

• Each hexadecimal start address must be even.

• Each line must have 16 data bytes, except the last line of a section.

• Data bytes are separated by a single space.

• The end-of-file termination tag q is mandatory.

The data record contains the following information:

Item

Description

@ADDR

Hexadecimal start address of a section

DATAn

Hexadecimal data byte

End-of-file termination character

Figure 11-10. TI-TXT Object Format

Section

start

@ADDR1

DATA01 DATA02

DATA16

Data

DATA17 DATA32

DATA32

bytes

DATAm

DATAn

Section

@ADDR2

start

Data

DATA01

DATAn

bytes

End-of-line

character

Example 11-5. TI-TXT Object Format

@F000

31 40 00 03 B2 40 80 5A 20 01 D2 D3 22 00 D2 E3

21 00 3F 40 E8 FD 1F 83 FE 23 F9 3F

@FFFE

00 F0

254

Hex Conversion Utility Description

Description of the Object Formats

11.11.6

Extended Tektronix Object Format (-x Option)

The Tektronix object format supports 32-bit addresses and has two types of records:

Data records

contains the header field, the load address, and the object code.

Termination records

signifies the end of a module.

The header field in the data record contains the following information:

Number of ASCII

Item

Characters

Description

Data type is Tektronix format

Block length

Number of characters in the record, minus the %

Block type

6 = data record

8 = termination record

Checksum

A 2-digit hex sum modulo 256 of all values in the record except the % and the

checksum itself.

The load address in the data record specifies where the object code will be located. The first digit

specifies the address length; this is always 8. The remaining characters of the data record contain

the object code, two characters per byte.

Figure 11-11 illustrates the Tektronix object format.

Figure 11-11. Extended Tektronix Object Format

Checksum: 21h =

1+5+6+8+1+0+0+0+0+0+0+

2+0+2+0+2+0+2+0+2+0+2+

Block length

1ah = 26

Object code: 6 bytes

%15621810000000202020202020

Header

character

Load address: 10000000h

Block type: 6

Length of

(data)

load address

Hex Conversion Utility Description

255

Overview of the .cdecls Directive

12.1

Overview of the .cdecls Directive

The .cdecls directive allows programmers in mixed assembly and C/C++ environments to share C headers

containing declarations and prototypes between the C and assembly code. Any legal C/C++ can be used

in a .cdecls block and the C/C++ declarations will cause suitable assembly to be generated automatically.

This allows the programmer to reference the C/C++ constructs in assembly code — calling functions,

allocating space, and accessing structure members — using the equivalent assembly mechanisms. While

function and variable definitions are ignored, most common C/C++ elements are converted to assembly:

enumerations, (non function-like) macros, function and variable prototypes, structures, and unions.

See the .cdecls topic for details on the syntax of the .cdecls assembler directive.

The .cdecls directive can appear anywhere in an assembly source file, and can occur multiple times within

a file. However, the C/C++ environment created by one .cdecls is not inherited by a later .cdecls; the

C/C++ environment starts over for each .cdecls instance.

For example, the following code causes the warning to be issued:

.cdecls C,NOLIST

#define ASMTEST 1

.cdecls C,NOLIST

#ifndef ASMTEST

#warn "ASMTEST not defined!"

/* will be issued */

#endif

Therefore, a typical use of the .cdecls block is expected to be a single usage near the beginning of the

assembly source file, in which all necessary C/C++ header files are included.

Use the compiler --include_path=path options to specify additional include file paths needed for the header

files used in assembly, as you would when compiling C files.

Any C/C++ errors or warnings generated by the code of the .cdecls are emitted as they normally would for

the C/C++ source code. C/C++ errors cause the directive to fail, and any resulting converted assembly is

not included.

C/C++ constructs that cannot be converted, such as function-like macros or variable definitions, cause a

comment to be output to the converted assembly file. For example:

; ASM HEADER WARNING - variable definition 'ABCD' ignored

The prefix ASM HEADER WARNING appears at the beginning of each message. To see the warnings,

either the WARN parameter needs to be specified so the messages are displayed on STDERR, or else

the LIST parameter needs to be specified so the warnings appear in the listing file, if any.

Finally, note that the converted assembly code does not appear in the same order as the original C/C++

source code and C/C++ constructs may be simplified to a normalized form during the conversion process,

but this should not affect their final usage.

12.2

Notes on C/C++ Conversions

The following sections describe C and C++ conversion elements that you need to be aware of when

sharing header files with assembly source.

12.2.1

Comments

Comments are consumed entirely at the C level, and do not appear in the resulting converted assembly

file.

258

Sharing C/C++ Header Files With Assembly Source

Notes on C/C++ Conversions

12.2.2

Conditional Compilation (#if/#else/#ifdef/etc.)

Conditional compilation is handled entirely at the C level during the conversion step. Define any necessary

macros either on the command line (using the compiler --define=name=value option) or within a .cdecls

block using #define. The #if, #ifdef, etc. C/C++ directives are not converted to assembly .if, .else, .elseif,

and .endif directives.

12.2.3

Pragmas

Pragmas found in the C/C++ source code cause a warning to be generated as they are not converted.

They have no other effect on the resulting assembly file. See the .cdecls topic for the WARN and

NOWARN parameter discussion for where these warnings are created.

12.2.4

The #error and #warning Directives

These preprocessor directives are handled completely by the compiler during the parsing step of

conversion. If one of these directives is encountered, the appropriate error or warning message is emitted.

These directives are not converted to .emsg or .wmsg in the assembly output.

12.2.5

Predefined symbol _ _ASM_HEADER_ _

The C/C++ macro _ _ASM_HEADER_ _ is defined in the compiler while processing code within .cdecls.

This allows you to make changes in your code, such as not compiling definitions, during the .cdecls

processing.

Be Careful With the _ _ASM_HEADER_ _ Macro

Note: You must be very careful not to use this macro to introduce any changes in the code that

could result in inconsistencies between the code processed while compiling the C/C++

source and while converting to assembly.

12.2.6

Usage Within C/C++ asm( ) Statements

The .cdecls directive is not allowed within C/C++ asm( ) statements and will cause an error to be

generated.

12.2.7

The #include Directive

The C/C++ #include preprocessor directive is handled transparently by the compiler during the conversion

step. Such #includes can be nested as deeply as desired as in C/C++ source. The assembly directives

.include and .copy are not used or needed within a .cdecls. Use the command line --include_path option to

specify additional paths to be searched for included files, as you would for C compilation.

12.2.8

Conversion of #define Macros

Only object-like macros are converted to assembly. Function-like macros have no assembly

representation and so cannot be converted. Pre-defined and built-in C/C++ macros are not converted to

assembly (i.e., __FILE__, __TIME__, __TI_COMPILER_VERSION__, etc.). For example, this code is

converted to assembly because it is an object-like macro:

#define NAME Charley

This code is not converted to assembly because it is a function-like macro:

#define MAX(x,y) (x>y ? x : y)

Some macros, while they are converted, have no functional use in the containing assembly file. For

example, the following results in the assembly substitution symbol FOREVER being set to the value

while(1), although this has no useful use in assembly because while(1) is not legal assembly code.

#define FOREVER while(1)

Sharing C/C++ Header Files With Assembly Source

259

Notes on C/C++ Conversions

Macro values are not interpreted as they are converted. For example, the following results in the

assembler substitution symbol OFFSET being set to the literal string value 5+12 and not the value 17.

This happens because the semantics of the C/C++ language require that macros are evaluated in context

and not when they are parsed.

#define OFFSET

5+12

Because macros in C/C++ are evaluated in their usage context, C/C++ printf escape sequences such as

\n are not converted to a single character in the converted assembly macro. See Section 12.2.11 for

suggestions on how to use C/C++ macro strings.

Macros are converted using the new .define directive (see Section 12.4.2), which functions similarly to the

.asg assembler directive. The exception is that .define disallows redefinitions of register symbols and

mnemonics to prevent the conversion from corrupting the basic assembly environment. To remove a

macro from the assembly scope, .undef can be used following the .cdecls that defines it (see

Section 12.4.3).

The macro functionality of # (stringize operator) is only useful within functional macros. Since functional

macros are not supported by this process, # is not supported either. The concatenation operator ## is only

useful in a functional context, but can be used degenerately to concatenate two strings and so it is

supported in that context.

12.2.9

The #undef Directive

Symbols undefined using the #undef directive before the end of the .cdecls are not converted to assembly.

12.2.10

Enumerations

Enumeration members are converted to .enum elements in assembly. For example:

enum state { ACTIVE=0x10, SLEEPING=0x01, INTERRUPT=0x100, POWEROFF, LAST};

is converted to the following assembly code:

state

.enum

ACTIVE

.emember 16

SLEEPING

.emember 1

NTERRUPT

.emember 256

POWEROFF

.emember 257

LAST

.emember 258

.endenum

The members are used via the pseudo-scoping created by the .enum directive.

The usage is similar to that for accessing structure members, enum_name.member.

This pseudo-scoping is used to prevent enumeration member names from corrupting other symbols within

the assembly environment.

12.2.11

C Strings

Because C string escapes such as \n and \t are not converted to hex characters 0x0A and 0x09 until their

use in a string constant in a C/C++ program, C macros whose values are strings cannot be represented

as expected in assembly substitution symbols. For example:

#define MSG "\tHI\n"

becomes, in assembly:

.define """\tHI\n""",MSG

; 6 quoted characters! not 5!

When used in a C string context, you expect this statement to be converted to 5 characters (tab, H, I,

newline, NULL), but the .string assembler directive does not know how to perform the C escape

conversions.

You can use the .cstring directive to cause the escape sequences and NULL termination to be properly

handled as they would in C/C++. Using the above symbol MSG with a .cstring directive results in 5

characters of memory being allocated, the same characters as would result if used in a C/C++ strong

context. (See Section 12.4.7 for the .cstring directive syntax.)

260

Sharing C/C++ Header Files With Assembly Source

Notes on C/C++ Conversions

12.2.12

C/C++ Built-In Functions

The C/C++ built-in functions, such as sizeof( ), are not translated to their assembly counterparts, if any, if

they are used in macros. Also, their C expression values are not inserted into the resulting assembly

macro because macros are evaluated in context and there is no active context when converting the

macros to assembly.

Suitable functions such as $sizeof( ) are available in assembly expressions. However, as the basic types

such as int/char/float have no type representation in assembly, there is no way to ask for $sizeof(int), for

example, in assembly.

12.2.13

Structures and Unions

C/C++ structures and unions are converted to assembly .struct and .union elements. Padding and ending

alignments are added as necessary to make the resulting assembly structure have the same size and

member offsets as the C/C++ source. The primary purpose is to allow access to members of C/C++

structures, as well as to facilitate debugging of the assembly code. For nested structures, the assembly

.tag feature is used to refer to other structures/unions.

The alignment is also passed from the C/C++ source so that the assembly symbol is marked with the

same alignment as the C/C++ symbol. (See Section 12.2.3 for information about pragmas, which may

attempt to modify structures.) Because the alignment of structures is stored in the assembly symbol,

built-in assembly functions like $sizeof( ) and $alignof( ) can be used on the resulting structure name

symbol.

When using unnamed structures (or unions) in typedefs, such as:

typedef struct { int a_member; } mystrname;

This is really a shorthand way of writing:

struct temporary_name { int a_member; };

typedef temporary_name mystrname;

The conversion processes the above statements in the same manner: generating a temporary name for

the structure and then using .define to output a typedef from the temporary name to the user name. You

should use your mystrname in assembly the same as you would in C/C++, but do not be confused by the

assembly structure definition in the list, which contains the temporary name. You can avoid the temporary

name by specifying a name for the structure, as in:

typedef struct a_st_name { ... } mystrname;

If a shorthand method is used in C to declare a variable with a particular structure, for example:

extern struct a_name { int a_member; } a_variable;

Then after the structure is converted to assembly, a .tag directive is generated to declare the structure of

the external variable, such as:

_a_variable .tag a_st_name

This allows you to refer to _a_variable.a_member in your assembly code.

12.2.14

Function/Variable Prototypes

Non-static function and variable prototypes (not definitions) will result in a .global directive being generated

for each symbol found.

See Section 12.3.1 for C++ name mangling issues.

Function and variable definitions will result in a warning message being generated (see the

WARN/NOWARN parameter discussion for where these warnings are created) for each, and they will not

be represented in the converted assembly.

The assembly symbol representing the variable declarations will not contain type information about those

symbols. Only a .global will be issued for them. Therefore, it is your responsibility to ensure the symbol is

used appropriately.

See Section 12.2.13 for information on variables names which are of a structure/union type.

Sharing C/C++ Header Files With Assembly Source

261

Notes on C++ Specific Conversions

12.2.15

C Constant Suffixes

The C constant suffixes u, l, and f are passed to the assembly unchanged. The assembler will ignore

these suffixes if used in assembly expressions.

12.2.16

Basic C/C++ Types

Only complex types (structures and unions) in the C/C++ source code are converted to assembly. Basic

types such as int, char, or float are not converted or represented in assembly beyond any existing .int,

.char, .float, etc. directives that previously existed in assembly.

Typedefs of basic types are therefore also not represented in the converted assembly.

12.3

Notes on C++ Specific Conversions

The following sections describe C++ specific conversion elements that you need to be aware of when

sharing header files with assembly source.

12.3.1

Name Mangling

Symbol names may be mangled in C++ source files. When mangling occurs, the converted assembly will

use the mangled names to avoid symbol name clashes. You can use the demangler (dem430) to

demangle names and identify the correct symbols to use in assembly.

To defeat name mangling in C++ for symbols where polymorphism (calling a function of the same name

with different kinds of arguments) is not required, use the following syntax:

extern "C" void somefunc(int arg);

The above format is the short method for declaring a single function. To use this method for multiple

functions, you can also use the following syntax:

extern "C"

{

void somefunc(int arg);

int anotherfunc(int arg);

}

12.3.2

Derived Classes

Derived classes are only partially supported when converting to assembly because of issues related to

C++ scoping which does not exist in assembly. The greatest difference is that base class members do not

automatically become full (top-level) members of the derived class. For example:

----------------------------------------------------------

class base

{

public:

int b1;

};

class derived : public base

{

public:

int d1;

}

----------------------------------------------------------

In C++ code, the class derived would contain both integers b1 and d1. In the converted assembly

structure "derived", the members of the base class must be accessed using the name of the base class,

such as derived.__b_base.b1 rather than the expected derived.b1.

A non-virtual, non-empty base class will have __b_ prepended to its name within the derived class to

signify it is a base class name. That is why the example above is derived.__b_base.b1 and not simply

derived.base.b1.

262

Sharing C/C++ Header Files With Assembly Source

New Assembler Support

12.3.3

Templates

No support exists for templates.

12.3.4

Virtual Functions

No support exists for virtual functions, as they have no assembly representation.

12.4

New Assembler Support

12.4.1

Enumerations (.enum/.emember/.endenum)

New directives have been created to support a pseudo-scoping for enumerations.

The format of these new directives is:

ENUM_NAME

.enum

MEMBER1

.emember [value]

MEMBER2

.emember [value]

.endenum

The .enum directive begins the enumeration definition and .endenum terminates it.

The enumeration name (ENUM_NAME) cannot be used to allocate space; its size is reported as zero.

The format to use the value of a member is ENUM_NAME.MEMBER, similar to a structure member

usage.

The .emember directive optionally accepts the value to set the member to, just as in C/C++. If not

specified, the member takes a value one more than the previous member. As in C/C++, member names

cannot be duplicated, although values can be. Unless specified with .emember, the first enumeration

member will be given the value 0 (zero), as in C/C++.

The .endenum directive cannot be used with a label, as structure .endstruct directives can, because the

.endenum directive has no value like the .endstruct does (containing the size of the structure).

Conditional compilation directives (.if/.else/.elseif/.endif) are the only other non-enumeration code allowed

within the .enum/.endenum sequence.

12.4.2

The .define Directive

The new .define directive functions in the same manner as the existing .asg directive, except that .define

disallows creation of a substitution symbol that has the same name as a register symbol or mnemonic. It

does not create a new symbol name space in the assembler, rather it uses the existing substitution

symbol name space. The syntax for the directive is:

.define substitution string, substitution symbol name

The .define directive is used to prevent corruption of the assembly environment when converting C/C++

headers.

12.4.3

The .undefine/.unasg Directives

The .undef directive is used to remove the definition of a substitution symbol created using .define or .asg.

This directive will remove the named symbol from the substitution symbol table from the point of the .undef

to the end of the assembly file. The syntax for these directives is:

.undefine substitution symbol name

Sharing C/C++ Header Files With Assembly Source

263

New Assembler Support

.unasg substitution symbol name

This can be used to remove from the assembly environment any C/C++ macros that may cause a

problem.

Also see Section 12.4.2, which covers the .define directive.

12.4.4

The $defined( ) Directive

The $defined directive returns true/1 or false/0 depending on whether the name exists in the current

substitution symbol table or the standard symbol table. In essence $defined returns TRUE if the

assembler has any user symbol in scope by that name. This differs from $isdefed in that $isdefed only

tests for NON-substitution symbols. The syntax is:

$defined( substitution symbol name)

A statement such as ".if $defined(macroname)" is then similar to the C code "#ifdef macroname".

See Section 12.4.2 and Section 12.4.3 for the use of .define and .undef in assembly.

12.4.5

The $sizeof Built-In Function

The new assembly built-in function $sizeof( ) can be used to query the size of a structure in assembly. It is

an alias for the already existing $structsz( ). The syntax is:

$sizeof( structure name)

The $sizeof function can then be used similarly to the C built-in function sizeof( ).

The assembler's $sizeof( ) built-in function cannot be used to ask for the size of basic C/C++ types, such

as $sizeof(int), because those basic type names are not represented in assembly. Only complex types are

converted from C/C++ to assembly.

Also see Section 12.2.12, which notes that this conversion does not happen automatically if the C/C++

sizeof( ) built-in function is used within a macro.

12.4.6

Structure/Union Alignment & $alignof( )

The assembly .struct and .union directives now take an optional second argument which can be used to

specify a minimum alignment to be applied to the symbol name. This is used by the conversion process to

pass the specific alignment from C/C++ to assembly.

The assembly built-in function $alignof( ) can be used to report the alignment of these structures. This can

be used even on assembly structures, and the function will return the minimum alignment calculated by

the assembler.

12.4.7

The .cstring Directive

You can use the new .cstring directive to cause the escape sequences and NULL termination to be

properly handled as they would in C/C++.

.cstring "String with C escapes.\nWill be NULL terminated.\012"

See Section 12.2.11 for more information on the new .cstring directive.

264

Sharing C/C++ Header Files With Assembly Source

DWARF Debugging Format

A.1

DWARF Debugging Format

A subset of the DWARF symbolic debugging directives are always listed in the assembly language file that

the compiler creates for program analysis purposes. To list the complete set used for full symbolic debug,

invoke the compiler with the --symdebug:dwarf option, as shown below:

cl6x --symdebug:dwarf --keep_asm input_file

The --keep_asm option instructs the compiler to retain the generated assembly file.

To disable the generation of all symbolic debug directives, invoke the compiler with the -symdebug:none

option:

cl6x --symdebug:none --keep_asm input_file

The DWARF debugging format consists of the following directives:

• The .dwtag and .dwendtag directives define a Debug Information Entry (DIE) in the .debug_info

section.

• The .dwattr directive adds an attribute to an existing DIE.

• The .dwpsn directive identifies the source position of a C/C++ statement.

• The .dwcie and .dwendentry directives define a Common Information Entry (CIE) in the .debug_frame

section.

• The .dwfde and .dwendentry directives define a Frame Description Entry (FDE) in the .debug_frame

section.

• The .dwcfi directive defines a call frame instruction for a CIE or FDE.

A.2

COFF Debugging Format

COFF symbolic debug is now obsolete. These directives are supported for backwards-compatibility only.

The decision to switch to DWARF as the symbolic debug format was made to overcome many limitations

of COFF symbolic debug, including the absence of C++ support.

The COFF debugging format consists of the following directives:

• The .sym directive defines a global variable, a local variable, or a function. Several parameters allow

you to associate various debugging information with the variable or function.

• The .stag, .etag, and .utag directives define structures, enumerations, and unions, respectively. The

.member directive specifies a member of a structure, enumeration, or union. The .eos directive ends a

structure, enumeration, or union definition.

• The .func and .endfunc directives specify the beginning and ending lines of a C/C++ function.

• The .block and .endblock directives specify the bounds of C/C++ blocks.

• The .file directive defines a symbol in the symbol table that identifies the current source filename.

• The .line directive identifies the line number of a C/C++ source statement.

266

Symbolic Debugging Directives

Debug Directive Syntax

A.3

Debug Directive Syntax

Table A-1 is an alphabetical listing of the symbolic debugging directives. For information on the C/C++

compiler, refer to the TMS320C6000 Optimizing Compiler User's Guide

Table A-1. Symbolic Debugging Directives

Label

Directive

Arguments

.block

[beginning line number]

.dwattr

DIE label,DIE attribute name(DIE attribute value)[,DIE attribute name(attribute value) [, ...]

.dwcfi

call frame instruction opcode[,operand[,operand]]

CIE label

.dwcie

version , return address register

.dwendentry

.dwendtag

.dwfde

CIE label

.dwpsn

" filename ", line number , column number

DIE label

.dwtag

DIE tag name,DIE attribute name(DIE attribute value)[,DIE attribute name(attribute value) [, ...]

.endblock

[ending line number]

.endfunc

[ending line number[,register mask[, frame size]]]

.eos

.etag

name[, size]

.file

" filename "

.func

[beginning line number]

.line

line number[, address]

.member

name, value[, type, storage class, size, tag, dims]

.stag

name[, size]

.sym

name, value[, type, storage class, size, tag, dims]

.utag

name[, size]

Symbolic Debugging Directives

267

Appendix B

XML Link Information File Description

The linker supports the generation of an XML link information file via the --xml_link_info file option. This

option causes the linker to generate a well-formed XML file containing detailed information about the result

of a link. The information included in this file includes all of the information that is currently produced in a

linker-generated map file.

As the linker evolves, the XML link information file may be extended to include additional information that

could be useful for static analysis of linker results.

This appendix enumerates all of the elements that are generated by the linker into the XML link

information file.

Topic

Page

B.1

XML Information File Element Types

270

B.2

Document Elements

270

XML Link Information File Description

269

XML Information File Element Types

B.1

XML Information File Element Types

These element types will be generated by the linker:

• Container elements represent an object that contains other elements that describe the object.

Container elements have an id attribute that makes them accessible from other elements.

• String elements contain a string representation of their value.

• Constant elements contain a 32-bit unsigned long representation of their value (with a 0x prefix).

• Reference elements are empty elements that contain an idref attribute that specifies a link to another

container element.

In Section B.2, the element type is specified for each element in parentheses following the element

description. For instance, the <link_time> element lists the time of the link execution (string).

B.2

Document Elements

The root element, or the document element, is <link_info>. All other elements contained in the XML link

information file are children of the <link_info> element. The following sections describe the elements that

an XML information file can contain.

B.2.1

Header Elements

The first elements in the XML link information file provide general information about the linker and the link

session:

• The <banner> element lists the name of the executable and the version information (string).

• The <copyright> element lists the TI copyright information (string).

• The <link_time> is a timestamp representation of the link time (unsigned 32-bit int).

• The <output_file> element lists the name of the linked output file generated (string).

• The <entry_point> element specifies the program entry point, as determined by the linker (container)

with two entries:

- The <name> is the entry point symbol name, if any (string).

- The <address> is the entry point address (constant).

Example B-1. Header Element for the hi.out Output File

<banner>TMS320Cxx Linker

Version x.xx (Jan 6 2008)</banner>

<link_time>0x43dfd8a4</link_time>

<output_file>hi.out</output_file>

<entry_point>

</entry_point>

270

XML Link Information File Description

Document Elements

B.2.2

Input File List

The next section of the XML link information file is the input file list, which is delimited with a

<input_file_list> container element. The <input_file_list> can contain any number of <input_file>

elements.

Each <input_file> instance specifies the input file involved in the link. Each <input_file> has an id attribute

that can be referenced by other elements, such as an <object_component>. An <input_file> is a container

element enclosing the following elements:

• The <path> element names a directory path, if applicable (string).

• The <kind> element specifies a file type, either archive or object (string).

• The <file> element specifies an archive name or filename (string).

• The <name> element specifies an object file name, or archive member name (string).

Example B-2. Input File List for the hi.out Output File

<input_file_list>

<input_file id="fl-1">

<kind>object</kind>

</input_file>

<input_file id="fl-2">

<path>/tools/lib/</path>

<kind>archive</kind>

<file>rtsxxx.lib</file>

</input_file>

<input_file id="fl-3">

<path>/tools/lib/</path>

<kind>archive</kind>

<file>rtsxxx.lib</file>

</input_file>

<input_file id="fl-4">

<path>/tools/lib/</path>

<kind>archive</kind>

<file>rtsxxx.lib</file>

<name>printf.obj</name>

</input_file>

</input_file_list>

XML Link Information File Description

271

Document Elements

B.2.3

Object Component List

The next section of the XML link information file contains a specification of all of the object components

that are involved in the link. An example of an object component is an input section. In general, an object

component is the smallest piece of object that can be manipulated by the linker.

The <object_component_list> is a container element enclosing any number of <object_component>

elements.

Each <object_component> specifies a single object component. Each <object_component> has an id

attribute so that it can be referenced directly from other elements, such as a <logical_group>. An

<object_component> is a container element enclosing the following elements:

• The <name> element names the object component (string).

• The <load_address> element specifies the load-time address of the object component (constant).

• The <run_address> element specifies the run-time address of the object component (constant).

• The <size> element specifies the size of the object component (constant).

• The <input_file_ref> element specifies the source file where the object component originated

(reference).

Example B-3. Object Component List for the fl-4 Input File

<object_component id="oc-20">

<load_address>0xac00</load_address>

<run_address>0xac00</run_address>

<input_file_ref idref="fl-4"/>

</object_component>

<object_component id="oc-21">

<load_address>0x80000000</load_address>

<run_address>0x80000000</run_address>

<input_file_ref idref="fl-4"/>

</object_component>

<object_component id="oc-22">

<load_address>0x80000000</load_address>

<run_address>0x80000000</run_address>

<input_file_ref idref="fl-4"/>

</object_component>

272

XML Link Information File Description

Document Elements

B.2.4

Logical Group List

The <logical_group_list> section of the XML link information file is similar to the output section listing in a

linker-generated map file. However, the XML link information file contains a specification of GROUP and

UNION output sections, which are not represented in a map file. There are three kinds of list items that

can occur in a <logical_group_list>:

•

The <logical_group> is the specification of a section or GROUP that contains a list of object

components or logical group members. Each <logical_group> element is given an id so that it may be

referenced from other elements. Each <logical_group> is a container element enclosing the following

elements:

- The <name> element names the logical group (string).

- The <load_address> element specifies the load-time address of the logical group (constant).

- The <run_address> element specifies the run-time address of the logical group (constant).

- The <size> element specifies the size of the logical group (constant).

- The <contents> element lists elements contained in this logical group (container). These elements

refer to each of the member objects contained in this logical group:

• The <object_component_ref> is an object component that is contained in this logical group

(reference).

• The <logical_group_ref> is a logical group that is contained in this logical group (reference).

•

The <overlay> is a special kind of logical group that represents a UNION, or a set of objects that

share the same memory space (container). Each <overlay> element is given an id so that it may be

referenced from other elements (like from an <allocated_space> element in the placement map). Each

<overlay> contains the following elements:

- The <name> element names the overlay (string).

- The <run_address> element specifies the run-time address of overlay (constant).

- The <size> element specifies the size of logical group (constant).

- The <contents> container element lists elements contained in this overlay. These elements refer to

each of the member objects contained in this logical group:

• The <object_component_ref> is an object component that is contained in this logical group

(reference).

• The <logical_group_ref> is a logical group that is contained in this logical group (reference).

•

The <split_section> is another special kind of logical group that represents a collection of logical

groups that is split among multiple memory areas. Each <split_section> element is given an id so that

it may be referenced from other elements. The id consists of the following elements.

- The <name> element names the split section (string).

- The <contents> container element lists elements contained in this split section. The

<logical_group_ref> elements refer to each of the member objects contained in this split section,

and each element referenced is a logical group that is contained in this split section (reference).

XML Link Information File Description

273

Document Elements

Example B-4. Logical Group List for the fl-4 Input File

<logical_group_list>

<logical_group id="lg-7">

<load_address>0x20</load_address>

<run_address>0x20</run_address>

<object_component_ref idref="oc-34"/>

<object_component_ref idref="oc-108"/>

<object_component_ref idref="oc-e2"/>

</contents>

</logical_group>

<name>UNION_1</name>

<run_address>0xb600</run_address>

<object_component_ref idref="oc-45"/>

<logical_group_ref idref="lg-8"/>

</contents>

</overlay>

<split_section id="lg-12">

<logical_group_ref idref="lg-10"/>

<logical_group_ref idref="lg-11"/>

</contents>

</logical_group_list>

274

XML Link Information File Description

Document Elements

B.2.5

Placement Map

The <placement_map> element describes the memory placement details of all named memory areas in

the application, including unused spaces between logical groups that have been placed in a particular

memory area.

The <memory_area> is a description of the placement details within a named memory area (container).

The description consists of these items:

• The <name> names the memory area (string).

• The <page_id> gives the id of the memory page in which this memory area is defined (constant).

• The <origin> specifies the beginning address of the memory area (constant).

• The <length> specifies the length of the memory area (constant).

• The <used_space> specifies the amount of allocated space in this area (constant).

• The <unused_space> specifies the amount of available space in this area (constant).

• The <attributes> lists the RWXI attributes that are associated with this area, if any (string).

• The <fill_value> specifies the fill value that is to be placed in unused space, if the fill directive is

specified with the memory area (constant).

• The <usage_details> lists details of each allocated or available fragment in this memory area. If the

fragment is allocated to a logical group, then a <logical_group_ref> element is provided to facilitate

access to the details of that logical group. All fragment specifications include <start_address> and

<size> elements.

- The <allocated_space> element provides details of an allocated fragment within this memory area

(container):

• The <start_address> specifies the address of the fragment (constant).

• The <size> specifies the size of the fragment (constant).

• The <logical_group_ref> provides a reference to the logical group that is allocated to this

fragment (reference).

- The <available_space element provides details of an available fragment within this memory area

(container):

• The <start_address> specifies the address of the fragment (constant).

• The <size> specifies the size of the fragment (constant).

Example B-5. Placement Map for the fl-4 Input File

<placement_map>

<memory_area>

<page_id>0x0</page_id>

<used_space>0xb240</used_space>

<unused_space>0xf4dc0</unused_space>

<usage_details>

<allocated_space>

<start_address>0x20</start_address>

<logical_group_ref idref="lg-7"/>

</allocated_space>

<available_space>

<start_address>0xb260</start_address>

</available_space>

</usage_details>

</memory_area>

</placement_map>

XML Link Information File Description

275

Document Elements

B.2.6

Far Call Trampoline List

The <far_call_trampoline_list> is a list of <far_call_trampoline> elements. The C6000 linker supports the

generation of far call trampolines to help a call site reach a destination that is out of range. A far call

trampoline function is guaranteed to reach the called function (callee) as it may utilize an indirect call to

the called function.

The <far_call_trampoline_list> enumerates all of the far call trampolines that are generated by the linker

for a particular link. The <far_call_trampoline_list> can contain any number of <far_call_trampoline>

elements. Each <far_call_trampoline> is a container enclosing the following elements:

• The <callee_name> element names the destination function (string).

• The <callee_address> is the address of the called function (constant).

• The <trampoline_object_component_ref> is a reference to an object component that contains the

definition of the trampoline function (reference).

• The <trampoline_address> is the address of the trampoline function (constant).

• The <caller_list> enumerates all call sites that utilize this trampoline to reach the called function

(container).

• The <trampoline_call_site> provides the details of a trampoline call site (container) and consists of

these items:

- The <caller_address> specifies the call site address (constant).

- The <caller_object_component_ref> is the object component where the call site resides

(reference).

Example B-6. Fall Call Trampoline List for the fl-4 Input File

<far_call_trampoline_list>

<far_call_trampoline>

<callee_name>_foo</callee_name>

<callee_address>0x08000030</callee_address>

<trampoline_object_component_ref idref="oc-123"/>

<trampoline_address>0x2020</trampoline_address>

<caller_list>

<call_site>

<caller_address>0x1800</caller_address>

<caller_object_component_ref idref="oc-23"/>

</call_site>

<call_site>

<caller_address>0x1810</caller_address>

<caller_object_component_ref idref="oc-23"/>

</call_site>

</caller_list>

</far_call_trampoline>

</far_call_trampoline_list>

276

XML Link Information File Description

Document Elements

B.2.7

Symbol Table

The <symbol_table> contains a list of all of the global symbols that are included in the link. The list

provides information about a symbol's name and value. In the future, the symbol_table list may provide

type information, the object component in which the symbol is defined, storage class, etc.

The <symbol> is a container element that specifies the name and value of a symbol with these elements:

• The <name> element specifies the symbol name (string).

• The <value> element specifies the symbol value (constant).

Example B-7. Symbol Table for the fl-4 Input File

<symbol_table>

</symbol>

</symbol>

<name>_printf</name>

</symbol>

</symbol_table>

XML Link Information File Description

277

Appendix C

Glossary

absolute address— An address that is permanently assigned to a TMS320C6000 memory location.

absolute lister— A debugging tool that allows you to create assembler listings that contain absolute

addresses.

alignment— A process in which the linker places an output section at an address that falls on an n-byte

boundary, where n is a power of 2. You can specify alignment with the SECTIONS linker directive.

allocation— A process in which the linker calculates the final memory addresses of output sections.

ANSI— American National Standards Institute; an organization that establishes standards voluntarily

followed by industries.

archive library— A collection of individual files grouped into a single file by the archiver.

archiver— A software program that collects several individual files into a single file called an archive

library. With the archiver, you can add, delete, extract, or replace members of the archive library.

ASCII— American Standard Code for Information Interchange; a standard computer code for representing

and exchanging alphanumeric information.

assembler— A software program that creates a machine-language program from a source file that

contains assembly language instructions, directives, and macro definitions. The assembler

substitutes absolute operation codes for symbolic operation codes and absolute or relocatable

addresses for symbolic addresses.

assembly-time constant— A symbol that is assigned a constant value with the .set directive.

assignment statement— A statement that initializes a variable with a value.

autoinitialization— The process of initializing global C variables (contained in the .cinit section) before

program execution begins.

autoinitialization at run time— An autoinitialization method used by the linker when linking C code. The

linker uses this method when you invoke it with the --rom_model link option. The linker loads the

.cinit section of data tables into memory, and variables are initialized at run time.

big endian— An addressing protocol in which bytes are numbered from left to right within a word. More

significant bytes in a word have lower numbered addresses. Endian ordering is hardware-specific

and is determined at reset. See also little endian

binding— A process in which you specify a distinct address for an output section or a symbol.

block— A set of statements that are grouped together within braces and treated as an entity.

.bss section— One of the default object file sections. You use the assembler .bss directive to reserve a

specified amount of space in the memory map that you can use later for storing data. The .bss

section is uninitialized.

byte— Per ANSI/ISO C, the smallest addressable unit that can hold a character.

C/C++ compiler— A software program that translates C source statements into assembly language

source statements.

Glossary

279

Appendix C

COFF— Common object file format; a system of object files configured according to a standard developed

by AT&T. These files are relocatable in memory space.

command file— A file that contains options, filenames, directives, or commands for the linker or hex

conversion utility.

comment— A source statement (or portion of a source statement) that documents or improves readability

of a source file. Comments are not compiled, assembled, or linked; they have no effect on the

object file.

compiler program— A utility that lets you compile, assemble, and optionally link in one step. The

compiler runs one or more source modules through the compiler (including the parser, optimizer,

and code generator), the assembler, and the linker.

conditional processing— A method of processing one block of source code or an alternate block of

source code, according to the evaluation of a specified expression.

configured memory— Memory that the linker has specified for allocation.

constant— A type whose value cannot change.

cross-reference lister— A utility that produces an output file that lists the symbols that were defined,

what file they were defined in, what reference type they are, what line they were defined on, which

lines referenced them, and their assembler and linker final values. The cross-reference lister uses

linked object files as input.

cross-reference listing— An output file created by the assembler that lists the symbols that were defined,

what line they were defined on, which lines referenced them, and their final values.

.data section— One of the default object file sections. The .data section is an initialized section that

contains initialized data. You can use the .data directive to assemble code into the .data section.

directives— Special-purpose commands that control the actions and functions of a software tool (as

opposed to assembly language instructions, which control the actions of a device).

ELF— Executable and linking format; a system of object files configured according to the System V

Application Binary Interface specification.

emulator— A hardware development system that duplicates the TMS320C6000 operation.

entry point— A point in target memory where execution starts.

environment variable— A system symbol that you define and assign to a string. Environmental variables

are often included in Windows batch files or UNIX shell scripts such as .cshrc or .profile.

executable module— A linked object file that can be executed in a target system.

expression— A constant, a symbol, or a series of constants and symbols separated by arithmetic

operators.

external symbol— A symbol that is used in the current program module but defined or declared in a

different program module.

field— For the TMS320C6000, a software-configurable data type whose length can be programmed to be

any value in the range of 1-32 bits.

global symbol— A symbol that is either defined in the current module and accessed in another, or

accessed in the current module but defined in another.

GROUP— An option of the SECTIONS directive that forces specified output sections to be allocated

contiguously (as a group).

hex conversion utility— A utility that converts object files into one of several standard ASCII hexadecimal

formats, suitable for loading into an EPROM programmer.

280

Glossary

Appendix C

high-level language debugging— The ability of a compiler to retain symbolic and high-level language

information (such as type and function definitions) so that a debugging tool can use this

information.

hole— An area between the input sections that compose an output section that contains no code.

incremental linking— Linking files in several passes. Incremental linking is useful for large applications,

because you can partition the application, link the parts separately, and then link all of the parts

together.

initialization at load time— An autoinitialization method used by the linker when linking C/C++ code. The

linker uses this method when you invoke it with the --ram_model link option. This method initializes

variables at load time instead of run time.

initialized section— A section from an object file that will be linked into an executable module.

input section— A section from an object file that will be linked into an executable module.

ISO— International Organization for Standardization; a worldwide federation of national standards bodies,

which establishes international standards voluntarily followed by industries.

label— A symbol that begins in column 1 of an assembler source statement and corresponds to the

address of that statement. A label is the only assembler statement that can begin in column 1.

linker— A software program that combines object files to form an object module that can be allocated into

system memory and executed by the device.

listing file— An output file, created by the assembler, that lists source statements, their line numbers, and

their effects on the section program counter (SPC).

little endian— An addressing protocol in which bytes are numbered from right to left within a word. More

significant bytes in a word have higher numbered addresses. Endian ordering is hardware-specific

and is determined at reset. See also big endian

loader— A device that places an executable module into system memory.

macro— A user-defined routine that can be used as an instruction.

macro call— The process of invoking a macro.

macro definition— A block of source statements that define the name and the code that make up a

macro.

macro expansion— The process of inserting source statements into your code in place of a macro call.

macro library— An archive library composed of macros. Each file in the library must contain one macro;

its name must be the same as the macro name it defines, and it must have an extension of .asm.

map file— An output file, created by the linker, that shows the memory configuration, section composition,

section allocation, symbol definitions and the addresses at which the symbols were defined for your

program.

member— The elements or variables of a structure, union, archive, or enumeration.

memory map— A map of target system memory space that is partitioned into functional blocks.

mnemonic— An instruction name that the assembler translates into machine code.

model statement— Instructions or assembler directives in a macro definition that are assembled each

time a macro is invoked.

named section— An initialized section that is defined with a .sect directive.

object file— An assembled or linked file that contains machine-language object code.

object library— An archive library made up of individual object files.

Glossary

281

Appendix C

object module— A linked, executable object file that can be downloaded and executed on a target

system.

operand— An argument of an assembly language instruction, assembler directive, or macro directive that

supplies information to the operation performed by the instruction or directive.

options— Command-line parameters that allow you to request additional or specific functions when you

invoke a software tool.

output module— A linked, executable object file that is downloaded and executed on a target system.

output section— A final, allocated section in a linked, executable module.

partial linking— Linking files in several passes. Incremental linking is useful for large applications

because you can partition the application, link the parts separately, and then link all of the parts

together.

quiet run— An option that suppresses the normal banner and the progress information.

raw data— Executable code or initialized data in an output section.

relocation— A process in which the linker adjusts all the references to a symbol when the symbol's

address changes.

ROM width— The width (in bits) of each output file, or, more specifically, the width of a single data value

in the hex conversion utility file. The ROM width determines how the utility partitions the data into

output files. After the target words are mapped to memory words, the memory words are broken

into one or more output files. The number of output files is determined by the ROM width.

run address— The address where a section runs.

section— A relocatable block of code or data that ultimately will be contiguous with other sections in the

memory map.

section program counter (SPC)— An element that keeps track of the current location within a section;

each section has its own SPC.

sign extend— A process that fills the unused MSBs of a value with the value's sign bit.

simulator— A software development system that simulates TMS320C6000 operation.

source file— A file that contains C/C++ code or assembly language code that is compiled or assembled to

form an object file.

static variable— A variable whose scope is confined to a function or a program. The values of static

variables are not discarded when the function or program is exited; their previous value is resumed

when the function or program is reentered.

string table— A table that stores symbol names that are longer than eight characters (symbol names of

eight characters or longer cannot be stored in the symbol table; instead they are stored in the string

table). The name portion of the symbol's entry points to the location of the string in the string table.

structure— A collection of one or more variables grouped together under a single name.

subsection— A relocatable block of code or data that ultimately will occupy continuous space in the

memory map. Subsections are smaller sections within larger sections. Subsections give you tighter

control of the memory map.

symbol— A string of alphanumeric characters that represents an address or a value.

symbolic debugging— The ability of a software tool to retain symbolic information that can be used by a

debugging tool such as a simulator or an emulator.

tag— An optional type name that can be assigned to a structure, union, or enumeration.

target memory— Physical memory in a system into which executable object code is loaded.

282

Glossary

Appendix C

.text section— One of the default object file sections. The .text section is initialized and contains

executable code. You can use the .text directive to assemble code into the .text section.

unconfigured memory— Memory that is not defined as part of the memory map and cannot be loaded

with code or data.

uninitialized section— A object file section that reserves space in the memory map but that has no actual

contents. These sections are built with the .bss and .usect directives.

UNION— An option of the SECTIONS directive that causes the linker to allocate the same address to

multiple sections.

union— A variable that can hold objects of different types and sizes.

unsigned value— A value that is treated as a nonnegative number, regardless of its actual sign.

variable— A symbol representing a quantity that can assume any of a set of values.

veneer— A sequence of instructions that serves as an alternate entry point into a routine if a state

change is required.

well-defined expression— A term or group of terms that contains only symbols or assembly-time

constants that have been defined before they appear in the expression.

word— A 32 bits-bit addressable location in target memory

well-defined expression— A term or group of terms that contains only symbols or assembly-time

constants that have been defined before they appear in the expression.

Glossary

283

TMS320C6000 Assembly Language Tools v 6.1. User's Guide - page 7