Home

TMS320C55x Assembly Language Tools User's Guide

1. modulel obj module2 0bj ROKK KK KK kk k kk k Ck kk Ck kk kk Ck kk IA ke ko kk ke koe ke ke I x f Specify the Memory Configurations MEMORY ROM origin 2000h length 2000h RAM origin 8000h length 8000h BKK HK KK IK I KIA I A I IA I I I ke ke ke x f os Specify the Output Sections xy J CK FOR IOI ek RII IR IR ICR IR IO IO CK eK eK I IR IA IR IR I Ok ek f SECTIONS data gt RAM Cexts gt ROM bss gt RAM Invoke the linker 1nk55 bttest cmd This creates an executable object file called bttest out use this new file as input for the absolute lister Absolute Lister Example Step 3 Now invoke the absolute lister abs55 bttest out This creates two files called module1 abs and module2 abs module1 abs nolist array setsym 0004000h dflag setsym 0004064h offset Setsym 0004066h data setsym 0004000h data setsym 0004000h edata setsym 0004000h edata setsym 0004000h text Setsym 0002000h text setsym 0002000h etext setsym 000200fh etext setsym 000200fh bss Setsym 0004000h bss Sets
2. End of Command File kJ f Linker Example Invoke the linker with the following command lnk55 demo cmd This creates the map file shown in Example 9 15 and an output file called demo out that can be run on a TMS320C55x Example 9 15 Output Map File demo map OUTPUT FILE NAME lt demo out gt ENTRY POINT SYMBOL 0 MEMORY CONFIGURATION name org bytes len bytes used bytes attributes fill RAM_PG 00000100 000006f80 00000064 RWIX ONCHIP 00007081 000000f7f 00000104 RWIX EXT 00008000 000001fff 00000000 RWIX ROM 0000c000 000003f80 0000001 f RWIX SECTION ALLOCATION MAP output attributes section page org bytes org words len bytes len words input sections text 0 0000c000 0000001f 0000c000 0000000a tables obj text 0000c00a 00000008 fft obj text 0000c012 0000000c demo obj text 0000c01e 00000001 HOLE fill 2020 var defs 0 00003841 00000002 00003841 00000002 fft obj var defs data 0 00003843 00000080 00003843 00000001 tables obj data 00003844 00000004 fft obj data 00003848 0000007b HOLE
3. 6 000000 Sect rset 7 000000 6A00 RSET goto init 000002 0010 8 000004 6A00 INTO goto ISR0 000006 0000 9 000008 6A00 INT1 goto ISR1 00000a 0000 20 00000c 6A00 INT2 goto ISR2 00000e 0000 21 22 23 000000 Sect ints 24 000000 6A00 TINT goto d time 000002 0000 25 000004 6A00 RINT goto 4 rcv 000006 0000 26 000008 6A00 XINT goto xmt 00000a 0000 27 00000c 6A00 USER goto proc 00000e 0000 28 29 d Initialize processor d 30 31L 000010 init initmac 1 initialize macro 1 000010 4693 bit ST1 STI SATD 1 1 000012 7800 DP O1FFH amp 0 lt lt 7 000014 0000 1 000016 7600 ACO 55 000018 3708 1 00001a 46B2 bit ST1 ST1_INTM 0 Sa Lc lt Field 1 Field 2 Field 3 Field 4 Assembler Description 3 39 Cross Reference Listings 3 13 Cross Reference Listings A cross reference listing shows symbols and their definitions To obtain a cross reference listing invoke the assembler with the x op
4. 10 000000 Sect Vars d WORD LEN Set 16 12 DWORD_LEN Set WORD_LEN 2 13 BYTE_LEN Set WORD LEN 2 14 000000 000E byte 14 15 ck ck ck ck ck ck 0k ck ck Ck ck ck ck ck ck ck ck ck Ck ck ck ck kk ck kc ck cock ck ck ck kk ck ck Sk ck kv ko ko KKK 16 A Resume assembling into text section 17 18 000008 text 19 000008 7B00 ADD 66 ACO Assembled into text 00000a 4200 20 21 we Resume assembling into Vars section Dry 22 ck ck ck ck ck 0k ck ck Ck ck ck ck ck ck ck ck ck ck ck ck ck ck ck ck ck kc ck ck ck ck ck ck kk ck ko ko kv KKK ko ck ok 23 000001 Sect Vars 24 000001 000D field 13 WORD LEN 25 000002 0A00 field OAh BYTE LF 26 000003 0000 field 10q DWORD LEN 000004 0008 27 Assembler Directives 4 85 set equ Define Assembly Time Constant Syntax Description Example 4 86 symbol set value symbol equ value The set and equ directives equate a value to a symbol The symbol can then be used in place of a value in assembly source Th
5. T Sample command file with MEMORY directive y BKK AK IK AK I I kk kk kk ko kk I kk kk kc ko kc ko kc ko ko koe ko ke koe ke ke ke k x f filel obj file2 0bj Input files o prog out Options if MEMORY r ROM origin 1C00h length 1000h 4 SCRATCH origin 60h j length 20h 7 r ONCHIP origin 80h 4 length 1000h 4 names origins lengths Linker Description 9 29 The MEMORY Directive The general syntax for the MEMORY directive is MEMORY PAGE 0 name 1 attr origin constant length constant PAGE n name n attr origin constant length constant PAGE name attr origin optional identifies a memory space If you do not specify a PAGE the linker uses memory on PAGE 0 Each PAGE represents a com pletely independent address space Configured memory on PAGE 0 can overlap configured memory on PAGE 1 Names a memory range A memory name may be one to eight characters valid characters include A Z a z and The names have no special significance to the linker they simply iden tify memory ranges Memory range names are internal to the linker and are not retained in the output file or in the symbol table Memory ranges on separate pages can have the same name with in a page however all memory ranges must have unique names and must not overlap Spec
6. 00000b C000 MOV ACO Var 1 Declare external bss symbols dd ck cock ck ck ck ck ck ck ck 0k 0k 0k 0k 0k 0k 00k ck kk kk ck ck ck ck ck ck ck ck Ck Pk kx KKK global ARRAY TEMP end Assembler Directives 4 33 byte Initialize Bytes Syntax Description Example byte value valuen ubyte value valuen char value valuen uchar value values The byte ubyte char and uchar directives place one or more 8 bit values into consecutive words in the current data section qu so Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of byte ubyte char and uchar directives in a section that includes C55x instruc tions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections In data sections each 8 bit value is placed in a word by itself the 8 MSBs are filled with Os A value can be An expression that the assembler evaluates and treats as an 8 bit signed or unsigned number A character string enclosed in double quotes Each characte
7. 20 as Reserve 50 words in varl 21 KEK KKK KKK KKK KKK KKK KKK ck ck ck ck ok ck ck ck KKK KKK KKK KK KK 22 000065 dflag usect varl 50 23 24 000006 7B06 ADD dflag ACO ACO Still in text 000008 5000 25 26 27 yw Reserve 100 words in var2 Es 28 29 000000 vec usect var2 100 30 31 00000a 7B00 ADD vec ACO ACO Still in text 00000c 0000 32 33 Declare an external usect symbol 34 35 global array 4 104 Reserve Uninitialized Space usect Figure 4 7 The usect Directive section var1 section var2 ptr gt array p 100 words 100 words 100 words reserved in var2 dflag gt 50 words 151 words reserved in var1 Assembler Directives 4 105 Var Use Substitution Symbols as Local Variables Syntax Descri
8. 25 000002 text 26 000002 D600 ADD Table ACO ACO 000004 00 27 28 cock ck ck ck ck ck ck ck Ck 0k ck ck Ck 0k 00k kk ko kk ko kk ck ck ck ck ck ck ck c ck ck ko ko o AX 29 Resume assembling into the data m 30 section at address OFh X 31 kk occ ck ck ck ck ck ck ck KKK KKK KK KKK kk kk ck ck ck ck ck ck KKK KKK KKK 32 00000f data Assembler Directives 4 41 double Idouble Syntax Description Initialize Double Precision Floating Point Value double value valuen Idouble value value The double and Idouble directives place the IEEE double precision floating point representation of one or more floating point values into the current sec tion Each value must be a floating point constant or a symbol that has been equated to a floating point constant Each constant is converted to a floating point value in IEEE double precision 64 bit format Floating point constants are aligned on a word boundary p 71 Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of double and Idouble directives in a section that includes C55x instructions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections LL SS The value consists of three fields Field Meaning
9. Assemble into the text section Ape 000000 text 000000 3C00 MOV 0 ACO KAEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK kk ko kok ok Allocate 4 words in bss for TEMP m 000000 Var 1 bss TEMP 4 Du Still in text am 000002 7B00 ADD 86 ACO ACO 000004 5600 000006 5272 MOV T3 HI AC2 000008 1E73 MPYK 115 AC2 ACO 00000a 80 KAKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK Allocate 100 words in bss for the Wo symbol named ARRAY this part of Wu bss must fit on a single page ui KAKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 0000004 bss ARRAY 100 1 kc kk ck ck ck Sk SC Ck kk Ck Ck kk kk ck Sk Sk kk ko ck Sk kk ko ck ke KKK KKK Assemble more code into text We
10. 4 74 Syntax Description Example Start Stop Expansion Listing mlist mnolist mlist mnolist Two directives enable you to control the listing of macro and repeatable block expansions in the listing file _j The mlist directive allows macro and loop endloop block expansions in the listing file The mnolist directive suppresses macro and loop endloop block expansions in the listing file By default the assembler behaves as if the mlist directive had been specified This example defines a macro named STR 3 The second time the macro is called the macro expansion is not listed because a mnolist directive was assembled The third time the macro is called the macro expansion is listed because a mlist directive was assembled 1 STR 3 macro P1 P2 P3 2 data 3 String ipli p2i spas 4 endm 5 6 000000 STR S ae IT am 1 000000 data 1 000000 003A Btring ipli ipai rpa 000001 0070 000002 0031 000003 003A 000004 003A 000005 0070 000006 0032 000007 003A 000008 003A 000009 0070 00000a 0033 00000b 003A 7 mnolist 8 00000c STR 3 ag UY an 9 mlist 10 000018 STR 3 ag UIT xw 1 000018 data 1 000018 003A String ipli i p2i spade 000019 0070 00001a 0031 00001b 003A 00001c 003A 00001d 0070 00001e 0032 00001f 003A 000020 003A 000021 0070 000022 0033 000023 003A Assembler Directives 4 75 mmregs Assign Memory Mapped Register
11. EK Page length 65 lines ok X Page width 85 characters Wo ck oko ok kk ck ck ck ck ck ck ck ck ck ck ck 0k 0k ck ck 00k ko kk ko ko ko ke ko sk ck ck ck ck ck ck ck ko Length 65 width 85 KKK KKK KKK Ck Ck ck KK KKK KKK KKK KKK KKK KKK KKK KK KKK KK KKK Ek Page length 55 lines WE o Page width 100 characters m length 55 width 100 Syntax Description Example Start Stop Source Listing list nolist list nolist Two directives enable you to control the printing of the source listing DD The list directive allows the printing of the source listing The nolist directive suppresses the source listing output until a list directive is encountered The nolist directive can be used to reduce assembly time and the source listing size It can be used in macro defini tions to suppress the listing of the macro expansion The assembler does not print the list or nolist directives or the source state ments that appear after a nolist directive However it continues to increment the line counter You can nest the list nolist directives each nolist needs a matching list to restore the listing By default the source listing is printed to the listing file the assembler acts as if the list directive had been specified However
12. data 0041 START string LORIE UBA Om 0042 0043 0058 END string FTE BL 0059 005a Begin assembling into text section text D600 ADD START ACO ACO OO D600 ADD END ACO ACO gow Resume assembling into data section KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KK KK data 000a byte OAh OBh 000b 000c byte OCh ODh 000d Resume assembling into text section text 2201 MOV ACO AC1 Syntax Description Example Define Page Title title title string The title directive supplies a title that is printed in the heading on each listing page The source statement itself is n
13. M M M Li When you use a label with the space directive it points to the first word re served in adata section When you use a label with the bes directive it points to the ast word reserved in a data section This example shows how memory is reserved with the space and bes directives 1 2 Begin assembling into data section EK 3 4 000000 data 5 000000 0049 string In data 000001 006E 000002 0020 000003 002E 000004 0064 000005 0061 000006 0074 000007 0061 6 7 xx Reserve 100 bits in the data section 8 AW RES 1 points to the first word that ee 9 Wok contains reserved bits e 10 11 000008 RES 1 Space 100 12 00000f 000F word 15 13 000010 0008 word RES 1 14 15 ck ck Ck ck ck Ck ck KKK ck 0k ck ck Ck
14. rom6000 b0 contains bits 0 through 7 J rom6000 b1 contains bits 8 through 15 13 18 The ROMS Directive Figure 13 7 shows how the ROMS directive partitions the infile out file into four output files Figure 13 7 The infile out File From Example 13 1 Partitioned Into Four Output Files 04000h 0487Fh 05B80h 0633Fh 06700h 07C7Fh COFF File infile out memwidth 16 bits Output Files EPROM 1 rom4000 b0 rom4000 b1 04000h org 04880h 05B80h O5FFFh width 8 bits len 2000h 8K EPROM2 rom6000 b0 rom6000 b1 06000h 06340h 06700h 07C80h 07FFFh Hex Conversion Utility Description 13 19 The ROMS Directive 13 5 3 Creating a Map File of the ROMS Directive The map file specified with the map option is advantageous when you use the ROMS directive with multiple ranges The map file shows each range its parameters names of associated output files and a list of contents section names and fill values broken down by address Following is a segment of the map file resulting from the example in Example 13 1 Example 13 2 Map File Output From Example 13 1 Showing Memory Ranges 13 20 00004000 00005fff Page 0 Width 8 EPROM1 OUTPUT FILES rom4000 b0 CONTENTS 00004000 rom4000 b1 0000487 f b0 b7 b8 b15 rex 00004880 00005b7f FILL 00000000 00005580 00005 ff data 00006000 00007fff Page 0 W
15. text is assigned the first address of the text output section It marks the beginning of executable code etext is assigned the first address following the text output section It marks the end of executable code data is assigned the first address of the data output section It marks the beginning of initialized data tables edata is assigned the first address following the data output section It marks the end of initialized data tables bss is assigned the first address of the bss output section It marks the beginning of uninitialized data end is assigned the first address following the bss output section It marks the end of uninitialized data 9 15 5 Symbols Defined Only For C Support c or cr Option STACK SIZE is assigned the size of the stack section SYSSTACK SIZEis assigned the size of the sysstack section SYSMEM SIZE is assigned the size of the sysmem section Creating and Filling Holes 9 16 Creating and Filling Holes The linker provides you with the ability to create areas within output sections that have nothing linked into them These areas are called holes In special cases uninitialized sections can also be treated as holes The following text describes how the linker handles such holes and how you can fill holes and uninitialized sections with a value 9 16 1 Initialized and Uninitialized Sections An output section contains one of the following J Raw data for the entire
16. Bad archive entry for macro name Bad archive name Can t read a line from archive entry library name macro library not found library name is not in archive format Description These are errors about macro library accessing A problem was encountered reading from or writing to a macro library archive file It is likely that the creation of the archive file was not done properly Action Make sure that the macro libraries are unassembled assem bler source files Also make sure that the macro name and member name are the same and the extension of the file is asm Can t use g on assembly code with line directives Illegal structure union member No structure union currently open sym not allowed inside structure union Description These are errors about the illegal use of symbolic debugging directives a symbolic debugging directive is not used in an appropriate place Action Correct the source per the error message text Assembler Error Messages Access to MMR bank not supported for this instruction operand combination Illegal target of a conditional execute instruction Instructions not permitted in structure union definitions Instruction qualifier used as a stand alone instruction Parallel operator without instruction Parallelism checks addressing modifier does not allow parallelism combined number of A unit loads is too high combined number of D unit loads is too high combined size is too large conflicting COEFFICIENT opera
17. Description Action This instructi This message occurs when the assembler encounters the C54x RETE RETED FRETE and FRETED instructions These instructions are mapped to the C55x RETI instruction The effects of RETI differ from the effects ofthe RETE instruc tions For example RETI automatically restores ST1 55 ST2 55 and part of STO 55 RETE does not You may need to adjust your code accordingly Furthermore you need to de termine if your C54x interrupt service routine contains any one to many mappings using C55x temporary registers If SO you need to preserve the registers For more information see Section 7 1 2 on page 7 3 on loads the memory address itself and not the contents at that memory address Description Action This message occurs when the first operand of an AMOV instruction is a symbol without an operand prefix For example AMOV symbol XAR3 not written as symbol This instruction may seem to load the contents at the memory address represented by symbol However the address of the symbol itself is loaded Use the prefix to correct this issue AMOV symbol XAR3 Assembler Error Messages C 19 Assembler Error Messages C54x and C55x port numbers are different Description Action This message occurs when the assembler encounters C54x PORTR and PORTW instructions A C55x instruction sequence will be encoded to perform the same function but the port number used will mos
18. Table A 19 Section Format for Auxiliary Table Entries Byte Number Type Description 0 3 Long integer Section length 4 6 Unsigned short integer Number of relocation entries 7 8 Unsigned short integer Number of line number entries 9 17 Not used zero filled A 7 8 3 Tag Names Table A 20 illustrates the format of auxiliary table entries for tag names Table A 20 Tag Name Format for Auxiliary Table Entries Byte Number Type Description 0 5 Unused zero filled 6 7 Unsigned short integer Size of structure union or enumeration 8 11 Unused zero filled 12 15 Long integer Index of next entry beyond this function 16 17 Unused zero filled Common Object File Format A 23 Symbol Table Structure and Content A 7 8 4 End of Structure Table A 21 illustrates the format of auxiliary table entries for ends of structures Table A 21 End of Structure Format for Auxiliary Table Entries Byte Number 0 3 4 5 6 7 8 17 A 7 8 5 Functions Type Long integer Unsigned short integer Description Tag index Unused zero filled Size of structure union or enumeration Unused zero filled Table A 22 illustrates the format of auxiliary table entries for functions Table A 22 Function Format for Auxiliary Table Entries Byte Number 0 3 4 7 8 11 12 15 16 17 Type Long integer Long integer Long integer Long integer Description Tag index Size of function in bits File pointer to
19. prints a list of the global symbols that are defined in the library This option is valid only with the a r and d commands verbose provides a file by file description of the creation of a new library from an old library and its constituent members names an archive library If you don t specify an extension for libname the archiver uses the default extension ib names individual member files that are associated with the library You must specify a complete filename including an extension if applicable It is possible but not desirable for a library to contain several members with the same name If you attempt to delete replace or extract a member and the library contains more than one member with the specified name then the archiver deletes replaces or extracts the first member with that name Archiver Description 8 5 Archiver Examples 8 4 Archiver Examples The following are some archiver examples If you want to create a library called function lib that contains the files sine obj cos obj and flt obj enter ar55 a function sine obj cos obj flt obj TMS320C55x Archiver Version x xx Copyright c 2000 Texas Instruments Incorporated gt new archive function 1lib gt building archive function lib You can print a table of contents of function lib with the t option ar55 t function TMS320C55x Archiver Version X xx Copyright c 2000 Te
20. text relocation information text line number entries As Figure A 2 on page A 3 shows uninitialized sections created with the bss and usect directives vary from this format Although uninitialized sections have section headers they have no raw data relocation information or line number information They occupy no actual space in the object file Therefore the number of relocation entries the number of line number en tries and the file pointers are O for an uninitialized section The header of an uninitialized section simply tells the linker how much space for variables it should reserve in the memory map Structuring Relocation Information A 5 Structuring Relocation Information A COFF object file has one relocation entry for each relocatable reference The assembler automatically generates relocation entries The linker reads the relocation entries as it reads each input section and performs relocation The relocation entries determine how references within each input section are treated COFF file relocation information entries use the 12 byte format shown in Table A 6 Table A 6 Relocation Entry Contents Byte Number Type Description 0 3 Long integer Virtual address of the reference 4 7 Unsigned long integer Symbol table index 8 9 Unsigned short integer Additional byte used for extended ad dress calculations 10 11 Unsigned short integer Relocation type see Table A 7 The virtual address
21. C54x register A B ARn IMRn ASM status bit in ST1 C55x register T3 ACO AC1 ARn IERn T2 7 2 4 Status Bit Field Mapping Using Ported C54x Functions with Native C55x Functions The C55x status bit fields map to C54x status bit fields as shown below a STO Bit s 15 14 13 12 11 10 9 8 0 b ST1 Bit s 15 14 13 12 C55x field ACOV2 ACOV3 TC1 TC2 CARRY ACOVO ACOV1 DP C55x field BRAF CPL XF HM INTM M40 SATD SXMD C16 FRCT C54CM ASM C54x field none none none TC C OVA OVB DP C54x field BRAF CPL XF HM INTM none OVM SXM C16 FRCT none ASM Migrating a C54x System to a C55x System 7 7 Using Ported C54x Functions with Native C55x Functions c ST2 Bit s C55x field 15 ARMS 14 18 Reserved 12 DBGM 11 EALLOW 10 RDM 9 Reserved 8 CDPLC 7 0 ARnLC d ST3 Bit s C55x field 15 8 Reserved CBERR MPNMC SATA AVIS Reserved m oO A ATA O N CLKOFF 1 SMUL 0 SST 7 8 C54x field none none none none none none none none C54x field none none MP MC none AVIS none CLKOFF SMUL SST Using Ported C54x Functions with Native C55x Functions 7 2 5 Switching Between Runtime Environments The runtime environment defined in Section 7 2 1 is not complete because it only defines registers and status bits that are new with C55x Registers and status bits that are not new with C55x inherit their co
22. ROM RIX origin O0COOh length 1000h RAM RWIX origin 0080h length 1000h SECTIONS text gt ROM data ALIGN 128 gt RAM bss gt RAM In this example the linker places text into the area called ROM The data and bss output sections are allocated into RAM You can align a section within a named memory range the data section is aligned on a 128 byte boundary within the RAM range Similarly you can link a section into an area of memory that has particular attributes To do this specify a set of attributes enclosed in parentheses instead of a memory name Using the same MEMORY directive declaration you can specify SECTIONS text gt X text executable memory Ef data gt RI data gt read or init memory bss gt RW bss read or write memory In this example the text output section can be linked into either the ROM or RAM area because both areas have the X attribute The data section can also go into either ROM or RAM because both areas have the R and attributes The bss output section however must go into the RAM area because only RAM is declared with the W attribute You cannot control where in a named memory range a section is allocated although the linker uses lower memory addresses first and avoids fragmenta tion when possible In the preceding examples assuming that no conflicting assignments exist the text section would start at address
23. The loader then uses the initialization tables directly from the object file to initialize variables in bss Linking C Code Figure 9 6 illustrates the RAM autoinitialization model Figure 9 6 RAM Model of Autoinitialization Object File Memory LJ ROM Model c option Variables are initialized at runtime The cinit section is loaded into memory along with all the other sections The linker defines a special symbol called cinit that points to the beginning of the tables in memory When the program begins running the C boot routine copies data from the tables into the specified variables in the bss section This allows initializa tion data to be stored in ROM and copied to RAM each time the program is started Figure 9 7 illustrates the ROM autoinitialization model Figure 9 7 ROM Model of Autoinitialization Object File Memory Initialization tables possibly ROM Loader Boot routine Linker Description 9 71 Linking C Code 9 18 5 The c and cr Linker Options The following list outlines what happens when you invoke the linker with the c or cr option m The symbol _c_int00 is defined as the program entry point _c_int00 is the start of the C boot routine in boot obj referencing _c_int00 ensures that boot obj is automatically linked in from the runtime support library rts55 lib The cinit output section is padded with a termination record to designate to the boot
24. and delimiters For example This is a comment To invoke the utility and use the options you defined in a command file enter hex55 command filename You can also specify other options and files on the command line For exam ple you could invoke the utility by using both a command file and command line options hex55 firmware cmd map firmware mxp The order in which these options and file names appear is not important The utility reads all input from the command line and all information from the command file before starting the conversion process However if you are using the q option it must appear as the first option on the command line or in a command file The q option suppresses the utility s normal banner and progress informa tion Command File 13 3 1 Examples of Command Files m Assume that a command file named firmware cmd contains these lines firmware out input file t TI Tagged f o firm lsb output file o firm msb output file You can invoke the hex conversion utility by entering hex55 firmware cmd This example converts a file called appl out into four hex files in Intel format Each output file is one byte wide and 16K bytes long The text section is converted to boot loader format appl out input file my i Intel format map appl mxp map file ur ROMS ROW1 origin 01000h len 04000h romwidth 8 files appl u0 appl ul ROW2 origin 05000h l
25. def Structl Struct2 bss Structl 8 allocate 8 WORDS for Structl bss Struct2 6 allocate 6 WORDS for Struct2 text MOV Structl 2 TO load 3rd WORD of Structl MOV 1000h T1 0x1000 is an absolute WORD address i e byte 0x2000 Example 3 2 C55x Code Example text ref Func CALL Func 3 jump to address Func plus 3 BYTES CALL 0x1000 0x1000 is an absolute BYTE address 3 4 1 3 Using Code as Data and Data as Code The assembler does not support using a code address as if it were a data address e g attempting to read or write data to program space Similarly the assembler does not support using a data address as if it were a code ad dress e g executing a branch to a data label This functionality cannot be supported because of the difference in the size of the addressable units a code label address is a 24 bit byte address while a data label address is a 23 bit word address Consequently m You should not mix code and data within one section All data even constant data should be placed into a section separate from code Applications that attempt to read and write bits into program sections will not work Assembler Description 3 9 C55x Assembler Features 3 4 2 Parallel Instruction Rules The assembler performs semantic checking of parallel pairs of instructions in accordance with the rules specified in the TMS320C55x Instruction Se
26. fill 7alc 000038c3 00000000 demo obj data bss 0 00000080 00000002 00000080 00000002 demo obj bss fill ffff 00000082 00000000 fft obj bss 00000082 00000000 tables obj bss xy 0 00000082 00000030 UNINITIALIZED 00000082 00000030 demo obj xy GLOBAL SYMBOLS Sorted alphabetically by name Sorted by symbol address abs value abs value byte addr word addr name byte addr word addr name 00000080 bss 00000080 bss 00003843 data 00000082 end 0000c000 text 00003843 data 0000c016 ARRAY 00003843 TEMP 00003843 TEMP 000038c3 edata 0000c012 _x42 0000c012 _x42 000038c3 edata 0000c000 text 00000082 end 0000c016 ARRAY 0000c01f etext 0000c01f etext Linker Description 9 75 Chapter 10 Absolute Lister Description The absolute lister is a debugging tool that accepts linked object files as input and creates abs files as output These abs files can be assembled to produce a listing that shows the absolute addresses of object code Manually this could be a tedious process requiring many operations however the absolute lister utility performs these operations automatically Topic Page 10 1 Producing an Absolute Listing i 10 2 Invoking the Absolute Lister ee OmAbsolute DsienEXxampler Tr Producing an Absolute Listing 10 1 Producing an Absolute Listing Figure 10 1 illustrates the steps required to produce an absolute listing Figure 10 1 Absolute Lister Development Flow Assembler First assembl
27. m l Jo lal o Lv o Oo o NI LOJ O1 F jo Oj IN e Table 4 1 Assembler Directives Summary Continued i Miscellaneous directives Mnemonic and Syntax arms on arms off cb4cm on c54cm off cpl on cpl off dp DP value emsg string end label ivec address stack mode mmregs mmsg string newblock sblock section name section name horemark num Vli off Vli on wmsg string Description Directives Summary Page Identify the beginning or end of a block of code to be assembled in ARMS mode Identify the beginning or end of a block of C54x 4 35 compatibility mode code code that has been trans lated from C54x code Identify the beginning or end of a block of code to be 4 40 assembled in CPL mode Specifies the value of the DP register Send user defined error messages to the output 4 46 device End program 4 48 Initialize the entries in the interrupt vector table 4 63 Enter memory mapped registers into the symboltable 4 76 Send user defined messages to the output device 4 46 Undefine local labels 4 79 Designates sections for blocking 4 84 Suppress the assembler remark identified by num 4 80 Identify the beginning of a block of code in which the 4 107 assembler will use the largest form of certain variable length instructions Resume the default behavior of resolving variable 4 107 lengt
28. Assign cur tab to one of the tables Linker Description 9 59 Assigning Symbols at Link Time 9 15 2 Assigning the SPC to a Symbol A special symbol denoted by a dot represents the current value of the SPC uo during allocation The linker s symbol is analogous to the assembler s symbol The symbol can be used only in assignment statements within a SECTIONS directive because is meaningful only during allocation and SECTIONS controls the allocation process See Section 9 9 The SECTIONS Directive on page 9 32 Note that the symbol cannot be used outside of the braces that define a single output section The symbol refers to the current run address not the current load address of the section For example suppose a program needs to know the address of the beginning of the data section By using the global directive you can create an external undefined variable called Dstart in the program Then assign the value of to Dstart SECTIONS text 1 data Dstart sisi This defines Dstart to be the first linked address of the data section Dstart is assigned before data is allocated The linker will relocate all references to Dstart A special type of assignment assigns a value to the symbol This adjusts the SPC within an output section and creates a hole between two input sec ony tions Any value assigned to to creat
29. C54x and C55x C compiler run time environments are well defined which makes the techniques shownin this example more concrete and easier to apply to your own situation Example 7 1 C Prototype of Called Function short firlat short x short k short r short dbuffer unsigned short nx unsigned short nk Using Ported C54x Functions with Native C55x Functions Example 7 2 Assembly Function _firlat_veneer def ref firlat veneer _firlat_veneer _firlat Saving Registers PSH AR5 PSH AR6 saved in ported C54x environment PSH AR7 t ditto PSH T2 PSH T3 Passing Arguments PSH T1 push rightmost argument first PSH TO then the next rightmost PSH AR3 and so on PSH AR2 PSH AR1 MOV ARO ACO leftmost argument goes in ACO Change Status Bits BSET C54CM BCLR ARMS BCLR C16 Call CALL _firlat Restore Status Bits BCLR C54CM BSE ARMS BSE SXMD Capture Result MOV ACO TO Clear Arguments From the Stack AADD 5 SP Restore Registers and Return POP T3 POP T2 POP AR7 POP AR6 POP AR5 RET The veneer function is described below It is separated into several parts to allow for a description of each segment Migrating a C54x System to a C55x System 7 11 Using Ported C54x Functions with Native C55x Functions Example 7 2 Assembly Function _firlat_veneer Continued a Saving registers PSH AR
30. Expected Smem 16 Expected Xmem Expression evaluation failed Four bit unsigned literal expected HWA instruction value exceeds the allowed n bits Illegal xxx operand Illegal absolute address specified for Smem Illegal qualifier used on RHS Illegal register Illegal shift operand Assembler Error Messages Immediate value not Invalid binary constant specified Invalid condition Invalid constant specification Invalid decimal constant specified Invalid float constant specified Invalid hex constant specified Invalid index register in the coefficient operand Invalid octal constant specified Make sure that the label name is not a reserved keyword Make sure that the literals are prefixed by Memory address mode must belong to dual subset More than 16 switch labels Only labels and comments may begin in the first column Register in multiply term should be an accumulator Section is not defined Symbol usage not supported here This address mode is invalid in xxx mode This Smem mode is not allowed here Undefined symbolic constant Unexpected parallel instruction delimiters Unknown xxx term Description These are errors about invalid operands The instruction parameter or other operand specified was not recognized Action Correct the source per the error message text Assembler Error Messages C 3 Assembler Error Messages C 4 Absolute well defined integer value expected Identifier expected
31. Identifier operand expected Illegal character argument specified Illegal operand Illegal structure reference Invalid data size for relocation Invalid identifier sym specified Invalid macro parameter specified Invalid operand char No parameters available for macro arguments Single character operand expected String constant or substitution symbol expected String operand expected Structure Union tag symbol expected Substitution symbol operand expected Description These errors are about illegal operands The instruction parameter or other operand specified was not legal for this syntax Action Correct the source per the error message text Missing field value operand Missing operand s Operand missing Tag identification operand required Tag symbol identifier required Description These are errors about missing operands a required oper and is not supplied Action Correct the source so that all required operands are declared break must occur within a loop Conditional assembly mismatch Assembler Error Messages Matching endloop missing No matching if specified No matching endif specified No matching endloop specified No matching if specified No matching loop specified Open block s inside macro Unmatched endloop directive Unmatched if directive Description These are errors about unmatched conditional assembly directives A directive was encountered that requires a matching directive but the a
32. Syntax Description Reserve Space in the bss Section bss bss symbol size in words blocking flag alignment flag The bss directive reserves space for variables in the bss section This directive is typically used to allocate variables in RAM m m The symbolis a required parameter It defines a label that points to the first location reserved by the directive The symbol name corresponds to the variable that you re reserving space for The size is a required parameter it must be an absolute expression The assembler allocates size words in the bss section There is no default size The blocking flag is an optional parameter If you specify a non zero value for this parameter the assembler allocates size words contiguously This means that the allocated space will not cross a page boundary unless size is greater than a page in which case the object will start on a page bound ary The alignment flag is an optional parameter This flag causes the assembler to allocate size on long word boundaries Note Specifying an Alignment Flag Only To specify an alignment flag without a blocking flag you can insert two commas before the alignment flag or you can specify 0 for the blocking flag The assembler follows two rules when it allocates space in the bss section Rule1 Whenever a hole is left in memory as shown in Figure 4 5 the bss directive attempts to fill it When a bss directive is
33. The conditional assembly directives are if elseif else endif and loop break endloop They can be nested within each other up to 32 levels deep The format of a conditional block is if well defined expression elseif well defined expression else well defined expression endif The elseif and else directives are optional in conditional assembly The elseif directive can be used more than once within a conditional assembly code block When elseif and else are omitted and when the if expression is false 0 the assembler continues to the code following the endif directive For more information on the if elseif else endif directives see page 4 59 The loop break endloop directives enable you to assemble a code block repeatedly The format of a repeatable block is loop well defined expression break well defined expression endloop The loop directive s optional expression evaluates to the loop count the number of loops to be performed If the expression is omitted the loop count defaults to 1024 unless the assembler encounters a break directive with an expression that is true nonzero For more information on the loop break endloop directives see page 4 71 The break directive and its expression are optional If the expression evaluates to false the loop continues The assembler breaks the loop when the break expression evaluates to true or when the break expression
34. disassembler example invoking options double directive 4 13 4 42 dp directive drlist directive 4 18 use in macros drnolist directive 4 18 same effect with option directive 4 18 use in macros DSECT section 9 58 dummy section 9 59 Index 6 e absolute lister option 10 3 hex conversion utility option linker option edata linker symbol else directive use in macros elseif directive 4 21 4 59 use in macros emsg directive 4 25 4 46 5 19 isting control eee emulator defined end linker symbol end directive endblock symbolic debugging directive endfunc symbolic debugging directive endif directive use in macros endloop directive use in macros endm directive endstruct directive endunion directive entry point defined value assigned enumeration definitions environment variables A DIR C DIR C55X A DIR C55X OC DIR eos symbolic debugging directive equ directive error messages displayed by assembler C 1 to C 20 displayed by linker D 1 to D 16 generating hex conversion utility producing in macros etag symbolic debugging directive etext linker symbol eval directive listing control use in macros 4 92 4 100 B 3 B 5 evaluation of expressions even directive executable module defined executable output expression arithmetic operators in conditional 3 33 conditional operators in 3 33 defined described 3 linker ove
35. elseif SYM2 byte SYM2 endif SYM2 SYM2 lt 10 SYM2 Equal values Unequal values Less than equal Greater than SYM2 SYM2 SYM4 SYM3 SYM3 SYM4 SYM2 Unequal value Equal values Syntax Description Initialize 16 bit Integer int uint word uword int value valuen uint value valuen word value values uword value valuen The int uint word and uword directives are equivalent they place one or more values into consecutive 16 bit fields in the current section A value can be either Anexpression thatthe assembler evaluates and treats as an 16 bit signed or unsigned number D Acharacter string enclosed in double quotes Each character in a string represents a separate value p HM H 4 Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of int uint word and uword directives in a section that includes C55x instruc tions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections The values can be either absolute or relocatable expressions If an expression is relocatable the assembler generates a relocation entry that refers to the appropriate symbol the
36. recursive expansion Macro Parameters Substitution Symbols 5 3 4 Forced Substitution In some cases substitution symbols are not recognizable to the assembler The forced substitution operator which is a set of colons enables you to force the substitution of a symbol s character string Simply enclose a symbol in colons to force the substitution Do not include any spaces between the colons and the symbol The syntax for the forced substitution operator is symbol The assembler expands substitution symbols enclosed in colons before it expands other substitution symbols You can use the forced substitution operator only inside macros and you cannot nest a forced substitution operator within another forced substitution operator Example 5 7 shows how the forced substitution operator is used Example 5 7 Using the Forced Substitution Operator force macro x loop 8 AUX x Set X eval x 1 x endloop endm force 0 The force macro would generate the following source code AUXO set 0 AUX1 set 1 AUX7 set 7 Macro Language 5 11 Macro Parameters Substitution Symbols 5 3 5 Accessing Individual Characters of Subscripted Substitution Symbols In a macro you can access the individual characters substrings of a substitu tion symbol with subscripted substitution symbols You must use the forced substitution operator for clarity You can access substrings in two ways
37. text load PROG PAGE 0 data load PROG PAGE 0 bss load DATA PAGE 1 JN The four modules of code are f1 f2 f3 and f4 The modules f1 and f2 are combined into output section S1 and f3 and f4 are combined into output section S2 The PAGE specifications for S1 and S2 tell the linker to link these sections into the corresponding pages As a result they are both linked to load address AOOh but in different memory spaces When the program is loaded a loader can configure hardware so that each section is loaded into the appropriate memory bank Output sections S1 and S2 are placed in a union that has a run address in on chip RAM The application must move these sections at runtime before executing them You can use the symbols s1 load and s1 length to move section S1 and s2 load and s2 length to move section S2 The special symbol refers to the current run address not the current load address Overlay Pages Within a page you can bind output sections or use named memory areas in the usual way In Example 9 12 S1 could have been allocated S1 load 01200h page 1 This binds S1 at address 1200h in page 1 Youcan also use page as a qualifier on the address For example S1 load 01200h PAGE 1 Los x osx q If you do not specify any binding or named memory range for the section the linker allocates the section into the page wherever it can just as it normally does with a single memory s
38. 2 4 or 8 followed by a series of zero or more Os Linker Error Messages blocking for redefined Description More than one blocking value is supplied for a section c requires fill value of 0 in cinit overridden Description The cinit tables must be terminated with 0 therefore the fill value of the cinit section must be 0 cannot complete output file write error Description This usually means that the file system is out of space cannot create output file Description This usually indicates an illegal filename Action Check spelling pathname environment variables etc The filename must conform to operating system conventions cannot resize section has initialized definition in Description An initialized input section named stack or heap exists pre venting the linker from resizing the section cannot specify a page for a section within a GROUP Description Asection was specified to a specific page within a group The entire group is treated as one unit so the group may be speci fied to a page of memory but the sections making up the group cannot be handled individually cannot specify both binding and memory area for Description Both binding and memory were specified The two are mutu ally exclusive Action If you wish the code to be placed at a specific address use binding only Linker Error Messages D 3 Linker Error Messages can t align a section
39. 31 30 23 22 0 Ce a E s When you use floatin a struct endstruct sequence float defines a member s size it does not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 This example shows the float directive 1 000000 data 2 000000 E904 float 1 0e25 000001 5951 3 000002 4040 float 3 000003 0000 4 000004 42F6 float 123 000005 0000 Assembler Directives 4 53 global def ref Syntax Description Example Identify Global Symbols global symbol symbol def symbol symbol ref symbol symbol The global def and ref directives identify global symbols which are defined externally or can be referenced externally The def directive identifies a symbol that is defined in the current module and can be accessed by other files The assembler places this symbol in the sym bol table The ref directive identifies a symbol that is used in the current module but defined in another module The linker resolves this symbol s definition at link time The global directive acts as a ref or a def as needed A global symbol is defined in the same manner as any other symbol that is it appears as a label or is defined by the set bss or usect directive As with all symbols if a global symbol is defined more than once the linker issues a multiple definition error ref always creates a symbol tabl
40. C55x Development Flow If your C54x code includes either of the following all code must also be placed on page 0 J Indirect calls with CALA 1 Modification of the repeat block address registers REA or RSA If your C54x code includes either of the following it can be placed on any page but it must fit within that page Indirect branches with BACC Modification or use of the function return address on the stack in a non standard way stack unwinding Otherwise code can be placed anywhere in memory Running C54x Code on C55x 6 3 Understanding the Listing File 6 2 Understanding the Listing File The assembler s listing file created when invoking masm55 with the option now provides additional information on how C54x instructions are mapped for the C55x Consider the following contrived C54x source file global name ADD AR2 A STL A AR3 RPT 10 MVDK AR4 name subm macro meml mem2 reg LD meml reg SUB mem2 reg endm subm name AR6 B MOV T1 AC3 native C55x instruction The listing file shown below has explanations inserted for clarification C54x instructions with the same syntax in C55x such as the ADD instruction below appear without any special notation 1 global name 2 3 000000D641 ADD AR2 A 00000200 Note that A in the example above is accepted even though it maps to ACO on the C55x C54x instructions with a different syntax in C55x but a single l
41. S A 1 bit sign field e An 11 bit biased exponent f A 52 bit mantissa The value is stored most significant word first least significant word second in the following format 31 30 20 19 0 31 0 When you use double or Idouble in a struct endstruct sequence the directives define a member s size they do not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 Initialize Double Precision Floating Point Value double Idouble Example This example shows the double and Idouble directives 1 000000 data 2 000000 C520 double 1 0e25 000001 8B2A 000002 2C28 000003 0291 2 000004 407C ldouble 456 0 000005 8000 000006 0000 000007 0000 Assembler Directives 4 43 dp Specify DP Value Syntax Description dp dp value The dp directive specifies the value of the DP register The dp value can be a constant or a symbolic expression By default direct memory addressing dma is relative to the data memory local page pointer register DP The dma syntax is dma where dma can be a constant or a linktime symbolic expression The assembler computes the difference between dma and the value in the DP register and encodes this dif ference into the output bits The assembler cannot track the value of the DP register however it must know the value of DP in order to assemble direct memory access operands Consequently you must use the dp directi
42. T_UCHAR T_USHORT Value o Oc nN ODO OC A CO PD ak ak O 12 13 Symbol Table Structure and Content Type Type not assigned Character Short integer Integer Long integer Floating point Double word Structure Union Enumeration Member of an enumeration Unsigned character Unsigned short integer Bits 4 15 of the type field are arranged as six 2 bit fields that can indicate one to six derived types Table A 16 lists the possible derived types Table A 16 Derived Types Mnemonic DT NON DT PTR DT FON DT ARY Value Type No derived type Pointer Function Array An example of a symbol with several derived types would be a symbol with a type entry of 00000000110100112 This entry indicates that the symbol is an array of pointers to short integers Common Object File Format A 21 Symbol Table Structure and Content A 7 8 Auxiliary Entries Each symbol table entry may have one or no auxiliary entry An auxiliary sym bol table entry contains the same number of bytes as a symbol table entry 18 but the format of an auxiliary entry depends on the symbol s type and storage class Table A 17 summarizes these relationships Table A 17 Auxiliary Symbol Table Entries Format Storage Name Class file C_FILE text data bss C_STAT tagname C_STRTAG C_UNTAG C_ENTAG eos C EOS fcname C EXT C STAT arrname See note 2 bb eb C BLOCK bf ef C FON Name related to a structure union
43. The smallest unit of an object file is called a section A section is a block of code or data that will ultimately occupy contiguous space in the memory map Each section of an object file is separate and distinct COFF object files always con tain three default sections text section contains executable code data section usually contains initialized data bss section usually reserves space for uninitialized variables In addition the assembler and linker allow you to create name and link named sections that are used like the data text and bss sections There are two basic types of sections initialized sections contain data or code The text and data sections are initialized named sections created with the Sect assembler directive are also initialized uninitialized sections reserve space for uninitialized data The bss sec tion is uninitialized named sections created with the usect assembler directive are also uninitial ized Several assembler directives allow you to associate various portions of code and data with the appropriate sections The assembler builds these sections during the assembly process creating an object file organized as shown in Figure 2 1 One of the linker s functions is to relocate sections into the target memory map this function is called allocation Because most systems contain several types of memory using sections can help you use target memory more effi ciently All sections are in
44. The specified size parameter must be in words since it is a data section Chapter 2 Introduction to Common Object File Format discusses COFF sections in detail Directives That Define Sections Example 4 1 shows how you can use sections directives to associate code and data with the proper sections This is an outputlisting column 1 shows line numbers and column 2 shows the SPC values Each section has its own pro gram counter or SPC When code is first placed in a section its SPC equals 0 When you resume assembling into a section after other code is assembled the section s SPC resumes counting as if there had been no intervening code The directives in Example 4 1 perform the following tasks text contains basic adding and loading instructions data initializes words with the values 9 10 11 12 13 14 15 and 16 var_defs initializes words with the values 17 and 18 bss reserves 19 words usect reserves 20 words The bss and usect directives do not end the current section or begin new sections they reserve the specified amount of space and then the assembler resumes assembling code or data into the current section Assembler Directives 4 9 Directives That Define Sections Example 4 1 Sections Directives Nor 0 000 10 01 5 U ho ES w O B00 dd OY us 22 23 24 25 26 25 28 29 30 31 32 33 34 35 36 000000 000000 000002 000000 000000 000001 000002 0000
45. a is speci fied by default Producing an Absolute Output Module a Option When you use the a option without the r option the linker produces an absolute executable output module Absolute files contain no relocation information Executable files contain the following B Special symbols defined by the linker subsection 9 15 4 Symbols Defined by the Linker on page 9 62 describes these symbols BI An optional header that describes information such as the program entry point B No unresolved references The following example links file1 obj and file2 obj and creates an absolute output module called a out ink55 a filel obj file2 0bj _ _ goOwnwnwnwrerwvreemeererereeerrveerreeeerrrewsgererrerersres rerrerreereerwererrerrrerrsrrererrerrrerrerrreerewrererrreere rnr reeee Note aand r Options If you do not use the a or the r option the linker acts as if you specified a Linker Options Producing a Relocatable Output Module r Option When you use the r option without the a option the linker retains relocation entries in the output module If the output module will be relocated at load time or relinked by another linker execution use r to retain the relocation entries The linker produces a file that is not executable when you use the r option without a A file that is not executable does not contain special linker symbols or an optional header The file may co
46. abs55 ea s ec csr eh hsr hello out An abs file will not be created for hello hsr the header file and hello abs will include the assembly file hello s not the C source file hello csr Absolute Lister Example 10 3 Absolute Lister Example This example uses three source files module1 asm and module2 asm both include the file globals def module1 asm bss array 100 bss dflag 2 Copy globals def Cext MOV offset ACO MOV dflag ACO module2 asm bss offset 2 Copy globals def text MOV offset ACO MOV array ACO globals def global dflag global array global offset The following steps create absolute listings for the files module1 asm and module2 asm Step 1 First assemble module1 asm and module2 asm masm55 modulel masm55 module2 This creates two object files called module1 obj and module2 obj Absolute Lister Description 10 5 Absolute Lister Example 10 6 Step 2 Next link module1 obj and module2 obj using the following linker command file called bttest cmd 8K KKK KK KR A I I A A ke ke ke ke ke I x f File bttest cmd COFF linker command file for linking TMS320C55x modules BOK KKK KK kk k ko kk I I ke ko k k ke koe OK kk ke ke x e e e e x x f o bttest out Name the output file m bttest map Create an output map J FECKCKCKCk kCkCk Ck kk kk Ck kk Ck kk kk Ck kk k kk k ko kc k koe ke koe ke ke ke ke ke kx x f JP Specify the Input Files f
47. and uchar directives place one or more 8 bit values into consecutive wordsin the current data section These directives are similar to word and uword except that the width of each value is restricted to 8 bits The field directive places a single value into a specified number of bits in the word within data sections With field you can pack multiple fields into a single word the assembler does not increment the SPC until a word is filled If a value can fit within a word the assembler will guarantee that it does not span a word address boundary Figure 4 2 shows how fields are packed into a word For this example assume the following code has been assembled notice that the SPC doesn t change for the first three fields the fields are packed into the same word 3 000000 data 4 000000 6000 field 3 3 5 000000 6400 field 8 6 6 000000 6440 field 16 5 7 000001 0123 field 01234h 20 000002 4000 8 000003 0000 field 01234h 32 000004 1234 Directives That Initialize Constants Figure 4 2 The field Directive m 15141 0 0 1 1 field 3 3 P 3 bits 15 121110 9 8 7 0 011001000 PEERS EC 6 bits 15 65432 0 0Ti000001000000 field 16 5 eJ 5 bits 15 0000000100100 0 1 i field 01234n 20 15 0100000000000000 000000000000000 field 01234h 32 0001001000110100 float and xfloat calculate the single precision 32 bit IEEE floating point representation of a single floating point value and store
48. instructions in their largest form d goto P24 d call P24 C55x Assembler Features The mv assembler option suppresses the size resolution of the above instructions within the entire file The vli_off and vli_on directives can be used to toggle this behavior for regions of an assembly file In the case of a conflict between the command line option and the directives the directives take pre cedence All other variable length instructions will continue to be resolved to their small est possible size by the assembler despite the mv option or vli off directive The scope of the vli off and vli on directives is static and not subject to the control flow of the assembly program 3 4 A Memory Modes The assembler supports three memory modes C54x compatibility CPL and ARMS The assembler accepts or rejects its input based on the mode specified it may also produce different encodings for the same input based on the mode The memory modes correspond to the value of the C54CM CPL and ARMS status bits The assembler cannot track the value of the status bits You must use assembler directives and or command line options to inform the assembler of the value of these bits An instruction that modifies the value of the C54CM CPL or ARMS status bit must be immediately followed by an appropriate assembler directive When the assembler is aware of changes to these bit values it can provide useful error and warning messages about
49. oe 6 3 Handling Reserved C55x Names 7 Migrating a C54x System to a C55x System sseseeeseeee eee Describes system considerations when porting C54x code to C55x 43 Handling Interrupts i eA Dex tb E ete rere adr ehe ode a 7 1 1 Differences in the Interrupt Vector Table ss 7 1 2 Handling Interrupt Service Routines i 7 1 8 Other Issues Related to Interrupts i Contents ix Contents 7 2 Using Ported C54x Functions with Native C55x Functions 7 2 1 Runtime Environment for Ported C54x Code pp 7 2 2 C55x Registers Used as Temporaries pp 7 2 8 C54x to C55x Register Mapping 0000s 7 2 4 Status Bit Field Mapping i 7 2 5 Switching Between Runtime Environments 0 00eeee eee eens 7 2 6 Example of C Code Calling C54x Assembly 0 0c eee ee eee 7 2 7 Example of C54x Assembly Calling C Code pp 7 3 Non Portable C54x Coding Practices i 7 4 Additional C54x Issues 0 00 sess hh 8 Archiver Description ss Contains instructions for invoking the archiver creating new archive libraries and modifying existing libraries 8 3 Archiver OVervIeW re 8 2 Archiver Development Flow 8 3 Invoking the Archiver ns 8 4 Archiver Examples em eee hme 9 Linker Description cece cee III HII IH Im Explains how to invoke the linker provides details about linker operation discusses linker directives and presents a detailed linking example 9 1
50. or an arithmetic type is required but not present Action Correct the source per the error message text Assembler Error Messages C 7 Assembler Error Messages C 8 Absolute operands required for FP operations Floating point divide by zero Floating point overflow Floating point underflow Floating point expression required Illegal floating point expression Invalid floating point operation Description These are errors about floating point expressions A float ing point expression was used where an integer expressionis required an integer expression was used where a float ing point expression is required or a floating point value is invalid Action Correct the source per the error message text Cannot equate an external symbol to an external Cannot redefine this section name Cannot tag an undefined symbol Empty structure or union definition Illegal structure or union tag Missing closing for repeat block Redefinition of sym attempted Structure tag can t be global Symbol can t be defined in terms of itself Symbol expected Symbol expected in label field Symbol sym has already been defined Symbol sym is not defined in this source file Symbol sym is operand to both ref and def Structure union member sym not found The following symbols are undefined Union member previously defined Union tag can t be global Description These are errors about general symbols An attempt was made to redefin
51. side of the local file This example shows how the local label 1 is declared reset and then declared again 1 ref ADDRA ADDRB ADDRC 2 foo Set 76h 3 4 000000 A000 LABEL1 MOV ADDRA ACO 5 000002 7C00 SUB f 00 ACO 000004 7600 6 000006 62200 BCC 1 ACO lt 0 7 000008 A000 MOV ADDRB ACO 8 00000a 4A02 B 2 9 10 00000c A000 1 MOV ADDRA ACO 11 000003 D600 2 ADD ADDRC ACO ACO 000010 00 12 newblock Undefine 1 to reuse 13 000011 6120 BCC 1 ACO lt 0 14 000013 C000 MOV ACO ADDRC 15 000015 20 SI NOP Assembler Directives 4 79 horemark Suppress Remarks Syntax Description Example 4 80 noremark num The noremark directive suppresses the assembler remark identified by num A remark is an informational assembler message that is less severe than a warning This directive is equivalent to using the rnum command line option This example shows how to suppress the R5002 remark Original listing file 1 00000020 RSBX CMPT file asm REMARK at line 1 R5002 Ignoring RSBX CMPT instruction 2 3 000001 4804 RETF file asm REMARK at line 3 R5004 Translation of RETF correct only for non interrupt routine Listing file with noremark i noremark 5002 2 000000 20 RSBX CMPT 3 4 000001 4804 RETF file asm REMARK at line 4 R5004 Translation of RETF correct only for non interrupt routine Select Listing Options option Syntax option option list Descriptio
52. specifying a runtime address to specifying linker input sections to uninitialized 2 4 to p 5 initializing 9 66 specifying a run address 9 42 Set directive 4 22 4 86 setsect directive setsym directive Short directive 4 13 4 57 sign extend defined simulator defined sname SECTIONS specification source file defined listings 3 36 to 3 39 e 4 to 5 5 source statement field format to 3 20 number in source listing syntax Space directive SPC aligning by creating a hole to word boundaries assembler symbol assembler s effect on assigning a label to to ETE 2 9 to 2 11 Index 13 Index SPC continued defined described linker symbol maximum number of predefined symbol for value associated with labels 9 18 shown in source listings B 36 special section types 9 58 special symbols to sslist directive 4 19 listing control 4 18 4 45 use in macros ssnolist directive 4 19 listing control 4 18 4 45 use in macros stack stack linker option stack pointers initializing for ported C54x code __ STACK SIZE 9 18 9 62 Stag symbolic debugging directive static defined symbols variables status bits C54x to C55x mapping storage class defined E 7 described string directive 4 14 limiting listing with option directive string functions 5 9 string table defined E 7 described stripping line number entries 9
53. such as a serial or communications port to initialize the code or data The hex conversion utility supports the boot loader by auto matically building the boot table 13 9 1 Description of the Boot Table The input for a boot loader is the boot table The boot table contains records that instruct the on chip loader to copy blocks of data contained in the table to specified destination addresses Some boot tables also contain values for ini tializing various processor control registers The boot table can be stored in memory or read in through a device peripheral The hex conversion utility automatically builds the boot table for the boot loader Using the utility you specify the COFF sections you want the boot loader to initialize the table location and the values for any control registers The hex conversion utility identifies the target device type from the COFF file builds a complete image of the table according to the format required by that device and converts it into hexadecimal in the output files Then you can burn the table into ROM or load it by other means The boot loader supports loading from memory that is narrower than the nor mal width of memory For example you can boot a 16 bit TMS320C55x from a single 8 bit EPROM by using the memwidth option to configure the width of the boot table The hex conversion utility automatically adjusts the table s format and length See the boot loader example in the TMS320C55x DSP CPU R
54. syntax and semantic violations of these modes 3 4 4 1 C54x Compatibility Mode C54x compatibility mode is necessary when a source file has been translated from C54x code Until you modify your translated source code to be C55x na tive code use the ml command line option when assembling the file or use the cb4cm on and cb4cm off directives to specify C54x compatibility mode for regions of code The cb4cm on and c54cm off directives take no argu ments In the case of a conflict between the command line option and the di rective the directive takes precedence The scope of the cb4cm on and cb4cm off directives is static and not sub ject to the control flow of the assembly program All assembly code between the cb4cm on and cb4cm off directives is assembled in C54x compatibility mode In C54x compatibility mode ARO is used instead of TO C55x index register in memory operands For example AR5 TO is invalid in C54x compatibility mode AR5 ARO should be used Assembler Description 3 11 C55x Assembler Features 3 4 4 CPL Mode 3 12 CPL mode affects direct addressing The assembler cannot track the value of the CPL status bit Consequently you must use the cpl on and cpl off direc tives to model the CPL value Issue one of these directives immediately follow ing any instruction that changes the value in the CPL bit The cpl on directive models the CPL status bit set to 1 itis equivalent to usin
55. the linker requires that all referenced symbols be defined This condition prevents the creation of an executable output file Action Link using the r option or define the symbol Linker Error Messages D 15 Linker Error Messages undefined symbol in expression Description An assignment statement contains an undefined symbol unrecognized option Action Check the list of valid options zero or missing length for memory area Description A memory range defined with the MEMORY directive did not have a nonzero length Appendix E Glossary absolute address An address that is permanently assigned to a TMS320C55x memory location absolute lister A debugging tool that accepts linked files as input and creates abs files as output These abs files can be assembled to pro duce a listing that shows the absolute addresses of object code Without the tool an absolute listing can be prepared with the use of many manual operations algebraic An instruction that the assembler translates into machine code alignment A process in which the linker places an output section at an address that falls on an n bit boundary where nis 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 archive library A collection of individual files that have been grouped into a single file archiver A softwa
56. the symbol table Assume that the original function in the C source contained three lines of code The first line of code produces 4 words of assembly lan guage code the second line produces 3 words and the third line produces 10 words Figure A 5 Line Number Entries line number entries symbol table Note that the symbol table entry for XYZ has a field that points back to the beginning of the line number block Because line numbers are not often needed the linker provides an option S that strips line number information from the object file this provides a more compact object module A 7 Symbol Table Structure and Content Symbol Table Structure and Content The order of symbols in the symbol table is very important they appear in the sequence shown in Figure A 6 Figure A 6 Symbol Table Contents filename 1 function 1 local symbols for function 1 function 2 local symbols for function 2 filename 2 function 1 local symbols for function 1 static variables defined global symbols undefined global symbols Staticvariables refer to symbols defined in C that have storage class static out side any function If you have several modules that use symbols with the same name making them static confines the scope of each symbol to the module that defines it this eliminates multiple definition conflicts Common Object F
57. ulong ushort uword and word An element can also be a com plete declaration of a nested structure or union or a structure or union declared by its tag Following a union directive these directives describe the element s size They do not allocate memory is an optional expression for the number of elements described This value defaults to 1 A string element is considered to be one word in size and a field element is one bit is an optional label for the total size of the union Note Directives That Can Appear in a union endunion Sequence The only directives that can appear in a union endunion sequence are ele ment descriptors structure and union tags conditional assembly directives and the align directive which aligns the member offsets on word bound aries Empty structures are illegal eee SS These examples show unions with and without tags Assembler Directives 4 101 union endunion tag Declare Union Types Example 1 000000 9 000000 10 13 12 000000 13 000000 000002 Example 2 4 102 1 000000 2 YAO BW 0000 0000 0000 0002 D600 00 0000 0000 0000 0002 xample ival fval sval real len employid size u global employid data union utag word memberl 0 float member2 0 string member3 0 endunion real len 4 bss employid real len j allocate memory tag xample text ADD employid fval ADD ADD access union element
58. 00000a 0045 String Extended Registers 12 13 14 px Reset the listing options ER 15 KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK 16 option R 17 00001c FFBD byte C OBOh 5 00001d 00B0 00001e 0005 18 000020 AABB long OAABBCCDDh 536 A 000021 CCDD 000022 0000 000023 0259 19 000024 15AA word 5546 78h 000025 0078 20 000026 0045 String Extended Registers 000027 0078 000028 0074 000029 0065 00002a 006E 000020 0064 00002c 0065 00002d 0064 00002e 0020 00002f 0052 000030 0065 000031 0067 000032 0069 000033 0073 000034 0074 000035 0065 000036 0072 000037 0073 4 82 Syntax Description Example Eject Page in Listing page page The page directive produces a page eject in the listing file The page directive is not printed in the source listing but the assembler increments the line counter when it encounters it Using the page directive to divide the source listing into logical divisions improves program readability This example shows how the page directive causes the assembler to begin a new page of the source listing Source file title Page Directive Example i i H 5 page Listing file TMS320C55x COFF Assembler Version x xx Copyright c 2000 Texas Instruments Incorporated Page Directive Example PA
59. 0046 0047 0048 0049 004A 004B 004C 004D 004E 004F 0050 005F Description Reserved Transition register Block repeat counter register Block repeat save register Computed single repeat register Repeat start address register RSAO Repeat end address register REAO Repeat start address register RSA1 Repeat end address register REA1 Single repeat counter register Interrupt mask register 1 Interrupt flag register 1 Debug interrupt register 0 Debug interrupt register 1 Interrupt vector pointer for DSP Interrupt vector pointer for HOST Status register 2 System stack pointer Data stack pointer High part of extended stack pointers High part of the extended CDP Reserved Syntax Description Example Terminate Local Symbol Block newblock newblock The newblock directive undefines any local labels currently defined Local labels by nature are temporary the newblock directive resets them and terminates their scope A local label is a label in the form n where n is a single decimal digit A local label like other labels points to an instruction word Unlike other labels local labels cannot be used in expressions Local labels are not included in the symbol table After a local label has been defined and perhaps used you should use the newblock directive to reset it The text data and named sections also reset local labels Local labels that are defined within an include file are not valid out
60. 0bj b3 0bj o bpart out lnk55 b r dl obj d2 0bj d3 0bj o dpart out The h option guarantees that bpart out and dpart out do not have global symbols and therefore that two distinct versions of GLOB exist The r option is used to allow bpart out and dpart outto retain their relocation entries These two partially linked files can then be linked together safely with the following command lnk55 bpart out dpart out o system out 9 4 8 Define Heap Size heap constant Option The C compiler uses an uninitialized section called sysmem for the C runtime memory pool used by malloc You can set the size of this memory pool at link time by using the heap option Specify the size in bytes as a constant immediately after the option lnk55 heap 0x0400 defines a heap size The linker creates the sysmem section only if there is a sysmem section in one of the input files Linker Options The linker also creates a global symbol _ SYSMEM SIZE and assigns it a value equal to the size of the heap The default size is 2000 bytes For more information about linking C code see Section 9 18 Linking C Code on page 9 69 9 4 9 Alter the Library Search Algorithm l Option i Option and C55X C DIR C DIR Environment Variables Usually when you want to specify a library as linker input you simply enter the library name as you would any other input filename the linker looks for the library in the current directory For exa
61. 1 4 1 16 Sym i 2 pA ply 16 sym _p 3 4 1 16 line 3 SP 1 T1 SP 0 TO line 5 SP 3 1 line 6 SP 2 1 AR1 T1 AR2 SP 2 TC1 AR2 gt AR1 if TCI goto L2 branch occurs line 7 T1 SP 0 ACO T1 SP 3 SP 3 ACO SP 2 SP 2 1 AR2 SP 1 AR1 SP 2 TC1 AR1 lt AR2 if TCl1 goto L1 branch occurs line TO line SP 8 9 endfunc SP 3 SP 5 return return occurs 9 000000000n 5 Symbolic Debugging Directives ine Create a Line Number Entry ine ine number address The line directive creates a line number entry in the object file Line number entries are used in symbolic debugging to associate addresses in the object code with the lines in the source code that generated them The line directive has two operands The ine number indicates the line of the C source that generated a portion of code Line numbers are relative to the beginning of the current function This is a required parameter Syntax Description L1 L1 Example C source i p for p 1 The address is an expression that is the address associated with the line number This is an optional parameter if you don t specify an address the assembler will use the current SPC value The line directive is followed by the assembly language source statements that are generated by the indicated line of C source
62. 100 unsigned defined usect directive 4 103 usect section Index 15 Index ushort directive 4 13 width directive 4 66 utag symbolic debugging directive listing control 4 18 uword directive widths See memory widths wmsg directive 4 25 5 19 V listing control word defined v archiver option word addressing var directive 4 106 5 13 word alignment listing control 4 18 word directive 4 13 0 variable length instructions limiting listing with option directive 4 19 4 81 variables local substitution symbols used as 5 13 ARITA TI SH CHOR 7 18 Vectors 9 34 X vli_off directive 4 107 Vli on directive 4 107 e archiver command assembler option 3 6 hex conversion utility option 13 42 w linker option linker option W MEMORY attribute X MEMORY attribute well defined expression Xfloat directive defined xlong directive described 3 33 xref55 command Index 16
63. 12 1 Invoking the Disassembler 0 00 cece eee eee es 12 2 12 2 Disassembly Examples 12 1 Invoking the Disassembler 12 1 Invoking the Disassembler Before using the disassembler consider using the assembler s s option or the shell s as option to generate your object files When files are assembled with this option local symbols are then included in the disassembly creating a more comprehensive listing To invoke the disassembler enter the following dis55 options input filename output filename dis55 is the command that invokes the disassembler input filename is an object file obj or an executable file out If you omit the input filename the disassembler prompts for a file If you do not specify a file extension the disassembler searches for filename filename out and then file name obj in that order output filename is the name of the disassembly listing file If you omit the output filename the listing is sent to standard output options identifies the disassembler options you want to use Options are not case sensitive and can appear anywhere on the command line following the invocation Precede each option with a hyphen The disassembler options are as follows a displays the branch destination address along with labels b displays data in bytes By default data is displayed in words C includes a COFF file description at the top of the listing T
64. 17 symbolic information Struct directive structure A 24 Bg definitions Index 14 subsections defined initialized overview uninitialized 5 substitution symbols arithmetic operations on assigning character strings to built in functions 5 8 described B3 directives that define 5 7 to 5 8 expansion listing 4 19 4 88 forcing substitution 5 11 in macros 5 6lto maximum number per macro passing commas and semicolons recursive substitution subscripted substitution 5 1 2 to 5 13 var macro directive sym symbolic debugging directive B 11 symbol defined definitions names symbol table creating entries 2 20 defined described entry from sym directive B 11 index placing unresolved symbols in special symbols used in A 15 to A 16 stripping entries structure and content A 13 to A 26 values symbolic constants symbolic debugging b linker option defined disable merge for linker 9 10 enumeration definitions B 9 file identification function definitions line number entries B 7 member definitions producing error messages in macros s assembler option stripping symbolic information structure definitions 5 19 symbolic debugging continued symbols table structure and content to A 26 union definitions Symbols assembler defined assigning values to rm 4 22 4 23 4 86 4 92 4100 at link ne p 59 b 59t0 9 64 attributes case character strings cros
65. 3 1 Assembler Development Flow C source files pem Assembler source co Macro source files aone Macro library Library build utility Runtime support library CB Library of object files Linker li Debugging tools Executable COFF file Hex conversion utility EPROM programmer Assembler Description 3 3 Invoking the Assembler 3 3 Invoking the Assembler To invoke the assembler enter the following masm55 input file object file listing file options asm55 input file object file listing file options masm55 asm55 input file object file listing file options are the commands that invoke the assembler masm55 invokes the mnemonic assembler asm55 invokes the algebraic assembler names the assembly language source file If you do not supply an extension the assembler uses the default extension asm unless the f assembler option is used If you do not supply an input filename the assembler prompts you for one names the C55x object file that the assembler creates If you do not supply an extension the assembler uses obj as a default If you do not supply an object file the assembler creates a file that uses the input filename with the obj extension names the optional listing file that the assembler can create Lj If you do not supply a listing
66. 4 1 Target Width 13 4 2 Data Width Understanding Memory Widths Target width is the unit size in bits of raw data fields in the COFF file This corresponds to the size of an opcode on the target processor The width is fixed for each target and cannot be changed The TMS320C55x targets have a width of 16 bits Data width is the logical width in bits of the data words stored in a particular section of a COFF file Usually the logical data width is the same as the target width The data width is fixed at 16 bits for the TMS320C55x and cannot be changed 13 4 3 Memory Width Memory width is the physical width in bits of the memory system Usually the memory system is physically the same width as the target processor width a 16 bit processor has a 16 bit memory architecture However some applica tions require target words to be broken up into multiple consecutive narrower memory words Moreover with certain processors like the C55x the memory width can be narrower than the target width The hex conversion utility defaults memory width to the target width in this case 16 bits You can change the memory width by _j Using the memwidth option This changes the memory width value for the entire file Setting the memwidth parameter of the ROMS directive This changes the memory width value for the address range specified in the ROMS directive and overrides the memwidth option for that range See Section 13 5 The
67. 4 18 to 4 19 creating ps the I option defined E 4 format 36 to 3 39 list options 4 81 macro listing page eject page length page width 4 66 substitution symbols 4 88 suppressing tab size title little endian ordering Ink55 command load address i B i described referring to m a label p 42 to 9 44 load linker keyword 2 17 p 41 to 5 43 loader defined loading a program local labels 8 28 logical operators long directive SEES limiting iir with option directive 4 18 4 81 loop directive 4 21 4 71 use in macros 5 15 m linker option m1 hex conversion utility option m2 hex conversion utility option m3 hex conversion utility option ma assembler option PE GEE Index 9 Index macro comments conditional ey 5 15 to 5 16 defined defining 53 described directives summary disabling macro expansion list Eg 4 18 1 81 formatting the output listing labels to libraries 5 14 mlib assembler directive 3 14 mlist assembler directive 4 75 parameters 5 6 to 5 13 producing messages recursive 5 22 to 5 24 substitution symbols 5 6 to 5 13 using a macro 5 2 macro call defined macro definition defined macro directive 4 72 summary table macro expansion defined macro library defined E 5 magic number defined main malloc map file creating defined example masm55 command math functions mb assembler option mc assembler option
68. 4 40 member defined member symbolic debugging directive B 8 memory allocation default P 13 described p 55 to g 57 map defined described model 9 28 named 9 37 pool C language o 12 p 7o Index 10 memory continued unconfigured 9 28 widths described Tapes TF ordering memory words ROM width 13 10 to target width 13 9 word ordering 13 13 to 13 14 MEMORY linker decia default model described A to overlay pages 9 50 to Bu PAGE option to 9 30 syntax 9 28 to memory modes ARMS mode 3 13 C54x compatibility mode CPL mode messages assembler C htotc 20 linker oE D 1 mexit directive migrating a C54x system to C55x 7 1 to ml assembler option mlib directive use in macros mlist directive 4 75 listing control 4 18 4 45 use in macros mmregs directive mmsg directive listing control 4 18 4 45 mnemonic defined field mnolist directive listing control 4 18 4 45 use in macros model statement defined Motorola S object format 13 40 mv assembler option 4 107 mw assembler option name MEMORY specification 9 30 named sections 2 7 COFF format A 3 defined sect directive usect directive nested macros 5 22 newblock directive 4 24 4 79 nolist directive 4 18 4 67 same effect with option directive 4 18 NOLOAD section 9 58 noremark directive 4 80 o linker option object code source li
69. 8 Separate Load Addresses for UNION Sections UNION run RAM textl load text2 load ROM filel obj text ROM file2 0bj text Linker Description 9 45 Using UNION and GROUP Statements Figure 9 4 Memory Allocation Shown in Example 9 7 and Example 9 8 Allocation for Example 9 7 Allocation for Example 9 8 RAM text 2 run Sections can run L n asaunion This is runtime allocation only Copies at runtime text 1 run Wd ROM text 1 load text Sections cannot J load as a union text 2 load Since the text sections contain data they cannot oad as a union although they can be run as a union Therefore each requires its own load address If you fail to provide a load allocation for an initialized section within a union the linker issues a warning and allocates load space anywhere it fits in configured memory Uninitialized sections are not loaded and do not require load addresses The UNION statement applies only to allocation of run addresses so it is redundant to specify a load address for the union itself For purposes of allocation the union is treated as an uninitialized section any one allocation specified is considered a run address and if both are specified the linker issues a warning and ignores the load address The alignment and
70. 8 Assembly Time Symbol Directives 0 4 9 Miscellaneous Directives oo ss 4 10 Directives Reference i Nacrolanguage se c PME Describes macro directives substitution symbols used as macro parameters and how to create macros Sl JUSING Matos on TA A bia eee dae Pde he Vee es 5 2 Defining Macros iioi tb cease dew ede probed ee DER DE ba ad eee e Rad 5 3 Macro Parameters Substitution Symbols i 5 3 1 Directives That Define Substitution Symbols i 5 3 2 Built In Substitution Symbol Functions 00 cece cece ences 5 8 5 3 3 Recursive Substitution Symbols i 5 3 4 Forced Substitution sci 3 vi aed er cued aee Deemed ad 5 3 5 Accessing Individual Characters of Subscripted Substitution Symbols 5 3 6 Substitution Symbols as Local Variables in Macros 0005 5 4 Macro Libraries uis e takasa Boks des a de oiia e RR URP RUR aiaia CR RURUR aa ia 5 5 Using Conditional Assembly in Macros i 5 6 Using Labels in Ma 5 7 Producing Messages in Macros sa ed i kannike aiias 5 8 Formatting the Output Listing 0 cece eee tenes 5 9 Using Recursive and Nested Macros 0 0 cece cece teen sees 5 10 Macro Directives Summary 0 Running C54x Code on C55x 4 Describes how to assemble a C54x application for use on the C55x 6 1 Cb4xto C55x Development Flow i 6 1 1 Initializing the Stack Pointers i 6 1 2 Handling Differences in Memory Placement 0000 eee e eee ee 6 2 Understanding the Listing File
71. 8 Formatting the Output Bistingl esee 5 21 5 9 Using Recursive and Nested Macros eene 5 22 5 10 Macro Directives Summary ee 5 25 Using Macros 5 1 Using Macros Programs often contain routines that are executed several times Instead of repeating the source statements for a routine you can define the routine as a macro then call the macro in the places where you would normally repeat the routine This simplifies and shortens your source program If you want to call a macro several times but with different data each time you can assign parameters within a macro This enables you to pass different information to the macro each time you call it The macro language supports a special symbol called a substitution symbol which is used for macro parameters Using a macro is a three step process Step 1 Define the macro You must define macros before you can use them in your program There are two methods for defining macros Macros can be defined at the beginning of a source file or in a copy include file See Section 5 2 Defining Macros for more information Macroscan be defined in a macro library A macro library is a col lection of files in archive format created by the archiver Each member of the archive file macro library contains one macro definition corresponding to the member name You can access a macro library by using the mlib directive See Section 5 4 Macro Libraries on page 5 14
72. A source statement may produce more than one word of object code The assembler lists the SPC value and object code on a separate line for each additional word Each additional line is listed immediately following the source statement line Field 1 Source Statement Number Line Number The source statement number is a decimal The assembler numbers source lines as it encounters them in the source file some state ments increment the line counter but are not listed For example title statements and statements following a nolist are not listed The difference between two consecutive source line numbers indi cates the number of intervening statements in the source file that are not listed Include File Letter The assembler may precede a line with a letter the letter indicates that the line is assembled from an included file Nesting Level Number The assembler may precede a line with a number the number indi cates the nesting level of macro expansions or loop blocks Field 2 Section Program Counter This field contains the section program counter SPC value which is hexadecimal All sections text data bss and named sections maintain separate SPCs Some directives do not affect the SPC and leave this field blank Source Listings Field 3 Object Code This field contains the hexadecimal representation of the object code All machine instructions and directives use this field to list object code This field also ind
73. Addresses in Linker Command File All addresses and sizes supplied in the linker command file should be byte addresses for both code and data sections Linker command files are ASCII files that contain one or more of the following Input filenames which specify object files archive libraries or other command files If a command file calls another command file as input this statement must be the ast statement in the calling command file The linker does not return from called command files DD Linker options which can be used in the command file in the same manner that they are used on the command line The MEMORY and SECTIONS linker directives The MEMORY directive defines the target memory configuration The SECTIONS directive controls how sections are built and allocated Assignment statements which define and assign values to global symbols To invoke the linker with a command file enter the Ink55 command and follow it with the name of the command file Ink55 command filename The linker processes input files in the order that it encounters them If the linker recognizes a file as an object file it links it Otherwise it assumes that a file is a command file and begins reading and processing commands from it Command filenames are case sensitive regardless of the system used Linker Command Files Example 9 1 shows a sample linker command file called link cmd Subsection 2 3 2 Placing Sections in the M
74. B ISR1 00000a 0000 20 00000c 6A00 INT2 B ISR2 00000e 0000 21 22 23 000000 Sect ints 24 000000 6A00 TINT B time 000002 0000 25 000004 6A00 RINT B rcv 000006 0000 26 000008 6A00 XINT B xmt 00000a 0000 27 00000c 6A00 USER B proc 00000e 0000 28 29 Initialize processor 30 34i 000010 init initmac initialize macro 000010 4693 BSET 49 ST1 55 000012 7800 MOV 0 DP 000014 0000 000016 7600 MOV 55 ACO 000018 3708 00001a 46B2 BCLR 11 ST1_55 ERU Se 4 Field 1 Field 2 Field 3 Field 4 b Algebraic example Source Listings 1 global RSET INTO INT1 INT2 2 global TINT RINT XINT USER 3 global ISRO ISR1 ISR2 4 global time rcv xmt proc 5 6 initmac macro 7 initialize macro 8 bit ST1 ST1_SATD 1 disable oflow 9 DP O1FFH amp 0 lt lt 7 set dp 0 ACO 55 set ACO 1 bit ST1 ST1_INTM 0 enable ints 2 endm 3 4 Reset and interrupt vectors 5
75. D RE E 1 Defines terms and acronyms used in this book xiv 1 1 TMS320C55x Software Development Flow i 2 1 Partitioning Memory Into Logical Blocks i 2 2 Object Code Generated by the File in Example 2 1 00 00 eee eee eee 2 3 Combining Input Sections to Form an Executable Object Module 3 1 Assembler Development Flow 7 4 1 The space and bes Directives 0 cece eee eens 4 2 The field Directive ry 4 3 Initialization Directives se IRI RTE PENA EENEG 4 4 The align Directive 4 5 Allocating bss Blocks Within a Page i 4 6 The field Directive eene ese x ERE ede RU RR NER DRE RA 4 7 TheUsect Die 1 Runtime Environments for Ported C54x Code and Native C55x Code Archiver Development Flow i 1 Linker Development Flow se 8 9 9 2 Section Allocation Defined by Example 9 4 i 9 3 Runtime Execution of Example 9 6 i 9 4 Memory Allocation Shown in Example 9 7 and Example 9 8 9 9 9 1 5 Overlay Pages Defined by Example 9 11 and Example 9 12 6 RAM Model of Autoinitialization 7 ROM Model of Autoinitialization 0 1 Absolute Lister Development Flow DUCES TN MERETUR 10 9 10 8 module lst oc icu suus ceed ee eb edem e ed edem ded d d edo et dd 11 1 Cross Reference Lister Development Flow i 18 1 Hex Conversion Utility Development Flow sssssssesss I 13 2 Hex Conversion Utility Process Flow et 13 3 Data and Memory Widths pp 13 4 Data
76. Directives on page 4 22 Assembler Directives 4 69 long ulong xlong _ Initialize Long Word Example This example shows how the long and xlong directives initialize double words 1 000000 data 2 000000 0000 DAT1 long OABCDh A 100h g o 000001 ABCD 000002 0000 000003 0141 000004 0000 000005 0067 000006 0000 000007 006F 3 000008 0000 xlong DAT1 OAABBCCDDh 000009 0000 00000a AABB 00000b CCDD 4 00000c DAT2 4 70 Syntax Description Example Assign Character Strings to Substitution Symbols loop break endloop loop well defined expression break well defined expression endloop Three directives enable you to repeatedly assemble a block of code The loop directive begins a repeatable block of code The optional expression evaluates to the loop count the number of times to repeat the assembly of the code contained in the loop If there is no expression the loop count defaults to 1024 unless the assembler first encounters a break directive with an ex pression that is true nonzero or omitted The break directive is optional along with its expression When the expres sion is false 0 the loop continues When the expression is true nonzero or omitted the assembler breaks the loop and assembles the code after the endloop directive The endloop directive terminates a repeatable block of code it executes whenthe break directive is true nonzero or when number of loo
77. Example 2 2 symbol X is relocatable since it is defined in another module Symbol Y is relative to the PC and relocation is not necessary When the code is assembled X has a value of 0 the assembler assumes all undefined exter nal symbols have values of 0 The assembler generates a relocation entry for X The reference to X is an external reference indicated by the character in the listing Each section in a COFF object file has a table of relocation entries The table contains one relocation entry for each relocatable reference in the section The linker usually removes relocation entries after it uses them This prevents the output file from being relocated again if it is relinked or when it is loaded A file that contains no relocation entries is an absolute file all its addresses are absolute addresses If you want the linker to retain relocation entries in voke the linker with the r option Runtime Relocation 2 5 Runtime Relocation At times you may want to load code into one area of memory and run it in another For example you may have performance critical code in a ROM based system The code must be loaded into ROM but it would run faster in RAM The linker provides a simple way to handle this Using the SECTIONS directive you can optionally direct the linker to allocate a section twice first to set its load address and again to set its run address Use the load keyword for the load address and the run keyword f
78. If amacro is expanded more than once its labels are defined more than once Defining labels more than once is illegal The macro language provides a method of defining labels in macros so that the labels are unique Follow the label with a question mark and the assembler replaces the question mark with a unique number When the macro is expanded you will not see the unique number in the listing file Your label appears with the question mark as it did in the macro definition You cannot declare this label as global The maximum label length is shortened to allow for the unique suffix If the macro is expanded fewer than 10 times the maximum label length is 126 characters If the macro is expanded from 10 to 99 times the maximum label length is 125 The label with its unique suffix is shown in the cross listing file The syntax for a unique label is label Example 5 13 shows unique label generation in a macro Example 5 13 Unique Labels in a Macro a Mnemonic example cO 10 01 C0 PD ES a OO O ODGO OD 000 000 000 000 000 000 000 000 000 000 00 00 02 04 06 08 Oa Oc Oe 10 define macro MLAB macro AVAR BVAR find minimum MOV AVAR ACO SUB BVAR ACO ACO BCC M1 ACO lt 0 MOV BVAR ACO B M2 M1 MOV AVAR ACO M2 endm call macro MLAB 50 100 A064 MOV 50 ACO 7C00 SUB 100 AC0 ACO 6400 6320 BCC M1 ACO lt 0 7600 MOV 100 ACO 6408 4A02
79. Messages alignment for redefined Description More than one alignment is supplied for a section attempt to decrement DOT Description A statement such as value is supplied this is illegal Assignments to dot can be used only to create holes bad fill value Description The fill value must be a 16 bit constant binding address for section is outside all memory on page Description Not every section falls within memory configured with the MEMORY directive Action If you are using a linker command file check that MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory binding address for section overlays at Description Two sections overlap and cannot be allocated Action If you are using a linker command file check that MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory binding address for redefined Description More than one binding value is supplied for a section binding address incompatible with alignment for section Description The section has an alignment requirement from an align directive or previous link The binding address violates this requirement blocking for must be a power of 2 Description Section blocking is not a power of 2 Action Make sure that in hexadecimal all powers of 2 consist of the integers 1
80. Names as Global Symbols Syntax mmregs Description The mmregs directive defines global symbolic names for the C55x registers and places them in the global symbol table It is equivalent to executing ACOL set 8 ACOH set 9 etc The symbols are local and absolute Using the mmregs directive makes it unnecessary to define these symbols Table 4 2 Memory Mapped Registers Name IERO IFRO STO ST1 ST3 STO ST1 ACOL ACOH ACOG AC1L AC1H AC1G T3 TRNO ARO AR1 AR2 ARS AR4 ARS AR6 AR7 Hexadecimal Address 0000 0001 0002 0003 0004 0005 0006 0007 0008 0009 000A 000B 000C 000D 000E 000F 0010 0011 0012 0013 0014 0015 0016 0017 Description Interrupt enable register Interrupt flag register For native C55x code that accesses STO For native C55x code that accesses ST1 For native C55x code that accesses ST3 Reserved For C54x code that accesses STO For C54x code that accesses ST1 Accumulator ACO Accumulator AC1 Temporary register T3 Transition register Auxiliary register Auxiliary register Auxiliary register Auxiliary register Auxiliary register Auxiliary register Auxiliary register Auxiliary register Table 4 2 Memory Mapped Registers Continued Name SP BK03 BRCO RSAOL REAOL PMST XPC TO T1 T2 T3 AC2L AC2H AC2G CDP AC3L AC3H AC3G DPH DP PDP BK47 BKC BSA01 BSA23 BSA45 BSA67 BSAC Assign Memory Mapped Register Names as G
81. O If a section must start on a specific address use binding instead of named memory Linker Description 9 37 The SECTIONS Directive 9 9 3 3 Alignment and blocking You can tell the linker to place an output section at an address that falls on an n byte boundary where n is a power of 2 For example text load align 128 allocates text so that it falls on a 128 byte boundary Blocking is a weaker form of alignment that allocates a section anywhere within a block of size n If the section is larger than the block size the section will begin on that boundary As with alignment n must be a power of 2 For example bss load block 0x80 allocates bss so that the section either is contained in a single 128 byte page or begins on a page You can use alignment or blocking alone or in conjunction with a memory area but alignment and blocking cannot be used together 9 9 3 4 Specifying input sections An input section specification identifies the sections from input files that are combined to form an output section The size of an output section is the sum of the sizes of the input sections that comprise it The linker combines input sections by concatenating them in the order in which they are specified unless alignment or blocking is specified for any of the input sections If alignment or blocking is specified for any input section the input sections within an output section are ordered as follows 1 all aligned se
82. RAE IRURE IRR ea eee aden beara 13 5 1 When to Use the ROMS Directive i 13 5 2 An Example of the ROMS Directive ee 13 5 3 Creating a Map File of the ROMS Directive ii The SECTIONS Directive se rey 0 0 teeta Output Filenaities cien irae rem Pace Ohba Reda Oe dow Een R Eod eee 13 7 1 Assigning Output Filenames i Image Mode and the fill Option pp 19 8 1 The image Option usce ee need akan caw i eo awl ee 13 8 2 Specifying a Fill Value siz sesane araa ae aioi aiak es 13 8 8 Steps to Follow in Image Mode pp Building a Table for an On Chip Boot Loader i 13 9 1 Description of the Boot Table i 13 9 2 The Boot Table Format 0 02 cece eee 13 9 3 How to Build the Boot Table i 13 9 4 Booting From a Device Peripheral i 13 9 5 Setting the Entry Point for the Boot Table 0 000 cece eee 13 9 6 Using the C55x Boot Loader i Controlling the ROM Device Address pp 13 10 1 Controlling the Starting Address pp 13 10 2 Controlling the Address Increment Index i 13 10 3 The byte Option a 13 10 4 Dealing With Address Holes i Description of the Object Formats 0 13 11 1 ASCII Hex Object Format a Option i 13 11 2 Intel MCS 86 Object Format Ci Option pp 13 11 3 Motorola Exorciser Object Format m1 m2 m3 Options 13 11 4 Texas Instruments SDSMAC Object Format t Option 13 11 5 Extended Tektronix Object Format x Option 0000000 Hex Conversion Utility Error Messages
83. ROMS directive and you have included a list of files files on that range the utility takes the filename from the list For example assume that the target data is 16 bit words being converted to two files each eight bits wide To name the output files using the ROMS directive you could specify ROMS RANGE1 romwidth 8 files xyz bO0 xyz bl The utility creates the output files by writing the least significant bits LSBs to xyz b0 and the most significant bits MSBs to xyz b1 It looks for the o options You can specify names for the output files by using the o option If no filenames are listed in the ROMS directive and you use o options the utility takes the filename from the list of o options The following line has the same effect as the example above using the ROMS directive o Xyz b0 o xyz bl Note that if both the ROMS directive and o options are used together the ROMS directive overrides the o options Hex Conversion Utility Description 13 23 Output Filenames 3 Itassigns a default filename If you specify no filenames or fewer names than output files the utility assigns a default filename A default filename consists of the base name from the COFF input file plus a 2 to 3 character extension The extension has three parts a A format character based on the output format a for ASCII Hex i for Intel t for TI Tagged m for Motorola S x for Tektronix b The range num
84. a symbol s name _j Ifthe symbol name is eight characters or less this field has type character The name is padded with nulls if necessary and stored in bytes 0 7 L Ifthe symbol name is greater than 8 characters this field is treated as two long integers The entire symbol name is stored in the string table Bytes 0 3 contain 0 and bytes 4 7 are an offset into the string table A 7 3 String Table Structure Symbol names that are longer than eight characters are stored in the string table The field in the symbol table entry that would normally contain the sym bol s name contains instead a pointer to the symbol s name in the string table Names are stored contiguously in the string table delimited by a null byte The first four bytes of the string table contain the size of the string table in bytes thus offsets into the string table are greater than or equal to four Figure A 9 is a string table that contains two symbol names Adaptive Filter and Fourier Transform The index in the string table is 4 for Adaptive Filter and 20 for Fourier Transform Figure A 9 String Table Common Object File Format A 17 Symbol Table Structure and Content A 7 4 Storage Classes Table A 11 Mnemonic C NULL C AUTO C EXT C STAT C REG C EXTREF C LABEL C ULABEL C MOS C ARG C_STRTAG C_MOU N O Oo A C Byte 16 of the symbol table entry indicates the storage class of the symbol Storage classes refer
85. add3 add3 asm You can access the macro library by using the mlib assembler directive de scribed on page 4 73 The syntax is mlib macro library filename When the assembler encounters the mlib directive it opens the library and creates a table of the library s contents The assembler enters the names of the individual members within the library into the opcode tables as library entries this redefines any existing opcodes or macros that have the same name If one of these macros is called the assembler extracts the entry from the library and loads it into the macro table The assembler expands the library entry in the same way it expands other macros You can control the listing of library entry expansions with the mlist directive For more information about the mlist directive see Section 5 8 Formatting the Output Listing on page 5 21 Only macros that are actually called from the library are extracted and they are extracted only once You can use the archiver to create a macro library by simply including the desired files in an archive A macro library is no different from any other archive except that the assembler expects the macro library to contain macro definitions The assembler expects only macro definitions in a macro library putting object code or miscellaneous source files into the library may produce undesirable results Using Conditional Assembly in Macros 5 5 Using Conditional Assembly in Macros
86. allocated in RAM file1 0bj and file2 obj aligned on 16 byte boundary The data section combines the data sections from file1 obj and file2 obj The linker will place it any where there is space for it in RAM in this illustration and align it to a 16 byte boundary The text section combines the text sections from file1 obj and file2 obj The linker combines all sec tions named text into this section The application must relocate the section to run at 0800h allocated in ROM allocated in ROM The const section combines the const sections from file1 obj and file2 obj FF80h vectors bound at OFF80h The vectors section is composed of the intvec1 section from t1 obj and the intvec2 section from t2 obj 9 34 9 9 3 Allocation The SECTIONS Directive The linker assigns each output section two locations in target memory the location where the section will be loaded and the location where it will be run Usually these are the same and you can think of each section as having only a single address In any case the process of locating the output section in the target s memory and assigning its address es is called allocation For more information about using separate load and run allocation see Section 9 10 Specifying a Section s Runtime Address on page 9 41 If you do not tell the linker how a section is to be allocated it uses a default algorithm to all
87. allow you to manipulate sections with greater precision 9 9 1 Default Configuration If you do notspecify a SECTIONS directive the linker uses a default algorithm for combining and allocating the sections Section 9 13 Default Allocation Algorithm on page 9 55 describes this algorithm in detail 9 9 2 SECTIONS Directive Syntax The SECTIONS directive is specified in a command file by the word SECTIONS uppercase followed by a list of output section specifications enclosed in braces The general syntax for the SECTIONS directive is SECTIONS name property property property name property property property name property property property The SECTIONS Directive Each section specification beginning with name defines an output section An output section is a section in the output file After the section name is a list of properties that define the section s contents and how the section is allocated The properties may be separated by optional commas Possible properties for a section are d Load allocation which defines where in memory the section is to be loaded Syntax load allocation or allocation or gt allocation Run allocation which defines where in memory the section is to be run Syntax run allocation or run gt allocation Input sections which define the input sections that constitute the output section Syntax input sections Section type which defines
88. an output section but are not explicitly specified by the SECTIONS directive they are automatically linked in at the end of the output section For example if the linker found more text sections in the preceding example and these text sections were not specified anywhere in the SECTIONS directive the linker would concatenate these extra sections after f4 obj sec2 The specifications in Example 9 5 are actually a shorthand method for the following SECTIONS text text data data bss bss The specification text means the unallocated text sections from all the input files This format is useful when You want the output section to contain all input sections that have a specified name but the output section name is different than the input sections name You want the linker to allocate the input sections before it processes addi tional input sections or commands within the braces Linker Description 9 39 The SECTIONS Directive The following example illustrates the two purposes above SECTIONS text abc obj xqt text data data fil obj table In this example the text output section contains a named section xqt from file abc obj which is followed by all the text input sections The data section contains all the data input sections followed by a named section table from the file fil obj This method includes all the unallocated s
89. assembled the assembler searches its list of holes left by previous bss directives and tries to allocate the current block into one of the holes This is the standard procedure whether the contiguous al location option has been specified or not Rule 2 Ifthe assembler does not find a hole large enough to contain the requested space it checks to see whether the blocking option is re quested _ If you do not request blocking the memory is allocated at the current SPC L If you request blocking the assembler checks to see whether there is enough space between the current SPC and the page boundary If there is not enough space the assembler creates another hole and allocates the space at the beginning of the next page Assembler Directives 4 31 DSS Reserve Space in the bss Section The blocking option allows you to reserve up to 128 words in the bss section and ensure that they fit on one page of memory Of course you can reserve more than 128 words at atime but they cannotfit on a single page The follow ing example code reserves two blocks of space in the bss section memptr bss A 64 1 memptrl bss B 70 1 Each block must be contained within the boundaries of a single page after the first block is allocated however the second block cannot fit on the current page As Figure 4 5 shows the second block is allocated on the next page Figure 4 5 Allocating bss Blocks Within a Page Memory 0a Mem
90. assembled when the copy include or mlib directive is encountered 2 Any directories named with the i assembler option 3 Any directories set with the environment variables C55X A DIR and A DIR You can augment the assembler s directory search algorithm by using the i assembler option or the C55X A DIR and A DIR environment variables Using the i Assembler Option The i assembler option names an alternate directory that contains copy include files or macro libraries The format of the i option is as follows masm55 ipathname source filename Each i option names one pathname There is no limit to the number of paths that you can specify In assembly source you can use the copy include or mlib directive without specifying path information If the assembler doesn t find the file in the directory that contains the current source file it searches the paths designated by the i options For example assume that a file called source asm is in the current directory source asm contains the following directive statement COPY copy asm Naming Alternate Files and Directories for Assembler Input Assume that the file is stored in the following directory Windows c tools files copy asm UNIX tools files copy asm Operating System Enter Windows masm55 ic tools files source asm UNIX masm55 i tools files source asm The assembler first searches for copy asm in the current directory becau
91. changes the DP register s value If the assembler is not given any information on the value of the DP register it assumes the value is 0 when encoding direct memory operands The end directive terminates assembly It should be the last source statement of a program This directive has the same effect as an end of file DD The ivec directive is used to initialize the entries in the interrupt vector table The mmregs directive defines symbolic names for the memory mapped register Using mmregs is the same as executing a set for all memory mapped registers See Table 4 2 on page 4 76 for a list of memory mapped registers The newblock directive resets local labels Local labels are symbols of the form n or name They are defined when they appear in the label field Local labels are temporary labels that can be used as operands for jump instructions The newblock directive limits the scope of local labels by resetting them after they are used For more information about local labels see subsection 3 9 6 Local Labels on page 3 28 The noremark directive begins a block of code in which the assembler will suppress the specified assembler remark A remark is an informational assembler message that is less severe than a warning The sblock directive designates sections for blocking Blocking is an address alignment mechanism similar to page alignment but weaker In acode section blocked code is guaranteed not
92. consecutive words in the current section The pstring also has a width of 8 bits but packs one character per byte Each string is either DD An expression that the assembler evaluates and treats as an 8 or 16 bit signed number or A character string enclosed in double quotes Each character in a string represents a separate byte Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of string and pstring directives in a section that includes C55x instructions will likely lead to the generation of an invalid access to the data at execution Conse quently Texas Instruments highly recommends that these directives be issued only within data sections With pstring values are packed into words starting with the most significant byte of the word Any unused space is padded with null bytes The assembler truncates any values that are greater than 8 bits You may have up to 100 operands but they must fit on a single source statement line If you use a label it points to the location of the first word in a data section that is initialized Note that when you use string in a struct endstruct sequence string defines a member s size it does not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 Example 1 000000 2 000000 000001 000002 000003 3 000004 000005 000006 000007 4
93. consists of a start of file record data records and end of file record Each of the data records is made up of a series of small fields and is signified by a tag character The sig nificant tag characters are Tag Character Description K followed by the program identifier 7 followed by a checksum 8 followed by a dummy checksum ignored 9 followed by a 16 bit load address B followed by a data word four characters F identifies the end of a data record followed by a data byte two characters Figure 13 13 illustrates the tag characters and fields in Tl Tagged object format Figure 13 13 Tl Tagged Object Format Start of file Load record Program address Tag characters identifier F1 WAT I1 F1 F1 F1 F1 r1 F1 FI F1 F1 KO00COFFTOTI90000BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7EFS3DFE 37E Data records BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7EE PEE E EE EE BEEREREEEE E EM 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 for any data byte but none is required The checksum field which is preceded by the tag character 7 is a 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
94. copy statement for a second file word asm When it encounters the copy statement for word asm the assembler switches to word asm to continue copying and assembling Then the assembler returns to its place in byte asm to continue copying and assembling After completing assembly of byte asm the assembler returns to copy asm to assemble its re maining statement byte asm word asm first copy file second copy file In byte asm In word asm data data byte 32 1 A word OABCDh 56q copy word asm Back in byte asm byte 67h 3q Listing file 1 000000 data 2 000000 Space 29 3 copy byte asm A 1 In byte asm A 2 000001 data A 3 000002 0020 byte 32 1 A 000003 0042 A 4 copy word asm B 1 In word asm B 2 000004 data B 3 000004 ABCD word OABCDh 56q 000005 002E A 5 Back in byte asm A 5 000006 006A byte 67h 3q 4 5 Back in original file 6 000007 646F pstring done 000008 6E65 Read Source File copy include Example 2 In this example the include directive is used to read and assemble source statements from other files then the assembler resumes assembling into the current file The mechanism is similar to the copy directive except that state ments are not printed in the listing file include asm byte2 asm word2 asm source file first include file second include file data In byte2 asm In word2 asm Space 29 data data in
95. corrupt try reassembling it fail to read Description The file may be corrupt Action If the input file is corrupt try reassembling it fail to seek Description The file may be corrupt Action If the input file is corrupt try reassembling it Linker Error Messages fail to skip Description The file may be corrupt Action If the input file is corrupt try reassembling it fail to write Description The disk may be full or protected Action Check disk volume and protection file has no relocation information Description You have attempted to relink a file that was not linked with r file is of unknown type magic number Description The binary input file is not a COFF file fill value for redefined Description More than one fill value is supplied for an output section Indi vidual holes can be filled with different values with the section definition i path too long Description The maximum number of characters in an i path is 256 illegal input character Description There is a control character or other unrecognized character in the command file illegal memory attributes for Description The attributes are not some combination of R W and X Linker Error Messages D 7 Linker Error Messages D 8 illegal operator in expression Description Review legal expression operators illegal option within SECTIONS Description The 4
96. defined again or automatically generated Local labels cannot be defined by directives A local label can be undefined or reset in one of four ways Example 3 3 demonstrates the n form of local labels This example assumes J By using the newblock directive By changing sections using a sect text or data directive By entering an include file specifying the include or copy directive LJ By leaving an include file reaching the end of an included file that symbols ADDRA ADDRB ADDRC have been defined previously Example 3 3 n Local Labels a Code that uses a local label legally Labell 1 2 1 MOV ADDRA ACO Load Address A to ACO SUB ADDRB ACO ACO Subtract Address B BCC 1 ACO 0 If lt 0 branch to 1 MOV ADDRB ACO otherwise load ADDRB to ACO B 2 and branch to 2 MOV ADDRA ACO 1 load ADDRA to ACO ADD ADDRC ACO ACO 2 add ADDRC newblock Undefine 1 so it can be used again BCC S1 ACO lt 0 If less than zero branch to 1 MOV ACO ADDRC Store ACO low in ADDRC NOP Symbols b Code that uses a local label illegally Labell OV ADDRA ACO SUB ADDRB ACO ACO BCC 1 ACO lt 0 OV ADDRB ACO B 2 1 OV ADDRA ACO 2 ADD ADDRC ACO ACO BCC 1 ACO lt 0 OV ACO ADDRC 1 OP Wrong 1 is multiply defined Local labels are especially useful in macros If a macro contains a normal label andis called more than
97. do not initialize memory when they are part of a struct endstruct sequence rather they define a member s size For more information about the struct endstruct directives see Section 4 8 Assembly Time Symbol Directives on page 4 22 Figure 4 3 compares the byte int long xlong float xfloat word and string directives For this example assume that the following code has been assembled 1 000000 data 2 000000 OOAA byte OAAh OBBh 000001 OOBB 3 000002 OCCC word OCCCh 4 000003 OEEE xlong OEEEEFFFh 000004 EFFE 5 000006 EEEE long OEEEEFFFFh 000007 FFFE 6 000008 DDDD int ODDDDh 7 000009 3FFE xfloat 1 99999 00000a FFAC 8 00000c 3FFE float 1 99999 00000d FFAC 9 00000e 0068 string help 00000f 0065 000010 006c 000011 0070 Directives That Initialize Constants Figure 4 3 Initialization Directives Word Code 15 0 15 0 0 1 0 O0 A A 0 0 B B byte OAAh OBBh 2 0 C C C word OCCCh 3 4 0 E E E E F F F xlong OEEEEFFFh 6 7 E E E E E FF F long EEEEFFFFh 8 D D D D int DDDDh 9 a 3 F F F F F A C xfloat 1 99999 c d oF F F F F A C float 1 99999 e f 0 0 6 8 0 0 6 25 string help h e 10 11 0 0 6 C 0 0 7 0 p Assembler Directives 4 15 Directives That Align the Section Program Counter 4 4 Directives That Align the Section Program Counter The align directive aligns the SPC at a byte bo
98. environment is already in place However when shifting from one kind of code to the other it is important to be aware of the status bit and register settings that make up a particular environment The following CPU environment is expected upon entry to a ported C54x function Lj 32 bit stack mode The SP and SSP must be initialized to point into memory reserved for a stack See Section 6 1 1 nitializing the Stack Pointers on page 6 2 Migrating a C54x System to a C55x System 7 5 Using Ported C54x Functions with Native C55x Functions 7 2 2 7 2 3 The status bits must be set as follows Status bit C54CM M40 ARMS RDM ST2 7 0 circular addressing bits be set to 0 C55x Registers Used as Temporaries The upper bits of addressing registers DPH CDPH ARnH SPH must The BSAxx registers must be set to 0 The following C55x registers may be used as temporaries in one to many mappings generated by masm55 TO T1 AC2 CDP CSR STO 55 TC1 bit only ST2 55 O O O C O O L Interrupt routines using these registers must save and restore them For more information see Section 7 1 2 Handling Interrupt Service Routines on page 7 3 Native C55x code that calls ported C54x code must account for the possibility that ported code may overwrite these registers C54x to C55x Register Mapping The following C54x registers map to C55x registers as shown below
99. expressions Built in Functions Table 3 2 Assembler Built In Math Functions Continued Function pow expr1 expr2 round expr sgn expr sin expr sinh expr sqrt expr tan expr tanh expr trunc expr Description raises expr1 to the power expr 2 returns the result of expr rounded to the nearest integer returns the sign of expr returns the sine of expr as a floating point value returns the hyperbolic sine of expr as a floating point value returns the square root of expr as a floating point value returns the tangent of expr as a floating point value returns the hyperbolic tangent of expr as a floating point value returns the result of expr rounded toward zero Assembler Description 3 35 Source Listings 3 12 Source Listings A source listing shows source statements and the object code they produce To obtain a listing file invoke the assembler with the lowercase L option Two banner lines a blank line and a title line are at the top of each source list ing page Any title supplied by a title directive is printed on the title line a page number is printed to the right of the title If you don t use the title directive the name ofthe source file is printed The assembler inserts a blank line below the title line Each line in the source file may produce a line in the listing file that shows a source statement number an SPC value the object code assembled and the Source statement
100. flags for special section types Syntax type COPY or type DSECT or type NOLOAD For more information on section types see Section 9 14 Special Section Types DSECT COPY and NOLOAD on page 9 58 Fill value which defines the value used to fill uninitialized holes Syntax fill value or name value For more information on creating and filling holes see Section 9 16 Creating and Filling Holes on page 9 63 Example 9 4 shows a SECTIONS directive in a sample linker command file Figure 9 2 shows how these sections are allocated in memory Linker Description 9 33 The SECTIONS Directive Example 9 4 The SECTIONS Directive J KOECKCECK Ck kk A kk kk kk ke ke ke ke ke ke e ke e e e ee e e x x f Sample command file with SECTIONS directive is d 8K HK Ck kk kk kk Ck Ck kk Ck kk kk kk kk kk kk ke ko ke ke ke ke ke ke e e e ee e e x x f Filel obj file2 0bj Input files o prog out Options SECTIONS p directive cen sane texti load ROM run 800h const load ROM pssi load RAM vectors load FF80h section pue tl obj intvecl specifications t2 0bj intvec2 endvec L data align 16 Figure 9 2 shows the five output sections defined by the sections directive in Example 9 4 vectors text const bss and data Figure 9 2 Section Allocation Defined by Example 9 4 00h The bss section combines the bss sections from
101. following directives format the listing file You can use the drnolist directive to suppress the printing of the following directives in the listing asg eval length mnolist var break fclist mlist sslist width emsg fcnolist mmsg ssnolist wmsg You can use the drlist directive to turn on the listing of these directives again The listing file contains a listing of false conditional blocks that do not gen erate code The fclist and fcnolist directives turn this listing on and off You can use the fclist directive to list false conditional blocks exactly as they appear in the source code This is the default behavior of the assembler You can use the fcnolist directive to list only the conditional blocks that are actually assembled The length directive controls the page length of the listing file You can use this directive to adjust listings for various output devices The list and nolist directives turn the output listing on and off You can use the nolist directive to stop the assembler from printing selected source statements in the listing file Use the list directive to turn the listing on again The listing file contains a listing of macro expansions and loop blocks The mlist and mnolist directives turn this listing on and off You can use the mlist directive to print all macro expansions and loop blocks to the listing the default behavior of the assembler and the mnolist directive to suppress thi
102. if you don t request a listing file when you invoke the assembler the assembler ignores the list directive This example shows how the copy directive inserts source statements from another file The first time this directive is encountered the assembler lists the copied source lines in the listing file The second time this directive is encoun tered the assembler does not list the copied source lines because a nolist directive was assembled Note that the nolist the second copy and the list directives do not appear in the listing file Note also that the line counter is incremented even when source statements are not listed Assembler Directives 4 67 list nolist Start Stop Source Listing Source file copy copy2 asm Back in original file NOP nolist Copy copy2 asm list Back in original file string Done Listing file I COpy copy2 asm A 1 In copy2 asm copy file A 2 000000 data A 3 000000 0020 word 32 1 A 4 000001 0042 2 Back in original file 3 000000 text 4 000000 90 NOP 9 Back in original file 10 000004 data 11 000004 0044 String Done 000005 006F 000006 006E 000007 0065 4 68 Syntax Description Initialize Long Word long ulong xlong long value valuen ulong value valuen Xlong value value The long ulong and xlong directives place one or more 32 bit values into consecutive words in the current section The most si
103. in sections linker definition 9 62 bss section 4 8 defined holes initializing built in functions byte hex conversion utility option byte addressing byte directive limiting listing with option directive C memory pool 9 12 9 70 System stack 9 18 9 70 C assembler option disassembler option linker option C code linking 9 69 to 9 72 C compiler block definitions COFF technical details defined enumeration definitions file identification function definitions line number entries line number information linking 9 10 9 69 to 9 72 member definitions B 8 special symbols A 15 to A 16 storage classes structure definitions symbol table entries union definitions B 9 C DIR environment variable 9 13 to _c_int00 c54cm_off directive c54cm_on directive Index 4 to A 12 C54x code on C55x C55x temporary registers code example development flow 6 2 differences in interrrupt vector table initializing stack pointers listing file description 6 4 memory placement differences mixing ported C54x code with C55x 7 5 modifying interrupt service routines non portable C54x coding practices to register mapping 7 6 reserved C55x names RETE instructions RPT differences running on C55x runtime environment status bit field mapping switching runtime environments unsupported C54x hardware features 7 19 C54x compatibility mode 3 11 C55X A DIR environmen
104. indicates a power of 10 These are examples of valid constants 3 0 3 14 3 0 314e13 314 59e 2 Assembler Description 3 23 Character Strings 3 8 Character Strings 3 24 A character string is a string of characters enclosed in double quotes Double quotes that are part of character strings are represented by two consecutive double quotes The maximum length of a string varies and is defined for each directive that requires a character string Characters are represented internally as 8 bit ASCII characters These are examples of valid character strings sample program defines the 14 character string sample program PLAN C defines the 8 character string PLAN C Character strings are used for the following Filenames as in copy filename Section names as in sect section name Data initialization directives as in byte charstring Operands of string directives O O O L 3 9 Symbols 3 9 1 Labels Symbols Symbols are used as labels constants and substitution symbols A symbol name is a string of up to 200 alphanumeric characters A Z a z 0 9 and _ The first character in a symbol cannot be a number and symbols can not contain embedded blanks The symbols you define are case sensitive for example the assembler recognizes ABC Abc and abc as three unique symbols You can override case sensitivity with the c assembler option A symbol is valid only during the assem
105. is omitted When the loop is broken the assembler continues with the code after the endloop directive Example 5 10 Example 5 11 and Example 5 12 show the loop break endloop directives properly nested conditional assembly directives and built in substitution symbol functions used in a conditional assembly code block Macro Language 5 15 Using Conditional Assembly in Macros Example 5 10 The loop break endloop Directives asg ly Loop break x 10 if x 10 quit loop break with H expression eval x 41 x endloop Example 5 11 Nested Conditional Assembly Directives asg 1 x loop if x 10 if x 10 quit loop break f force break endif eval x 41 x endloop Example 5 12 Built In Substitution Symbol Functions Used in a Conditional Assembly Code Block ref OPZ fcnolist Double Add or Subtract DB macro ABC ADDR dst add or subtract double if symcmp ABC 0 ADD dbl ADDR dst add double elseif symcmp ABC 0 SUB dbl ADDR dst subtract double else emsg Incorrect Operator Parameter endif endm Macro Call DB OPZ ACO For more information about conditional assembly directives see Section 4 7 Conditional Assembly Directives on page 4 21 5 16 Using Labels in Macros 5 6 Using Labels in Macros All labels in an assembly language program must be unique including labels in macros
106. is the symbol s address in the current section before relo cation it specifies where a relocation must occur This is the address of the field in the object code that must be patched Following is an example of code that generates a relocation entry 2 global X 3 000000 6A00 B X 000001 0000 In this example the virtual address of the relocatable field is 0001 The symbol table index is the index of the referenced symbol In the preceding example this field would contain the index of X in the symbol table The amount of the relocation is the difference between the symbol s current address in the section and its assembly time address The relocatable field must be relocated by the same amount as the referenced symbol In the example X has a value of 0 before relocation Suppose X is relocated to address 2000h This is the relocation amount 2000h 0 2000h so the relocation field at address 1 is patched by adding 2000h to it You can determine a symbol s relocated address if you know which section it is defined in For example if X is defined in data and data is relocated by 2000h X is relocated by 2000h Common Object File Format A 9 Structuring Relocation Information If the symbol table index in a relocation entry is 1 OFFFFh this is called an internal relocation n this case the relocation amount is simply the amount by which the current section is being relocated The relocation type specifies the si
107. it in two con secutive words in the current section The most significant word is stored first The float directive automatically aligns to the nearest long word boundary and xfloat does not int uint half uhalf short ushort word and uword place one or more 16 bit values into consecutive words in the current section double and Idouble calculate the double precision 64 bit IEEE float ing point representation of one or more floating point values and store them in four consecutive words in the current section The double direc tive automatically aligns to the long word boundary long ulong and xlong place 32 bit values into two consecutive words in the current section The most significant word is stored first The long directive automatically aligns to a long word boundary and the xlong directive does not Assembler Directives 4 13 Directives That Initialize Constants 4 14 string and pstring place 8 bit characters from one or more character strings into the current section The string directive is similar to byte It places 8 bit characters into consecutive words in the current data section The pstring directive also has a width of 8 bits but packs one character per byte For pstring the last word in a string is padded with null charac ters 0 if necessary SSS LLLLLL LLL LLLA Zt 5 oo 50 5 0 Note These Directives in a struct endstruct Sequence The directives listed above
108. line number Index of next entry beyond this function Unused zero filled A 7 8 6 Arrays Symbol Table Structure and Content Table A 23 illustrates the format of auxiliary table entries for arrays Table A 23 Array Format for Auxiliary Table Entries Byte Number 0 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 Type Long integer Unsigned short integer Unsigned short integer Unsigned short integer Unsigned short integer Unsigned short integer Unsigned short integer A 7 8 7 End of Blocks and Functions Description Tag index line number declaration Size of array First dimension Second dimension Third dimension Fourth dimension Unused zero filled Table A 24 illustrates the format of auxiliary table entries for the ends of blocks and functions Table A 24 End of Blocks Functions Format for Auxiliary Table Entries Byte Number 0 3 4 5 6 17 Type Unsigned short integer Description Unused zero filled C source line number Unused zero filled Common Object File Format A 25 Symbol Table Structure and Content A 7 8 8 Beginning of Blocks and Functions Table A 25 illustrates the format of auxiliary table entries for the beginnings of blocks and functions Table A 25 Beginning of Blocks Functions Format for Auxiliary Table Entries Byte Number 0 3 4 5 6 11 12 15 16 17 Type Unsigned short integer Long integer Description Unused zero filled C sourc
109. linker can then correctly patch relocate the refer ence This allows you to initialize memory with pointers to variables or labels You can use as many values as fit on a single line 200 characters If you use a label it points to the first word that is initialized When you use these directives in a struct endstruct sequence they define a member s size they do not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 Assembler Directives 4 61 int uint word uword Initialize 16 bit Integer Example 1 In this example the int directive is used to initialize words 1 000000 data 2 000000 Space 73h 3 000000 bss PAGE 128 4 000080 bss SYMPTR 3 5 000000 text 6 0000007600 INST MOV 86 ACO 000002 5608 7 000007 data 8 000008 000A int 10 SYMPTR 1 35 a 000009 0080 00000a FFFF 00000b 0084 Example 2 In this example the word directive is used to initialize words The symbol WordX points to the first word that is reserved 1 000000 data 1 000000 0C80 WORDX word 3200 1 AB OAFh X 000001 4143 000002 FF51 000003 0058 4 62 Syntax Description Initialize Interrupt Table Entries ivec labe ivec address stack mode The ivec directive is used to initialize the entries in the interrupt vector table This directive has the following operands _j The abel if specified will be assigned the code by
110. loader has several different modes You can select these modes by using the bootorg and memwidth options 8 bit parallel MO bootorg PARALLEL memwidth 8 16 bit parallel I O bootorg PARALLEL memwidth 16 8 bit serial RS232 bootorg SERIAL memwidth 8 16 bit serial RS232 bootorg SERIAL memwidth 16 8 bit parallel EPROM bootorg 0x8000 memwidth 8 16 bit parallel EPROM bootorg 0x8000 memwidth 16 You should set the romwidth equal to the memwidth unless you want to have multiple output files The C55x can boot through either the serial or parallel interface with either 8 or 16 bit data The format is the same for any combination the boot table consists of a field containing the destination address a field containing the length and a block containing the data Hex Conversion Utility Description 13 31 Building a Table for an On Chip Boot Loader You can boot only one section If you are booting from an 8 bit channel 16 bit words are stored in the table with the MSBs first the hex conversion utility automatically builds the table in the correct format To boot from a serial port specify bootorg SERIAL when invoking the utility Use either memwidth 8 or memwidth 16 DD To load from a parallel I O port invoke the utility by specifying bootorg PARALLEL Use either memwidth 8 or memwidth 16 To boot from external memory EPROM specify the source address of the boot memory by using
111. lowercase L option is the only option allowed within a SECTIONS directive illegal relocation type found in section s of file Description The binary file is corrupt internal error Description This linker has an internal error invalid archive size for file Description The archive file is corrupt invalid path specified with i flag Description The operand of the i option flag is not a valid file or path name invalid value for f flag Description The value for f option flag is not a 2 byte constant invalid value for heap flag Description The value for heap option flag is not a 2 byte constant invalid value for stack flag Description The value for stack option flag is not a 2 byte constant invalid value for v flag Description The value for v option flag is not a constant l O error on output file Description The disk may be full or protected Action Check disk volume and protection Linker Error Messages length redefined for memory area Description A memory area in a MEMORY directive has more than one length library member has no relocation information Description The library member has no relocation information It is possible for a library member to not have relocation informa tion this means that it cannot satisfy unresolved references in other files when linking line number entry found for absolute symbol Descriptio
112. member reg 2 1 4 16 16 member _result 2 4 16 16 eos Symbolic Debugging Directives B 9 Sym Define a Symbol Syntax Description Example sym name value type storage class size tag dims The sym directive specifies symbolic debug information about a global vari able local variable or a function DD Nameis the name ofthe variable that is put in the object symbol table The first 32 characters of the name are significant DD Value is the value associated with the variable Any legal expression absolute or relocatable is acceptable DD Type is the C type of the variable Appendix A Common Object File Format contains more information about C types Storage class is the C storage class of the variable Appendix A Common Object File Format contains more information about C storage classes Size is the number of bits of memory required to contain this variable Tag is the name of the type if any or structure of which this variable is a type This name must have been previously declared by a stag etag or utag directive Dims may be up to four expressions separated by commas This allows up to four dimensions to be specified for the variable The order of parameters is significant The name and value are required parameters All other parameters may be omitted or empty adjacent commas indicate an empty entry This allows you to skip a parameter and specify a parameter that occurs later i
113. memory Glossary 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 source statements that are substituted for the macro call and are subsequently assembled 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 magic number A COFF file header entry that identifies an object file as a module that can be executed by the TMS320C55x map file An output file created by the linker that shows the memory configuration section composition and section allocation as well as symbols and the addresses at which they were defined member The elements or variables of a structure union archive or enu meration memory map A map of target system memory space which 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 A file that has been assembled or linked and contains machine language object code object format converter A p
114. model An autoinitialization model used by the linker when linking C code The linker uses this model when you invoke the linker with the c option In the ROM model the linker loads the cinit section of data tables into memory and variables are initialized at runtime Glossary ROM width The width in bits of each output file or more specifically the width of a single data value in the 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 will ultimately occupy con tiguous space in the TMS320C55x memory map section header A portion of a COFF object file that contains information about a section in the file Each section has its own header the header points to the section s starting address contains the section s size etc section program counter See SPC sign extend To fill the unused MSBs of a value with the value s sign bit simulator A software development system that simulates TMS320C55x operation source file A file that contains C code or assembly language code that will be compiled or assembled to form an object file SPC Section Program counter An element of the assembler that keeps track of the current l
115. not want those comments to appear in the macro expansion use an exclamation point to precede your comments If you do want your comments to appear in the macro expansion use an asterisk or semicolon For more information about macro comments see Section 5 7 Producing Messages in Macros on page 5 19 Example 5 1 shows the definition call and expansion of a macro a Mnemonic example OO 1001 QU O22 OO 0 0 120 O1 4S CO PD ES 000000 nd 000000 1 000002 000004 1 000005 000007 1 000008 A000 D600 00 D600 00 C000 add3 add3 abc add3 ADDRP P1 P2 P3 macro P1 P2 P3 ADDRP MOV P1 ACO ADD P2 ACO ACO ADD P3 ACO ACO MOV ACO ADDRP endm global abc def ghi adr def ghi adr MOV abc ACO ADD def ACO ACO ADD ghi ACO ACO MOV ACO adr Example 5 1 Macro Definition Call and Expansion Continued b Algebraic example Defining Macros T 2 3 add3 4 5 ADDRP P1 P2 P3 6 7 add3 macro P1 P2 P3 ADDRP 8 9 ACO Q0 P1 10 ACO ACO Q P2 11 ACO ACO P3 12 ADDRP ACO 13 endm 14 15 16 global abc def ghi adr 17 18 000000 add3 abc def ghi adr 1 1 000000 A000 ACO Q abc 1 000002 D600 ACO ACO def 000004 00 1 000005 D600 ACO ACO ghi 000007 00 1 000008 C000 adr ACO Macro Language 5 5 Macro Parameters Substitution Symbols 5 3 Macro Parameters Substitution Symbols If you
116. off directives is static and not subject to the control flow of the assembly program All of the assembly code between the arms on and the arms off directives is assembled in ARMS mode By default arms off indirect memory access modifiers targeted to the assembly code are selected In ARMS mode arms on short offset modifiers for indirect memory access are used These modifiers are more efficient for code size optimization Assembler Description 3 13 Naming Alternate Files and Directories for Assembler Input 3 5 Naming Alternate Files and Directories for Assembler Input 3 5 1 3 14 The copy include and mlib directives tell the assembler to use code from external files The copy and include directives tell the assembler to read source statements from another file and the mlib directive names a library that contains macro functions Chapter 4 Assembler Directives contains examples of the copy include and mlib directives The syntax for these directives is copy filename include filename mlib filename The filename names a copy include file that the assembler reads statements from or a macro library that contains macro definitions The filename may be a complete pathname a partial pathname or a filename with no path informa tion The assembler searches for the file in the following order 1 The directory that contains the current source file The current source file is the file being
117. one directory but you can use several i options per invocation When you use the i option to name an alternate directory it must precede the option on the command line or in a command file For example assume that there are two archive libraries called r lib and lib2 lib The table below shows the directories that r lib and lib2 lib reside in how to set environment variable and how to use both libraries during a link Select the row for your operating system Operating System Pathname Invocation Command DOS UNIX Md and Nd2 1nk55 f1 0bj f2 0bj i ld i ld2 lr lib llib2 1lib ld and Id2 1nk55 f1 0bj f2 0bj i ld i 1d2 lr lib 1lib2 1lib Linker Options 9 4 9 2 Name an Alternate Library Directory C DIR Environment Variable Operating System An environment variable is a system symbol that you define and assign a string to The linker uses environment variables named C_DIR andC55X_C_DIRto name alternate directories that contain object libraries The commands for assigning the environment variable are Operating System Enter DOS set C DIR pathname another pathname UNIX setenv C DIR pathname another pathname The pathnames are directories that contain object libraries Use the option on the command line or in a command file to tell the linker which libraries to search for In the example below assume that two archive libraries called r lib and lib2 lib reside in Id and Id2 directories The table
118. other than 0 for this parameter the assembler associates size words contiguously the allocated space will not cross a page boundary unless size is greater than a page in which case the object will start on a page boundary alignment flag is an optional parameter If you specify a value other than 0 for this parameter the section is aligned to a long word boundary section name tells the assembler which named section to reserve space in For more information about named sections see subsection 2 2 3 Named Sections on page 2 7 The text data and sect directives tell the assembler to stop assembling into the current section and begin assembling into the indicated section The bss and usect directives however do notend the current section and begin a new one they simply escape temporarily from the current section The bss and usect directives can appear anywhere in an initialized section without affecting its contents Uninitialized subsections can be created with the usect directive The assem bler treats uninitialized subsections in the same manner as uninitialized sections See subsection 2 2 4 Subsections on page 2 8 for more informa tion on creating subsections Introduction to Common Object File Format 2 5 How the Assembler Handles Sections 2 2 2 Initialized Sections Initialized sections contain executable code or initialized data The contents of these sections are stored in the object file and placed in
119. output files The number of output files is determined by the following formula where memory width ROM width number of files memory width ROM width For example for a memory width of 16 you could specify a ROM width of 16 and get a single output file containing 16 bit words Or you can use a ROM width value of 8 to get two files each containing 8 bits of each word 13 10 Understanding Memory Widths The default ROM width that the hex conversion utility uses depends on the out put format All hex formats except Tl Tagged are configured as lists of 8 bit bytes the default ROM width for these formats is 8 bits _j Tl Tagged is a 16 bit format the default ROM width for Tl Tagged is 16 bits rr Note The TI Tagged Format ls 16 Bits Wide You cannot change the ROM width of the Tl Tagged format The Tl Tagged format supports a 16 bit ROM width only a You can change ROM width except for Tl Tagged by Using the romwidth option This changes the ROM width value for the entire COFF file Setting the romwidth parameter of the ROMS directive This changes the ROM width value for a specific ROM address range and overrides the romwidth option for that range See Section 13 5 The ROMS Directive on page 13 15 For both methods use a value that is a power of 2 greater than or equal to 8 If you select a ROM width that is wider than the natural size of the output format 16 bits for Tl Tagged or 8
120. present The elseif di rective is optional in the conditional blocks and more than one elseif can be used If an expression is false and there is no elseif statement the assembler continues with the code that follows a else if present or a endif The else directive identifies a block of code that the assembler assembles when the if expression and all elseif expressions are false 0 This directive is optional in the conditional block if an expression is false and there is no else statement the assembler continues with the code that follows the endif The endif directive terminates a conditional block The elseif and else directives can be used in the same conditional assembly block and the elseif directive can be used more than once within a conditional assembly block For information about relational operators see subsection 3 10 4 Conditional Expressions on page 3 33 Assembler Directives 4 59 if elseif else endif Assemble Conditional Blocks Example 4 60 This example shows conditional assembly DAAINADUOFWNRFOOWATAAIHWNE NNNNNNNNDND H COO 10 O1 i PO 000000 000000 000001 000002 000003 0004 000a 0008 0005 SYM1 SYM2 SYM3 SYM4 If If Tf If 4 Set 1 Set 2 Set 3 Set 4 data Xf SYMA byte SYM4 else byte SYM2 endif df SYM1 byte 10 else byte SYM1 endif f SYM3 byte SYM3 else byte SYMA endif if SYM1 2 byte SYM1
121. processor memory when the program is loaded Each initialized section is independently relocat able and may reference symbols that are defined in other sections The linker automatically resolves these section relative references Three directives tell the assembler to place code or data into a section The syntaxes for these directives are text value data value sect section name value When the assembler encounters one of these directives it stops assembling into the current section acting as an implied end current section command It then assembles subsequent code into the designated section until it encoun ters another text data or sect directive The value if present specifies the starting value of the section program counter The starting value of the section program counter can be specified only once it must be done the first time the directive for that section is encountered By default the SPC starts at 0 Sections are built through an iterative process For example when the assem bler first encounters a data directive the data section is empty The state ments following this first data directive are assembled into the data section until the assembler encounters a text or sect directive If the assembler encounters subsequent data directives it adds the statements following these data directives to the statements already in the data section This creates a single data section that c
122. routine ROM model or the loader RAM model when to stop reading the initialization tables In the ROM model c option the linker defines the symbol cinit as the starting address of the cinit section The C boot routine uses this symbol as the starting point for autoinitialization In the RAM model cr option B The linker sets the symbol cinit to 1 This indicates that the initialization tables are not in memory so no initialization is performed at runtime B The STYP COPY flag 0010h is set in the cinit section header STYP COPY is the special attribute that tells the loader to perform autoinitialization directly and notto loadthe cinit section into memory The linker does not allocate space in memory for the cinit section 9 19 Linker Example Linker Example This example links three object files named demo obj fft obj and tables obj and creates a program called demo out The symbol SETUP is the program entry point Assume that target memory has the following configuration Byte Address Range Contents 000100 to 007080 On chip RAM PG 007081 to 008000 RAM block ONCHIP 008001 to 00A000 Mapped external addresses EXT 00C000 to 00FF80 On chip ROM The output sections are constructed from the following input sections m J Executable code contained in the text sections of demo obj fft obj and tables obj must be linked into program ROM Variables contained in the var_defs section of demo obj mu
123. same virtual address that it was bound to when the linker created it Linker Description 9 9 Linker Options 9 4 2 Disable Merge of Symbolic Debugging Information b Option By default the linker eliminates duplicate entries of symbolic debugging information Such duplicate information is commonly generated when a C program is compiled for debugging For example header h typedef struct lt define some structure members gt XYZ Eilge qe include header h i 2ee j include header h When these files are compiled for debugging both f1 obj and f2 obj will have symbolic debugging entries to describe type XYZ For the final output file only one set of these entries is necessary The linker eliminates the duplicate entries automatically Use the b option if you want the linker to keep such duplicate entries Using the b option has the effect of the linker running faster and using less machine memory 9 4 3 C Language Options c and cr Options The c and cr options cause the linker to use linking conventions that are required by the C compiler The c option tells the linker to use the ROM autoinitialization model The cr option tells the linker to use the RAM autoinitialization model For more information about linking C code see Section 9 18 Linking C Code on page 9 69 and subsection 9 18 5 The c and cr Linker Options on page 9 72 Linker Options 9 4 4 Def
124. section I Noraw data A section that has raw data is referred to as initialized This means that the object file contains the actual memory image contents of the section When the section is loaded this image is loaded into memory at the section s specified starting address The text and data sections a ways have raw data if anything was assembled into them Named sections defined with the sect assembler directive also have raw data By default the bss section and sections defined with the usect directive have no raw data they are uninitialized They occupy space in the memory map but have no actual contents Uninitialized sections typically reserve space in RAM for variables In the object file an uninitialized section has a normal sec tion header and may have symbols defined in it however no memory image is stored in the section 9 16 2 Creating Holes You can create a hole in an initialized output section A hole is created when you force the linker to leave extra space between input sections within an out put section When such a hole is created the linker must follow the first guide line above and supply raw data for the hole Holes can be created only within output sections Space can exist between output sections but such space is not holes There is no way to fill or initialize the space between output sections with the SECTIONS directive To create a hole in an output section you must use a special type of linker
125. sees Common Object File Format nnn nnn Contains supplemental technical data about the internal format and structure of COFF object files A 1 A 2 A 3 A 4 A 5 A 6 A 7 GOFF File StruCture icesescecetzee rece e Re xem Goede a Re mr aed RR D RR a File Header Structure 2 0 0 0 cect nett nett nee e eens Optional File Header Format i Section Header Structure i pac uirai auii a a nents Structuring Relocation Information 0 Line Number Table Structure os Symbol Table Structure and Content os AZA Special Symbols srs ha ber dores dde Ded sided ec dun e idus A 7 2 Symbol Name Format a 00 cece eee eens A 7 3 String Table Structure pp Contents xiii Contents AZA Storage ClasS S i202 enia duaya ag adaa aiea PEDIR beaded TR RULED TER IE ee A70 Section N mb68E 2 esca REPE VERRE E RR RR Rar eas AG IDE ENtty 2 56 vane state is ie Eo AE ie xe dace wkd Tasa d A 7 8 Auxiliary Entries 3 ma III II B Symbolic Debugging Directives seeeeeeeeree III Discusses symbolic debugging directives that the C compiler uses C Assembler Error Messages pp FE Lists the error messages that the assembler and linker issue and gives a description of the condition s that caused each error D Linker Error Messages sseeueeeeee I III I III HII m D 1 Lists the error messages that the assembler and linker issue and gives a description of the condition s that caused each error GOSS ANY eC
126. single archive file For example you can collect several macros into a macro library The assembler will search the library and use the members that are called as macros by the source file You can also use the archiver to collect a group of object files into an object library The linker will include in the library the mem bers that resolve external references during the link Topic Page 8 1 Archiver Overview u ei sien c TORTE EERE E EEEE A b 2 8 2 Archiver Development Flow Leere B 3 8 3 Invoking the Archiver me meaa e seed release 3 dAuArchiven Examples Ecc ECC EEETTTURRUPRCEERREEERTEEREEESE 8 1 Archiver Overview 8 1 Archiver Overview The TMS320C55x archiver lets you combine several individual files into a single file called an archive or a library Each file within the archive is called a member Once you have created an archive you can use the archiver to add delete or extract members You can build libraries from any type of files Both the assembler and the linker accept archive libraries as input the assembler can use libraries that contain individual source files and the linker can use libraries that contain individual object files One of the most useful applications of the archiver is building libraries of object modules For example you can write several arithmetic routines assemble them and use the archiver to collect the object files into a single logical group You ca
127. struct endstruct Sequence The only directives that can appear in a struct endstruct sequence are ele ment descriptors structure and union tags conditional assembly directives and the align directive which aligns the member offsets on word bound aries Empty structures are illegal st These examples show various uses of the struct tag and endstruct directives Assembler Directives 4 93 struct endstruct tag Declare Structure Types Example 1 1 000000 data 2 REAL REC struct 3 0000 NOM int 4 0001 ODE int 5 0002 REAL LEN endstruct 6 000000 text 7 000000 D600 ADD REAL REAL REC DEN 000002 00 8 i 9 10 000000 bss REAL REAL LEN Example 2 TA data 12 CPLX REC struct 13 0000 REALI tag REAL REC i 14 0002 IMAGI tag REAL REC H 15 0004 CPLX LEN endstruct 16 T2 COMPLEX tag CPLX REC H 18 19 000002 bss COMPLEX CPLX_LEN 20 000003 text 21 000003 D600 ADD Q COMPLEX REALI ACO ACO 000005 00 22 000006 C000 MOV ACO COMPLEX REALI 23 24 000008 D600 ADD COMPLEX IMAGI AC1 AC1 00000a 11 Example 3 1 000000 data 2 struct 3 4 0000 X int 5 0001 Y int 6 0002 Z int 7 0003 endstruct 4 94 stag memberl 0 member2 1 real len 2 ACO ACO access structure element allocate mem rec stag memberl 0 cplx_len 4 assign structure attrib access structure allocate space no stag puts me
128. suggests possible remedies Cannot find beginning of repeat block Comma required to separate arguments Comma required to separate parameters Commas must separate directive elements Left parenthesis expected Missing comma Missing left parenthesis Missing right parenthesis Missing right quote of string constant No matching right parenthesis Open repeat block at EOF Repeat block too deeply nested Right parenthesis expected Syntax Error Unrecognized character type Description These are errors about general syntax The required syntax is not present Action Correct the source per the error message text C 1 Assembler Error Messages C 2 Invalid mnemonic specification Description This error relates to invalid mnemonics The instruction macro or directive specified was not recognized Action Check the directive or instruction used ARO cannot be used as an index register in LEAD3 mode Absolute address used PC relative expected Cluttered character operand encountered Cluttered string constant operand encountered Cluttered identifier operand encountered Cluttered register operand encountered Concurrent Dreg update is illegal here Conditionals cannot begin in the first column Constant out of range dma offset too big DRO cannot be used as an index reigster in LEAD mode Dst register must be the same as Expected a reg Expected an accumulator Expected reg as Expected same Expected shift
129. syntax for invoking the linker is Ink55 options filename filenamen Ink55 is the command that invokes the linker options can appear anywhere on the command line or in a linker command file Options are discussed in Section 9 4 Linker Options on page 9 6 filenames can be object files linker command files or archive libraries The default extension for all input files is obj any other exten sion must be explicitly specified The linker can determine whether the input file is an object or ASCII file that contains linker commands The default output filename is a out There are three methods for invoking the linker Specify options and filenames on the command line This example links two files file1 obj and file2 obj and creates an output module named link out lnk55 filel obj file2 0bj o link out Enter the Ink55 command with no filenames and no options the linker prompts for them Command files Object files 0bj Output file a out Options B For command files enter one or more command filenames B Forobjectfiles enter one or more object filenames The default exten sion is obj Separate the filenames with spaces or commas if the last character is a comma the linker prompts for an additional line of object filenames B The output file is the name of the linker output module This overrides any o options entered with any of the other prompts If there are no o options and you d
130. table and autoinitializes global variables in the ROM model Disables interrupts and calls main The runtime support object libraries rts55 lib and rts55x lib contain boot obj You can Use the archiver to extract boot obj from the library and then link the module in directly J Include the appropriate runtime library as an input file the linker automati cally extracts boot obj when you use the c or cr option 9 18 2 Object Libraries and Runtime Support The TMS320C55x Optimizing C Compiler User s Guide describes additional runtime support functions that are included in rts55 lib and rts55x lib If your program uses any of these functions you must link the appropriate runtime li brary with your object files You can also create your own object libraries and link them The linker includes and links only those library members that resolve undefined references Linker Description 9 69 Linking C Code 9 18 3 Setting the Size of the Stack and Heap Sections C uses uninitialized sections called sysmem stack and sysstack for the memory pool used by the malloc functions and the runtime stacks respec tively You can set the size of these by using the heap option stack option or sysstack option and specifying the size of the section as a constant immediately after the option The default size for sysmem is 2000 bytes The default size for stack and sysstack is 1000 bytes For more informati
131. the same address If you provide both allocations the section is allocated as if it were two sections of the same size This means that both allocations occupy space in the memory map and cannot overlay each other or other sections The UNION directive provides away to overlay sections see subsection 9 11 1 Overlaying Sections With the UNION Statement on page 9 45 If either the load or run address has additional parameters such as alignment or blocking list them after the appropriate keyword Everything related to allocation after the keyword oad affects the load address until the keyword run is seen after which everything affects the run address The load and run allocations are completely independent so any qualification of one such as alignment has no effect on the other You may also specify run first then load Use parentheses to improve readability Linker Description 9 41 Specifying a Section s Runtime Address The examples below specify load and run addresses data load ROM align 32 run RAM align applies only to load data load ROM align 32 run RAM identical to previous example data run load RAM align 32 align 16 align 32 in RAM for run align 16 anywhere for load 9 10 2 Uninitialized Sections Uninitialized sections such as bss are not loaded so their only significant address is the run address The linker allocates uninitialized sections only once if you specify bo
132. to cross a 128 byte bound ary if itis smaller than 128 bytes or to start on a 128 byte boundary if it is larger than 128 bytes In a data section blocked code is guaranteed not to cross a 128 word page boundary if it is smaller than a page or to start ona page boundary ifit is larger than a page Note that this directive allows specification of blocking for initialized sections only not uninitialized sections declared with usect or the bss section The vli_off directive begins a block of code in which the assembler will use the largest P24 forms of certain variable length instructions By de Miscellaneous Directives fault the assembler tries to resolve variable length instructions to their smallest form The vli_on directive ends this block of code and resumes the default behavior of the assembler These three directives enable you to define your own error and warning messages d The emsg directive sends error messages to the standard output device The emsg directive generates errors in the same manner as the assembler incrementing the error count and preventing the assembler from producing an object file The mmsg directive sends assembly time messages to the standard output device The mmsg directive functions in the same manner as the emsg and wmsg directives but does not increment the error count or the warning count It does not affect the creation of the object file The wmsg directive sends warning me
133. to interrupts 7 1 1 Differences in the Interrupt Vector Table The C54x interrupt table is composed of 32 vectors Each vector contains 4 words of executable code The C55x vector table is also composed of 32 vectors The vectors in both tables are the same length but on the C55x the length is counted as 8 bytes The order of the vectors in the interrupt vector table is documented in the data sheet for the specific device in your system Since the order of the vectors is device specific any access to the IMR or IFR register needs to be updated accordingly Likewise if you use the TRAP instruction its operand may need to be updated C54x and C55x handle the contents of their vectors in different ways To handle these differences you must modify the C54x vectors themselves In the C55x vector table the first byte is ignored and the next three bytes are interpreted as the address of the interrupt service routine ISR Use the ivec assembler directive to initialize a C55x vector entry as shown in the examples below For more information on the ivec directive see the description on page 4 63 Simple Branch to ISR If the C54x vector contains B isr Change the corresponding C55x vector to ivec isr Delayed Branch to ISR If the C54x vector contains BD isr inst 1 two instruction words of code inst 2 The easiest solution is to write the vector as ivec isr and move the instructions inst and inst2 t
134. to the method in which the C compiler accesses a symbol Table A 11 lists valid storage classes Symbol Storage Classes Storage Class No storage class Automatic variable External symbol Static Register variable External definition Label Undefined label Member of a structure Function argument Structure tag Member of a union Mnemonic C UNTAG C TPDEF C USTATIC C ENTAG C MOE C REGPARM C FIELD C BLOCK C FON C EOS C FILE C LINE Value 12 13 14 15 16 17 18 100 101 102 103 104 Storage Class Union tag Type definition Uninitialized static Enumeration tag Member of an enumeration Register parameter Bit field Beginning or end of a block used only for the bb and eb special symbols Beginning or end of a func tion used only for the bf and ef special symbols End of structure used only for the eos special symbol Filename used only for the file special symbol Used only by utility programs Some special symbols are restricted to certain storage classes Table A 12 lists these symbols and their storage classes Symbol Table Structure and Content Table A 12 Special Symbols and Their Storage Classes A 7 5 Symbol Values Special Symbol file bb eb bf ef Restricted to This Special Storage Class Symbol C FILE eos C BLOCK text C_BLOCK data C_FCN bss C FCN Restricted to This Storage Class C EOS C STAT C STAT C
135. two assemblers x masm55 the mnemonic assembler accepts C54x mnemonic and C55x mnemonic assembly source asm55 the algebraic assembler accepts only C55x algebraic assembly source Each assembler does the following d m E m Processes the source statements in a text file to produce a relocatable C55x object file Produces a source listing if requested and provides you with control over this listing Allows you to segment your code into sections and maintain an SPC section program counter for each section of object code Defines and references global symbols and appends a cross reference listing to the source listing if requested Assembles conditional blocks Supports macros allowing you to define macros inline or in a library The masm55 assembler generates error and warning messages for C54x instructions that are not supported Some C54x instructions do not map directly to a single C55x instruction The masm55 assembler will translate these instructions into an appropriate series of C55x instructions The listing file generated by the assembler with the option shows the translations that have occurred Assembler Development Flow 3 2 Assembler Development Flow Figure 3 1 illustrates the assembler s role in the assembly language develop ment flow The assembler accepts assembly language source files as input whether created by the assembler itself or by the C compiler Figure
136. warnings about truncated values The expression given was too large to fit within the instruction opcode or the required number of bits Action Check the source to make sure the result will be acceptable or change the source if an error has occurred Address expression will wrap around Expression will overflow value truncated Description These are warnings about arithmetic expressions The assembler has done a calculation that will produce the indicated result which may or may not be acceptable Action Verify the result will be acceptable or change the source if an error has occurred Incorrect size for the type sym for function name required before func Description This is a warning about problems with symbolic debugging directives A sym directive defining the function does not appear before the func directive Action Correct the source Assembler Error Messages C 15 Assembler Error Messages access only allowed in top most structure definition Access point has already been defined Open block s at EOF Description These are warnings about problems with structure defini tions Action Correct the source per the error message text Conflicting modifications of CDP by two memory operands Conflicting modifications of AR by two memory operands Parallelism checks conflicting COEFFICIENT operands conflicting modifications of CDP conflicting modifications of an AR same bus resource used by both instructions s
137. warnings it encounters and prints these numbers on the last line of the listing file The emsg directive sends error messages to the standard output device in the same manner as the assembler incrementing the error count and prevent ing the assembler from producing an object file The mmsg directive sends assembly time messages to the standard output device in the same manner as the emsg and wmsg directives but it does not set the error or warning counts and it does not prevent the assembler from producing an object file The wmsg directive sends warning messages to the standard output device inthe same manner as the emsg directive but it increments the warning count rather than the error count and it does not prevent the assembler from produc ing an object file In this example the message ERROR MISSING PARAMETER is sent to the standard output device Source file global PARAM MSG EX macro parml df symlen parml 0 emsg ERROR MISSING PARAMETER else ADD parml ACO ACO endif endm MSG EX PARAM MSG EX Define Messages emsg mmsg wmsg Listing file 1 global PARAM 2 MSG EX macro parmi 3 ede Ssymlen parml 0 4 emsg ERROR MISSING PARAMETER 5 else 6 ADD parml ACO ACO 7 endif 8 endm 9 10 000000 MSG EX PARAM 1 Xf Ssymlen parml 0 1 emsg ERROR MISSING PARAMETER 1 else 1 000000 D600 ADD PARAM ACO ACO 000002 00 1 e
138. which they are encountered Each output section is placed into the first available memory space considering alignment where necessary Note that the linker pads the end of the final text section the grouping of all text sections from object files in the application with a non parallel NOP rr Note The PAGE Option If you do not use the PAGE option to explicitly specify a memory space for an output section the linker allocates the section into PAGE 0 This occurs even if PAGE 0 has no room and other pages do To use a page other than PAGE 0 you must specify the page with the SECTIONS directive es Linker Description 9 57 Special Section Types DSECT COPY and NOLOAD 9 14 Special Section Types DSECT COPY and NOLOAD You can assign three special type designations to output sections DSECT COPY and NOLOAD These types affect the way that the program is treated when it is linked and loaded You can assign a type to a section by placing the type enclosed in parentheses after the section definition For example SECTIONS secl 2000h DSECT fl obj sec2 4000h COPY 2 0bj sec3 6000h NOLOAD 3 0bj The DSECT type creates a dummy section with the following qualities B ltisnotincludedinthe output section memory allocation It takes up no memory and is not included in the memory map listing B ltcan overlay other output sections other DSECTs and unconfigured memory Bi Global symbol
139. with Os causes raw data to be generated for all unallocated blocks of memory in the range The following example specifies a memory range with the R and W attributes and a fill constant of OFFFFh MEMORY RFILE RW o 02h 1 OFEh f OFFFFh You normally use the MEMORY directive in conjunction with the SECTIONS directive to control allocation of output sections After you use the MEMORY directive to specify the target system s memory model you can use the SECTIONS directive to allocate output sections into specific named memory ranges or into memory that has specific attributes For example you could allocate the text and data sections into the area named ROM and allocate the bss section into the area named ONCHIP Linker Description 9 31 The SECTIONS Directive 9 9 The SECTIONS Directive The SECTIONS directive DD Describes how input sections are combined into output sections DD Defines output sections in the executable program DD Specifies where output sections are placed in memory in relation to each other and to the entire memory space DD Permits renaming of output sections Refer to Section 2 3 How the Linker Handles Sections on page 2 12 for details on how the linker handles sections Refer to Section 2 4 Helocation on page 2 15 for information on the relocation of sections Refer to subsection 2 2 4 Subsections on page 2 8 for information on defining subsections subsections
140. within GROUP not aligned Description A section in a group was specified for individual alignment The entire group is treated as one unit so the group may be aligned or bound to an address but the sections making up the group cannot be handled individually can t align within UNION section not aligned Description A section in a union was specified for individual alignment The entire union is treated as one unit so the union may be aligned or bound to an address but the sections making up the union cannot be handled individually can t allocate size page Description A section can t be allocated because no existing configured memory area is large enough to hold it Action If you are using a linker command file check that the MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory can t create map file Description Usually indicates an illegal filename Action Check spelling pathname environment variables etc The filename must conform to operating system conventions can t find input file filename Description The file filename is not in your PATH is misspelled etc Action Check spelling pathname environment variables etc The filename must conform to operating system conventions can t open Description The specified file does not exist Action Check spelling pathname environment variables etc The f
141. 0 000000 000000 000002 000000 000000 7B00 5600 0000 d 0000 d d 7B00 5600 0000 Identify Global Symbols global def ref Global symbol defined in this file global INIT Global symbols defined in file2 1st global X Y Z INIT ADD 86 ACO ACO data word X end Global symbols defined in this file global X Y Z Global symbol defined in filel lst global INIT X Set 1 Y Set 2 Z Set data word INIT end Global symbol defined in this file def INIT Global symbols defined in file4 1st ref X Y Z INIT ADD 86 AC0 ACO data word X end Assembler Directives 4 55 global def ref Identify Global Symbols file4 Ist 1 Global symbols defined in this file 2 def X Y Z 3 Global symbol defined in file3 1st 4 ref INIT 5 X Set 1 6 Y set 2 7 Zi Set 3 8 000000 data 9 000000 0000 word INIT 10 gt T s T2 A s is end 4 56 Syntax Description Initialize 16 bit Integer half uhalf short ushort half value valuen uhalf value values Short value valuej ushort value value The half uhalf short and ushort directives place one or more values into consecutive 16 bit fields in the current section A value can be Anexpression that the assembler evaluates and treats as an 16 bit signed or unsigned number D A character string enclosed in double quo
142. 0 000000 000000 000000 000000 000002 000004 co 103 01 01 5 CO P2 ES LOC1 4 CCCh START TEMP 3200 40F0 C000 data Space SEL bss text 300 15 LOC1 48h ABS ACO ACO ADD T EMP ACO ACO MOV ACO LOC1 end Syntax Description Example Control the Listing of False Conditional Blocks _ fclist fcnolist fclist fcnolist Two directives enable you to control the listing of false conditional blocks The fclist directive allows the listing of false conditional blocks conditional blocks that do not produce code The fcnolist directive suppresses the listing of false conditional blocks until a fclist directive is encountered With fcnolist only code in conditional blocks that are actually assembled appears in the listing The if elseif else and endif directives do not appear By default all conditional blocks are listed the assembler acts as if the fclist directive had been used This example shows the assembly language and listing files for code with and without the conditional blocks listed Source File AAA Set 1 BBB Set 0 fclist d f AAA ADD 1024 AC0 ACO else ADD 1024 10 ACO ACO endif fcnolist if AAA ADD 1024 AC0 ACO else ADD 1024 10 ACO ACO endif Listing file 1 AAA set 1 2 BBB set 0 3 fclist 4 Jr AAA 5 000000 7B04 ADD 1024 ACO ACO 000002 0000 6 else 7 ADD 1024 10 ACO ACO 8 endif 9 10 fcnolist 11 13
143. 000 bytes 9 4 16 Define Secondary Stack Size sysstack constant Option The TMS320C55x C compiler uses an uninitialized section sysstack to allo cate space for the secondary runtime stack You can set the size of the Sysstack section at link time with the sysstack option Specify the size in bytes as a constant immediately after the option lnk55 sysstack 0x1000 defines secondary stack size When the linker defines the sysstack section it also defines a global symbol SYSSTACK SIZE and assigns it a value equal to the size of the section The default secondary stack size is 1000 bytes 9 4 17 Introduce an Unresolved Symbol u symbol Option The u option introduces an unresolved symbol into the linker s symbol table This forces the linker to search a library and include the member that defines the symbol The linker must encounter the u option before it links in the member that defines the symbol For example suppose a library named rts lib contains a member that defines the symbol symtab none of the object files being linked reference symtab However suppose you plan to relink the output module and you would like to include the library member that defines symtab in this link Using the u option as shown below forces the linker to search rts lib for the member that defines symtab and to link in the member lnk55 u symtab filel obj file2 obj rts lib If you do not use u this member is not included b
144. 000004 7B04 ADD 1024 ACO ACO 000006 0000 Assembler Directives 4 49 field Initialize Field Syntax Description field value size in bits The field directive can initialize multiple bit fields within a single word in data sections p 7 Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of the field directive in a section that includes C55x instructions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommendsthatthis directive be issued only with in data sections This directive has two operands _j The valueis a required parameter itis an expression that is evaluated and placed in the field If the value is relocatable size must be 16 or 24 _j The sizeis an optional parameter it specifies a number from 1 to 32 which is the number of bits in the field If you do not specify a size the assembler assumes that the size is 16 bits If you specify a size of 16 or more the field will start on a word boundary If you specify a value that cannot fit into size bits the assembler truncates the value and issues an error message For example field 3 1 causes the assembler to truncate the value 3 to 1 the assembler also prints the message warning value truncated Successive field directives pack values into the specif
145. 000008 000009 00000a 00000b 00000c 00000d 00000e 5 00000f 0041 0042 0043 0044 0041 0042 0043 0044 4175 7374 696 486EF 757 746F 6E00 0030 1 LH 1 Str Ptr string pstring Initialize Text This example shows 8 bit values placed into words in the current section data String 41h 42h 43h 44h string ABCD pstring Austin Houston string 36 12 Assembler Directives 4 91 struct endstruct tag Declare Structure Type Syntax Description stag memo mem mam memy size label Struct expr element expr element expr tag stag expra element exprw endstruct tag stag The struct directive assigns symbolic offsets to the elements of a data structure definition This enables you to group similar data elements together and then let the assembler calculate the element offset This is similar to a C structure or a Pascal record A struct definition may contain a union definition and structs and unions may be nested The struct directive does not allocate memory it merely creates a symbolic template that can be used repeatedly The endstruct directives terminates the structure definition The tag directive gives structure characteristics to a label simplifying the symbolic representation and providing the ability to define structures that con tain other structures The tag directive does not allocate memory The struct
146. 0101100 0000000 field x 2 0000000000000001 0000000000000000 field 04321 32 e 3 4 0100001100100001 Syntax Description Example Initialize Floating Point Value float xfloat float value valuen Xfloat value values The float and xfloat directives place the floating point representation of one or more floating point constants into the current data section The value must be a floating point constant or a symbol that has been equated to a floating point constant Each constant is converted to a floating point value in IEEE single precision 32 bit format Floating point constants are aligned on the long word boundaries unless the xfloat directive is used The xfloat directive performs the same function as the float directive but does not align the result on the long word boundary Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of float and xfloat directives in a section that includes C55x instructions will likely lead to the generation of an invalid access to the data at execution Conse quently Texas Instruments highly recommends that these directives be is sued only within data sections l The 32 bit value consists of three fields Field Meaning S A 1 bit sign field e An 8 bit biased exponent f A23 bit mantissa The value is stored most significant word first least significant word second in the following format
147. 03 000000 000000 000001 000004 000004 000005 000000 000006 000007 000004 000004 000000 000006 x Start assembling into the text section ck ck ck ck ck ck 0k ok ck 0k ck 0k ck ck Ck ck ck ck ck ck ck ck ck ck ck ck ck o ckck ck ck ck ck ck ck o ckock kk ck kk ck Sk Sk A ko ko ko text 3CA0 MOV 10 ACO 2201 MOV ACO AC1 Start assembling into the data section data 0009 word 9 10 000A 000B word Iip L2 000C Start assembling into a named initialized section var_defs ck ck ck ck ck ck KK ck 0k ck 0k ck ck Ck ck ck Ck ck ck ck ck ck ck ck ck ck ckck ck ck ck ck ck ck ck ck kk ck kk ck Sk Sk A ko ko ko sect var defs 0011 word 17 18 001
148. 108 example_B 38 overview relocation at runtime P 17 described to during linking 9 8 sections directives 2 4lto source listings 3 36 to 3 39 suppressing remarks symbols assembler directives to 4 26 absolute lister setsect setsym aligning the section program counter SPC 4 16 to align even 4 default directive Index 2 assembler directives continued defining assembly time symbols 4 22 to 4 23 asg endstruct endunion nolist option page Sslist assembler directives continued initializing constants 4 11 to 1 15 4 11 k 87 Index assembler directives continued referencing other files assembly time constants 4 86 defined assignment statement defined E 2 expressions 9 60 to 9 61 attr MEMORY A ne attributes autoinitialization defined described to specifying type auxiliary entr defined E EL described A 22 to A 26 b disassembler option 12 2 linker option bes directive big endian ordering binary integer constants binding defined named memor sections block auxiliary table entry A 25 defined described reference block symbolic debugging directive blocking boot loader See on chip boot loader boot table See on chip boot loader boot table boot obj Index 3 Index bootorg hex conversion utility option break directive listing control 4 18 4 45 use in macros bss directive 4 8
149. 12 000002 ADD2 ADDRX ADDRY 1 000002A000 MOV ADDRX ACO 000004D600 ADD ADDRY ACO ACO 00000600 1 000007C000 OV ACO ADDRY 13 14 Sslist 15 16 000009C083 MOV ACO AR4 17 00000bC003 MOV ACO ARO 18 19 00000d ADD2 ADDRX ADDRY 1 00000dA000 MOV ADDRA ACO MOV ADDRX ACO 1 00000fD600 ADD ADDRB ACO ACO d ADD ADDRY ACO ACO 00001100 1 000012C000 MOV ACO ADDRB MOV ACO ADDRY 4 88 Control Listing of Substitute Symbols b Algebraic example SF FFE Fe hb 13 14 15 16 17 18 19 000000 000001 000002 000003 ADD2 000000C083 000002 000002A000 000004D600 00000600 000007C000 000009C083 000005C003 00000d 00000dA000 00000 D600 00001100 000012C000 bss ADDRX 1 bss ADDRY 1 bss ADDRA 1 bss ADDRB 1 macro ADDRA ADDRB ACO Q ADDRA ACO ACO ADDRB ADDRB ACO endm AR4 ACO ADD2 ADDRX ADDRY ACO ADDRX ACO ACO ADDRY ADDRY ACO Sslist AR4 ACO ARO ACO ADD2 ADDRX ADDRY ACO ADDRA ACO ADDRX ACO ACO ADDRB ACO ACO ADDRY ACO ACO ADDRB ADDRY Assembler Directives sslist ssnolist 4 89 string pstring Syntax Description Initialize Text String string string pstring string strings The string and pstring directives place 8 bit characters from a character string into the current section The string directive places 8 bit characters into
150. 2 Resume assembling into the data section data 000D word 13 14 000E bss sym 19 Reserve space in bss 000F word 15 16 2 Still ain data 0010 Resume assembling into the text section ck ck ck ck ck ck 0k ck ck Ck ck ck ck ck Ck ck ck ck ck ck ck ck ck ck ck ck ck o ckck ck ck ck ck ck ck kk kk ck Pk ko ck Sk kv A ko ko ko text 2412 ADD AC1 AC2 usym usect xy 20 Reserve space in xy 2220 MOV AC2 ACO Still in text 4 10 Directives That Initialize Constants 4 3 Directives That Initialize Constants This section describes several directives that assemble values for the current section gt Fo OO oo sM s s U_i CS S CT _ h_ h i tsh th t SssseFseFheoes Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of these directives in a section that incl
151. 2 Octal Integers ord a E e ee 3 93 Decimal Negers 22r et RR ERR RR ee eta D Ra Ree RE E DE ete ea 3 74 Hexadecimal Integers 3 0s 3 75 Character Constants 23 ws nm Da aan ete eens 3 7 6 Floating Point Constants 0 cece eects 3 8 Character Strings nn i a saa eaa aa EE a sn 9 9 Symbols ase kiat i mana karaa d me ce yh der waa ya do i a DlA ee A sonal S91 ab 3 9 2 Symbolic Constants se ny teens 3 9 3 Defining Symbolic Constants d Option pp 3 9 4 Predefined Symbolic Constants i 3 9 5 Substitution Symbols ns 00 0 ete eee 39 6 Local babels a csse Lass sed ded Ded one iro d adnan da emi m RC eT A 3101 Operat lS sy on donata adn a e a nei fen eatin aTa a ee a as 3 10 2 Expression Overflow and Underflow pp 3 10 3 Well Defined Expressions i 3 10 4 Conditional Expressions i 3 41 Built in Functions 0 0 00 ccc Rh 3 12 Source Listings ciues ccs uan hr ee Rd Ma doa dos ee 3 13 Cross Reference Listings 9 4 Assembler Directives sv eT cede wena Ea vote ee eee eee eee ese TTE Describes the directives according to function and presents the directives in alphabetical order 4 1 Directives Summary sm 4 2 Directives That Define Sections 0 bce eet eee 4 3 Directives That Initialize Constants viii Contents 4 4 Directives That Align the Section Program Counter 4 5 Directives That Format the Output Listing os 4 6 Directives That Reference Other Files i 4 7 Conditional Assembly Directives es 4
152. 2 asm global GLOBAL global FUNC GLOBAL set 100 FUNC RETURN The examples below assume that test asm and test2 asm have been as sembled and linked with the following commands masm55 qs test asm masm55 qs test2 asm lnk55 q test obj test2 0bj o test out J To create a standard disassembly listing of an object file enter dis55 test obj TMS320C55x COFF Disassembler Version x xx Copyright c 1996 2000 Texas Instruments Incorporated Disassembly of test obj EXT Section text 0x8 bytes at 0x0 000000 START 000000 2298 MOV AR1 ARO 000002 4010 ADD 1 ACO 000004 last 000004 7b000000 ADD 0 ACO ACO DATA Section data 0x3 words at 0x0 000000 0004 word 0x0004 000001 foo 000001 0001 word 0x0001 000002 0000 word 0x0000 Notice that the value 1 was encoded into the first ADD instruction and that the 16 bit ADD instruction was used For the second ADD instruction the 12 4 Disassembly Examples use of the global symbol GLOBAL caused the assembler to use the 32 bit ADD instruction The symbols GLOBAL and FUNC will be resolved by the linker You can view the COFF file information with the c option The q option suppresses the printing of the banner dis55 qc test obj gt gt Target is C55x Phase 3 mem small call c55 std Relocation information may exist in file File is not executable Line number information may be present in the file Local symbols may be presen
153. 20C55x Optimizing C Compiler User s Guide The ported C54x environment expects the first argument to be in A ACO on C55x and the remaining arguments to be placed on the stack in reverse order of appearance in the argument list The right most argument T1 is pushed onto the stack first The next argument TO is then pushed onto the Using Ported C54x Functions with Native C55x Functions stack The argument placement continues until the left most argument ARO is reached This argument is copied to ACO Example 7 2 Assembly Function firlat veneer Continued c Changing status bits BSET C54CM BCLR ARMS BCLR C16 It is necessary to change the status settings of the native C55x code to the settings required by ported C54x code These settings are shown in Section 7 2 1 on page 7 5 In this case only the C54CM and ARMS bits need to be changed Because of the requirements for executing the original C54x code it may be necessary to set the C16 bit to 0 This bit ignored by C55x compiled code is assumed to be 0 by the C54x compiler Setting the bit to 0 is the conserva tive approach to account for this assumption d Function call CALL _firlat Now that registers have been saved and status bits set the call to ported C54x code can be made e Restoring status bits BCLR C54CM BSE ARMS BSE SXMD After the call restore the status bits to the settings requir
154. 32 bit integers but do not align on long word boundary Assembler Directives Page 4 8 A Ka eo A oj o AB Wj Lo NS A a M AIB WwW co Ajlo C1 M Directives Summary Table 4 1 Assembler Directives Summary Continued c Directives that align the section program counter SPC Mnemonic and Syntax align size even d Directives that format the output listing Mnemonic and Syntax drlist drnolist fclist fcnolist length page length list mlist mnolist nolist option B L M R T W X page sslist ssnolist tab size title string Width page width 4 4 Description Align the SPC on a byte or word boundary specified by the parameter the parameter must be a power of 2 defaults to a 128 byte or 128 word boundary Equivalent to align 2 Description Enable listing of all directive lines default Suppress listing of certain directive lines Allow false conditional code block listing default Suppress false conditional code block listing Set the page length of the source listing Restart the source listing Allow macro listings and loop blocks default Suppress macro listings and loop blocks Stop the source listing Select output listing options Eject a page in the source listing Allow expanded substitution symbol listing Suppress expanded substitution symbol listing default Set tab size Print a title in the listing page heading Set the pa
155. 5 PSH AR6 Saved in ported C54x environment PSH AR7 gt ditto PSH T2 PSH T3 If the C55x runtime environment expects that certain registers will not be mod ified by a function call these registers must be saved In the case of the C55x C compiler environment registers XAR5 XAR7 T2 and T3 must be saved Because C54x code cannot modify the upper bits of the XARn registers only the lower bits need to be preserved The instructions that push AR6 and AR7 are commented out because the runtime environment of the C54x ported code as defined by the C54x C compiler presumably saves these registers A more conservative approach would be to save these registers anyway b Passing arguments PSH T1 push right most argument first PSH TO then the next argument PSH AR3 and so on PSH AR2 PSH AR1 MOV ARO ACO left most argument goes in ACO Arguments passed from native C55x code must be placed where the ported C54x code expects them In this case all arguments are passed in registers According to the calling conventions of the C55x C compiler the arguments to the firlat function will be passed and the result returned in the registers shown below TO ARO AR1 AR2 ARS short firlat short x short k short r short dbuffer unsigned short nx unsigned short nk For more information on the C compiler s calling conventions see the Runtime Environment chapter of the TMS3
156. 6 000004 00AA ivals word OAAh OBBh OCCh 000005 00BB 000006 00CC 27 28 xx Define another section for more variables 29 KKK KKK KKK KKK KKK KKK ck Ck ck ck ck ck kk ck ck ck ck ck ck o ckock KKK KKK Sk KKK ko ko ko 30 000000 vara usect newvars 1 31 000001 inbuf usect newvars 7 32 ck ck 0k ck ck 0k ck kk ck Ck ck ck Ck ck 0k 0k ck Ck ck ck ck ck kc ck ck ck ck ck ck cock ck ck ok kk ck Sk Sk KK ko ko ko 33 FE Assemble more code into text Um 34 35 000007 text 36 000007 A114 mpy MOV OAh AC1 37 000009 5272 mloop MOV T3 HI AC2 38 00000b 1E0A MPYK 10 AC2 AC1 00000d 90 39 00000e 0471 BCC mloop overflow AC1 000010 F8 40 41 xx Define a named section for int vectors 42 KKK KKK KKK KKK KKK KKK KKK KKK kc ck ck ck ck ck ck ck ock ck ck ck kk ck KKK KKK KK 43 000000 sect vectors 44 000000 0011 word 011h 033h 45 000001 0033 Field1 Field2 Field 3 Field 4 Ho
157. 9 2 9 3 9 4 Linker Overview 0 Linker Development Flow 0 0 cece eee III Invokingithe Inker zu a ni A de Seeded RR REC RRRELRIEEUEREETE AE Linker Options ses a RR mmm 9 4 1 Relocation Capabilities Ca and r Options i 9 4 2 Disable Merge of Symbolic Debugging Information b Option 9 4 3 C Language Options c and cr Options 0 0 cee eee eee 9 4 4 Define an Entry Point e global symbol Option 4 9 45 Set Default Fill Value Cf cc Option 00 eee eee 9 4 6 Make a Symbol Global g global symbol Option 9 4 7 Make All Global Symbols Static h Option pp 9 4 8 Define Heap Size heap constant Option pp 9 4 9 Alter the Library Search Algorithm Option i Option and C55X C DIR C DIR Environment Variables llus 9 4 10 Ignore Alignment Flags Ck Option pp 9 4 11 Create a Map File m filename Option 0 0c eee eee eee 9 4 12 Name an Output Module o filename Option pp 9 4 13 Specify a Quiet Run q Option pp 9 4 14 Strip Symbolic Information s Option i 9 4 15 Define Stack Size stack constant Option pp 9 4 16 Define Secondary Stack Size sysstack constant Option 9 4 17 Introduce an Unresolved Symbol u symbol Option 9 5 9 6 9 7 9 8 9 9 9 10 9 11 9 12 9 13 9 14 9 15 9 16 9 17 9 18 Contents 9 4 18 Display a Message for Out
158. B M2 A064 M1 MOV 50 ACO M2 Macro Language 5 17 Using Labels in Macros Example 5 13 Unique Labels in a Macro Continued b Algebraic example T define macro 2 MLAB macro AVAR BVAR find minimum 3 4 ACO AVAR 5 ACO ACO BVAR 6 if ACO lt 0 goto M1 7 ACO BVAR 8 goto M2 9 M1 ACO AVAR 10 M2 11 endm 12 13 call macro 14 000000 MLAB 50 100 000000 A064 ACO 50 000002 7000 ACO ACO 100 000004 6400 000006 7B20 if ACO lt 0 goto M1 000008 6B00 ACO 100 00000a 6480 00000c 0082 goto M2 00000e A064 M1 ACO 50 000010 M2 5 18 Producing Messages in Macros 5 7 Producing Messages in Macros The macro language supports three directives that enable you to define your own assembly time error and warning messages These directives are especially useful when you want to create messages specific to your needs The last line of the listing file shows the error and warning counts These counts alert you to problems in your code and are especially useful during debugging emsg mmsg wmsg sends error messages to the listing file The emsg directive generates errors in the same manner as the assembler incrementing the error count and preventing the assembler from producing an object file sends assembly time messages to the listing file The mmsg directive functions in the same manner as the emsg directi
159. For example assume that the lines of C source below are line 4 and 5 in the original C source line 5 produces the assembly language source statements that are shown below i lt n i er Resulting assembly language code line Tl ACO SP 3 SP 2 AR2 AR1 Tcl if TC1 7 SP 0 Tl SP 3 ACO SP 2 SP 1 SP 2 AR1 lt AR2 goto Ll 1 branch occurs L2 line TO line SP 8 SP 3 9 SP 5 return return occurs Syntax Description Example Define a Member member member nare value type storage class size tag dims The member directive defines a member of a structure union or enumera tion Itis valid only when it appears in a structure union or enumeration defini tion a LJ d Name is the name of the member that is put in the symbol table The first 32 characters of the name are significant Value is the value associated with the member Any legal expression absolute or relocatable is acceptable Type is the C type of the member Appendix A Common Object File Format contains more information about C types Storage classis the C storage class of the member Appendix A Common Object File Format contains more information about C storage classes Size is the number of bits of memory required to contain this member Tag is the name of the type if any or structure of which this member is
160. Format discusses the COFF format in detail Topic Page 931 Linker Overview 7 7 5 0 S a a tel reet Ba 9 2 Linker Development Flow ss 9 3 9 3 SInvoKing the Linker a aeee a E 9c InkenODptionsPPee eC CE EPPPPEECEPEEDEME OCC 9 5 Byte Word Addressing 8 21 9 6 Linker Command Files 2 30 me ERR 9 22 97 Object libraries oean retos eae Ov en weenie a s 0 26 9 8 The MEMORY Directive pp B 33 B 59 9 9 The SECTIONS Directive 9 10 Specifying a Section s Runtime Address 9 11 Using UNION and GROUP Statements 9 12 Overlay Pages v E e eec ER 9 13 Default Allocation Algorithm Leere 9 14 Special Section Types DSECT COPY and NOLOAD 9 15 Assigning Symbols at Link Time eee 9 16 Creating and Filling Holes eI 9 17 Partial Incremental Linking eese 9 67 918 BinkingiC Gode sai cs saat 0o do eR ue aeu S DER 9 19uPinkenExampled coooncaosocannnmpeaveannonpnsdoRannonoodsoaans 9 73 9 1 Linker Overview 9 1 Linker Overview The TMS320C55x linker allows you to configure system memory by allocating output sections efficiently into the memory map As the linker combines object files it performs the following tasks D Allocates sections into the target system s configured memory DD Relocates symbols and sections to assign them to final addresses Resolves unde
161. GE 1 2 3 4 TMS320C55x COFF Assembler Version X xx Copyright c 2000 Texas Instruments Incorporated Page Directive Example PAGE 2 Assembler Directives 4 83 Sblock Specify Blocking for an Initialized Section Syntax Description Example sblock section name section name The sblock directive designates sections for blocking Blocking is an address alignment mechanism similar to page alignment but weaker A blocked code section is guaranteed to not cross a 128 byte boundary if itis smaller than 128 bytes It will starton a 128 byte boundary if itis larger than 128 bytes A blocked data section is guaranteed to not cross a 128 word page boundary if it is smaller than a page It will start on a page boundary if itis larger than a page This directive allows specification of blocking for initialized sections only not uninitialized sections declared with usect or the bss directives The section names may optionally be enclosed in quotes This example designates the text and data sections for blocking d ccc ck ck ck ck ck ck 0k 0k 0k 0k 0k 0k 0k 0k 0k 0k 0k ke ke kv ko ko ko ko ko ko kx kx X 2 Specify blocking for the text dew 3 and data sections e 4 5 Sblock text data Syntax Description Example Assign Characte
162. Memory and ROM Widths i 13 5 C55x Memory Configuration Example i 13 6 Varying the Word Order 0 ccc een e nee e eens 13 7 The infile out File From Example 13 1 Partitioned Into Four Output Files 13 8 Sample Command File for Booting From a C55x EPROM 000000 13 9 Hex Command File for Avoiding a Hole at the Beginning of a Section 13 10 ASCII Hex Object Format 4 13 11 Intel Hex Object Format 5 Contents XV Contents 18 12 Motorola S Format oe 13 13 Tl Tagged Object Format 0 cece e 13 14 Extended Tektronix Object Format i A 1 COFF File StrUct re aa iuo etica bcr feet Feder Godan Y aduer abate e eet dados A 2 COFF Object File sa a ce os tues IURE md E par ting deg eta eee ie UL ad A 3 Section Header Pointers for the text Section A 4 Line Number Blocks es A 5 LEinesNumber Entries i ree rk Rr wb aie CR C baa Gawain A 6 Symbol Table Contents i A 7 Symbols for Blocks sn 0 0 0 0 cece ann A 8 Symbols for Functions 1 A 9 String Table sei exe terr dane EMG ddan yeaa cd d gates ane oa xvi 3 1 Operators Used in Expressions Precedence ssssseeelesseeessssseeen 3 2 Assembler Built In Math Functions i 3 3 Symbol AUIDUTeS so a pu domed ie Does eek duet rs ache Beane a Wa deg ands 4 1 Assembler Directives Summary 4 4 2 Memory Mapped Registers 200 c eee ee ee n 5 1 Functions and Return Values 300 233 i on ED n 5 2 Creating Macr
163. O cinit RO vectors gt VECTOR data gt RA bss gt RA Sysmem gt RA Stack gt RA Sysstack gt RA cio gt RA If the input files contain initialized named sections the linker allocates them into program memory following the data section If the input files contain uninitialized named sections the linker allocates them into data memory fol lowing the bss section You can override this by specifying an explicit PAGE in the SECTIONS directive If you use a SECTIONS directive the linker performs no part of the default allocation Allocation is performed according to the rules specified by the SECTIONS directive and the general algorithm described in subsection 9 13 2 General Rules for Output Sections Linker Description 9 55 Default Allocation Algorithm 9 13 2 General Rules for Output Sections An output section can be formed in one of two ways Rule 1 As the result of a SECTIONS directive definition Rule 2 By combining input sections with the same names into an out put section that is not defined in a SECTIONS directive If an output section is formed as a result of a SECTIONS directive rule 1 this definition completely determines the section s contents See Section 9 9 The SECTIONS Directive on page 9 32 for examples of how to define an output section s content An output section can also be formed when input sections are not specified by a SECTIONS directive rule 2 In this case the linke
164. PAGE 0 since no page is specified XROM and XRAM are on PAGE 1 Note that XROM on PAGE 1 overlays ROM on PAGE 0 and XRAM on PAGE 1 overlays RAM on PAGE 0 In the output link map obtained with the m linker option the listing of the memory model is keyed by pages This provides an easy method of verifying that you specified the memory model correctly Also the listing of output sections has a PAGE column that identifies the memory space into which each section will be loaded Default Allocation Algorithm 9 13 Default Allocation Algorithm The MEMORY and SECTIONS directives provide flexible methods for building combining and allocating sections However any memory locations or sections that you choose not to specify must still be handled by the linker The linker uses default algorithms to build and allocate sections within the specifications you supply Subsections 9 13 1 Allocation Algorithm and 9 13 2 General Rules for Output Sections describe default allocation 9 13 1 Allocation Algorithm If you do not use the MEMORY and SECTIONS directives the linker allocates output sections as though the following definitions are specified Example 9 13 Default Allocation for TMS320C55x Devices MEMORY ROM RIX origin 0100h length OFEFFh VECTOR RIX origin OFFFF00h length 0100h RAM RWIX origin 010100h length OFFFFh SECTIONS text gt RO Switch RO const gt R
165. PPLICATIONS IS UNDERSTOOD TO BE FULLY AT THE CUSTOMER S RISK In order to minimize risks associated with the customer s applications adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards Tl assumes no liability for applications assistance or customer product design TI does not warrant or represent that any license either express or implied is granted under any patent right copyright mask work right or other intellectual property right of TI covering or relating to any combination machine or process in which such semiconductor products or services might be or are used Tl s publication of information regarding any third party s products or services does not constitute Tl s approval warranty or endorsement thereof Copyright 2000 Texas Instruments Incorporated About This Manual Preface Read This First The TMS320C55x Assembly Language Tools User s Guide tells you how to use these assembly language tools D D UD D D C Assembler Archiver Linker Absolute lister Cross reference lister Hex conversion utility How to Use This Manual The goal of this book is to help you learn how to use the Texas Instruments assembly language tools specifically designed for the TMS320C55x DSPs This book is divided into four parts d Introductory information gives you an overview of the assembly language development tools and also discusses common object file for
166. RMS mode informs the assembler that the ARMS status bit will be enabled during the execution of this source file By default the assembler assumes that the bit is disabled Assembler Description 3 5 Invoking the Assembler r S U X controls the severity of diagnostic messages printed for bus conflicts between parallel instructions By de fault bus conflicts are reported as errors When the mb option is used bus conflicts will be reported as warnings CPL mode informs the assembler that the CPL sta tus bit will be enabled during the execution of this source file This causes the assembler to enforce the use of SP relative addressing syntax By default the assembler assumes that the bit is disabled C54x compatibility mode informs the assembler that the C54CM status bit will be enabled during the exe cution of this source file By default the assembler assumes that the bit is disabled causes the assembler to use the largest P24 form of certain variable length instructions By default the assembler tries to resolve all variable length instruc tions to their smallest size suppresses assembler warning messages Sup ported for asm55 only quiet suppresses the banner and all progress information rnum suppresses the assembler remark identified by num A remark is an informational assembler message that is less severe than a warning If you do not specify a value for num all remar
167. RO FP asg AR1 Ind asg AR1 0b Rc_Prop asg string strng asg a b c parms frame pointer indirect addressing reverse carry propagation string parameters m Ne Ne Ne Ne Ne The eval directive performs arithmetic on numeric substitution symbols The syntax of the eval directive is eval well defined expression substitution symbol The eval directive evaluates the expression and assigns the string value of the result to the substitution symbol If the expression is not well defined the assembler generates an error and assigns the null string to the symbol Example 5 4 shows arithmetic being performed on substitution symbols Example 5 4 The eval Directive asg 1 counter loop 100 word counter eval counter 1 counter endloop In Example 5 4 the asg directive could be replaced with the eval directive without changing the output In simple cases like this you can use eval and asg interchangeably However you must use eval if you want to calculate a value from an expression While asg only assigns a character string to a substitution symbol the eval directive evaluates an expression and assigns the character string equivalent to a substitution symbol 5 3 2 Built In Substitution Symbol Functions The following built in substitution symbol functions enable you to make decisions based on the string value of substitution symbols These functions always retur
168. ROMS Directive on page 13 15 For both methods use a value that is a power of 2 greater than or equal to 8 You should change the memory width default value of 16 only in exceptional situations for example when you need to break single target words into consecutive narrower memory words Situations in which memory words are narrower than target words are most common when you use on chip boot loaders several of which support booting from narrower memory For exam ple a 16 bit TMS320C55x can be booted from 8 bit memory or an 8 bit serial port with each 16 bit value occupying two memory locations this would be specified as memwidth 8 Hex Conversion Utility Description 13 9 Understanding Memory Widths Figure 13 3 demonstrates how the memory width is related to the data width Figure 13 3 Data and Memory Widths Source file word OAABBh word 01122h Data width 16 fixed Data after OAABBh phase of hex utility QlLZ2 ia Memory widths variable data width 16 memwidth 16 default memwidth 8 Data after phase II of hex utility 13 4 4 ROM Width ROM width specifies the physical width in bits of each ROM device and corre sponding output file Usually one byte or eight bits The ROM width deter mines how the hex conversion utility partitions the data into output files After the target words are mapped to the memory words the memory words are bro ken into one or more
169. SCII hexadecimal formats suitable for loading into an EPROM programmer high level language debugging The ability of a compiler to retain sym bolic 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 actual code or data incremental linking Linking files that will be linked in several passes Often this means a very large file that will have sections linked and then will have the sections linked together initialized section A COFF section that contains executable code or initial ized data An initialized section can be built up with the data text or sect directive input section A section from an object file that will be linked into an executable module label A symbol that begins in column 1 of a source statement and corre sponds to the address of that statement line number entry An entry in a COFF output module that maps lines of assembly code back to the original C source file that created them linker A software tool that combines object files to form an object module that can be allocated into TMS320C55x system memory and executed by the device listing file An output file created by the assembler that lists source state ments their line numbers and their effects on the SPC loader A device thatloads an executable module into TMS320C55x system
170. STAT Bytes 8 11 of a symbol table entry indicate a symbol s value A symbol s value depends on the symbol s storage class Table A 13 summarizes the storage classes and related values Table A 13 Symbol Values and Storage Classes Storage Class Value Description C AUTO C EXT C STAT C REG C LABEL C MOS C ARG C STRTAG C MOU Stack offset in bits C UNTAG Relocatable address C TPDEF Relocatable address C ENTAG Register number C MOE Relocatable address C REGPARM Offset in bits C FIELD Stack offset in bits C BLOCK 0 C FCN Offset in bits C FILE Storage Class Value Description Enumeration value Register number Bit displacement Relocatable address Relocatable address 0 If asymbol s storage class is C FILE the symbol s value is a pointer to the next file symbol Thus the file symbols form a one way linked list in the symbol table When there are no more file symbols the final file symbol points back to the first file symbol in the symbol table The value of a relocatable symbol is its virtual address When the linker relocates a section the value of a relocatable symbol changes accordingly Common Object File Format A 19 Symbol Table Structure and Content A 7 6 Section Number Bytes 12 13 of a symbol table entry contain a number that indicates which section the symbol was defined in Table A 14 lists these numbers and the sections they indicate Table A 14 Section Numbers A 7 7 Ty
171. Section 13 3 Command Files on page 13 6 The general syntax for the SECTIONS directive is SECTIONS sname paddr value sname paddrzboot sname boot Hex Conversion Utility Description 13 21 The SECTIONS Directive 13 22 SECTIONS begins the directive definition sname identifies a section in the COFF input file If you specify a sec tion that doesn t exist the utility issues a warning and ignores the name paddr specifies the physical ROM address at which this section should be located This value overrides the section load address given by the linker See Section 13 10 Controlling the ROM Device Address on page 13 33 This value must be a decimal octal or hexadecimal constant It can also be the word boot to indicate a boot table section for use with the on chip boot loader f your file contains multiple sections and if one section uses a padar parameter then all sections must use a paddr parameter z boot configures a section for loading by the on chip boot loader This is equivalentto using paddrzboot Boot sections have a physi cal address determined both by the target processor type and by the various boot loader specific command line options The commas separating section names are optional For more similarity with the linker s SECTIONS directive you can use colons after the section names in place of the equal sign on the boot keyboard For example the following statements are equival
172. Sections 2 2 6 An Example That Uses Sections Directives Example 2 1 shows how you can build COFF sections incrementally using the sections directives to swap back and forth between the different sections You can use sections directives to begin assembling into a section for the first time or to continue assembling into a section that already contains code In the latter case the assembler simply appends the new code to the code that is already in the section The format in Example 2 1 is a listing file Example 2 1 shows how the SPCs are modified during assembly A line in a listing file has four fields Field 1 contains the source code line counter Field 2 contains the section program counter Field 3 contains the object code Field 4 contains the original source statement Introduction to Common Object File Format 2 9 How the Assembler Handles Sections Example 2 1 Using Sections Directives 2 10 2 3 Assemble an initialized table into data 4 KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKKA KKK KKK ko ko ko 5 000000 data 6 000000 0011 coeff word O11h 022h 033h 000001 0022 000002 0033 7 KKK KKK KKK KKK KKK KKK KK ck ck ck ck KK ck ck ck ck ck ck ck ook ck ck ck kk ck Sk KKK ko ko ko 8 e Reserve spac
173. Symbol Expansion Listing SSlist expands substitution symbols in the listing This is useful for debugging the expansion of substitution symbols The ex panded line appears below the actual source line Ssnolist turns off substitution symbol expansion in the listing For substitution symbol expansion listing ssnolist is the default Directive Listing drlist causes the assembler to print to the listing file all directive lines drnolist suppresses the printing of the following directives in the list ing file asg eval var sslist mlist fclist ssnolist mnolist fcnolist emsg wmsg mmsg length width and break For directive listing drlist is the default Macro Language 5 21 Using Recursive and Nested Macros 5 9 Using Recursive and Nested Macros The macro language supports recursive and nested macro calls This means that you can call other macros in a macro definition You can nest macros up to 32 levels deep When you use recursive macros you call a macro from its own definition the macro calls itself When you create recursive or nested macros you should pay close attention to the arguments that you pass to macro parameters because the assembler uses dynamic scoping for parameters This means that the called macro uses the environment of the macro from which it was called Example 5 15 shows nested macros Note that the y in the in block macro hides the y in the out block macro The x and z
174. TMS320C55x Assembly Language Tools User s Guide Literature Number SPRU280B April 2000 xta PUTET TEXAS is 2 SOYINK m INSTRUM ENTS Printed on Recycled Paper IMPORTANT NOTICE Texas Instruments and its subsidiaries Tl reserve the right to make changes to their products or to discontinue any product or service without notice and advise customers to obtain the latest version of relevant information to verify before placing orders that information being relied on is current and complete All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgement including those pertaining to warranty patent infringement and limitation of liability TI warrants performance of its semiconductor products to the specifications applicable at the time of sale in accordance with Tl s standard warranty Testing and other quality control techniques are utilized to the extent Tl deems necessary to support this warranty Specific testing of all parameters of each device is not necessarily performed except those mandated by government requirements CERTAIN APPLICATIONS USING SEMICONDUCTOR PRODUCTS MAY INVOLVE POTENTIAL RISKS OF DEATH PERSONAL INJURY OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE CRITICAL APPLICATIONS TI SEMICONDUCTOR PRODUCTS ARE NOT DESIGNED AUTHORIZED OR WARRANTED TO BE SUITABLE FOR USE IN LIFE SUPPORT DEVICES OR SYSTEMS OR OTHER CRITICAL APPLICATIONS INCLUSION OF TI PRODUCTS IN SUCH A
175. Target width 16 fixed 01122h Memory widths variable memwidth 8 memwidth 8 order LS default order MS 13 14 The ROMS Directive 13 5 The ROMS Directive The ROMS directive specifies the physical memory configuration of your system as a list of address range parameters Each address range produces one set of files containing the hex conversion utility output data that corresponds to that address range Each file can be used to program one single ROM device The ROMS directive is similar to the MEMORY directive of the TMS320C55x linker both define the memory map of the target address space Each line entry in the ROMS directive defines a specific address range The general syntax is ROMS PAGE n romname origin value length value romwidth va ue memwidth va ue fillz value filesz filename 1 filename2 romname origin value length value romwidth va ue memwidth va ue fill va ue files filename 1 filename2 ROMS begins the directive definition PAGE identifies a memory space for targets that use program and data address spaces If your program has been linked nor mally PAGE 0 specifies program memory and PAGE 1 speci fies data memory Each memory range after the PAGE com mand belongs to that page until you specify another PAGE If you don t include PAGE all ranges belong to page 0 romname identifies a memory range The name of the memory
176. These names are of the form nfake where n is an integer The compiler begins numbering these symbol names at 0 Common Object File Format A 15 Symbol Table Structure and Content A 7 1 1 Symbols and Blocks In C a block is a compound statement that begins and ends with braces A block always contains symbols The symbol definitions for any particular block are grouped together in the symbol table and are delineated by the bb eb special symbols Blocks can be nested in C and their symbol table entries can be nested correspondingly Figure A 7 shows how block symbols are grouped in the symbol table Figure A 7 Symbols for Blocks Symbol Table Block 1 bb Symbols for block 1 eb Block 2 bb symbols for block 2 A 7 1 2 Symbols and Functions The symbol definitions for a function appear in the symbol table as a group delineated by bf ef special symbols The symbol table entry for the function name precedes the bf special symbol Figure A 8 shows the format of symbol table entries for a function Figure A 8 Symbols for Functions function name bf symbols for the function e If a function returns a structure or union a symbol table entry for the special symbol target will appear between the entries for the function name and the bf special symbol Symbol Table Structure and Content A 7 2 Symbol Name Format The first eight bytes of a symbol table entry bytes 0 7 indicate
177. To ensure that an interrupt will work you can preserve the entire list of registers Or you can simply preserve the register s used 1 Assemble the ISR using masm55 with the option to generate a listing file 2 Check the listing to see if it includes any one to many instruction map pings These mappings are marked by a PORT comment For more information see Section 6 2 Understanding the Listing File on page 6 4 3 Determine if the one to many mappings actually use any of the temporaries listed in Section 7 2 2 If so the appropriate register or bit must be pushed on the stack at the beginning of the ISR and popped off the stack at the end Note that you may refer to C55x register names within C54x instruction mnemonics For example LD AR2 AC3 7 1 3 Other Issues Related to Interrupts You should be aware of the interrupt issues described below When the assembler encounters RETE RETED FRETE FRETED RETF or RETFD a warning will be issued With these instructions the assembler is processing an interrupt service routine or the interrupt vector table itself and may not be able to port the instructions correctly INTR has the same mnemonic syntax for both C54x and C55x Consequently the assembler cannot distinguish when an instruction is intended for a native C55x interrupt which is acceptable or for a C54x interrupt for which the interrupt number would be wrong If your code writes values to IPTR
178. When an operation overflows into the guard bits and then a left shift clears the guard bits the C54x has the value of zero while the C55x has a saturated value The C54x and C55x mnemonic assembly languages differ significantly in the representation of instruction parallelism The C55x implements two types of parallelism implied parallelism within a single instruction using the operator and user defined parallelism between two instructions using the operator The C54x implements only one type of parallelism which is analogous to implied parallelism on the C55x However C54x parallelism uses parallel bars as its operator C55x parallelism is documented in the TMS320C55x DSP Mnemonic Instruction Set Reference Guide Migrating a C54x System to a C55x System 7 19 Additional C54x Issues 7 20 When using indirect access with memory mapped access instructions such as STM 0x1234 AR2 the C54x masks the upper 9 bits of the ARn register This masking effectively occurs both before and after the post increment to AR2 For example AR2 0x127f STM 0x1234 AR2 access location Ox7f AR2 0x7f 1 amp 7 gt 0 However the C55x assembler maps this as AND 0x7f AR2 MOV 0x1234 AR2 note no masking afterward to account for the possibility of a memory mapped address for AR2 Chapter 8 Archiver Description The TMS320C55x archiver combines several individual files into a
179. a type This name must have been previously declared by a stag etag or utag directive Dims may be one to four expressions separated by commas This allows up to four dimensions to be specified for the member The order of parameters is significant The name and value are required parameters All other parameters may be omitted or empty Adjacent commas indicate an empty entry This allows you to skip a parameter and specify a parameter that occurs later in the list Operands that are omitted or empty assume a null value Following is an example of a C structure definition and the corresponding as sembly language statements C source struct doc char title char group int job_number doc_info Resulting assembly language code stag _doc 48 member _title 0 2 8 16 member _group 16 2 8 16 member job number 32 4 8 16 eos Symbolic Debugging Directives B 7 stag etag utag eos Define a Structure Syntax Description Example 1 Stag name size member definitions eos etag name size member definitions eos utag name size member definitions eos The stag directive begins a structure definition The etag directive begins an enumeration definition The utag directive begins a union definition The eos directive ends a structure enumeration or union definition fied The stag etag or utag directive should be followed by a number of member directives whi
180. a colon Hex Conversion Utility Description 13 41 Description of the Object Formats 13 11 5 Extended Tektronix Object Format x Option The Tektronix object format supports 32 bit addresses and has two types of records data record contains the header field the load address and the object code termination record signifies the end of a module The header field in the data record contains the following information Number of ASCII Item Characters Description 96 1 Data type is Tektronix format Block length 2 Number of characters in the record minus the 96 Block type 1 6 data record 8 termination record Checksum 2 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 charac ters per byte Figure 13 14 illustrates the Tektronix object format Figure 13 14 Extended Tektronix Object Format Checksum 21h 1 5 6 8 1 0 0 0 0 0 0 0 2 0 2 04 2 0 2 0 2 0 2 0 Block length 15hs21 r Object code 6 bytes Fd o 1 Header 815621810000000202020202020 character L Load address 10000000h Blocktype 6 Length of data load address 13 42 Hex Conversion Utility Error Messages 13 12 Hex Conversion Util
181. a mnemonic and operands the mnemonic word is reserved 3 6 6 Comment Field Acomment can begin in any column and extends to the end of the source line Acommentcan contain any ASCII character including blanks Comments are printed in the assembly source listing but they do not affect the assembly A source statement that contains only a commentis valid If it begins in column 1 it can start with a semicolon or asterisk Comments that begin any where else on the line must begin with a semicolon The asterisk identifies a comment only if it appears in column 1 3 7 Constants Constants The assembler supports six types of constants Binary integer Octal integer Decimal integer Hexadecimal integer Character Assembly time Floating point O G O O O O L The assembler maintains each constant internally as a 32 bit quantity Constants are not sign extended For example the constant OFFH is equal to OOFF base 16 or 255 base 10 it does not equal 1 In general in C55x algebraic assembly source code constants must begin with a 3 7 1 Binary Integers A binary integer constant is a string of up to 16 binary digits 0s and 1s followed by the suffix B or b If fewer than 16 digits are specified the assembler right justifies the value and zero fills the unspecified bits These are examples of valid binary constants 00000000B Constant equal to 049 or 046 0100000b Constant equal to 3240 or 2046 01b C
182. a new word 0 ck ck ck ck ck kk ck ck ck ck ck ck ck ck ck ck Ck 0k 0k 0k 0k kk ke kv ko ko ko kokok 11 000001 5000 LF field OAh 5 12 13 ck ck ck kk kk ck ck ck ck ck ck ck ck ck ck 0k 0k 0k 0k ck ko kk kv ko ko ko ko 14 ER Initialize a 4 bit field 15 TUE in the same word WE 16 17 000001 5600 x field OCh 4 18 19 ck ck ck ck ck ck kk ck ck ck ck ck ck ck ck ck Ck 0k 0k 0k 0k ko ke kv kv ko ko ko kokok 20 xk 16 bit relocatable field EE 21 a in the next word KK 22 23 000002 0001 field x 24 25 ck ck ck cec ck ck ck ck ck ck ck ck ck 0k 0k 0k 0k 0k kk ke ko ko ko ko kokok 26 ax Initialize a 32 bit field UE 27 28 000003 0000 field 04321h 32 000004 4321 Assembler Directives 4 51 field Initialize Field Figure 4 6 shows how the directives in this example affect memory Figure 4 6 The field Directive Word Code 15 0 a 0 00101010111100 field OABCh 14 Fr 14 bit field b 0 00101010111100 00 field 00Ah 5 1 61016 v 5 bit field c 1 01010 1100 field 000Ch 4 4 bit field 01
183. a nine bit field in the PMST indicating the location of the interrupt vector table you will need to modify your code to reflect the changes in the C55x system Using Ported C54x Functions with Native C55x Functions 7 2 Using Ported C54x Functions with Native C55x Functions When rewriting a C54x application to be completely C55x consider working on one function at a time continually testing If you encounter a problem you can easily find it in the changes recently made Throughout this process you will be working with both ported C54x code and native C55x code Keep the following in mind J Avoid mixing C54x and C55x instructions within the same function Transitions between ported C54x instructions and native C55x instructions should occur only at function calls and returns J The C compiler provides an automatic solution when you are dealing with C code calling assembly However see the example in Section 7 2 6 for a detailed description of using a veneer function when calling a ported C54x assembly function from C code 7 2 1 Runtime Environment for Ported C54x Code A runtime environment is the set of presumptions and conventions that govern the use of machine resources such as registers status register bit settings and the stack The runtime environment used by ported C54x code differs from the environment used by native C55x code When you execute ported C54x code from reset the appropriate runtime
184. a warning when it encounters a section that contains an ivec directive and an instruction larger than 4 bytes This prevents you from overfilling the last 4 bytes of an interrupt vector with an instruction that is too big The assembler also issues a warning when it encounters more than one instruction immediately after an ivec Only one instruction is executed before branching to the ISR Assembler Directives 4 63 ivec Initialize Interrupt Table Entries Asection containing an ivec directive is marked as an interrupt vector section The linker can recognize such sections and does not add a non parallel NOP at the end of it as it does for normal code sections Example This example shows the use of the ivec directive Sect vectors start vectors section ref start nmi isr isr2 symbols referenced from other files def rsv no isr symbols defined in this file rsv ivec start cb4x stk C54x compatibility Stack mode nmi ivec nmi isr Standard usage int2 ivec isr2 PSH ARO executed just before branch to isr2 int3 ivec one way to skip a vector int4 ivec no isr better way to skip a vector and so on Fill out all 32 vectors int31 ivec no isr last vector Lext change to text section no isr B no isr default ISR Note the difference between int3 and int4 If the int3 vector is raised the exam ple branches to 0 with unpredictable results However if the int4 vector is raised the example br
185. a wide word into consecutive memory locations in the same hex conversion utility output file order MS specifies big endian ordering in which the most significant part of the wide word occupies the first of the consecutive locations order LS specifies little endian ordering in which the the least signifi cant part of the wide word occupies the first of the consecutive locations By default the utility uses little endian format because the C55x boot loaders expect the data in this order Unless you are using your own boot loader pro gram avoid using order MS Hex Conversion Utility Description 13 13 Understanding Memory Widths Note When the order Option Applies LI This option applies only when you use a memory width with a value less than 16 Otherwise order is ignored _ This option does not affect the way memory words are split into output files Think of the files as a set the set contains a least significant file and a most significant file but there is no ordering over the set When you list filenames fora set offiles you alwayslistthe least significant first regard less of the order option Figure 13 6 demonstrates how order affects the conversion process This figure and the previous figure Figure 13 4 explain the condition of the data in the hex conversion utility output files Figure 13 6 Varying the Word Order Source file word OAABBh word 01122h
186. able A 5 lists the flags that can appear in the section header The flags can be combined For example if the flag s byte is set to 024h both STYP GROUP and STYP TEXT are set Table A 5 Section Header Flags Mnemonic Flag STYP REG 0000h STYP DSECT 0001h STYP NOLOAD 0002h STYP GROUP 0004h STYP PAD 0008h STYP COPY 0010h STYP TEXT 0020h STYP DATA 0040h STYP BSS 0080h STYP CLINK 4000h Note Section Header Structure Description Regular section allocated relocated loaded Dummy section relocated not allocated not loaded Noload section allocated relocated not loaded Grouped section formed from several input sections Padding section loaded not allocated not relocated Copy section relocated loaded but not allocated relo cation and line number entries are processed normally Section that contains executable code Section that contains initialized data Section that contains uninitialized data Section that is conditionally linked The term oaded means that the raw data for this section appears in the object file Common Object File Format A 7 Section Header Structure Figure A 3 illustrates how the pointers in a section header would point to the elements in an object file that are associated with the text section Figure A 3 Section Header Pointers for the text Section text 0 7 8 11 12 15 16 19 20 23 24 27 28 31 32 33 34 35 36 37 38 39 Section Header text raw data
187. absolute lister remember that you must use the a option when you invoke the assembler masm55 a modulel abs masm55 a module2 abs This creates two listing files called module1 Ist and module2 Ist no object code is produced These listing files are similar to normal listing files however the addresses shown are absolute addresses The absolute listing files created are module1 Ist see Figure 10 2 and module2 Ist see Figure 10 3 Absolute Lister Example Figure 10 2 module1 lst TMS320C55x COFF Assembler Version x xx Wed Oct 16 12 00 05 2000 Copyright c 2000 Texas Instruments Incorporated modulel abs PAGE 1 21 002000 text 22 COPY modulel asm A 1 Copy globals def B Wb global dflag B 2 global array B 3 global offset A 2 002000 text A 3 004000 bss array 100 A 4 004064 bss dflag 2 A 5 002000 6B40 MOV offset ACO 002002 6680 A 6 002004 A000 MOV dflag ACO No Errors No Warnings Figure 10 3 module2 Ist TMS320C55x COFF Assembler Version x xx Wed Oct 16 12 00 17 200 Copyright c 2000 Texas Instruments Incorporated module2 abs PAGE 21 002006 text COpy module2 asm Copy globals def global dflag global array global offset 004066 bss offset 2 002006 6B40 MOV foffset ACO 002008 6680 00200a 6B40 MOV array ACO 00200c 0080 A B B B A A Errors No Warnings Absolute Lister Description 10 9 Chapter 11 Cross Reference Lister Description The cro
188. ace 16 bit values 10 1 abc and a into memory short is used to place 16 bit values 8 3 def and b into memory The label STRN has the value 106h which is the location of the first initialized word 1 000000 data 2 000000 Space 100h 16 3 4 000100 000A half 10 1 abc a 000101 FFFF 000102 0061 000103 0062 000104 0063 000105 0061 5 000106 0008 STRN Short 8 3 def b 000107 FFFD 000108 0064 000109 0065 00010a 0066 00010b 0062 4 58 Syntax Description Assign Character Strings to Substitution Symbols if elseitf else endif if well defined expression elseif well defined expression else endif The following directives provide conditional assembly The if directive marks the beginning of a conditional block The well defined expression is a required parameter _j If the expression evaluates to true nonzero the assembler assembles the code that follows the expression up to a elseif else or endif DD If the expression evaluates to false 0 the assembler assembles code that follows a elseif if present else if present or endif if no elseif or else is present The elseif directive identifies a block of code to be assembled when the if expression is false 0 and the elseif expression is true nonzero When the elseif expression is false the assembler continues to the next elseif if pres ent else if present or endif if no elseif or else is
189. adecimal constants 0x78 Constant equal to 12010 or 007816 OxOF Constant equal to 1549 or 000F46 0x37AC Constant equal to 14 25249 or 37AC46G 3 7 5 Character Constants A character constant is a string of one or two characters enclosed in single quotes The characters are represented internally as 8 bit ASCII characters Two consecutive single quotes are required to represent each single quote that is part of a character constant A character constant consisting only of two single quotes is valid and is assigned the value 0 If only one character is speci fied the assembler right justifies the bits These are examples of valid charac ter constants a Represented internally as 6146 C Represented internally as 4346 D Represented internally as 2 74446 Constants Note the difference between character constants and character strings Section 3 8 Character Strings on page 3 24 discusses character strings Acharacter constant represents a single integer value a string is a list of char acters 3 7 6 Floating Point Constants A floating point constant is a string of decimal digits followed by an optional decimal point fractional portion and exponent portion The syntax for a floating point number is i nnn nnn Ele nnn J Replace nnn with a string of decimal digits You can precede nnn with a or a You must specify a decimal point For example 3 e5 is valid but 3e5 is not valid The exponent
190. align the section so that individual alignments remain intact when a section is loaded into memory This example shows several types of alignment including even align 4 and a default align 1 000000 data 2 000000 0004 word 4 3 even 4 000002 0045 string Errorcent 000009 0074 5 align 6 000080 6000 field 343 7 000080 6A00 field 5 4 8 align 2 9 000082 6000 field 344 10 align 8 11 000088 5000 field 5 4 12 align 13 000100 0004 word 4 Assembler Directives 4 27 arms_on arms_ off Syntax Description Select Indirect Addressing Mode arms_on arms_off The arms on and arms off directives model the ARMS status bit The assembler cannot track the value of the ARMS status bit You must use the assembler directives and or command line options to communicate the value of this mode bit to the assembler An instruction that modifies the value of the ARMS status bit must be immediately followed by the appropriate as sembler directive The arms on directive models the ARMS status bit set to 1 it is equivalent to using the ma command line option The arms off directive models the ARMS status bit set to 0 In the case of a conflict between the command line option and the directive the directive takes precedence By default arms off the assembler uses indirect memory access modifiers targeted to the assembly code In ARMS mode arms on the assembler uses short offset modifiers for
191. alue uchar value value uhalf value valuen ushort value value Uint value valuen ulong value value uword value values word value valuen xfloat value values Xlong value value Description Reserve size bits in the current section note that a label points to the last addressable word in the reserved space Initialize one or more successive bytes or words in the current section Initialize one or more 64 bit IEEE double precision floating point constants Initialize a variable length field Initialize one or more 32 bit IEEE single precision floating point constants Initialize one or more 16 bit integers Initialize one or more 16 bit integers Initialize one or more 32 bit integers Initialize one or more text strings packed Reserve size bits in the current section note that a label points to the beginning of the reserved space Initialize one or more text strings Initialize one or more successive bytes or words in the current section Initialize one or more unsigned 16 bit integers Initialize one or more unsigned 16 bit integers Initialize one or more unsigned 32 bit integers Initialize one or more unsigned16 bit integers Initialize one or more 16 bit integers Initialize one or more 32 bit IEEE single precision floating point constants but do not align on long word boundary Initialize one or more
192. am Each memory range has a name a starting address and a length By default the linker uses a single address space on PAGE 0 However the linker allows you to configure separate address spaces by using the MEMORY directive s PAGE option The PAGE option causes the linker to treat the specified pages as completely separate memory spaces C55x supports as many as 255 PAGES but the number available to you depends on the configuration you have chosen When you use the MEMORY directive be sure to identify all the memory ranges that are available for object code Memory defined by the MEMORY directive is configured memory any memory that you do not explicitly account for with the MEMORY directive is unconfigured memory The linker does not place any part of a program into unconfigured memory You can represent non existent memory spaces by simply not including an address range in a MEMORY directive statement The MEMORY Directive The MEMORY directive is specified in a command file by the word MEMORY uppercase followed by a list of memory range specifications enclosed in braces The MEMORY directive in Example 9 3 defines a system that has 4K bytes of ROM at byte address 1C00h 32 bytes of RAM at byte address 60h and 4K bytes at byte address 80h Example 9 3 The MEMORY Directive MEMORY directive
193. ame register used as destination of both instructions Same register used as multiple destinations of the instruction Description These are warnings about problems with parallel instructions Action Correct the source per the error message text A branch to an empty label just inside the loop closing brace is a branch out of the loop Large model not available ignored Open branch delay slot at end of section Overriding previous definition Power of 2 required next larger power of 2assumed Section name absolute address set to 0 Unknown model parameter Value truncated to 8 bit size Description These are general warnings Action Correct the source per the warning message text Assembler Error Messages Any or all of the R500n messages can be suppressed with the r option see Section 3 3 on page 3 4 or with the noremarks directive see page 4 80 Possible dependence in delay slot of RPTBD be sure delay instructions do not modify repeat control registers Description This message occurs when the instructions in the delay slots of a C54x RPTBD instruction perform indirect memory references Action If these instructions modify the REA or RSA repeat address control registers the C55x instructions used to implement RPTBD will not work If the instructions do not modify REA or RSA you can either ignore this message or rewrite your code to use RTPB Ignoring RSBX CMPT instruction Description This C54x instruction d
194. an be allocated contiguously into memory Initialized subsections can be created with the sect directive The assembler treats initialized subsections in the same manner as initialized sections See subsection 2 2 4 Subsections on page 2 8 for more information on creating subsections How the Assembler Handles Sections 2 2 3 Named Sections Named sections are sections that you create You can use them like the de fault text data and bss sections but they are assembled separately For example repeated use of the text directive builds up a single text section in the object file When linked this text section is allocated into memory as a single unit Suppose there is a portion of executable code perhaps an initiali zation routine that you don t want allocated with text If you assemble this segment of code into a named section it is assembled separately from text and you can allocate it into memory separately You can also assemble initial ized data that is separate from the data section and you can reserve space for uninitialized variables that is separate from the bss section The following directives let you create named sections _j The usect directive creates sections that are used like the bss section These sections reserve space in RAM for variables The sect directive creates sections like the default text and data sections that can contain code or data The sect directive creates named sec
195. an be allocated separately or grouped with other sections using the same base name For example to create a subsection called func within the text section enter the following sect text func You can allocate func separately or with other text sections You can create two types of subsections D Initialized subsections are created using the sect directive See subsection 2 2 2 Initialized Sections on page 2 6 J Uninitialized subsections are created using the usect directive See subsection 2 2 1 Uninitialized Sections on page 2 4 Subsections are allocated in the same manner as sections See Section 9 9 The SECTIONS Directive on page 9 32 for more information 2 2 5 Section Program Counters The assembler maintains a separate program counter for each section These program counters are known as section program counters or SPCs An SPC represents the current address within a section of code or data Initially the assembler sets each SPC to 0 As the assembler fills a section with code or data it increments the appropriate SPC If you resume assembling into a section the assembler remembers the appropriate SPC s previous val ue and continues incrementing the SPC at that point The assembler treats each section as if it began at address 0 the linker relocates each section according to its final location in the memory map For more information see Section 2 4 Relocation on page 2 15 How the Assembler Handles
196. an input filename when you invoke the absolute lister the absolute lister will prompt you for one The absolute lister produces an output file for each file that was linked These files are named with the input filenames and an extension of abs Header files however do not generate a corresponding abs file Assemble these files with the a assembler option as follows to create the absolute listing masm55 a filename abs The e options affect both the interpretation of filenames on the command line and the names of the output files They should always precede any filename on the command line Absolute Lister Description 10 3 Invoking the Absolute Lister The e options are useful when the linked object file was created from C files compiled with the debugging option g compiler option When the debugging option is set the resulting linked object file contains the name of the source files used to build it In this case the absolute lister will not generate a corresponding abs file for the C header files Also the abs file corresponding to a C source file will use the assembly file generated from the C source file rather than the C source file itself For example suppose the C source file hello csr is compiled with debugging set this generates the assembly file hello s hello csr also includes hello hsr Assuming the executable file created is called hello out the following command will generate the proper abs file
197. anches to the no_isr spin loop which generates predict able results 4 64 Syntax Description Example Create a Relocatable Label label label symbol The label directive defines a special symbol that refers to the loadtime address rather than the runtime address within the current section Most sec tions created by the assembler have relocatable addresses The assembler assembles each section as if it started at 0 and the linker relocates it to the address at which it loads and runs For some applications itis desirable to have a section load at one address and run at a differentaddress For example you may wish to load a block of perfor mance critical code into slower off chip memory to save space and then move the code to high speed on chip memory to run it Such a section is assigned two addresses at link time a load address and a run address All labels defined in the section are relocated to refer to the run time address so that references to the section Such as branches are correct when the code runs The label directive creates a special label that refers to the loadtime address This function is useful primarily to designate where the section was loaded for purposes of the code that relocates the section This example shows the use of a loadtime address label Sect EXAMP label EXAMP LOAD load address of section START run address of section code FINISH run address of section e
198. arget memory to accomplish this task The MEMORY directive allows you to specify a model of target memory so that you can define the types of memory your system contains and the address ranges they occupy The linker maintains the model as it allocates output sections and uses it to determine which memory locations can be used for object code The memory configurations of TMS320C55x systems differ from application to application The MEMORY directive allows you to specify a variety of configurations After you use MEMORY to define a memory model you can use the SECTIONS directive to allocate output sections into defined memory Refer to Section 2 3 How the Linker Handles Sections on page 2 12 for details on how the linker handles sections Refer to Section 2 4 Relocation on page 2 15 for information on the relocation of sections 9 8 1 Default Memory Model The assembler enables you to assemble code for the TMS320C55x device The assembler inserts a field in the output file s header identifying the device The linker reads this information from the object file s header If you do not use the MEMORY directive the linker uses a default memory model specific to the named device For more information about the default memory model see subsection 9 13 1 Allocation Algorithm on page 9 55 9 8 2 MEMORY Directive Syntax The MEMORY directive identifies ranges of memory that are physically present in the target system and can be used by a progr
199. as Instruments Related Documentation From Texas Instruments Trademarks vi The following books describe the TMS320C55x devices and related support tools TMS320C55x Optimizing C Compiler User s Guide literature number SPRU281 describes the C55xx C compiler This C compiler accepts ANSI standard C source code and produces assembly language source code for the TMS320C55x device TMS320C55x DSP CPU Reference Guide SPRUS71 describes the architecture registers and operation of the CPU for these digital signal processors DSPs This book also describes how to make individual portions of the DSP inactive to save power TMS320C55x DSP Mnemonic Instruction Set Reference Guide SPRU374 describes the TMS320C55x digital signal processor mnemonic instructions individually This book also includes a summary of the instruction set a list of instruction opcodes and a cross reference to the algebraic instruction set TMS320C55x DSP Algebraic Instruction Set Reference Guide SPRU375 describes the TMS320C55x digital signal processor algebraic instructions individually This book also includes a summary of the instruction set a list of instruction opcodes and a cross reference to the mnemonic instruction set TMS320C55x DSP Programmer s Guide SPRU376 describes ways to optimize C code and assembly code for the TMS320C55x DSPs It also explains how to write code that uses special features and instructions of the DSP Code Composer U
200. as an integer constant following the fill option The width of the constant is assumed to be that of a word on the target processor For example for the C55x specifying fill OFFh results in a fill pattern of OOFFh The constant value is not sign extended The hex conversion utility uses a default fill value of zero if you don t specify a value with the fill option The fill option is valid only when you use image otherwise it is ignored 13 8 3 Steps to Follow in Image Mode 13 26 Step 1 Define the ranges of target memory with a ROMS directive See Section 13 5 The ROMS Directive on page 13 15 for details Step 2 Invoke the hex conversion utility with the image option To number the bytes sequentially use the byte option to reset the address origin to zero for each output file use the zero option See subsection 13 10 3 The byte Option on page 13 35 for details on the byte option and page 13 34 for details on the zero option If you don t specify a fill value with the ROMS directive and you want a value other than the default of zero use the fill option Building a Table for an On Chip Boot Loader 13 9 Building a Table for an On Chip Boot Loader Some DSP devices such as the C55x have a built in boot loader that initial izes memory with one or more blocks of code or data The boot loader uses a special table a boot table stored in memory such as EPROM or loaded from a device peripheral
201. assignment statement within an output section definition The assignment statement modifies the SPC denoted by by adding to it assigning a greater value to it or aligning it on an address boundary The operators expressions and syntaxes of assignment statements are described in Section 9 15 Assigning Symbols at Link Time on page 9 59 Linker Description 9 63 Creating and Filling Holes The following example uses assignment statements to create holes in output sections SECTIONS outsect filel obj text t 100h Create a hole with size 100h bytes file2 obj text align 16 Create a hole to align the SPC file3 obj text The output section outsect is built as follows O The text section from file1 obj is linked in The linker creates a 256 byte hole The text section from file2 obj is linked in after the hole d The linker creates another hole by aligning the SPC on a 16 byte boundary Finally the text section from file3 obj is linked in All values assigned to the symbol within a section refer to the relative adaress within the section The linker handles assignments to the symbol as if the section started at address 0 even if you have specified a binding address Consider the statement align 16 in the example This statement effectively aligns file3 obj text to start on a 16 byte boundary within outsect If outsect is ultimately allocated t
202. ation i 2 3 2 Placing Sections in the Memory Map i 2 4 Relocatlonm ee sen one a ee a 2 5 Runtime Relocation sn ed Vs 2 6 Loading a Program cee ie See eee a od de eo de Skin Bats 2 7 Symbols ina COFF File a na g cece teen eens 2 7 1 External Symbols 0000 cece a daa a a een eee eee eae 2 2 Whe Symbol Table ever i o dead Lakes Debate deeds Assembler Description 0000 0c cece eee eee eee nnn nnn Explains how to invoke the assembler and discusses source statement format valid constants and expressions and assembler output 3 4 Assembler Overview 06 eee eee eee ee B 2 3 2 Assembler Development Flow sss 3 3 3 3 Invoking the Assembler 3 4 vii Contents 3 4 C55x Assembler Features es 3 4 4 Byte Word Addressing 2 0c Dm iinis iinei da e eee 3 4 2 Parallel Instruction Rules i 3 4 8 Variable Length Instruction Size Resolution i 3 4 4 Memory Modes 0 3 5 Naming Alternate Files and Directories for Assembler Input 3 5 4 Using the i Assembler Option i 3 5 2 Using Environment Variables C55X A DIR and A DIR 3 6 Source Statement Format i 0 cece cence n 3 6 1 Source Statement Syntax ss saa 3 6 2 kabel Field 1 22 dctae a aana dade aee acea eee ae dd 3 6 3 Mnemonic Field el ee 3 6 4 Operand Field 0 cece a nn 3 65 Instruction Field 0 0 eee n 3 6 6 Comment Fleld ite dedeiadsee beanie E ORE S Re ni WO 3 7
203. ay also be preceded by a character that describes the symbol s attributes Table 11 1 lists these characters and names This hexadecimal number is the value assigned to the symbol after linking The statement number where the symbol is defined Theline number where the symbol is referenced If the line number is followed by an asterisk then that reference may modify the contents of the object If the line number is followed by a letter such as A B or C the symbol is referenced in a file specified by a include directive in the assembly source A is assigned to the first file specified by a include directive B is assigned to the second file etc A blank in this column indicates that the symbol was never used Cross Reference Lister Description 11 5 Cross Reference Listing Example Table 11 1 11 6 Symbol Attributes Character Meaning Symbol defined in a text section Symbol defined in a data section Symbol defined in a sect section Symbol defined in a bss or usect section Symbol defined in a reg section Chapter 12 Disassembler Description The COFF disassembler accepts object files and executable files as input and produces an assembly listing as output This listing shows assembly instructions their opcodes and the section program counter values The disassembly listing is useful for viewing Lj instruction size DD instruction encoding the results of a link Topic Page
204. be the input filename with an xrf extension Cross Reference Lister Description 11 3 Cross Reference Listing Example 11 3 Cross Reference Listing Example Symbol INIT Filename RTYP AsmVal LnkVal DefLn RefLn RefLn RefLn filel asm EDEF 000000 000080 3 1 file2 asm EREE 000000 000080 2 11 Symbol X Filename RTYP AsmVal LnkVal DefLn RefLn RefLn RefLn filel asm EREE 000000 000001 2 5 file2 asm EDEF 000001 000001 5 1 Symbol Y Filename RTYP AsmVal LnkVal DefLn RefLn RefLn RefLn file2 asm EDEF 000000 000080 7 1 Symbol Z Filename RTYP AsmVal LnkVal DefLn RefLn RefLn RefLn file2 asm EDEF 000003 000003 9 i Cross Reference Listing Example The terms defined below appear in the preceding cross reference listing Symbol Name Filename RTYP AsmvVal LnkVal DefLn RefLn Name of the symbol listed Name of the file where the symbol appears The symbol s reference type in this file The possible refer ence types are STAT The symbol is defined in this file and is not declared as global EDEF Thesymbolis defined in this file and is declared as global EREF The symbolis not defined in this file but is refer enced as a global UNDF The symbol is not defined in this file and is not declared as global This hexadecimal number is the value assigned to the symbol at assembly time A value m
205. below shows the directories that r lib and lib2 lib reside in how to setthe environment variable and how to use both libraries during a link Select the row for your operating system Pathname Invocation Command DOS UNIX ld and ld2 set C_DIR ld 1ld2 lnk55 fl obj f2 0bj L r lib 1 lib2 1lib ld and Id2 setenv C DIR ld 1d2 1nk55 fl obj f2 0bj 1 r lib 1 lib2 1lib Linker Description 9 15 Linker Options Note that the environment variable remains set until you reboot the system or reset the variable by entering Operating System Enter DOS set C DIR UNIX unsetenv C DIR The assembler uses an environment variable named A DIR to name alterna tive directories that contain copy include files or macro libraries If C DIR is not set the linker will search for object libraries in the directories named with A DIR Section 9 7 Object Libraries on page 9 26 contains more information about object libraries 9 4 10 Ignore Alignment Flags k Option The k option forces the linker to ignore any SECTIONS directive alignment specifications For more information on the SECTIONS directive see Section 9 9 The SECTIONS Directive 9 4 11 Create a Map File m filename Option The m option creates a linker map listing and puts it in filename The syntax for the m option is m filename Note that symbols in a data section are in words and symbols in a code section are in bytes The linker map des
206. ber 0 1 2 3 4 7 8 11 12 15 16 19 20 23 24 27 Type Short integer Short integer Long integer Long integer Long integer Long integer Long integer Long integer Description Magic number for SunOS or HP UX it is 108h for DOS it is 801h Version stamp Size in bytes of executable code Size in bytes of initialized data sections Size in bytes of uninitialized bss sec tions Entry point Beginning address of executable code Beginning address of initialized data Common Object File Format A 5 Section Header Structure A 4 Section Header Structure COFF object files contain a table of section headers that define where each section begins in the object file Each section has its own section header Table A 4 shows the section header contents for COFF files Table A 4 Section Header Contents Byte 0 7 8 11 12 15 16 19 20 23 24 27 28 31 32 35 36 39 40 43 44 45 46 47 Type Character Long integer Long integer Long integer Long integer Long integer Long integer Unsigned long Unsigned long Unsigned long Short Unsigned short Description 8 character section name padded with nulls Section s physical address Section s virtual address Section size in bytes File pointer to raw data File pointer to relocation entries File pointer to line number entries Number of relocation entries Number of line number entries Flags see Table A 5 Reserved Memory page number T
207. ber in the ROMS directive Ranges are numbered starting with 0 If there is no ROMS directive or only one range the utility omits this character c The file number in the set of files for the range starting with 0 for the least significant file For example assume coff out is for a 16 bit target processor and you are creating Intel format output With no output filenames specified the utility produces two output files named coff i0 and coff i1 If you include the following ROMS directive when you invoke the hex conversion utility you would have two output files ROMS rangel o 1000h 1 1000h range2 o 2000h 1 1000h These Output Files Contain This Data coff i01 1000h through 1FFFh coff i11 2000h through 2FFFh 13 24 Image Mode and the fill Option 13 8 Image Mode and the fill Option This section points out the advantages of operating in image mode and describes how to produce output files with a precise continuous image of a target memory range 13 8 1 The image Option With the image option the utility generates a memory image by completely filling all of the mapped ranges specified in the ROMS directive A COFF file consists of blocks of memory sections with assigned memory locations Typically all sections are not adjacent there are gaps between sec tions in the address space for which there is no data When such a file is con verted withoutthe use of image mode the hex conversion utility
208. bits for all others the utility simply writes multibyte fields into the file Figure 13 4 illustrates how the target memory and ROM widths are related to one another Hex Conversion Utility Description 13 11 Understanding Memory Widths Figure 13 4 Data Memory and ROM Widths Source file word OAABBCDDh word 01122344h Data width 16 fixed Data after phase OAABBh of hex utility 01122h Memory widths variable a Pd A SS Data after phase II of hex utility gt Output files romwidth 16 o file wrd AABB1122 P Data after romwidth 8 P4 phase Ill lt o file bO BB 22 22 of hex utility EEA Ae o file b1 E Ed romwidth 8 d 13 12 Understanding Memory Widths 13 4 5 A Memory Configuration Example Figure 13 5 shows a typical memory configuration example This memory system consists of two 128K x 8 bit ROM devices Figure 13 5 C55x Memory Configuration Example Data width 16 bits Lower 8 bits data AABBh lt Upper 8 bits data CPU AAh BBh 128K x 8 128K x 8 ROMO ROM1 i Source file oe oe word AABBh its its L J System memory width 16 bits 13 4 6 Specifying Word Order for Output Words When memory words are narrower than target words memory width lt 16 tar get words are split into multiple consecutive memory words There are two ways to split
209. bject files to produce a cross reference listing showing symbols their definitions and their references in the linked source files The purpose of this development process is to produce a module that can be executed in a C55x target system You can use one of several debugging tools to refine and correct your code Available products include An instruction accurate software simulator An XDS emulator Chapter 2 Introduction to Common Object File Format The assembler and linker create object files that can be executed by a TMS320C55x device The format for these object files is called common object file format COFF COFF makes modular programming easier because it encourages you to think in terms of blocks of code and data when you write an assembly language program These blocks are known as sections Both the assembler and the linker provide directives that allow you to create and manipulate sections This chapter provides an overview of COFF sections For additional information see Appendix A Common Object File Format which explains the COFF structure Topic Page 24 Sectlons vance ree a ne ea ney geen ty 2 2 2 2 How the Assembler Handles Sections ssse 2 3 How the Linker Handles Sections ss b 12 2 400RelOcation se TT 2 15 2 5900 Runtime Relocatlion HERE 2 17 2 6 LoadingaProgram se ee ee ee 2 7 Symbolsina COFF File e cese tete e cete 2 1 Sections 2 1 Sections
210. ble object code is loaded text One of the default COFF sections The text section is an initialized section that 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 COFF section that reserves space in the memory map but that has no actual contents These sections are built up with the bss and usect directives UNION An option of the SECTIONS directive that causes the linker to allo cate the same address to multiple sections union A variable that may hold objects of different types and sizes unsigned A kind of value that is treated as a positive number regardless of its actual sign well defined expression An expression that contains only symbols or assembly time constants that have been defined before they appear in the expression word A 16 bit addressable location in target memory assembler option linker option in assembly language source operand prefix symbol for SPC assembler option r assembler option in assembly language source operand prefix a archiver command 8 4 assembler option 3 4 disassembler option 12 2 hex conversion utility option linker option 9 8 A_DIR environment variable abs55 command See absolute lister invoking absolute address defined absolute lister creating the absol
211. ble operand ER T3 12 000000 data 13 000000 000A LABEL word 10 14 SYMTAB SeL LABEL 1 15 16 1 KK Set symbol NSYMS equal to the symbol KE 18 KE INDEX and use it as you would INDEX oe 19 20 NSYMS Set INDEX 21 000001 0035 word NSYMS Syntax Description Example Reserve Space Space bes space size in bits bes size in bits The space and bes directives reserve size number of bits in the current sec tion and fill them with Os qe R M H Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of space and bes directives in a section that includes C55x instructions will likely lead tothe generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections a
212. block attributes of a union are the maximum alignment and block attributes of any of its members Using UNION and GROUP Statements F7 1 Note UNION and Overlay Page Are Not the Same The UNION capability and the overlay page capability see Section 9 12 Overlay Pages on page 9 50 may sound similar because they both deal with overlays They are in fact quite different UNION allows multiple sections to be overlaid within the same memory space Overlay pages on the other hand define multiple memory spaces It is possible to use the page facility to approximate the function of UNION but this is cumbersome 9 11 2 Grouping Output Sections Together The SECTIONS directive has a GROUP option that forces several output sections to be allocated contiguously For example assume that a section named term rec contains a termination record for a table in the data section You can force the linker to allocate data and term rec together Example 9 9 Allocate Sections Together SECTIONS text Normal output section J bss Normal output section A GROUP 1000h Specify a group of sections data First section in the group EJ term rec Allocated immediately after data You can use binding alignment or named memory to allocate a GROUP in the same manner as a single output section In the preceding example the GROUP is bound to byte address 1000h This means that data is allocat
213. bly if condition is true The break 4 71 construct is optional else Assemble code block if the if condition is false The 4 59 else construct is optional This directive can be used as the default case in a conditional block elseif well defined expression Assemble code block if the if condition isfalse andthe 4 59 elseif condition is true The elseif construct is optional endif End if code block 4 59 endloop End loop code block Af well defined expression Assemble code block if the condition is true 4 59 loop well defined expression Begin repeatable assembly of a code block The well 4 71 defined expression is a loop count gt a Assembler Directives Directives Summary Table 4 1 Assembler Directives Summary Continued h Directives that define symbols at assembly time Mnemonic and Syntax asg character string substitution symbol endstruct endunion equ eval well defined expression substitution symbol label symbol Set Struct tag union 4 6 Description Assign a character string to a substitution symbol End structure definition End union definition Equate a value with a symbol Perform arithmetic on numeric substitution symbols Define a load time relocatable label in a section Equate a value with a symbol Begin structure definition Assign structure attributes to a label Begin union definition Sls o e ol o
214. bly in which it is defined unless you use the global directive to declare it as an external symbol Symbols used as labels become symbolic addresses associated with loca tions in the program Labels used locally within a file must be unique Assem bler directive names without the prefix are valid label names Labels can also be used as the operands of global ref def or bss direc tives for example global labell label2 nop ADD 8labell ACI1 ACI1 B label2 Reserved words are not valid label names 3 9 2 Symbolic Constants Symbols can be set to constant values By using constants you can equate meaningful names with constant values The set and struct tag endstruct directives enable you to set constants to symbolic names Symbolic constants cannot be redefined The following example shows how these directives can be used K set 1024 constant definitions maxbuf set 2 K value set 0 delta set 1 item Struct item structure definition int value constant offsets value 0 int delta constant offsets delta 1 i len endstruct array tag item array declaration bss array i len K The assembler also has several predefined symbolic constants these are discussed in the next section Assembler Description 3 25 Symbols 3 9 8 Defining Symbolic Constants d Option The d option equates a constant value with a symbol The symbol can then be used in place of a value in assembly source T
215. bol vec points to the first word reserved in the var2 section Figure 4 7 on page 4 105 shows how this example reserves space in two unini tialized sections var1 and var2 1 ck ck ck ck ck ck ck Ck ck kc kk ck 0k ck ck 0k ck kk ck ck ck ck ck ck kk ck kk kk Sk ke Sk kv kx ko ok 2 VN Assemble into text section EK 3 4 000000 text 5 000000 3C30 MOV 3 ACO 6 7 8 Reserve 1 word in varl ew 9 ck ck ck ck ck ck ck ck ck 0k 0k ck ck ck Ck ck ck 0k ck ck ck ck ck ck ck ck ck ck ock ck kk kk Sk KK ko ko ko ko 10 000000 ptr usect v ri 1 Ti 12 13 Wu Reserve 100 words in varl mE 14 15 000001 array usect varl 100 16 17 000002 7B00 ADD 55 ACO ACO Still in text 000004 3700 18 19
216. bootorg SERIAL or bootorg PARALLEL or if you do not use the bootorg option at all the utility places the table at the origin of the first memory range in a ROMS directive If you do not use a ROMS directive the table will start at the first section load address There is also a bootpage option for starting the table somewhere other than page O Set boot loader specific options Set such options as entry point and memory control registers as needed Describe your system memory configuration See Section 13 4 Understanding Memory Widths on page 13 8 and Section 13 5 The ROMS Directive on page 13 15 for details Hex Conversion Utility Description 13 29 Building a Table for an On Chip Boot Loader 13 9 3 2 Leaving Room for the Boot Table The complete boot table is similar to a single section containing all of the header records and data for the boot loader The address of this section is the boot table origin As part of the normal conversion process the hex conversion utility converts the boot table to hexadecimal format and maps it into the output files like any other section Be sure to leave room in your system memory for the boot table especially when you are using the ROMS directive The boot table cannot overlap other nonboot sections or unconfigured memory Usually this is not a problem typi cally a portion of memory in your system is reserved for the boot table Simply configure this memory as one or more
217. bridges these gaps by using the address records in the output file to skip ahead to the start of the next section In other words there may be discontinuities in the output file addresses Some EPROM programmers do not support address disconti nuities In image mode there are no discontinuities Each output file contains a contin uous stream of data that corresponds exactly to an address range in target memory Any gaps before between or after sections are filled with a fill value that you supply An output file converted by using image mode still has address records because many of the hexadecimal formats require an address on each line However in image mode these addresses will always be contiguous Fe cI Note Defining the Ranges of Target Memory If you use image mode you must also use a ROMS directive In image mode each output file corresponds directly to a range of target memory You must define the ranges If you don t supply the ranges of target memory the utility tries to build a memory image of the entire target processor address space potentially a huge amount of output data To prevent this situation the utility requires you to explicitly restrict the address space with the ROMS directive Hex Conversion Utility Description 13 25 Image Mode and the fill Option 13 8 2 Specifying a Fill Value The fill option specifies a value for filling the holes between sections The fill value must be specified
218. bval bval 2 bval 12 B bval The set and equ directives produce no object code The two directives are identical and can be used interchangeably The struct endstruct directives set up C like structure definitions and the tag directive assigns the C like structure characteristics to a label The struct endstruct directives allow you to organize your information into structures so that similar elements can be grouped together Element offset calculation is then left up to the assembler The struct endstruct directives do not allocate memory They simply create a symbolic template that can be used repeatedly Assembly Time Symbol Directives The tag directive associates structure characteristics with a label symbol This simplifies the symbolic representation and also provides the ability to define structures that contain other structures The tag directive does not allocate memory and the structure tag stag must be defined before it is used data type struct structure tag definition X int X int T LEN endstruct COORD tag type declare COORD coordinate bss COORD T LEN actual memory allocation text ADD Q COORD Y ACO ACO The union endunion directives create a symbolic template that can be used repeatedly providing a way to manipulate several different kinds of data in the same storage area The union sets up a C like union definition While it does not allocate any memory it allows alternate
219. ce address of the boot loader table bootpage value Specify the target page number of the boot loader table e value Specify the entry point for the boot loader table Hex Conversion Utility Description 13 5 Command File 13 3 Command File A command file is useful if you plan to invoke the utility more than once with the same input files and options It is also useful if you want to use the ROMS and SECTIONS hex conversion utility directives to customize the conversion process Command files are ASCII files that contain one or more of the following Options and filenames These are specified in a command file in exactly the same manner as on the command line DD ROMS directive The ROMS directive defines the physical memory con figuration of your system as a list of address range parameters For more information about the ROMS directive see Section 13 5 The ROMS Directive on page 13 15 SECTIONS directive The SECTIONS directive specifies which sections from the COFF object file should be selected For more information about the SECTIONS directive see Section 13 6 The SECTIONS Directive on page 13 21 You can also use this directive to identify specific sections that will be initialized by an on chip boot loader For more information on the on chip boot loader see Section 13 9 3 Building a Table for an On Chip Boot Loader on page 13 28 Comments You can add comments to your command file by using the
220. ch define members in the structure The member directive is the only directive that can appear inside a structure enumeration or union definition The assembler does not allow nested structures enumerations or unions The C compiler unwinds nested structures by defining them separately and then referencing them from the structure they are referenced in Following is an example of a structure definition C source struct doc char title char group int job_number doc info Resulting assembly language code stag doc 48 member title 0 2 8 16 member group 16 2 8 16 member job number 32 4 8 16 eos D Name is the name of the structure enumeration or union The first 32 characters of the name are significant This is a required parameter Sizeis the number of bits the structure enumeration or union occupies in memory This is an optional parameter if omitted the size is unspeci Example 2 Example 3 Define a Structure Stag etag utag eos Following is an example of a union definition C source union u_tag int vall float val2 char valge valu Resulting assembly language code utag u tag 32 member _vall 0 4 11 16 member _val2 0 6 11 32 member _valc 0 2 11 16 eos Following is an example of an enumeration definition C Source enum o_ty reg_l reg_2 result optypes Resulting assembly language code etag o ty 16 member reg 1 0 4 16 16
221. ck kk kk ck ck ck Ck ck ck kk ck kk ck Sk Sk kv Sk kv kx ko ko ko 16 Reserve 20 bits in the data section 17 RES 2 points to the last word that AU 18 No contains reserved bits 205 19 ck ck Ck ck ck Ck ck ck 0k ck ck 0k ck kk ck kk ck kk ck kc ck Ck ck ck ck ck ok kk ck ko Sk kv Sk kv kx ko ko ko 20 000012 RES 2 bes 20 21 000013 0036 word 36h 22 000014 0012 word RES 2 Assembler Directives 4 87 sslist ssnolist Control Listing of Substitution Symbols Syntax sslist ssnolist Description Two directives enable you to control substitution symbol expansion in the listing file The sslist directive allows substitution symbol expansion in the listing file The expanded line appears below the actual source line The ssnolist directive suppresses substitution symbol expansion in the listing file By default all substitution symbol expansion in the listing file is inhibited Lines with the pound character denote expanded substitution symbols Example This example shows code that by default suppresses the listing of substitu tion symbol expansion and it shows the sslist directive assembled instructing the assembler to list substitution symbol code expansion a Mnemonic example 1 000000 bss ADDRX 1 2 000001 bss ADDRY 1 3 000002 bss ADDRA 1 4 000003 bss ADDRB 1 5 ADD2 macro ADDRA ADDRB 6 OV ADDRA ACO 7 ADD ADDRB ACO ACO 8 MOV ACO ADDRB 9 endm 10 11 000000C083 OV ACO AR4
222. clude byte2 asm word OABCDh 56q byte 32 14 A include word2 asm Back in byte2 asm byte 67h 3q Back in original file string done Listing file 1 000000 data 2 000000 Space 29 3 include byte2 asm 4 5 Back in original file 6 000007 0064 string done 000008 006F 000009 006E 00000a 0065 Assembler Directives 4 39 cpl on cpl off Syntax Description Select Direct Addressing Mode cpl on cpl off The cpl on and cpl off directives model the CPL status bit The assembler cannot track the value of the CPL status bit you must use the assembler directives and or command line options to model this mode to the assembler An instruction that modifies the value of the CPL status bit must be immediately followed by the appropriate assembler directive The cpl ondirective models the CPL status bit setto 1 itis equivalentto using the mc command line option The cpl off directive models the CPL status bit setto 0 In the case of a conflict between the command line option and the di rective the directive takes precedence The cpl on and cpl off directives take no arguments In CPL mode cpl on direct memory addressing is relative to the stack pointer SP The dma syntax is SP dma where dma can be a constant or a linktime known symbolic expression The assembler encodes the value of dma into the output bits By default cpl off direct memory addressing dma is relative t
223. constant value See Table 5 1 for a description of the assembler s non mathematical built in functions Table 3 2 Assembler Built In Math Functions 3 34 Function acos expr asin expr atan expr atan2 expr ceil expr cosh expr cos expr cvf expr cvi expr exp expr fabs expr floor expr fmod expr1 expr2 int expr Idexp expr1 expr2 log10 expr log expr max expr1 expr2 min expr1 expr2 Description returns the arc cosine of expr as a floating point value returns the arc sine of expr as a floating point value returns the arc tangent of expr as a floating point value returns the arc tangent of expr as a floating point value pi to pi returns the smallest integer that is not less than the expression returns the hyperbolic cosine of expr as a floating point value returns the cosine of expr as a floating point value converts expr to floating point value converts exprto integer value returns the result of raising e to the expr power returns absolute value of expr as a floating point value returns the largest integer that is not greater than the expression returns the remainder after dividing expr and expr2 returns 1 if expr has an integer result returns the result of expr multiplied by 2 raised to the expr2 power returns the base 10 logarithm of expr returns the natural logarithm of expr returns the maximum of 2 expressions returns the minimum of 2
224. cremental Linking Step 2 Link the file file2 com use the r option to retain relocation information in the output file tempout2 out lnk55 r o tempout2 file2 com file2 com contains SECTIONS SS23 gl obj g2 0bj gn obj Step 3 Link tempout1 out and tempout2 out lnk55 m final map o final out tempoutl out tempout2 out 9 68 Linking C Code 9 18 Linking C Code The TMS320C55x C compiler produces assembly language source code that can be assembled and linked For example a C program consisting of modules prog1 prog2 etc can be assembled and then linked to produce an executable file called prog out lnk55 c o prog out progl obj prog2 0bj rts55 lib To use the large memory model you must specify the rtsb5x lib runtime library The c option tells the linker to use special conventions that are defined by the C environment The runtime library contains C runtime support functions For more information about C including the runtime environment and runtime support functions see the 7MS320C55x Optimizing C Compiler User s Guide 9 18 1 Runtime Initialization All C programs must be linked with an object module called boot obj When a program begins running it executes boot obj first boot obj contains code and data for initializing the runtime environment The module performs the follow ing tasks DD Sets up the primary and secondary system stacks _j Processes the runtime initialization
225. cribes DD Memory configuration Input and output section allocation The addresses of external symbols after they have been relocated The map file contains the name ofthe output module and the entry point it may also contain up to three tables Atable showing the new memory configuration if any non default memory is specified DD Atable showing the linked addresses of each output section and the input sections that make up the output sections Atable showing each external symbol and its address This table has two columns the left column contains the symbols sorted by name and the right column contains the symbols sorted by address Linker Options This example links file1 obj and file2 obj and creates a map file called file map lnk55 filel obj file2 obj m file map Example 9 15 on page 9 75 shows an example of a map file 9 4 12 Name an Output Module o filename Option The linker creates an output module when no errors are encountered If you do not specify a filename for the output module the linker gives it the default name a out If you want to write the output module to a different file use the o option The syntax for the o option is o filename The filename is the new output module name This example links file1 obj and file2 obj and creates an output module named run out lnk55 o run out filel obj file2 0bj 9 4 13 Specify a Quiet Run q Option The q option suppresses the lin
226. ct Formats e 13 37 13 12 Hex Conversion Utility Error Messages 13 43 Hex Conversion Utility Development Flow 13 1 Hex Conversion Utility Development Flow Figure 13 1 highlights the role of the hex conversion utility in the assembly language development process Figure 13 1 Hex Conversion Utility Development Flow C Source files Macro Source files i C compiler Archiver Assembler source Macro Assembler library Library build utility Runtime support library CD Library of object files seeeee eeeee Linker ll Debugging li Executable zi COFF file Hex conversion utility EPROM programmer 13 2 Invoking the Hex Conversion Utility 13 2 Invoking the Hex Conversion Utility There are two basic methods for invoking the hex conversion utility Specify the options and filenames on the command line The following example converts the file firmware out into Tl Tagged format producing two output files firm lsb and firm msb hex55 t firmware o firm lsb o firm msb Specify the options and filenames in a command file You can create a batch file that stores command line options and filenames for invoking the hex conversion utility The following example invokes the utility using a command file called hexutil cmd hex55 hexutil cmd In addition to regular command li
227. ctions from largest to smallest followed by 2 all blocked sections from largest to smallest followed by 3 all other input sections from largest to smallest Example 9 5 shows the most common type of section specification note that no input sections are listed Example 9 5 The Most Common Method of Specifying Section Contents n ECTIONS we xis data SS sis The SECTIONS Directive In Example 9 5 the linker takes all the text sections from the input files and combines them into the text output section The linker concatenates the text input sections in the order that it encounters them in the input files The linker performs similar operations with the data and bss sections You can use this type of specification for any output section You can explicitly specify the input sections that form an output section Each input section is identified by its filename and section name SECTIONS text Build text output section fl obj text Link text section from fl obj f 2 0bj secl Link secl section from f2 0bj f3 0bj Link ALL sections from f3 0bj x f4 obj text sec2 Link text and sec2 from f4 0bj It is not necessary for input sections to have the same name as each other or as the output section they become part of If a file is listed with no sections all of its sections are included in the output section If any additional input sections have the same name as
228. ctives ee 1 21 4 8 Assembly Time Symbol Directives eeeeee 1 22 4 9 Miscellaneous Directives leeren 4 10 Directives Reference 0 0 4 1 Directives Summary 4 1 Directives Summary This section summarizes the assembler directives Besides the assembler directives documented here the TMS320C55x software tools support the following directives The assembler uses several directives for macros The macro directives are listed in this chapter but they are described in detail in Chapter 5 Macro Language The absolute lister also uses directives Absolute listing directives are not entered by the user but are inserted into the source program by the absolute lister Chapter 10 Absolute Lister Description discusses these directives they are not discussed in this chapter The C compiler uses directives for symbolic debugging Unlike other directives symbolic debugging directives are not used in most assembly language programs Appendix B Symbolic Debugging Directives discusses these directives they are not discussed in this chapter Note Labels and Comments in Syntax In most cases a source statement that contains a directive may also contain a label and a comment Labels begin in the first column they are the only elements except comments that can appear in the first column and com ments must be preceded by a semicolon or an asterisk if the comment is the only statemen
229. ctives 4 19 Directives That Reference Other Files 4 6 Directives That Reference Other Files These directives supply information for or about other files LI The copy and include directives tell the assembler to begin reading source statements from another file When the assembler finishes reading the source statements in the copy include file it resumes reading source statements from the current file immediately following the point at which the copy or include directive occurred The statements read from a copied file are printed in the listing file the statements read from an included file are not printed in the listing file The def directive identifies a symbol that is defined in the current module and that can be used by another module The assembler includes the symbol in the symbol table The global directive declares a symbol external so that it is available to other modules at link time For more information about global symbols see subsection 2 7 1 External Symbols on page 2 19 The global directive does double duty acting as a def for defined symbols and as a ref for undefined symbols The linker resolves an undefined global symbol only if it is used in the program The ref directive identifies a symbol that is used in the current module but defined in another module The assembler marks the symbol as an undefined external symbol and enters it in the object symbol table so that the linker can resolve its defi
230. cture The elements of a COFF object file describe the file s sections and symbolic debugging information These elements are A file header Optional header information A table of section headers A symbol table A string table O O O O O O O L Raw data for each initialized section Relocation information for each initialized section Line number entries for each initialized section The assembler and linker produce object files with the same COFF structure however a program that is linked for the final time does not usually contain relocation entries Figure A 1 illustrates the overall object file structure Figure A 1 COFF File Structure file header optional file header section 1 header section n header section 1 raw data section n raw data section 1 relocation information section n relocation information section 1 line numbers section n line numbers symbol table string table A 2 section headers raw data executable code andinitialized data relocation information line number entries COFF File Structure Figure A 2 shows a typical example of a COFF object file that contains the three default sections text data and bss and a named section referred to as lt named gt By default the tools place sections into the object file in the following order text data initialized named sections bss and uninitialized
231. d label2 word X Set goodsyml set goodsym2 set goodsym3 set goodsym4 set 0 1 2 3 50h 100h X Because value of X is defined before referenced this is a valid well defined expression All references to previously defined local labell labels including the current SPC are considered to be well defined label2 labell Although labell and label2 are not absolute symbols because they are local labels defined in the same section their difference can be computed by the assembler The difference is absolute so the expression is well defined 3 10 4 Conditional Expressions The assembler supports relational operators that can be used in any expression except with relocatable link time operands they are especially useful for conditional assembly Relational operators include the following Equal to Equalto Notequalto lt Less than lt Less than or equal to gt Greater than gt Greater than or equal to Conditional expressions evaluate to 1 if true and 0 if false they can be used only on operands of equivalent types for example absolute value compared to absolute value but not absolute value compared to relocatable value Assembler Description 3 33 Built in Functions 3 11 Built in Functions The assembler supports built in functions for conversions and various math computations Table 3 2 describes the built in functions Note that expr must be a
232. d these terms with quotation marks At assembly time the assembler replaces the substitution symbol with its corresponding character string then translates the source code into object code Example 5 2 shows the expansion of a macro with varying numbers of arguments Macro Parameters Substitution Symbols Example 5 2 Calling a Macro With Varying Numbers of Arguments Macro definition Parms macro a b c a tas b ib i C Cs endm Calling the macro Parms 100 1abel Parms 100 label x y H a 100 A a 100 b label b label Ce C XY Parms 100 x Parms 100 200 300 x y a 100 A a 100 200 300 QoS E b x 7 C x c y Parms string ry a string b x 7 c y 5 3 1 Directives That Define Substitution Symbols You can manipulate substitution symbols with the asg and eval directives The asg directive assigns a character string to a substitution symbol The syntax of the asg directive is asg character string substitution symbol The quotation marks are optional If there are no quotation marks the assembler reads characters up to the first comma and removes leading and trailing blanks In either case a character string is read and assigned to the substitution symbol Example 5 3 shows character strings being assigned to substitution symbols Macro Language 5 7 Macro Parameters Substitution Symbols Example 5 3 The asg Directive asg A
233. data union utag long memberl long float member2 float word member3 word endunion real len 4 Syntax Description Reserve Uninitialized Space usect symbol usect section name size in words blocking flag alignment flag The usect directive reserves space for variables in an uninitialized named section This directive is similarto the bss directive both simply reserve space for data and have no contents However usect defines additional sections that can be placed anywhere in memory independently of the bss section symbol points to the first location reserved by this invocation of the usect directive The symbol corresponds to the name of the variable for which you re reserving space section name must be enclosed in double quotes This parameter names the uninitialized section The name can be up to 200 characters For COFF1 formatted files only the first 8 characters are significant A section name can contain a subsection name in the form section name subsection name size in words is an expression that defines the number of words that are reserved in section name blocking flag is an optional parameter If specified and nonzero the flag means that this section will be blocked Blocking is an ad dress mechanism similar to alignment but weaker It means a section is guaranteed to not cross a page bound ary 128 words if itis smaller than a page and to start on a page boundary i
234. ddress 12 15 Long integer Number of entries in the symbol table 16 17 Unsigned short integer Number of bytes in the optional header This field is either 0 or 28 if it is 0 then there is no optional file header 18 19 Unsigned short integer Flags see Table A 2 20 21 Unsigned short integer Target ID magic number indicates the file can be executed in a TMS320C55x system Table A 2 lists the flags that can appear in bytes 18 and 19 of the file header Any number and combination of these flags can be set at the same time for example if bytes 18 and 19 are set to 0003h F RELFLG and F EXEC are both set Table A 2 File Header Flags Bytes 18 and 19 Mnemonic Flag Description F RELFLG 0001h Relocation information was stripped from the file F EXEC 0002h The file is relocatable it contains no unresolved external references F LNNO 0004h Line numbers were stripped from the file F LSYMS 0008h Local symbols were stripped from the file F LITTLE 0100h The file has the byte ordering used by C55x devices 16 bits per word least significant byte first F SYMMERGE 1000h Duplicate symbols were removed A 3 Optional File Header Format Optional File Header Format The linker creates the optional file header and uses it to perform relocation at download time Partially linked files do not contain optional file headers Table A 3 illustrates the optional file header format Table A 3 Optional File Header Contents Byte Num
235. ddress to return to unlabeled location This includes instructions such as B 10 Using READA and WRITEA instructions to access instructions and not data Migrating a C54x System to a C55x System 7 17 Non Portable C54x Coding Practices Using READA WRITA with an accumulator whose upper bits are not zero The READA WRITA instruction on C54x devices other than C548 or later uses the lower 16 bits of the accumulator and ignores the upper 16 bits C548 and later devices however use the lower 23 bits The assembler cannot easily know the device for which the code is targeted It assumes C548 or later Consequently code for C548 and later devices will map with no problems Code for devices other than these will not run Additional C54x Issues 7 4 Additional C54x Issues This section contains some additional system issues If your C54x code m O O O O uses a SP offset operand in the MMR slot of MMR instructions like LDM copies blocks of code usually from off chip memory to on chip memory uses memory mapped access to peripherals uses repeat blocks larger than 32K after mapping to C55x uses the branch conditions BIO NBIO you may need to modify this code to use native C55x instructions You should also be aware of the following issues m E m The C5x compatibility features of the C54x are not supported on C55x RPT instructions non interruptible on C54x can be interrupted on C55x
236. definitions of size and type that may be temporarily stored in the same memory space The tag directive associates union characteristics with a label symbol A union can be defined and given a tag and later it can be declared as a member of a structure by using the tag directive A union may also be de clared without a tag in which case all of its members will be entered in the symbol table and each member must have a unique name A union may also be defined within a structure in which case any reference to such a union must be made via with the structure that encloses it For example data s2 tag struct structure tag definition union union is first structure member struct structure is union member hl half hl h2 and wl h2 uhalf exist in the same memory endstruct wl word word is another union member endunion w2 word Second structure member S2 len endstruct XYZ tag s2 tag bss XYZ s2 len declare instance of structure text ADD Q XYZ h2 ACO ACO Assembler Directives 4 23 Miscellaneous Directives 4 9 Miscellaneous Directives These directives enable miscellaneous functions or features The dp directive specifies the value of the DP register The assembler cannot track the value of the DP register however it needs to know the value of DP in order to assemble direct memory access operands Conse quently this directive should be placed immediately following any instruc tion that
237. dependently relocatable you can place any section into any allocated block of target memory For example you can define a sec tion that contains an initialization routine and then allocate the routine into a portion of the memory map that contains ROM Sections Figure 2 1 shows the relationship between sections in an object file and a hypothetical target memory Figure 2 1 Partitioning Memory Into Logical Blocks Object File Target Memory op RAM EEPROM Introduction to Common Object File Format 2 3 How the Assembler Handles Sections 2 2 How the Assembler Handles Sections 2 2 1 The assembler identifies the portions of an assembly language program that belong in a section The assembler has several directives that support this function bss USect text data Sect O O O O L The bss and usect directives create uninitialized sections the other directives create initialized sections You can create subsections of any section to give you tighter control of the memory map Subsections are created using the sect and usect directives Subsections are identified with the base section name and a subsection name separated by a colon See subsection 2 2 4 Subsections page 2 8 for more information Note Default Section Directive If you don t use any of the sections directives the assembler assembles everything into the text section Uninitialized Sections Uninitialized sections res
238. des the others The default format is Tektronix x option Table 13 3 Options for Specifying Hex Conversion Formats Address Default Option Format Bits Width a ASCII Hex 16 8 i Intel 32 8 m1 Motorola S1 16 8 m2 or m Motorola S2 24 8 m3 Motorola S3 32 8 TI Tagged 16 16 X Tektronix 32 8 Address bits determine how many bits of the address information the format supports Formats with 16 bit addresses support addresses up to 64K only The utility truncates target addresses to fit in the number of available bits The default width determines the default output width You can change the default width by using the romwidth option or by using the romwidth param eter in the ROMS directive You cannot change the default width of the TI Tagged format which supports a 16 bit width only Hex Conversion Utility Description 13 37 Description of the Object Formats 13 11 1 ASCII Hex Object Format a Option The ASCII Hex object format supports 16 bit addresses The format consists of a byte stream with bytes separated by spaces Figure 13 10 illustrates the ASCII Hex format Figure 13 10 ASCII Hex Object Format Nonprintable Nonprintable Address end code start code d B SAXXXX ro XX XX XX XX XX XX XX XX XX XX C Data byte The file begins with an ASCII STX character ctrl B 02h and ends with an ASCII ETX character ctrl C 03h Address records are indicated with AXXXX i
239. directive to keep the following instructions in their largest form goto P24 d goto P24 call P24 dcall P24 The vli off and vli on directives can be used to toggle this behavior for re gions of an assembly file Note that all other variable length instructions will continue to be resolved to their smallest possible size by the assembler de spite the use of the vli off directive The scope of the vli off and vli on directives is static and not subject to the control flow of the assembly program Assembler Directives 4 107 Chapter 5 Macro Language The assembler supports a macro language that enables you to create your own instructions This is especially useful when a program executes a particular task several times The macro language lets you DD Define your own macros and redefine existing macros L Simplify long or complicated assembly code Access macro libraries created with the archiver D Define conditional and repeatable blocks within a macro DD Manipulate strings within a macro J Control expansion listing Topic Page Gh USIndgIMacroS c ee E E 5 2 5 2ugDetiningiMacrosq nc ECEECCEREPHEEERREEEERIREEEEERETISEEERETSSEE 5 3 5 3 Macro Parameters Substitution Symbols 5 4 Macro Libraries ee de a a 5 5 Using Conditional Assembly in Macros 5 15 5 5uUsingilabelsiiniMacros cc P det E 5 17 5 7 Producing Messages in Macros uusese 5
240. do not use f the linker uses 0 as the default fill value This example fills holes with the hexadecimal value ABCD lnk55 f OABCDh filel obj file2 0bj Linker Description 9 11 Linker Options 9 4 6 Make a Symbol Global g global symbol Option The h option makes all global symbols static If you have a symbol that you want to remain global and you use the h option you can use the g option to declare that symbol to be global The g option overrides the effect of the h option for the symbol that you specify The syntax for the g option is g global symbol 9 4 7 Make All Global Symbols Static h Option The h option makes all global symbols defined with the global assembler directive static Static symbols are not visible to externally linked modules By making global symbols static global symbols are essentially hidden This allows external symbols with the same name in different files to be treated as unique The h option effectively nullifies all global assembler directives All symbols become local to the module in which they are defined so no external references are possible For example assume that b1 obj b2 obj and b3 obj are related and reference a global variable GLOB Also assume that d1 obj d2 obj and d3 obj are related and reference a separate global variable GLOB By using the h option and partial linking you can link the related files without conflict 1nk55 h r bl obj b2
241. e 2 If itis notthe first entry in a block it is the physical ad dress of the line indicated by bytes 4 5 4 5 Unsigned This entry may have one of two values short integer 4 if this field is 0 this is the first line of a function entry 2 If this field is not 0 this is the line number of a line in C source code Figure A 4 shows how line number entries are grouped into blocks Figure A 4 Line Number Blocks Symbol Index 1 0 physical address line number physical address line number Symbol Index n 0 physical address line number physical address line number As Figure A 4 shows each entry is divided as follows Forthe first line of a function bytes 0 3 point to the name of a symbol or a function in the symbol table and bytes 4 5 contain a 0 which indicates the beginning of a block Common Object File Format A 11 Line Number Table Structure For the remaining linesin a function bytes 0 3 show the physical address the number of bytes created by a line of C source and bytes 4 5 show the address of the original C source relative to its appearance in the C source program The line number entry table can contain many of these blocks Figure A 5 illustrates line number entries for a function named XYZ As shown the function name is entered as a symbol in the symbol table The first portion on XYZ s block of line number entries points to the function name in
242. e 1 H F named section table_1 file 2 table_1 file2 FFT table_1 initialized named section unused u vars uninitialized namedsection FFT initialized namedsection Y L In Figure 2 3 file1 obj and file2 obj have been assembled to be used as linker input Each contains the text data and bss default sections in addition each contains named sections The executable output module shows the combined sections The linker combines file1 text with file2 text to form one text section then combines the data sections then the bss sections and finally places the named sections at the end The memory map shows how the sections are put into memory by default the linker begins at address 080h and places the sections one after the other as shown Introduction to Common Object File Format 2 13 How the Linker Handles Sections 2 3 2 Placing Sections in the Memory Map 2 14 Figure 2 3 illustrates the linker s default methods for combining sections Sometimes you may not want to use the default setup For example you may not want all of the text sections to be combined into a single text section Or you may want a named section placed where the data section would normally be allocated Most memory maps contain various types of memory RAM ROM EPROM etc in varying amounts you may want to place a section in a specific type of memory For further exp
243. e Operands Relocatable link time operands do not support the relational operators lt lt gt gt l and i Table 3 1 Operators Used in Expressions Precedence Evaluation Symbols Operators Unary plus minus 1s complement Right to left Be of 9 Multiplication division modulo Left to right Addition subtraction Left to right lt lt gt gt Left shift right shift Left to right lt lt gt gt Less than LT or equal greater than Left to right GT or equal l Not equal to equal to Left to right amp Bitwise AND Left to right Bitwise exclusive OR Left to right Bitwise OR Left to right Note Unary and have higher precedence than the binary forms 3 10 2 Expression Overflow and Underflow The assembler checks for overflow and underflow conditions when arithmetic operations are performed at assembly time It issues a Value Truncated warn ing whenever an overflow or underflow occurs The assembler does not check for overflow or underflow in multiplication 3 32 Expressions 3 10 3 Well Defined Expressions Some assembler directives require well defined expressions as operands Well defined expressions contain only symbols or assembly time constants that are defined before they are encountered in the expression The evaluation of a well defined expression must be absolute Example 3 5 Well Defined Expressions data labell word word wor
244. e a hole is relative to the beginning of the section not to the address actually represented by Assignments to and holes are described in Section 9 16 Creating and Filling Holes on page 9 63 9 15 3 Assignment Expressions These rules apply to linker expressions Expressions can contain global symbols constants and the C language operators listed in Table 9 1 All numbers are treated as long 32 bit integers DD Constants are identified by the linker in the same way as by the assembler That is numbers are recognized as decimal unless they have a suffix H Assigning Symbols at Link Time or h for hexadecimal and Q or q for octal C language prefixes are also recognized 0 for octal and Ox for hex Hexadecimal constants must begin with a digit No binary constants are allowed Symbols within an expression have only the value of the symbol s address No type checking is performed Linker expressions can be absolute or relocatable If an expression contains any relocatable symbols and zero or more constants or absolute symbols it is relocatable Otherwise the expression is absolute If a symbol is assigned the value of a relocatable expression it is relocatable if itis assigned the value of an absolute expression it is absolute The linker supports the C language operators listed in Table 9 1 in order of precedence Operators in the same group have the same precedence Besides t
245. e a source file source file Link the resulting object file Invoke the absolute lister use the linked object file as input This creates a file with an abs extension Finally assemble the abs file you must invoke the assembler with the a option This Assembler produces a listing file that contains absolute addresses Invoking the Absolute Lister 10 2 Invoking the Absolute Lister The syntax for invoking the absolute lister is abs55 options input file abs55 is the command that invokes the absolute lister options identifies the absolute lister options that you want to use Options are not case sensitive and can appear anywhere on the command line following the command Precede each option with a hyphen The absolute lister options are as follows e enables you to change the default naming conventions for filename extensions on assembly files C source files and C header files The three options are listed below Lj ea asmext for assembly files default is asm ec cext for C source files default is c DD eh hext for C header files default is h The in the extensions and the space between the option and the extension are optional q quiet suppresses the banner and all progress infor mation input file names the linked object file If you do not supply an extension the absolute lister assumes that the input file has the default extension out If you do not supply
246. e a symbol or to define a symbol illegally Action Correct the source per the error message text Assembler Error Messages Cannot redefine local substitution symbol Substitution stack overflow Substitution symbol not found Description These are errors about general substitution symbols An attempt was made to redefine a symbol or to define a symbol illegally Action Correct the source per the error message text Make sure that the operand of a substitution symbol is defined either as a macro parameter or with a asg or eval directive Symbol table entry is not balanced Description Asymbolic debugging directive does not have acomplement ing directive i e a block without an endblock Action Check the source for mismatched conditional assembly directives Macro argument string is too long Missing macro name Too many variables declared in macro Description These are errors about general macros A macro definition was probably corrupted Action Correct the source per the error message text Macro definition not terminated with endm Matching endm missing Assembler Error Messages C 9 Assembler Error Messages Matching macro missing mexit directive outside macro definition No active macro definition Description These are errors about macro definition directives A macro directive does not have a complementing directive that is a macro without a endm Action Correct the source per the error message text
247. e entry for a symbol whether the module uses the symbol or not global however creates an entry only if the module actually uses the symbol A symbol may be declared global for two reasons Ifthe symbol is not defined in the current module including macro copy and include files the global or ref directive tells the assembler that the symbolis defined in an external module This prevents the assembler from issuing an unresolved reference error At link time the linker looks for the symbol s definition in other modules Ifthe symbol is defined in the current module the global or def directive declares that the symbol and its definition can be used externally by other modules These types of references are resolved at link time This example shows four files file1 Ist and file3 Ist are equivalent Both files define the symbol Init and make it available to other modules both files use the external symbols x y and z file1 Ist uses the global directive to identify these global symbols file3 Ist uses ref and def to identify the symbols file2 Ist and file4 Ist are equivalent Both files define the symbols x y and z and make them available to other modules both files use the external symbol Init file2 Ist uses the global directive to identify these global symbols file4 Ist uses ref and def to identify the symbols file1 Ist file2 Ist file3 Ist 000000 000000 000002 000000 000000 000000 00000
248. e file name The line directive identifies the line number of a C source statement These symbolic debugging directives are not usually listed in the assembly language file that the compiler creates If you want them to be listed invoke the compiler shell with the g option as shown below cl55 g input file This appendix contains an alphabetical directory of the symbolic debugging directives With the exception of the file directive each directive contains an example of C source and the resulting assembly language code B 1 block endblock Define a Block Syntax Description Example block beginning line number endblock ending line number The block and endblock directives specify the beginning and end of a C block The line numbers are optional they specify the location in the source file where the block is defined Block definitions can be nested The assembler will detect improper block nesting Following is an example of C source that defines a block and the resulting assembly language code C source Beginning of a block End of a block Resulting assembly language code block 7 Sym a 2 Sym Dray line 9 AR1 SP 3 SP 2 AR1 endblock 9 Syntax Description Example Supply a File Identifier file file filename The file directive allows a debugger to map locations in memory back to lines in a C source file The filename is the name of th
249. e file that contains the original C source program The first 14 characters of the filename are significant You can also use the file directive in assembly code to provide a name in the file and improve program readability In the following example the filename text c contained the C source that pro duced this directive file text c Symbolic Debugging Directives B 3 func endfunc Define a Function Syntax Description Example func beginning line number endfunc ending line number The func and endfunc directives specify the beginning and end of a C func tion The ine numbers are optional they specify the location in the source file where the function is defined Function definitions cannot be nested Following is an example of C source that defines a function and the resulting assembly language code C source power x n Beginning of a function int x n int LE p p 1 for i 1 i lt n i p p x return p End of function func Resulting assembly language code 1 Define a Function func endfunc PRR RK k k k k k e k k Ae e k k KKK KKK Ae e ke koc kk koc KKK ke kk koc KKK KEK KERR KKK KER ek ke koe k ke e ke FUNCTION NAME power PRR RRR KR ERR KKK KKK KEK ko kc kk ke kk KKK KK RK KR KR KEK KR KEK koc kk kc kk koc ke kk koc ke KK ee ke ke power L1 Lag SP SP 5 Sym X 12 4 17 10 Sym n 13 4 17 16 Sym _x 0 4 1 16 sym n
250. e for the section label fir end load address of section end Copy fir section from ROM into RAM text OV fir_src AR1 get load address OV BRCO TL OV T1 BRC1 OV fir_end fir src 1 BRCO RPTB end end OV AR1 CDP OV BRC1 T1 OV T1 BRCO jump to section now in RAM CALL fir Linker Command File PARTIAL LINKER COMMAND FILE FOR FIR EXAMPLE MEMORY ONCHIP origin 000100h length 000700h PROG E origin 000800h length 002400h DATA z origin 002C00h length 00D200h SECTIONS text load PROG SELES load DATA run ONCHIP Linker Description 9 43 Specifying a Section s Runtime Address Figure 9 3 illustrates the runtime execution of this example Figure 9 3 Runtime Execution of Example 9 6 Program Memory 100h ONCHIP r fir relocated to run here 800h 2C00h pata fir loads here FEOOh 9 44 Using UNION and GROUP Statements 9 11 Using UNION and GROUP Statements Two SECTIONS statements allow you t
251. e global symbol f fill value g global symbol h help 2 heap size i dir k filename Produce an absolute executable module This is the default if neither a nor r is specified the linker acts as if a were specified Produce a relocatable executable object module Disable merge of symbolic debugging information Use linking conventions defined by the ROM autoin itialization model of the TMS320C55x C compiler Use linking conventions defined by the RAM autoin itialization model of the TMS320C55x C compiler Define a global symbol that specifies the primary entry point for the output module Set the default fill value for holes within output sec tions fil value is a 16 bit constant Keep a global symbol global overrides h Make all global symbols static Display a listing of all available linker command line options Set heap size for the dynamic memory allocation in C to size bytes and define a global symbol that speci fies the heap size The default is 2000 bytes Alter the library search algorithm to look in dir before looking in the default location This option must appear before the l option The directory or filename must follow operating system conventions Ignore alignment flags in input sections Name an archive library file as linker input filename is an archive library name This option must appear af ter the i option The directory or filename mu
252. e in bss for a variable Wee 9 10 000000 bss buffer 10 Tq ck ck Ck ck ck 0k ck kk ck Ck ck ck Ck ck Sk 0k ck ck ck ck ck ck kc ck ck ck ck ck ck ck ock ck ck ck kk ck kx KKK ko ko ko 12 ax Still in data ok 13 14 000003 0123 ptr word 0123n 15 KKK KK KKK KKK KKK KKK KKK KKK KKK ck ck ck ck ck ck o ckock ck ck ck kk ck Sk KKK ko ko ko 16 dee Assemble code into the text section Wd TY 18 000000 text 19 000000 AO1E add MOV OFh ACO 20 000002 4210 aloop SUB 1 ACO 21 000004 0450 BCC aloop ACO gt 0 000006 FB 2 2 ck ck Kok ck 0k ck kk ck Ck ck ck 0k ck 0k 0k ck ck ck ck ck ck kc ck ck ck ck ck ck ckock kk ck ko Sk ck KKK ko ko ko ko 23 Another initialized table into data d 24 25 000004 data 2
253. e individual library members into the opcode table as library entries This re defines any existing opcodes or macros that have the same name If one of these macros is called the assembler extracts the entry from the library and loads it into the macro table The assembler expands the library entry in the same way it expands other macros but it does not place the source code into the listing Only macros that are actually called from the library are extracted and they are extracted only once Assembler Directives 4 73 mlib Define Macro Library Example This example creates a macro library that defines two macros incr and decr The file incr asm contains the definition of incr and decr asm contains the defi nition of decr incr asm decr asm Macro for decrementing decr macro SUB 1 ACO ACO SUB 1 AC1 AC1 SUB 1 AC2 AC2 SUB 1 AC3 AC3 endm Macro for incrementing incr macro ADD 1 AC0 ACO ADD 1 AC1 AC1 ADD 1 AC2 AC2 ADD 1 AC3 AC3 endm Use the archiver to create a macro library ar55 a mac incr asm decr asm Now you can use the mlib directive to reference the macro library and define the incr and decr macros 1 mlib mac lib 2 000000 incr Macro call 000000 4010 ADD 1 AC0O ACO 000002 4011 ADD 1 AC1 AC1 000004 4012 ADD 1 AC2 AC2 000006 4013 ADD 2 AC3 AC3 3 000008 decr Macro call 000008 4210 SUB 1 AC0 ACO 00000a 4211 SUB 1 AC1 AC1 00000c 4212 SUB 1 AC2 AC2 00000e 4213 SUB 1 AC3 AC3
254. e line number Unused zero filled Index of next entry past this block Unused zero filled A 7 8 9 Names Related to Structures Unions and Enumerations Table A 26 illustrates the format of auxiliary table entries for the names of structures unions and enumerations Table A 26 Structure Union and Enumeration Names Format for Auxiliary Table Entries Byte Number 0 3 4 5 6 7 8 17 16 17 Type Long integer Unsigned short integer Description Tag index Unused zero filled Size of the structure union or enu meration Unused zero filled Unused zero filled Appendix B Symbolic Debugging Directives The TMS320C55x assembler supports several directives that the TMS320C55x C compiler uses for symbolic debugging The sym directive defines a global variable a local variable or a function Several parameters allow you to associate various debugging information with the symbol 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 enu meration or union definition The func and endfunc directives specify the beginning and ending lines of a C function The block and endblock directives specify the bounds of C blocks _j The file directive defines a symbol in the symbol table that identifies the current sourc
255. e output file address field to contain a byte count rather than a word count If you use the byte option the output file address increments once for each byte For example if the starting address is Oh the first line contains eight words and you use no byte option the second line would start at address 8 8h If the starting address is Oh the first line contains eight words and you use the byte option the second line would start at address 16 010h The data in both examples are the same byte affects only the calculation of the output file address field not the actual target processor address of the converted data The byte option causes the address records in an output file to refer to byte locations within the file whether the target processor is byte addressable or not Hex Conversion Utility Description 13 35 Controlling the ROM Device Address 13 10 4 Dealing With Address Holes When memory width is different from data width the automatic multiplication of the load address by the correction factor might create holes at the beginning of a section or between sections For example assume you want to load a COFF section sec1 at address 0x0100 of an 8 bit EPROM If you specify the load address in the linker com mand file at location 0x0100 the hex conversion utility will multiply the address by 2 data width divided by memory width 16 8 2 giving the output file a starting address of 0x0200 Unless you cont
256. ecause there is no explicit reference to it in file1 obj or file2 obj Linker Options 9 4 18 Display a Message for Output Section Information w Option The w option displays additional messages pertaining to the creation of memory sections Additional messages are displayed in the following circumstances N In a linker command file you can set up a SECTIONS directive that describes how input sections are combined into output sections However ifthe linker encounters one or more input sections that do not have a corre sponding output section defined in the SECTIONS directive the linker combines the input sections that have the same name into an output section with that name By default the linker does not display a message to tell you when this has occurred If this situation occurs and you use the w option the linker displays a message when it creates a new output section If you do not use the heap stack and sysstack options the linker creates the sysmem stack and sysstack respectively sections for you The sysmem section has a default size of 2000 bytes the stack and sysstack sections have a default size of 1000 bytes You might not have enough memory available for one or all of these sections In this case the linker issues an error message saying a section could not be allocated If you use the w option the linker displays another message with more details which includes the name ofthe direct
257. ections For example if one of the text input sections was already included in another output section when the linker encountered text the linker could not include that first text input section in the second output section Specifying a Section s Runtime Address 9 10 Specifying a Section s Runtime Address At times you may want to load code into one area of memory and run it in another For example you may have performance critical code in a ROM based system The code must be loaded into ROM but it would run faster in RAM The linker provides a simple way to accomplish this You can use the SECTIONS directive to direct the linker to allocate a section twice once to set its load address and again to set its run address For example fir load ROM run RAM Use the oad keyword for the load address and the run keyword for the run address Refer to Section 2 5 Runtime Relocation on page 2 17 for an overview on runtime relocation 9 10 1 Specifying Load and Run Addresses The load address determines where a loader will place the raw data for the section All references to the section such as labels in it refer to its run address The application must copy the section from its load address to its run address this does not happen automatically when you specify a separate run address If you provide only one allocation either load or run for a section the section is allocated only once and will load and run at
258. ed at byte 1000h and term_rec follows it in memory The alignment and block attributes of a GROUP are the maximum alignment and block attributes of any of its members An allocator for a GROUP is subject to the consistency checking rules listed in Section 9 11 4 Linker Description 9 47 Using UNION and GROUP Statements 9 11 3 Nesting UNIONs and GROUPs The linker allows arbitrary nesting of GROUP and UNION statements with the SECTIONS directive By nesting GROUP and UNION statements you can express hierarchical overlays and groupings of sections Example 9 10 shows how two overlays of sections can be grouped together Example 9 10 Nesting GROUP and UNION statements S ECTIONS GROUP 1000h run RAM UNION mysecti load ROM mysect2 load ROM UNION mysect3 load ROM mysect4 load ROM Given the example linker control file above the linker performs the following allocations d The four sections mysect1 mysect2 mysect3 mysect4 are assigned unique non overlapping load addresses in the ROM memory region This assignment is determined by the particular load allocations given for each section Sections mysect1 and mysect2 are assigned the same run address in RAM Sections mysect3 and mysect4 are assigned the same run address in RAM The run addresses of mysect1 mysect2 and mysect3 mysect4 are allo cated contiguously as directed by the GROUP statement s
259. ed by the native C55x environment Ported C54x code makes no assumption about the SXMD bit SXM on C54x after a function call However C55x compiled code expects this bit to be set to 1 f Capturing results MOV ACO TO The ported C54x environment returns the result in ACO while the native C55x environment expects the result to be returned in TO Consequently the result must be copied from ACO to TO Migrating a C54x System to a C55x System 7 13 Using Ported C54x Functions with Native C55x Functions Example 7 2 Assembly Function firlat veneer Continued g Clearing arguments from the stack AADD 5 SP At this point you should decrease the stack by the number of words originally needed to push the function s passed arguments In this case the amount is 5 words Because the stack grows from high addresses to low addresses addition is used to change the stack pointer from a low address to a higher one h Restoring registers and returning POP T3 POP T2 POP ART POP AR6 POP ARS RET Restore the registers saved at the beginning of the function and return 7 2 Example of C54x Assembly Calling C Code This example contains a C54x assembly routine calling a compiled C routine Because the C routine is recompiled with the C55x C compiler the assembly routine must handle the differences between the ported C54x runtime environment and the runtime environm
260. ed register name size of structure represented by structure tag a reference point of structure represented by structure tag a t For more information about predefined register names see Section 3 9 Symbols on page 3 25 Example 5 5 shows built in substitution symbol functions Example 5 5 Using Built In Substitution Symbol Functions asg label ADDR ADDR label kt Ssymemp ADDR label 0 evaluates to true SUB ADDR ACO ACO endif asg x y z list list x y z SLf Sismember ADDR list addr x list y z SUB ADDR ACO ACO sub x endif Macro Language 5 9 Macro Parameters Substitution Symbols 5 3 3 Recursive Substitution Symbols When the assembler encounters a substitution symbol it attempts to substitute the corresponding character string If that string is also a substitution symbol the assembler performs substitution again The assembler continues doing this until it encounters a token that is not a substitution symbol or until it encounters a substitution symbol that it has already encountered during this evaluation In Example 5 6 the x is substituted for z z is substituted for y and y is substituted for x The assembler recognizes this as infinite recursion and ceases substitution Example 5 6 Recursive Substitution asg x z declare z and assign z x asg z y declare y and assign y z asg y x declare x and assign x y ADD x ACO ACO
261. ed within the group However a load allocation is accepted for an entire group only if all of the following conditions are true B The group is initialized i e it has at least one initialized member B The groupis not nested inside another group that has a load allocator B The group does not contain a union containing initialized sections If the group contains a union with initialized sections it is necessary to specify the load allocation for each initialized section nested within the group Consider the following example SECTIONS GROUP load ROM run ROM textl UNION text2 text3 The load allocator given for the group does not uniquely specify the load allocation for the elements within the union text2 and text3 In this case the linker will issue a diagnostic message to request that these load alloca tions be specified explicitly Linker Description 9 49 Overlay Pages 9 12 Overlay Pages Some target systems use a memory configuration in which all or part of the memory space is overlaid by shadow memory This allows the system to map different banks of physical memory into and out of a single address range in response to hardware selection signals In other words multiple banks of physical memory overlay each other at one address range You may want the linker to load various output sections into each of these banks or into banks that are not mapped at load time The linker supports t
262. ef y REF of y x ADD 486 ACO ACO Define x B y Reference y The def definition of x says that itis an external symbol defined in this module and that other modules can reference x The ref definition of y says that it is an undefined symbol that is defined in another module The assembler places both x and y in the object file s symbol table When the file is linked with other object files the entry for x defines unresolved references to x from other files The entry for y causes the linker to look through the symbol tables of other files for y s definition The linker must match all references with corresponding definitions If the linker cannot find a symbol s definition it prints an error message about the unresolved reference This type of error prevents the linker from creating an executable object module Introduction to Common Object File Format 2 19 Symbols in a COFF File 2 7 2 The Symbol Table 2 20 The assembler always generates an entry in the symbol table when it encoun ters an external symbol both definitions and references The assembler also creates special symbols that point to the beginning of each section the linker uses these symbols to resolve the address of and references symbols that are defined in the section The assembler does not usually create symbol table entries for any symbols other than those described above because the linker does not use them For example labels are not included in t
263. eference Guide for an illustration of a boot table 13 9 2 The Boot Table Format The boot table format is simple Typically there is a header record containing the width of the table and possibly some values for various control registers Each subsequent block has a header containing the size and destination address of the block followed by data for the block Multiple blocks can be entered a termination block follows the last block Finally the table can have a footer containing more control register values See the boot loader section in the TMS320C55x DSP CPU Reference Guide for more information Hex Conversion Utility Description 13 27 Building a Table for an On Chip Boot Loader 13 9 3 How to Build the Boot Table Table 13 2 summarizes the hex conversion utility options available for the boot loader Table 13 2 Boot Loader Options 13 28 Option boot bootorg PARALLEL bootorg SERIAL bootorg value bootpage value e value Description Convert all sections into bootable form use instead of a SECTIONS directive Specify the source of the boot loader table as the parallel port Specify the source of the boot loader table as the serial port Specify the source address of the boot loader table Specify the target page number of the boot loader table Specify the entry point for the boot loader table Building a Table for an On Chip Boot Loader 13 9 3 1 Building the Boot Table To build the b
264. egins with a colon followed by the byte count the address the record type 01 and the checksum Record type 04 the extended linear address record specifies the upper 16 address bits It begins with a colon followed by the byte count a dummy address of Oh the record type 04 the most significant 16 bits of the address and the checksum The subsequent address fields in the data records contain the least significant bits of the address Figure 13 11 illustrates the Intel hexadecimal object format Intel Hex Object Format Extended linear address record Most significant 16 bits a 2000000000000100020003000400050006000700080009000A000B000C000D000E000F0068 2000200010001100120013001400150016001700180019001A001B001C001D001E001F0048 Data 2000400000000100020003000400050006000700080009000A000B8000C000D000E000F0028 records 2000600010001100120013001400150016001700180019001A001B001C001D001E001F0008 00000001FF L1 EN ELE Checksum Byte Record count type End of file record Hex Conversion Utility Description 13 39 Description of the Object Formats 13 11 3 Motorola Exorciser Object Format m1 m2 m3 Options The Motorola S1 S2 and S3 formats support 16 bit 24 bit and 32 bit addresses respectively The formats consist of a start of file header record data records and an end of file termination record Each record is made up of five fields rec
265. el or symbol is optional it is usually not shown If it is a required parameter then it will be shown starting against the left margin of the shaded box as in the example below No instruction command directive or parameter other than a symbol or label should begin in column 1 symbol usect section name size in words blocking flag alignment flag The symbolis required for the usect directive and must begin in column 1 The section name must be enclosed in quotes and the section size in words must be separated from the section name by a comma The blocking flag and alignment flag are optional and if used must be separated by commas Some directives can have a varying number of parameters For example the byte directive can have up to 100 parameters The syntax for this directive is byte value Valuen This syntax shows that byte must have at least one value parameter but you have the option of supplying additional value parameters separated by commas Following are other symbols and abbreviations used throughout this document Symbol Definition Symbol Definition ARO AR7 Auxiliary Registers PC Program counter 0 through 7 register B b Suffix binary integer Q q Suffix octal integer H h Suffix hexadecimal SP Stack pointer register integer LSB Least significant bit ST Status register MSB Most significant bit Read This First V Related Documentation From Tex
266. embler may be corrupt or confused Action Assemble a smaller file If a smaller file does not assemble reinstall the assembler Pipeline conflict detected Description This error reports a pipeline conflict Action Check the source to determine what caused the problem and correct the source Assembler Error Messages C 13 Assembler Error Messages Choosing to parse the instruction as MPOLY instead of MAC Invalid page number specified ignored Macro parameter conflict No operands expected Operands ignored Short 3 bit offset mode not available using 16 bit offset Trailing operand does not exist Trailing operands ignored Unrecognized operand ignored Value does notfit into the 1 7 range encoding as register indirect Value does not fit into the 1 7 range using 16 bit offset Description These are warnings about operands The assembler encoun tered operands that it did not expect Action Check the source to determine what caused the problem and whether you need to correct the source Assembler Error Messages Field value truncated to value Field width truncated to size in bits Maximum alignment is to 32K boundary alignment ignored Offset expression value out of range Power of 2 required next larger power of 2 assumed Section Name is limited to 8 characters Specified value out of 8 bit range String is too long will be truncated Value truncated Value truncated to x bit width Description These are
267. emory Map on page 2 14 con tains another example of a linker command file Example 9 1 Linker Command File a obj First input filename y b obj Second input filename o prog out Option to specify output file m prog map Option to specify map file wy The sample file in Example 9 1 contains only filenames and options You can place comments in a command file by delimiting them with and To invoke the linker with this command file enter lnk55 link cmd You can place other parameters on the command line when you use a command file lnk55 r link cmd c obj d obj The linker processes the command file as soon as it encounters it so a obj and b obj are linked into the output module before c obj and d obj You can specify multiple command files If for example you have a file called names lIst that contains filenames and another file called dir cmd that contains linker directives you could enter lnk55 names lst dir cmd One command file can call another command file this type of nesting is limited to 16 levels If a command file calls another command file as input this statement must be the ast statement in the calling command file Linker Description 9 23 Linker Command Files Blanks and blank lines are insignificant in a command file except as delimiters This also applies to the format of linker directives in a command file Example 9 2 shows a sample command file that contains li
268. en 04000h romwidth 8 files appl u2 appl u3 CD ECTIONS text BOOT data cinit sectl vectors const Hex Conversion Utility Description 13 7 Understanding Memory Widths 13 4 Understanding Memory Widths The hex conversion utility makes your memory architecture more flexible by allowing you to specify memory and ROM widths In order to use the hex conversion utility you must understand how the utility treats word widths Four widths are important in the conversion process target width data width memory width and ROM width The terms target word data word memory word and ROM word refer to a word of such a width Figure 13 2 illustrates the three separate and distinct phases of the hex conversion utility s process flow Figure 13 2 Hex Conversion Utility Process Flow Raw data in COFF files is repre d sented in target width sized f words For C55x this is 16 bits COFF input file The target width is fixed and cannot be changed The raw data in the COFF file is Phase truncated to the size specified by the default data width 16 bits The data width sized internal representation is divided into words Phase II according to size specified by the memwidth option The memwidth sized words are broken up according to the size Phase III specified by the romwidth option and are written to a file s according to the specified format i e Intel Tektronix etc Output file s 13
269. ent SECTIONS text data boot SECTIONS text data boot In the example below the COFF file contains six initialized sections text data const vectors coeff and tables Suppose you want only text and data to be converted Use a SECTIONS directive to specify this SECTIONS text data To configure both of these sections for boot loading add the boot keyword SECTIONS text boot data boot F7 Note Using the boot Option and the SECTIONS Directive When you use the SECTIONS directive with the on chip boot loader the boot option is ignored You must explicitly specify any boot sections in the SECTIONS directive For more information about boot and other command line options associated with the on chip boot loader see Table 13 2 page 13 28 Output Filenames 13 7 Output Filenames When the hex conversion utility translates your COFF object file into a data format it partitions the data into one or more output files When multiple files are formed by splitting data into byte wide or word wide files filenames are always assigned in order from least to most significant This is true regardless of target or COFF endian ordering or of any order option 13 7 1 Assigning Output Filenames The hex conversion utility follows this sequence when assigning output file names 1 It looks for the ROMS directive If a file is associated with a range in the
270. ent used by the C55x compiler If you use a different runtime environment for your C55x code your code changes will differ slightly from those in this example However you must still consider the issues addressed here Example 7 3 Prototype of Called C Function 7 14 int C func int buffer int length The assembly function performs some calculations not shown in this example and calls the C function The returned result is copied to the C global variable named result Further calculations also not shown here are then performed Using Ported C54x Functions with Native C55x Functions Example 7 4 Original C54x Assembly Function Declare some data data buffer word 0 10 20 30 40 50 60 70 80 BUFLEN set 11 text Assembly routine starts callsc original C54x code 90 Call C function original C54x code ST BUFLEN SP 0 pass 2nd arg on stack CALLD f C func LD buffer A pass lst arg inA Effects of calling C May modify A B ARO AR2 AR5 T BRC Will not modify AR1 AR6 AR7 May modify ASM BRAF C OVA OVB SXM TC Will not modify other status bits Presume CMPT 0 CPL 1 STL A result Result is in accumulator A original C54x code RE 100 To use this assembly function on C55x it is necessary to change the call to the C function Migrating a C54x System to a C55x S
271. er a hole is created and filled in an initialized output section the hole is identified in the link map along with the value the linker uses to fill it 9 16 4 Explicit Initialization of Uninitialized Sections An uninitialized section becomes a hole only when it is combined with an initialized section When uninitialized sections are combined with each other the resulting output section remains uninitialized However you can force the linker to initialize an uninitialized section by specifying an explicit fill value for it in the SECTIONS directive This causes the entire section to have raw data the fill value For example CD ECTIONS bss fill 1234h Fills bss with 1234h FS S 8 C0aoMV VM MQOOOoooooaao0 mnaxaua maqamaoaoaoaoaoaoaoa _ _s_ a Note Filling Sections Because filling a section even with Os causes raw data to be generated for the entire section in the output file your output file will be very large if you specify fill values for large sections or holes Partial Incremental Linking 9 17 Partial Incremental Linking An output file that has been linked can be linked again with additional modules This is known as partial linking or incremental linking Partial linking allows you to partition large applications link each part separately and then link all the parts together to create the final executable program Follow these guidelines for prod
272. erefore an object module could not be built symbol from file being redefined Description A defined symbol is redefined in an assignment statement too few symbol names in string table for archive n Description The archive file may be corrupt Action If the input file is corrupt try recreating the archive Linker Error Messages too many arguments use a command file Description You used more than ten arguments on a command line or in response to prompts too many i options 7 allowed Action More than seven i options were used Additional search di rectories can be specified with a C DIR or A DIR environ ment variable type flags for redefined Description More than one section type is supplied for a section Note that type COPY has all ofthe attributes of type DSECT so DSECT need not be specified separately type flags not allowed for GROUP or UNION Description A type is specified for a section in a group or union Special section types apply to individual sections only u does not specify a legal symbol name Description The u option did not specify a legal symbol name that exists in one of the files that you are linking unexpected EOF end of file Description There is a syntax error in the linker command file undefined symbol first referenced in file Description Either a referenced symbolis not defined or the r option was not used Unless the r option is used
273. erve space in processor memory they are usually allocated into RAM These sections have no actual contents in the object file they simply reserve memory A program can use this space at runtime for creating and storing variables Uninitialized data areas are built by using the bss and usect assembler directives _j The bss directive reserves space in the bss section The usect directive reserves space in a specific uninitialized named section Each time you invoke the bss directive the assembler reserves more space in the appropriate section Each time you invoke the usect directive the assembler reserves more space in the specified named section How the Assembler Handles Sections The syntax for these directives is bss symbol size in words blocking flag alignment flag symbol usect section name size in words blocking flag alignment flag symbol points to the first word reserved by this invocation of the bss or usect directive The symbol corresponds to the name of the variable that you re reserving space for It can be referenced by any other section and can also be de clared as a global symbol with the global assembler direc tive size in words is an absolute expression The bss directive reserves size words in the bss sec tion Lj The usect directive reserves size words in section name blocking flag is an optional parameter If you specify a value
274. es and must follow operating system conventions You can specify a full pathname for example c dsp file1 asm If you do not speci fy a full pathname the assembler searches for the file in 1 The directory that contains the current source file 2 Any directories named with the i assembler option 3 Any directories specified by the environment variable A DIR For more information about the i option and A DIR see Section 3 5 Naming Alternate Directories for Assembler Input on page 3 14 The copy and include directives can be nested within a file being copied or included The assembler limits nesting to 32 levels the host operating system may set additional restrictions The assembler precedes the line numbers of copied files with a letter code to identify the level of copying An A indicates the first copied file B indicates a second copied file etc Assembler Directives 4 37 copy include Read Source File Example 1 Back in original file 4 38 copy asm source file data Space 29 copy byte asm pstring done In this example the copy directive is used to read and assemble source state ments from other files then the assembler resumes assembling into the cur rent file The original file copy asm contains a copy statement copying the file byte asm When copy asm assembles the assembler copies byte asm into its place in the listing note listing below The copy file byte asm contains a
275. ess A constant used in this context should be expressed in words A label defined in a data section can be handled correctly by the assembler and linker However a label defined in a code section cannot be used in this context The PC value column of the assembly listing file is counted in units that are appropriate for the section being listed For code sections the PC is counted in bytes for data sections it is counted in words For example 1 000000 text PC is counted in BYTES 2 000000 2298 MOV AR1 ARO 3 000002 4010 ADD 1 ACO 4 5 000000 data PC is counted in WORDS 6 000000 0004 word 4 5 6 7 000001 0005 PC is 1 word 000002 0006 PC is 2 words 000003 0007 7 000004 0001 foo word 1 The data placement directives that operate on characters byte ubyte char uchar and string allocate one character per byte when in a code section and one character to a word when in a data section However Texas Instruments highly recommends that you use these directives only in data sections E C55x Assembler Features Directives that have a size parameter expressed in addressable units ex pect this parameter to be expressed in bytes for a code section and in words for a data section For example align 2 aligns the PC to a 2 byte 16 bit boundary in a code section and to a 2 word 32 bit boundary in a data section The code examples below display data and code for C55x Example 3 1 C55x Data Example
276. etween the hex conversion utility output file address field and the paddr parameter can be summarized as follows out_file_addrt paddr_val load addr sect beg load addr x data width mem width 13 34 out_file_addr is the address of the output file paddr_val is the value supplied with the paddr parameter inside the SECTIONS directive sec beg load addr is the section load address assigned by the linker t If paddr is not specified The value of data width divided by memory width is a correction factor for address generation The section beginning load address factor subtracted from the load address is an offset from the beginning of the section 3 The zero option When you use the zero option the utility resets the address origin to 0 for each output file Since each file starts at 0 and counts upward any address records represent offsets from the beginning of the file the address within the ROM rather than actual target addresses of the data You must use the zero option in conjunction with the image option to force the starting address in each output file to be zero If you specify the zero option without the image option the utility issues a warning and ignores the zero option Boot Loader Mode When the boot loader is used the hex conversion utility places the different COFF sections that are in the boot table into consecutive memory locations Each COFF section becomes a boot table block w
277. f it is larger than a page This blocking applies to the section not to the object declared with this instance of the usect directive alignment flag is an optional parameter This flag causes the assembler to allocate size on long word boundaries ee Note Specifying an Alignment Flag Only To specify an alignment flag without a blocking flag you must insert two commas before the alignment flag as shown in the syntax Other sections directives text data and sect end the current section and tell the assembler to begin assembling into another section The usect and the bss directives however do not affect the current section The assembler assembles the usect and the bss directives and then resumes assembling into the current section Variables that can be located contiguously in memory can be defined in the same specified section to do so repeat the usect directive with the same sec tion name Assembler Directives 4 103 USect Reserve Uninitialized Space For more information about COFF sections see Chapter 2 ntroduc tion to Common Object File Format Example This example uses the usect directive to define two uninitialized named sec tions var1 and var2 The symbol ptr points to the first word reserved in the var1 section The symbol array points to the first word in a block of 100 words reserved in var1 and dflag points to the first word in a block of 50 words in var1 The sym
278. ference Lister Description 0000e cece eect eens 11 1 Explains how to invoke the cross reference lister to obtain a listing of symbols their definitions and their references in the linked source files 11 1 Producing a Cross Reference Listing pp 11 2 Invoking the Cross Reference Lister i 11 8 Cross Reference Listing Example Disassembler Description 000 cece eee m I mnn Explains how to invoke the disassembler to obtain a listing of the COFF disassembly for object files or linked executable files 12 1 Invoking the Disassembler pp 2 2 12 2 Disassembly Examples 0000 eect teen eee teens 2 4 Hex Conversion Utility Description 0 ccc eee 13 1 Explains how to invoke the hex utility to convert a COFF object file into one of several standard hexadecimal formats suitable for loading into an EPROM programmer 13 1 Hex Conversion Utility Development Flow 13 2 Invoking the Hex Conversion Utility llle 19 3 Command File eius Leber her a n RR Re ee ERR e 13 3 1 Examples of Command Files i 13 4 Understanding Memory Widths 13 4 1 Target Width 19 4 2 Data WIG 2225922 kobe aein an a diiested 13 4 3 Memory Width 1344 ROM WIG ias aiao ian daaa ERE E IR Eel ERIS LR EREER Let RESR 13 4 5 A Memory Configuration Example i 13 4 6 Specifying Word Order for Output Words i 13 6 13 7 13 8 13 10 13 11 13 12 Contents The ROMS Directive 2 n nece ated
279. file the assembler does not create one unless you use the lowercase L option or the x option In this case the assembler uses the input file name with a lst extension and places the listing file in the in put file directory J If you supply a listing file but do not supply an extension the assembler uses st as the default extension identifies the assembler options that you want to use Options are not case sensitive and can appear anywhere on the com mand line following the assembler name Precede each option with a hyphen Single letter options without parameters can be combined for example lc is equivalent to c Options that have parameters such as i must be specified separately filename appends the contents of filename to the command line You can use this option to avoid the limitations on command line length imposed by the host operating system a creates an absolute listing When you use a the assembler does not produce an object file The a option is used in conjunction with the absolute lister C d h help Invoking the Assembler makes case insignificant in the assembly language files For example c will make the symbols ABC and abc equivalent f you do not use this option case is signifi cant default Case significance is enforced primarily with symbol names not with mnemonics and register names dname value sets the name symbol This i
280. fine the memory map of a target system You can name portions of memory and specify their starting addresses and their lengths J The SECTIONS directive tells the linker how to combine input sections into output sections and where to place these output sections in memory Subsections allow you to manipulate sections with greater precision You can specify subsections with the linker s SECTIONS directive If you do not specify asubsection explicitly then the subsection is combined with the other sections with the same base section name It is not always necessary to use linker directives If you don t use them the linker uses the target processor s default allocation algorithm described in Section 9 13 Default Allocation Algorithm on page 9 55 When you do use linker directives you must specify them in a linker command file Refer to the following sections for more information about linker command files and linker directives Section Number Section Name Page 9 6 Linker Command Files 9 22 9 8 The MEMORY Directive 9 9 The SECTIONS Directive 9 32 9 13 Default Allocation Algorithm 9 55 How the Linker Handles Sections 2 3 4 Default Memory Allocation Figure 2 3 illustrates the process of linking two files Figure 2 3 Combining Input Sections to Form an Executable Object Module Program Memory file1 obj Data Memory file 1 file 2 data initialized named section nos u vars i uninitialized fil
281. fined external references between input files The linker command language controls memory configuration output section definition and address binding The language supports expression assign ment and evaluation You configure system memory by defining and creating a memory model that you design Two powerful directives MEMORY and SECTIONS allow you to Allocate sections into specific areas of memory DD Combine object file sections Define or redefine global symbols at link time Linker Development Flow 9 2 Linker Development Flow Figure 9 1 illustrates the linker s role in the assembly language development process The linker accepts several types of files as input including object files command files libraries and partially linked files The linker creates an executable COFF object module that can be downloaded to one of several development tools or executed by a TMS320C55x device Figure 9 1 Linker Development Flow C Source files Macro Source files i C compiler Arcniver Assembler source Macro library Library build utility Runtime ae uc support e Library of e library object 1 L files Linker ll Debugging tools Executable COFF file Hex conversion utility EPROM programmer Linker Description 9 3 Invoking the Linker 9 3 Invoking the Linker The general
282. for more information Step 2 Callthe macro After defining a macro you call itby using the macro name as a mnemonic in the source program This is referred to as a macro call Step 3 Expand the macro The assembler expands your macros when the source program calls them During expansion the assembler passes arguments by variable to the macro parameters replaces the macro call statement with the macro definition and assembles the source code By default the macro expansions are printed in the listing file You can turn off expansion listing by using the mnolist directive See Section 5 8 Formatting the Output Listing on page 5 21 for more information When the assembler encounters a macro definition it places the macro name in the opcode table This redefines any previously defined macro library entry directive or instruction mnemonic that has the same name as the macro This allows you to expand the functions of directives and instructions as well as to add new instructions Defining Macros 5 2 Defining Macros You can define a macro anywhere in your program but you must define the macro before you can use it Macros can be defined at the beginning of a source file in an include copy file or in a macro library For more information about macro libraries see Section 5 4 Macro Libraries on page 5 14 Macro definitions can be nested and they can call other macros but all elements of any macro must be defined in the sa
283. for the whole range Gaps before between or after sections are filled with the fill value from the ROMS directive with the value specified with the fill option or with the default value of 0 Hex Conversion Utility Description 13 17 The ROMS Directive 13 5 2 An Example of the ROMS Directive The ROMS directive in Example 13 1 shows how 16K words of 16 bit memory could be partitioned for four 8K x 8 bit EPROMs Example 13 1 A ROMS Directive Example infile out image memwidth 16 ROMS EPROM1 org 04000h len 02000h romwidth 8 files rom4000 b0 rom4000 b1 EPROM2 org 06000h len 02000h romwidth fill OFFh files rom6000 b0 rom6 000 b1 ll oo In this example EPROM 1 defines the address range from 4000h through 5FFFh The range contains the following sections This section Has this range text 4000h through 487Fh data 5B80H through 5FFFh The rest of the range is filled with Oh the default fill value The data from this range is converted into two output files rom4000 b0 contains bits 0 through 7 rom4000 b1 contains bits 8 through 15 EPROM2 defines the address range from 6000h through 7FFFh The range contains the following sections This section Has this range data 6000h through 633Fh table 6700h through 7C7Fh The rest of the range is filled with OFFh from the specified fill value The data from this range is converted into two output files
284. from the out block macro however are accessible to the in block macro Example 5 15 Using Nested Macros 5 22 in block macro y a Visible parameters are y a and s x z from the calling macro endm out block macro x y z visible parameters are x y z in block x y macro call with x and y as arguments endm out block macro call Using Recursive and Nested Macros Example 5 16 shows recursive macros The fact macro produces assembly code necessary to calculate the factorial of n where n is an immediate value The result is placed in data memory address loc The fact macro accomplishes this by calling fact1 which calls itself recursively Example 5 16 Using Recursive Macros a Mnemonic example fact macro N loc if N 2 MOV 1 loc else MOV N loc eval N 1 factl endif endm factl macro zif NO I MOV loc T3 MOV T3 HI AC2 MOV ACO loc eval N 1 facti endif endm N MPYK N AC2 ACO N n is an integer constant loc memory address n 0 1 1 n gt 2 so store n at loc decrement n and do the factorial of n 1 call factl with current environment multiply present factorial by present position save result decrement position recursive call Macro Language 5 23 Using Recursive and Nested Macros Example 5 16 Using Recursive Macros Continued b Algebraic example fact macro N loc n is an intege
285. fy the Input Files Ves f demo obj fft obj tables obj f Ree Specify the Memory Configurations os 7 KOR KKK KK KK KR I KC ECKE KC ECKE KC ECKE AR A ECKE k kk ke ko ke KR e x f MEMORY RAM PG origin 00100h length 06F80h ONCHIP origin 007081h length 0F7Fh EXT origin 08001h length 01FFFh ROM origin 0C000h length 03F80h KK RK RRR AA RA AAA AAA AA AA A A IA IA A ke koe ek koe ok oe ke x f free Specify the Output Sections RUN KR KKK KK KKK I A AAA AA Ck Kk kk kk ke koe ke ke oe oe x x f SECTIONS text load ROM link text into ROM var_defs load ONCHIP defs in RAM data fill 07A1Ch load ONCHIP tables obj data data input fft obj data data input 100h create hole fill with 07A1Ch and link with ONCHIP bss load RAM_PG fill OFFFFh Remaining bss fill and link
286. g ERROR Missing Parameter ERROR Missing Parameter mexit 5 20 Formatting the Output Listing 5 8 Formatting the Output Listing Macros substitution symbols and conditional assembly directives may hide information You may need to see this hidden information so the macro language supports an expanded listing capability By default the assembler shows macro expansions and false conditional blocks in the output list file You may want to turn this listing off or on within your listing file Four sets of directives enable you to control the listing of this information m m m m Macro and Loop Expansion Listing mlist expands macros and loop endloop blocks The mlist directive prints all code encountered in those blocks mnolist suppresses the listing of macro expansions and loop endloop blocks For macro and loop expansion listing mlist is the default False Conditional Block Listing fclist causes the assembler to include in the listing file all conditional blocks that do not generate code false condi tional blocks Conditional blocks appear in the listing exactly as they appear in the source code fcnolist suppresses the listing of false conditional blocks Only the code in conditional blocks that actually assemble appears in the listing The if elseif else and endif directives do not appear in the listing For false conditional block listing fclist is the default Substitution
287. g the mc command line option The cpl off directive models the CPL status bit set to 0 The cpl on and cpl off directives take no arguments In the case of a conflict be tween the command line option and the directive the directive takes prece dence The scope of the cpl on cpl off directives is static and not subject to the control flow of the assembly program All of the assembly code between the cpl on line and the cpl off line is assembled in CPL mode In CPL mode cpl on direct memory addressing is relative to the stack pointer SP The dma syntax is SP dma where dma can be a constant or a linktime known symbolic expression The assembler encodes the value of dma into the output bits By default cpl off direct memory addressing dma is relative to the data page register DP The dma syntax is dma where dma can be a constant or a linktime known symbolic expression The assembler computes the differ ence between dma and the value in the DP register and encodes this differ ence into the output bits The DP can be referenced in a file but never defined in that file it is set exter nally Consequently you must use the dp directive to inform the assembler of the DP value before it is used Issue this directive immediately following any instruction that changes the value in the DP register The syntax of the direc tive is dp dp value dp value can be a constant or a symbolic expression If the dp d
288. ge width of the source listing Page 4 27 A m SI SE REEF JA SA oJ Lol co Lon lall aj xl o SU e Loa Ex EIS EE Oo 1co1 1 1 Co 09 JOO L gt 10 LO LD Directives Summary Table 4 1 Assembler Directives Summary Continued e Directives that reference other files Mnemonic and Syntax Description Page copy filename Include source statements from another file 4 37 def symbol symbol Identify one or more symbols that are defined in the 4 54 current module and may be used in other modules global symbol symbol Identify one or more global external symbols 4 54 include filename Include source statements from another file 4 37 ref symbol symbol Identify one or more symbols that are used in the cur 4 54 rent module but may be defined in another module f Directives that define macros Mnemonic and Syntax Description Page macro Identify the source statement as the first line of a 4 72 macro definition You must place macro in the opcode field mlib filename Define macro library mexit Go to endm This directive is useful when error test ing confirms that macro expansion will fail endm End macro code block Var Define a local macro substitution symbol 4 106 g Directives that control conditional assembly Mnemonic and Syntax Description Page break well defined expression End loop assem
289. gnificant word is stored first The long and ulong directives align the result on the long word boundary while the xlong directive does not A value can be Anexpression that the assembler evaluates and treats as an 32 bit signed or unsigned number D A character string enclosed in double quotes Each character in a string represents a separate value Fr rr Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of long ulong and xlong directives in a section that includes C55x instructions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections The value operand can be either an absolute or relocatable expression If an expression is relocatable the assembler generates a relocation entry that re fers to the appropriate symbol the linker can then correctly patch relocate the reference This allows you to initialize memory with pointers to variables or with labels You can use up to 100 values but they must fit on a single source statement line If you use a label it points to the first word that is initialized When you use the directives in a struct endstruct sequence they define a member s size they do not initialize memory For more information about Struct endstruct see Section 4 8 Assembly Time Symbol
290. h instructions to their smallest form Send user defined warning messages to the output 4 46 device Assembler Directives 4 7 Directives That Define Sections 4 2 Directives That Define Sections These directives associate portions of an assembly language program with the appropriate sections m m bss reserves space in the bss section for uninitialized variables The specified size parameter must be in words since it is a data section Clink sets the STYP_CLINK flag in the type field for the named section The clink directive can be applied to initialized or uninitialized sections The STYP_CLINK flag enables conditional linking by telling the linker to leave the section out of the final COFF output of the linker if there are no references found to any symbol in the section data identifies portions of code in the data section The data section usually contains initialized data On C55x data sections are word addressable sect defines initialized named sections and associates subsequent code or data with that section A section defined with sect can contain execut able code or data text identifies portions of code in the text section The text section con tains executable code On C55x code sections are byte addressable usect reserves space in an uninitialized named section The usect directive is similar to the bss directive but it allows you to reserve space separately from the bss section
291. hat a Struct or union is always used in a data context ee 3 4 1 1 Definition of Code Sections The assembler identifies a section as a code section if the section is introduced with a text directive or the section has at least one instruction assembled into it If a section is not established with a text data or sect directive the assembler assumes that it is a text code section Because the section type determines the assembler s offset and size computations it is important to clearly define your current working section as code or data before assembling bits into the section Assembler Description 3 7 C55x Assembler Features 3 4 1 2 Assembly Programs and Native Units The assembler and the linker assume that your code is written using word addresses and offsets in the context of data segments and byte addresses and offsets in the context of code segments m If an address is to be sent via a program address bus e g an address used as the target of a call or a branch the processor expects a full 24 bit address A constant used in this context should be expressed in bytes A label defined in a code section can be handled correctly by the assembler and linker However a label defined in a data section cannot be used in this context If an address is to be sent via a data address bus e g an address denotes alocation in memory to be read or written the processor expects a 23 bit word addr
292. hat a file called source asm contains these statements Copy copyl asm copy copy2 asm Assembler Description 3 15 Naming Alternate Files and Directories for Assembler Input 3 16 Assume that the files are stored in the following directories Windows c tools files copy1 asm c dsys copy2 asm UNIX tools files copy1 asm dsys copy2 asm You could set up the search path with the commands shown in the following table Operating System Enter Windows set A_DIR c dsys masm55 ic tools files source asm UNIX setenv A DIR dsys masm55 i tools files source asm The assembler first searches for copy1 asm and copy2 asm in the current directory because source asm is in the current directory Then the assembler searches in the directory named with the i option and finds copy1 asm Finally the assembler searches the directory named with A DIR and finds copy2 asm Note that the environment variable remains set until you reboot the system or reset the variable by entering one of these commands Operating System Enter Windows set A_DIR UNIX unsetenv A_DIR Source Statement Format 3 6 Source Statement Format TMS320C55x assembly language source programs consist of source state ments that can contain assembler directives assembly language instructions macro directives and comments Source statement lines can be as long as the source file format allows Example source statements are shown below a Mnemonic
293. he address field of the hex conver sion utility output file is a function of the load address as given in the linker command file and the hex conversion utility parameter values The rela tionship is summarized as follows out file addrt load addr x data width mem width out file addr is the address of the output file load addr is the linker assigned load address data width is specified as 16 bits for the TMS320C55x devices See subsection 13 4 2 Data Width on page 13 9 mem width is the memory width of the memory system You can specify the memory width by the memwidth option or by the memwidth parameter inside the ROMS directive See subsection 13 4 3 Memory Width on page 13 9 t If paddr is not specified The value of data width divided by memory width is a correction factor for address generation When data width is larger than memory width the correction factor expands the address space For example if the load address is 0 x 1 and data width divided by memory width is 2 the output file address field would be 0 x2 The data is split into two consecutive loca tions the size of the memory width 2 The paddr parameter of the SECTIONS directive When the paddr parameter is specified for a section the hex conversion utility bypasses Hex Conversion Utility Description 13 33 Controlling the ROM Device Address the section load address and places the section in the address specified by paddr The relationship b
294. he format of the d option is as follows masm55 dname value The nameis the name of the symbol you want to define The value is the value you want to assign to the symbol If the valueis omitted the symbol is setto 1 Within assembler source you may test the symbol with the following direc tives Type of Test Directive Usage Existence if isdefed name Nonexistence if isdefed name 0 Equal to value if name value Not equal to value if name value Note that the argument to the isdefed built in function must be enclosed in quotes The quotes cause the argument to be interpreted literally rather than as a substitution symbol 3 9 4 Predefined Symbolic Constants The assembler has several predefined symbols including the following LJ the dollar sign character represents the current value of the section program counter SPC jj Memory mapped registers are set up as symbols by the assembler 3 9 5 Substitution Symbols Symbols can be assigned a string value variable This enables you to alias character strings by equating them to symbolic names Symbols that represent character strings are called substitution symbols When the assembler encounters a substitution symbol its string value is substituted for the symbol name Unlike symbolic constants substitution symbols can be redefined A string can be assigned to a substitution symbol anywhere within a program for example a
295. he operators listed in Table 9 1 the linker also has an align operator that allows a symbol to be aligned on an n byte boundary within an output sec tion n is a power of 2 For example the expression align 16 aligns the SPC within the current section on the next 16 byte boundary Because the align operator is a function of the current SPC it can be used only in the same context as that is within a SECTIONS directive Table 9 1 Operators Used in Expressions Precedence Symbols Operators Evaluation Unary plus minus 1s complement Right to left Multiplication division modulo Left to right Addition subtraction Left to right lt lt gt gt Left shift right shift Left to right lt lt gt Se Less than LT or equal greater than Left to right GT or equal l Not equal to equal to Left to right amp Bitwise AND Left to right Bitwise exclusive OR Left to right Bitwise OR Left to right Note Unary and have higher precedence than the binary forms Linker Description 9 61 Assigning Symbols at Link Time 9 15 4 Symbols Defined by the Linker The linker automatically defines several symbols that a program can use at runtime to determine where a section is linked These symbols are external so they appear in the link map They can be accessed in any assembly language module if they are declared with a global directive Values are assigned to these symbols as follows
296. he parent processor The EPROM format and ROMS directive address correspond to those used by the parent processor not those that are used by the child Building a Table for an On Chip Boot Loader 13 9 5 Setting the Entry Point for the Boot Table After completing the boot load process program execution starts at the ad dress of the first block loaded the default entry point By using the e option with the hex conversion utility you can set the entry pointto a different address For example if you want your program to start running at address 0123h after loading specify e 0123h on the command line or in a command file You can determine the e address by looking at the map file that the linker generates rr Note Valid Entry Points The value must be a constant the hex conversion utility cannot evaluate symbolic expressions like c_int00 default entry point assigned by the TMS320C55x C compiler When you use the e option the utility builds a dummy block of length 1 and data value 0 that loads at the specified address Your blocks follow this dummy block Since the dummy block is loaded first the dummy value of 0 is over written by the subsequent blocks Then the boot loader jumps to the e option address after the boot load is completed 13 9 6 Using the C55x Boot Loader This subsection explains and gives an example on using the hex conversion utility with the boot loader for C55x devices The C55x boot
297. he symbol table unless they are declared with global For symbolic debugging purposes it is sometimes useful to have entries in the symbol table for each symbol in a program To accomplish this invoke the assembler with the s option Chapter 3 Assembler Description The assembler translates assembly language source files into machine language object files These files are in common object file format COFF which is discussed in Chapter 2 Introduction to Common Object File Format and Appendix A Common Object File Format Source files can contain the following assembly language elements Assembler directives described in Chapter 4 Macro directives described in Chapter 5 Assembly language instructions described in the TMS320C55x Instruction Set Reference Guides Topic Page 31 Assembler Overview o e arrearen nean pep OPE 5 2 3 2 Assembler Development Flow eeeeeeeeeeeese 8 3 3 3 Invoking the Assembler ss EET 3 4 C55x Assembler Features me cece cece e eee eee ee 3 5 Naming Alternate Files and Directories for Assembler Input 3 6 Source Statement Format rer rrr rer ttt itt et ters r rir 8 17 37 Constants zero no b 21 3 ouECharacterStringsg ene 3g SV TD OS M e cL E e acne B 25 3 10EXxpressions eerie ns ere saei 3 31 ERNITDADNZTR E oea a a a E 3 12 SourcelListinge a en oo no a Srl Cross Reierence Stn Glee terete tee III 3 1 Assembler Overview 3 1 Assembler Overview TMS320C55x has
298. his description includes information on the memory model relocation line numbers and local symbols d suppresses the display of data sections in the listing h displays a listing of the available disassembler options i the disassembler will attempt to disassemble data sections into instructions q quiet suppresses the banner and all progress information S Invoking the Disassembler suppresses the banner all progress information and the section header information added by the disassembler causes the disassembler to use the compiler s con vention of enabling the ARMS and CPL bits By de fault the disassembler assumes that ARMS and CPL are disabled Use when disassembling any file generated from C source suppresses the display of the opcode and section program counter in the listing When you use this option along with qq the disassembly listing looks like the original assembly source file suppresses the display of text sections in the list ing Disassembler Description 12 3 Disassembly Examples 12 2 Disassembly Examples This section provides examples of the various features of the disassembler Consider the following assembly source file called test asm global GLOBAL global FUNC CONSTANT Set text START MOV AR1 ARO ADD CONSTANT ACO last ADD GLOBAL ACO data word 4 foo word 1 word FUNC The symbols GLOBAL and FUNC are defined in test
299. his feature by providing overlay pages Each page represents an address range that must be configured separately with the MEMORY directive You can then use the SECTIONS directive to specify the sections to be mapped into various pages 9 12 1 Using the MEMORY Directive to Define Overlay Pages To the linker each overlay page represents a completely separate memory comprising the full 24 bit range of addressable locations This allows you to link two or more sections at the same or overlapping addresses if they are on different pages Pages are numbered sequentially beginning with 0 If you do not use the PAGE option the linker allocates all sections into PAGE 0 For example assume that your system can select between two banks of physical memory for data memory space address range AO0h to FFFFh for PAGE 1 and OAOOh to 2BFF for PAGE 2 Although only one bank can be selected at a time you can initialize each bank with different data This is how you use the MEMORY directive to obtain this configuration Example 9 11 Memory Directive With Overlay Pages ONCHIP origin PROG origin 0800h length 02C00h length OAOOh length 02C00h length OAOOh length 0240h 0D200h 02200h 0D400h 02200h OVR MEM origin DATA origin OVR MEM origin Overlay Pages Example 9 11 defines three separate address spaces PAGE 0 defines an area of on chip program memory and the rest of program memory space PAGE 1 defines the fir
300. hose destination address is equal to the linker assigned section load address The address field of the the hex conversion utility output file is not related to the section load addresses assigned by the linker The address fields are sim ply offsets to the beginning ofthe table multiplied by the correction factor data width divided by memory width The beginning of the boot table defaults to the linked load address of the first bootable section in the COFF input file unless you use one of the following mechanisms listed here from low to high priority Higher priority mechanisms override the values set by low priority options in an overlapping range 1 The ROM origin specified in the ROMS directive The hex conversion utility places the boot table at the origin of the first memory range in a ROMS directive Controlling the ROM Device Address 2 The bootorg option The hex conversion utility places the boot table at the address specified by the bootorg option if you select boot loading from memory Neither bootorg PARALLEL nor bootorg SERIAL affect the address field 13 10 2 Controlling the Address Increment Index By default the hex conversion utility increments the output file address field according to the memory width value If memory width equals 16 the address increments on the basis of how many 16 bit words are present in each line of the output file 13 10 3 The byte Option Some EPROM programmers may require th
301. icates the relocation type by appending one of the following characters to the end of the field undefined external reference text relocatable data relocatable sect relocatable bss usect relocatable complex relocation expression Field 4 Source Statement Field This field contains the characters of the source statement as they were scanned by the assembler Spacing in this field is determined by the spacing in the source statement Example 3 6 shows an assembler listing with each of the four fields identified Assembler Description 3 37 Source Listings Example 3 6 Assembler Listing a Mnemonic example 3 38 1 global RSET INTO INT1 INT2 2 global TINT RINT XINT USER 3 global ISRO ISR1 ISR2 4 global time rcv xmt proc 5 6 initmac macro 7 initialize macro 8 BSET 9 ST1_55 j disable overflow 9 MOV 0 DP set dp 0 MOV 55 ACO set ACO 1 BCLR 11 ST1_55 enable ints 2 endm 3 4 Reset and interrupt vectors 5 6 000000 Sect rset 7 000000 6A00 RSET B init 000002 0010 8 000004 6A00 INTO B ISRO 000006 0000 9 000008 6A00 INTI
302. idth 8 EPROM2 OUTPUT FILES rom6000 b0 rom6000 b1 CONTENTS 00006000 0000633f 00006340 000066ff 00006700 00007c7E 00007c80 00007ffF b0 b7 b8 b15 data FILL 000000ff table FILL 000000ff The SECTIONS Directive 13 6 The SECTIONS Directive You can convert specific sections of the COFF file by name with the SECTIONS directive You can also specify those sections you want the utility to configure for loading from an on chip boot loader and those sections that you want to locate in ROM at a different address than the oad address speci fied in the linker command file Ifyou use a SECTIONS directive the utility converts only the sections that you list in the directive and ignores all other sections in the COFF file If you don t use a SECTIONS directive the utility converts all initialized sections that fall within the configured memory The TMS320C55x compiler generated initialized sections include text const cinit and switch Uninitialized sections are never converted whether or not you specify them in a SECTIONS directive Note Sections Generated by the C Compiler The TMS320C55x C compiler automatically generates these sections J Initialized sections text const cinit and switch _j Uninitialized sections bss stack and sysmem Use the SECTIONS directive in a command file For more information about using a command file see
303. ied number of bits start ing at the current word in a data section Fields are packed starting at the most significant part of the word moving toward the least significant part as more fields are added If the assembler encounters a field size that does not fit into the current word it writes out the word increments the SPC and begins packing fields into the next word You can use the align directive with an oper and of 1 to force the next field directive to begin packing into a new word If you use a label it points to the word that contains the specified field When you use field in a struct endstruct sequence field defines a member s size it does not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 Initialize Field field Example This example shows how fields are packed into a word Notice that the SPC does not change until a word is filled and the next word is begun 1 000000 data A2 3 xx Initialize a 14 bit field Ek 4 KKK KKK KK ck ck ck ck ck ck ck KK KKK KKK KKKKAKK KK ko kockok 5 000000 2AF0 field OABCh 14 6 7 8 ax Initialize a 5 bit field lt x 9 Wok in
304. ies an indirect address The assembler goes to the address specified by the contents of register AR4 and then moves the contents of that location to the specified accumulator Immediate Value for Directives The immediate value mode is primarily used with instructions In some cases it can also be used with the operands of directives 3 6 5 Instruction Field In algebraic assembly the instruction field is a combination of the mnemonic and operand fields used in mnemonic syntax You usually do not have a mne monic followed by operands Rather the operands are part of the overall state ment The following items describe how to use the instruction field for algebra ic syntax Assembler Description 3 19 Source Statement Format Generally operands are not separated by commas Some algebraic instructions consist of a mnemonic and operands For algebraic state ments of this type commas are used to separate operands For example Ims Xmem Ymem ACx ACy Expressions that have more than one term that is used as a single oper and must be delimited with parentheses This rule does not apply to state ments using a function call format since they are already set off with parentheses For example ACO AC1 amp 1 lt lt sym lt lt 5 The expression 1 lt lt sym is used as a single operand and is therefore set off with parentheses L All register names are reserved J For algebraic instructions that consist of
305. ifies one to four attributes associated with the named range Attributes are optional when used they must be enclosed in parentheses Attributes restrict the allocation of output sections into certain memory ranges If you do not use any attributes you can allocate any output section into any range with no restrictions Any memory for which no attributes are specified including all memory in the default model has all four attributes Valid attributes include R specifies that the memory can be read W specifies that the memory can be written to X specifies that the memory can contain executable code l specifies that the memory can be initialized Specifies the starting address of a memory range enter as origin org or o The value specified in bytes is a 24 bit constant and may be decimal octal or hexadecimal The MEMORY Directive length Specifies the length of a memory range enter as length len or l The value specified in bytes is a 24 bit constant and may be deci mal octal or hexadecimal fill Specifies a fill character for the memory range enter as fillor f Fills are optional The value is a 2 byte integer constant and may be decimal octal or hexadecimal The fill value will be used to fill areas of the memory range that are not allocated to a section Ti T Note Filling Memory Ranges If you specify fill values for large memory ranges your output file will be very large because filling a memory range even
306. ig it will start on an address boundary text block 0x80 Page specifies the memory page to be used see Section 9 12 Overlay Pages on page 9 50 text PAGE 0 For the load usually the only allocation you may simply use a greater than sign and omit the load keyword ROM text gt ROM 0x1000 UCextt stex If more than one parameter is used you can string them together as follows text gt ROM align 16 PAGE 2 Or if you prefer use parentheses for readability text load ROM align 16 page 2 You can supply a specific starting address for an output section by following the section name with an address text 0x1000 This example specifies that the text section must begin at byte location 1000h The binding address must be a 24 bit constant Output sections can be bound anywhere in configured memory assuming there is enough space but they cannot overlap If there is not enough space to bind a section to a specified address the linker issues an error message UU S1 Note Binding and Alignment or Named Memory are Incompatible You cannot bind a section to an address if you use alignment or named memory If you try to do so the linker issues an error message The SECTIONS Directive 9 9 3 2 Named memory You can allocate a section into a memory range that is defined by the MEMORY directive This example names ranges and links sections into them MEMORY
307. ile Format A 13 Symbol Table Structure and Content The entry for each symbol in the symbol table contains the symbol s Name or a pointer into the string table Type Value Section it was defined in Storage class Basic type integer character etc Derived type array structure etc Dimensions Line number of the source code that defined the symbol O O O O O O O O L Section names are also defined in the symbol table All symbol entries regardless of class and type have the same format in the symbol table Each symbol table entry contains the 18 bytes of information listed in Table A 9 Each symbol may also have an 18 byte auxiliary entry the special symbols listed in Table A 10 on page A 15 always have an auxiliary entry Some symbols may not have all the characteristics listed above if a par ticular field is not set it is set to null Table A 9 Symbol Table Entry Contents Byte Number Type Description 0 7 Character This field contains one of the following 1 An 8 character symbol name padded with nulls 2 A pointer into the string table if the symbol name is longer than 8 characters 8 11 Long integer Symbol value storage class dependent 12 13 Short integer Section number of the symbol 14 15 Unsigned short Basic and derived type specification integer 16 Character Storage class of the symbol 17 Character Number of auxiliary entries always 0 or 1 Symbol Table Structure and Content A 7 1 Specia
308. ilename must conform to operating system conventions Linker Error Messages can t open filename Description The specified file does not exist Action Check spelling pathname environment variables etc The filename must conform to operating system conventions can t read Description The file may be corrupt Action If the input file is corrupt try reassembling it can t seek Description The file may be corrupt Action If the input file is corrupt try reassembling it can t write Description Disk may be full or protected Action Check disk volume and protection command file nesting exceeded with file Description Command file nesting is allowed up to 16 levels Linker Error Messages D 5 Linker Error Messages e flag does not specify a legal symbol name Description The e option is not supplied with a valid symbol name as an operand entry point other than c intO0O specified Description For c or cr option only A program entry point other than the value of c intOO was supplied The runtime conventions of the compiler assume that c intOO is the one and only entry point entry point symbol undefined Description The symbol used with the e option is not defined errors in input not built Description Previous errors prevent the creation of an output file fail to copy Description The file may be corrupt Action If the input file is
309. indi rect memory access These modifiers are more efficient for code size optimization The scope of the arms on and arms off directives is static and not subject to the control flow of the assembly program All assembly code between the arms on line and the arms off line is assembled in ARMS mode Syntax Description Assign Character Strings to Substitution Symbols asg eval asg character string substitution symbol eval well defined expression substitution symbol The asg directive assigns character strings to substitution symbols Substitution symbols are stored in the substitution symbol table The asg directive can be used in many of the same ways as the set directive but while set assigns a constant value which cannot be redefined to a symbol asg assigns a character string which can be redefined to a substitution symbol Ll The assembler assigns the character string to the substitution symbol The quotation marks are optional If there are no quotation marks the assembler reads characters up to the first comma and removes leading and trailing blanks In either case a character string is read and assigned to the substitution symbol The substitution symbol must be a valid symbol name The substitution symbol may be 32 characters long and must begin with a letter Remaining characters of the symbol can be a combination of alphanumeric characters the underscore and the dollar sign The e
310. ine an Entry Point e global symbol Option The memory address at which a program begins executing is called the entry point When a loader loads a program into target memory the program counter must be initialized to the entry point the PC then points to the beginning of the program The linker can assign one of four possible values to the entry point These values are listed below in the order in which the linker tries to use them If you use one of the first three values it must be an external symbol in the symbol table The value specified by the e option The syntax is e global symbol Where global symbol defines the entry point and must appear as an external symbol in one of the input files The value of symbol c int0O if present _c_int00 mustbe the entry point if you are linking code produced by the C compiler _j The value of symbol main if present Lj Zero default value This example links file1 obj and file2 obj The symbol begin is the entry point begin must be defined as external in file1 or file2 lnk55 e begin filel obj file2 0bj 9 4 5 Set Default Fill Value f cc Option The f option fills the holes formed within output sections or initializes uninitial ized sections when they are combined with initialized sections This allows you to initialize memory areas during link time without reassembling a source file The argument ccis a 16 bit constant up to four hexadecimal digits If you
311. ine mapping also appear without any special notation 4 000003E961 STL A AR3 000005 00 The STL instruction above could be written as MOV ACO AR3 Understanding the Listing File The code below shows a one to many instruction mapping that requires the C55x instructions to be in a different order than the original source A one to many mapping starts with a PORT line that echoes the original source The multiple lines that correspond to the mapping will begin and end with the original source line number 7 in this case 7 Xxx PORT MVDK AR4 name 7 000006 EC31 AMAR name XCDP port of 000008 7E00 MVDK AR4 name 00000a 0000 5 6 00000c4COA RPT 410 7 00000eEF83 MOV AR4 coef CDP port of 00001005 MVDK AR4 name To summarize in the example above the original C54x code RPT 410 MVDK AR4 name was mapped to be AMAR name XCDP RPT 10 MOV AR4 coef CDP A macro definition is simply echoed 8 9 subm macro meml mem2 reg 10 LD meml reg 11 SUB mem2 reg T2 endm A macro invocation is marked with a MACRO line Within the macro expansion you may see any of the cases described above 13 14 MACRO subm name AR6 B 14 000011A100 LD name B 14 000013D7C1 SUB AR6 B 00001511 Native C55x instructions appear without any special notation For more information on using ported C54x code with native C55x code see Section 7 2 Using P
312. inguish commands that you enter from items that the system displays such as prompts command output error messages etc Here is a sample program listing 2 0001 2f x byte 47 3 0002 32 Z byte 50 4 0003 text In syntax descriptions the instruction command or directive is in a bold typeface font and parameters are in an italic typeface Portions of a syntax that are in bold should be entered as shown portions of a syntax that are in italics describe the type of information that should be entered Here is an example of command line syntax abs55 filename abs55 is a command The command invokes the absolute lister and has one parameter indicated by filename When you invoke the absolute lister you supply the name of the file that the absolute lister uses as input Square brackets and identify an optional parameter If you use an optional parameter you specify the information within the brackets you don t enter the brackets themselves This is an example of a command that has an optional parameter hex55 options filename The hex55 command has two parameters The first parameter options is optional Since options is plural you may select several options The second parameter filename is required Note that byte does not begin in column 1 m Notational Conventions In assembler syntax statements column 1 is reserved for the first character of a label or symbol If the lab
313. inking using with byte directive 4 34 defined label directive described 9 67 to 9 68 Idouble directive Index 8 length MEMORY specification ROMS specification length directive listing control 4 18 library search algorithm library build utility described line symbolic debugging directive line number table structure a 11 to a 12 line number entry defined directive linker assigning symbols S assignment pressions C code 9 10 9 69 to 9 72 COFF 2 ro 9 25 9 73 command files 2 4 9 22 configured memory 9 56 defined described error messages D 1 to D 16 examples 9 790 9 76 GROUP statement handling COFF sections 2 12 to 2 14 in the development flow 8 59 9 60 to 9 61 invoking keywords 9 53 tol9 43 loading a program MEMORY directive _ 2 12 9 28 to object libraries 9 26 to 9 27 options described poe summary table 9 6 to 9 7 output 9 3 9 17 overlay pages overview partial linking 9 67 to 9 68 section runtime address sections in memory map output 9 56 special D 58 SECTIONS directive 9 32 to 9 40 symbols 2 19 to 2 20 unconfigured memory 9 58 UNION statement 9 45 to 9 47 Index linker command file editing for ported C54x code list directive same effect with option directive 4 19 lister absolute 10 1 to 10 10 cross reference 11 1 to 11 6 listing cross reference listing enabling 4 67 file
314. instructions SYM1 set 2 Symbol SYM1 2 Begin MOV SYM1 AR1 Load AR1 with 2 data byte 016h Initialize word 016h b Algebraic instructions SYM1 set 2 Symbol SYM1 2 Begin AR1 SYM1 Load AR1 with 2 data byte 016h Initialize word 016h 3 6 1 Source Statement Syntax A source statement can contain four ordered fields The general syntax for Source statements is as follows Mnemonic syntax abel mnemonic operand list comment Algebraic syntax label instruction comment Follow these guidelines All statements must begin with a label a blank an asterisk or a semico lon Labels are optional if used they must begin in column 1 One or more blanks must separate each field Tab characters are equivalent to blanks DD Comments are optional Comments that begin in column 1 can begin with an asterisk or a semicolon or but comments that begin in any other column must begin with a semicolon Assembler Description 3 17 Source Statement Format 3 6 2 Label Field Labels are optional for all assembly language instructions and for most but not all assembler directives When used a label must begin in column 1 of a source statement A label can contain up to 32 alphanumeric characters A Z a z 0 9 _ and Labels are case sensitive and the first character cannot be a number A label can be followed by a colon the colon is not t
315. int 0 text nop nop B mylab newblock directive allowing sixth definition of mylab newblock data mylab int 0 text nop nop B mylab 3 30 3 10 Expressions Expressions An expression is an operand or a series of operands separated by arithmetic operators An operand is an assembly time constant or a link time relocatable symbol The range of valid expression values is 32 768 to 32 767 Three main factors influence the order of expression evaluation Parentheses Precedence groups Left to right evaluation Expressions that are enclosed in parentheses are always evaluated first 8 4 2 4 but8 4 2 1 You cannot substitute braces or brackets for parentheses The C55x assembler uses the same order of pre cedence as the C language does as summarized in Table 3 1 This differs from the order of prece dence of other TMS320 assemblers When paren theses do not determine the order of expression evaluation the highest precedence operation is evaluated first 8 4 2 10 4 2is evaluated first When parentheses and precedence groups do not determine the order of expression evaluation the expressions are evaluated as happens in the C language 8 4 2 4 but 8 4 2 1 Assembler Description 3 31 Expressions 3 10 1 Operators Table 3 1 lists the operators that can be used in expressions ee d Note Relational Operators Cannot Be Applied to Relocatable Link Tim
316. into an executable file Assemble the assembly lan guage files with the x option This option creates a cross reference listing and adds cross reference information to the object file By default the assembler cross references only global symbols but if assembler is invoked with the s option local symbols are also added Link the object files to obtain an execut able file To invoke the cross reference lister enter the following xref55 options input filename output filename xref55 is the command that invokes the cross reference utility options identifies the cross reference lister options you want to use Options are not case sensitive and can appear any where on the command line following the command Pre cede each option with a hyphen The cross reference lister options are as follows lowercase L specifies the number of lines per page for the output file The format of the option is Inum where num is a decimal constant For example 30 sets the number of lines per page in the output file to 30 The space between the option and the decimal constant is optional The default is 60 lines per page q quiet suppresses the banner and all progress information input filename _ is a linked object file If you omit the input filename the utility prompts for a filename output filename is the name of the cross reference listing file If you omit the output filename the default filename will
317. into target memory Several methods can be used for loading a program depending on the execu tion environment Two common situations are described below Li The TMS320C55x debugging tools including the software simulator and software development system have built in loaders Each of these tools contains a LOAD command that invokes a loader the loader reads the executable file and copies the program into target memory You can use the hex conversion utility hex55 which is shipped as part of the assembly language package to convert the executable COFF object module into one of several object file formats You can then use the con verted file with an EPROM programmer to burn the program into an EPROM Symbols in a COFF File 2 7 Symbols in a COFF File A COFF file contains a symbol table that stores information about symbols in the program The linker uses this table when it performs relocation Debugging tools can also use the symbol table to provide symbolic debugging 2 7 1 External Symbols External symbols are symbols that are defined in one module and referenced in another module You can use the def ref or global directives to identify symbols as external def Defined in the current module and used in another module ref Referenced in the current module but defined in another module global May be either of the above The following code segment illustrates these definitions def x DEF of x r
318. irective is not used in a file the assembler assumes that the value of the DP is 0 The scope of the dp directive is static and not subject to the control flow of the program The value set by the directive is used until the next dp directive is encountered or until the end of the source file is reached Note that dma access to the MMR page and to the I O page is processed iden tically by the assembler whether CPL mode is specified or not The access to the MMR page is indicated by the mmap qualifier in the syntax The access to the I O page is indicated by the readport and writeport qualifiers These dma accesses are always encoded by the assembler as relative to the origin of 0 3 4 4 3 ARMS Mode C55x Assembler Features ARMS mode affects indirect addressing and is useful in the context of controller code The assembler cannot track the value of the ARMS status bit Consequently you must use the arms on and arms off directives to model the ARMS value Issue one of these directives immediately following any in struction that changes the value in the ARMS bit The arms on directive mod els the ARMS status bit set to 1 it is equivalent to using the ma command line option The arms off directive models the ARMS status bit set to 0 The arms on and arms off directives take no arguments In the case of a conflict between the command line option and the directive the directive takes precedence The scope of the arms on and arms
319. is allows you to equate meaningful names with constants and other values DD The symbol is a label that must appear in the label field The value must be a well defined expression that is all symbols in the expression must be previously defined in the current source module Undefined external symbols and symbols that are defined later in the module cannot be used in the expression If the expression is relocatable the symbol to which it is assigned is also relocatable The value of the expression appears in the object field of the listing This value is not part of the actual object code and is not written to the output file Symbols defined with set or equ can be made externally visible with the def or global directive In this way you can define global absolute constants This example shows how symbols can be assigned with set and equ 1 KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKKAKKKK KKK KKK KKK 2 x Set symbol index to an integer expr EK 3 ide and use it as an immediate operand Aw 4 5 INDEX equ 100 2 3 6 000000 7B00 ADD INDEX ACO ACO 000002 3500 7 8 Kock ck ck ck KKK KKK KKK KKK KKK Ck ck ck ck ck ck ck ck kk ck ck ck ck KKK KKK KKK KKK 9 Set symbol SYMTAB to a relocatable expr 10 KE and use it as a relocata
320. is example the Vars and Counts sections are set for conditional linking 1 000000 Sect Vars 2 Vars section is conditionally linked 3 clink 4 5 000000 001A X word 01Ah 6 000001 001A Y word 01Ah 7 000002 001A 2 word 01Ah 8 000000 sect Counts 9 Counts section is conditionally linked 0 clink 1 2 000000 001A Xcount word 01Ah 3 000001 001A Ycount word 01Ah 14 000002 001A Zcount word 01Ah 15 By default text is unconditionally linked 6 000000 text 7 Reference to symbol X cause the Vars section 8 to be linked into the COFF output 19 000000 3C00 MOV 0 ACO 20 000002 C000 MOV ACO X Syntax Description Read Source File copy include copy filename include filename The copy and include directives tell the assembler to read source state ments from a different file The statements that are assembled from a copy file are printed in the assembly listing The statements that are assembled from an included file are not printed in the assembly listing regardless of the num ber of list nolist directives assembled The assembler 1 Stops assembling statements in the current source file 2 Assembles the statements in the copied included file 3 Resumes assembling statements in the main source file starting with the statement that follows the copy or include directive The filename is a required parameter that names a source file It may be en closed in double quot
321. isables the C5x compatibility mode of the C54x Because C55x does not support C5x compatibility mode this instruction is ignored Action Remove this instruction from your code or simply ignore this message Assembler Error Messages C 17 Assembler Error Messages C54x does not modify ARn but C55x does Description This message occurs when both memory operands of an ADD or SUB instruction use the same ARn register but only the second operand modifies the register For example SUB AR3 AR3 A Action On C54x such an instruction will not modify AR3 by adding one to it On C55x the same instruction will add one to AR3 This difference in behavior may or may not affect your code To prevent this message from being issued move the ARn modification to the first operand SUB AR3 AR3 A Port of RETF correct only for non interrupt routine Description This message occurs when the assembler encounters RETF and RETFD the C54x fast interrupt return instructions Because it is possible to correctly use these instructions in non interrupt routines the RETF instruction is mapped to the C55x RET instruction Action If this instance of RETF or RETFD is actually used to return from an interrupt you need to consider the issues described in R5005 and then rewrite this instruction using the C55x RETI instruction Assembler Error Messages Port of F RETE is probably not correct Consider rewriting to use RETI instead
322. ity Error Messages section mapped to reserved memory message Description A section or a boot loader table is mapped into a reserved Action memory area listed in the processor memory map Correct the section or boot loader address Refer to the TMS320C55x DSP CPU Reference Guide for valid memory locations sections overlapping Description Two or more COFF section load addresses overlap or a boot Action table address overlaps another section This problem may be caused by an incorrect translation from load address to hex output file address that is performed by the hex conversion utility when memory width is less than data width See Section 13 4 Understanding Memory Widths on page 13 8 and Section 13 10 Controlling the ROM Device Address on page 13 33 unconfigured memory error Description This error could have one of two causes Action B The COFF file contains a section whose load address falls outside the memory range defined in the ROMS directive B The boot loader table address is not within the memory range defined by the ROMS directive Correct the ROM range as defined by the ROMS directive to cover the memory range as needed or modify the section load address or boot loader table address Remember that if the ROMS directive is not used the memory range defaults to the entire processor address space For this reason removing the ROMS directive could also be a workaround Hex Conversion Utility Descri
323. ive to allocate the sysmem or Stack section yourself For more information about the SECTIONS directive see Section 9 9 The SECTIONS Directive on page 9 32 For more information about the default actions of the linker see Section 9 13 Default Allocation Algorithm on page 9 55 Linker Description 9 19 Linker Options 9 4 19 Exhaustively Read Libraries x Option The linker normally reads input files including archive libraries only once when they are encountered on the command line or in the command file When an archive is read any members that resolve references to undefined symbols are included in the link If an input file later references a symbol defined in a previously read archive library the reference will not be resolved With the x option you can force the linker to reread all libraries The linker rereads libraries until no more references can be resolved Linking using the x option may be slower so you should use it only as needed For example if a lib contains a reference to a symbol defined in b lib and b lib contains a reference to a symbol defined in a lib you can resolve the mutual dependencies by listing one of the libraries twice as in lnk55 la lib lb lib la lib or you can force the linker to do it for you lnk55 la lib lb lib Byte Word Addressing 9 5 Byte Word Addressing C55x memory is byte addressable for code and word addressable for data The assembler and linker keep trac
324. iven directive requires a label but none is specified Action Correct the source by specifying the required label Cannot find the end of the repeat statement Label s for SWITCH statement must be defined within current section Standalone labels not permitted in structure union defs Description These are errors about invalid labels The given directive does not permit a label but one is specified Description Remove the invalid label Assembler Error Messages Local label number defined differently in each pass Local label number is multiply defined Local label number is not defined in this section Local labels can t be used with directives Description These are errors about the illegal use of local labels Action Correct the source per the error message text Use newblock to reuse local labels Bad term in expression Binary operator can t be applied Cannot resolve symbol in expression Difference between segment symbols not permitted Expression evaluation failed Illegal divide by zero Illegal remainder by zero Integer divide by zero Integer remainder by zero Loop size too big for LOCALREPEAT Offset out of range Operation cannot be performed on given operands Unable to compose expression Unary operator can t be applied Value of expression has changed due to jump expansion Well defined expression required Description These are errors about general expressions An illegal oper and combination was used
325. k of the addresses relative offsets and sizes of the bits in units that are appropriate for the given section words for data sections and bytes for code sections Note Use Byte Addresses in Linker Command File All addresses and sizes supplied in the linker command file should be byte addresses for both code and data sections qL J In the case of program labels the unchanged byte addresses will be encoded in the executable output and during execution sent over the program address bus In the case of data labels the byte addresses will be divided by 2 in the linker converting them to word addresses prior to being encoded in the executable output and sent over the data address bus The map file output by the linker shows code addresses and sizes in bytes and data addresses and sizes in words Linker Description 9 21 Linker Command Files 9 6 Linker Command Files Linker command files allow you to put linking information in a file this is useful when you invoke the linker often with the same information Linker command files are also useful because they allow you to use the MEMORY and SECTIONS directives to customize your application You must use these directives in a command file you cannot use them on the command line Note Use Byte
326. k that MEMORY and SECTIONS directives allow enough room to ensure that no sections overlap section enters unconfigured memory at address Description A section can t be allocated because no existing configured memory area is large enough to hold it Action If you are using a linker command file check that MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory Linker Error Messages D 13 Linker Error Messages section not built Description Most likely there is a syntax error in the SECTIONS directive section not found Description An input section specified in a SECTIONS directive was not found in the input file section won t fit into configured memory Description A section can t be allocated because no configured memory area exists that is large enough to hold it Action If you are using a linker command file check that the MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory seek to failed Description The input file may be corrupt Action If the input file is corrupt try reassembling it semicolon required after assignment Description There is a syntax error in the command file statement ignored Description There is a syntax error in an expression symbol referencing errors not built Description Symbol references could not be resolved Th
327. ker s banner when q is the first option on the command line or in a command file This option is useful for batch operation 9 4 14 Strip Symbolic Information s Option The s option creates a smaller output module by omitting symbol table information and line number entries The s option is useful for production applications when you must create the smallest possible output module This example links file1 obj and file2 obj and creates an output module stripped of line numbers and symbol table information named nosym out lnk55 o nosym out s filel obj file2 0bj Using the s option limits later use of a symbolic debugger and may prevent a file from being relinked Linker Description 9 17 Linker Options 9 4 15 Define Stack Size stack constant Option The TMS320C55x C compiler uses an uninitialized section stack to allocate space for the runtime stack You can set the size of the stack section at link time with the stack option Specify the size in bytes as a constant immediately after the option lnk55 stack 0x1000 defines a stack size If you specified a different stack size in an input section the input section stack size is ignored Any symbols defined in the input section remain valid only the stack size will be different When the linker defines the stack section it also defines a global symbol STACK SIZE and assigns it a value equal to the size of the section The default stack size is 1
328. ks will be suppressed puts all defined symbols in the object file s symbol table The assembler usually puts only global symbols into the symbol table When you use s symbols defined as labels or as assembly time constants are also placed in the table uname undefines the predefined constant name which overrides any d options for the specified constant produces a cross reference table and appends it to the end ofthe listing file also adds cross reference informa tion to the object file for use by the cross reference utility If you do not request a listing file the assembler creates one anyway 3 4 3 4 1 C55x Assembler Features C55x Assembler Features The sections that follow provide important information on features specific to the C55x assembler byte word addressing Section 3 4 1 DD parallel instruction rules Section 3 4 2 variable length instructions Section 3 4 3 memory modes Section 3 4 4 Byte Word Addressing C55x memory is byte addressable for code and word addressable for data The assembler and linker keep track of the addresses relative offsets and sizes of the bits in units that are appropriate for the given section words for data sections and bytes for code sections Ye Note Offsets in struct and union constructs Offsets of fields defined in struct or union constructs are always counted in words regardless of the current section The assembler assumes t
329. l Symbols The symbol table contains some special symbols that are generated by the compiler assembler and linker Each special symbol contains ordinary symbol table information as well as an auxiliary entry Table A 10 lists these symbols Table A 10 Special Symbols in the Symbol Table Symbol Description file File name text Address of the text section data Address of the data section bss Address of the bss section bb Address of the beginning of a block eb Address of the end of a block bf Address of the beginning of a function ef Address of the end of a function target Pointer to a structure or union that is returned by a function nfake Dummy tag name for a structure union or enumeration 6OS End of a structure union or enumeration etext Next available address afterthe end of the text output section edata Next available address after the end of the data output section end Next available address after the end of the bss output section Several of these symbols appear in pairs bb eb indicate the beginning and end of a block Lj bf ef indicate the beginning and end of a function nfake eos name and define the limits of structures unions and enumera tions that were not named The eos symbol is also paired with named structures unions and enumerations When a structure union or enumeration has no tag name the compiler assigns ita name so that it can be entered into the symbol table
330. lanation of section placement within the memory map see Section 9 8 The MEMORY Directive on page 9 28 and Section 9 9 The SECTIONS Directive on page 9 32 Relocation 2 4 Relocation The assembler treats each section as if it began at address 0 All relocatable symbols labels are relative to address 0 in their sections Of course all sections can t actually begin at address 0 in memory so the linker relocates sections by DD Allocating them into the memory map so that they begin at the appropriate address DD Adjusting symbol values to correspond to the new section addresses _j Adjusting references to relocated symbols to reflect the adjusted symbol values The linker uses relocation entries to adjust references to symbol values The assembler creates a relocation entry each time a relocatable symbol is refer enced The linker then uses these entries to patch the references after the symbols are relocated Example 2 2 contains a code segment for the C55x that generates relocation entries Example 2 2 Code That Generates Relocation Entries a Mnemonic example ref X 000000 text 000000 4A04 B Y 000002 7600 MOV X ACO Generates relocation entry 000004 0008 000006 9400 Y reset b Algebraic example ref X 000000 text 000000 4A04 goto 4 Y 000002 7600 ACO X Generates relocation entry 000004 0008 000006 9400 Y reset Introduction to Common Object File Format 2 15 Relocation 2 16 In
331. lobal Symbols mmregs Hexadecimal Address 0018 0019 001A 001B 001C 001D 001E 001F 0020 0021 0022 0023 0024 0025 0026 0027 0028 0029 002A 002B 002C 002E 002F 0030 0031 0032 0033 0034 0035 0036 002D Description Data stack pointer Circular buffer size register Block repeat counter register Block repeat start address register Block repeat end address register Processor mode status register PMST Program counter extension register for C54x code that accesses PMST Reserved Temporary register Temporary register Temporary register Temporary register Accumulator register AC2 Coefficient data pointer Accumulator register AC3 High part of extended data page register Reserved Data page register Peripheral data page register Circular buffer size register Circular buffer size register Circular buffer offset register Circular buffer offset register Circular buffer offset register Circular buffer offset register Circular buffer offset register Assembler Directives 4 77 mmregs Assign Memory Mapped Register Names as Global Symbols Table 4 2 Memory Mapped Registers Continued Name TRN1 BRC1 BRS1 CSR RSAOH RSAOL REAOH REAOL RSA1H RSA2L REA1H REA1L RPTC IER1 IFR1 DBIERO DBIER1 IVPD IVPH ST2 SSP SP SPH CDPH Hexadecimal Address 0037 0038 0039 003A 003B 003C 003D 003E 003F 0040 0041 0042 0043 0044 0045
332. lt lialf vcn cee aes x 4 57 WMS san x textes 4 46 Jf Liziletrekrepge reves 4 59 word uword 005 4 61 NCUde ereere 6 tek ee 4 37 Var 4 106 te etd nd ete 4 A 61 MMOAL 4 dds edi ded cae Shanes 4 53 oe peer hae eee 4 63 KONG ds dha eae ees 4 69 label ss 4 65 Syntax Description Example Align SPC on a Boundary align even align size even The align directive aligns the section program counter SPC on the next boundary depending on the size parameter The size may be any power of 2 although only certain values are useful for alignment The size parameter should be in bytes for a code section and in words for a data section If a size is not specified the SPC is aligned on the next 128 byte boundary for a code section or the next 128 word page boundary for a data section A hole is created by the align directive if the SPC at the point at which the directive occurs is noton the desired byte or word boundary In a data section the assembler fills holes created by align with null values 0 In a code section holes are filled with NOP instructions The even directive aligns the SPC on a word code section or long word data section boundary This directive is equivalentto the align directive with an op erand of 2 Using the align directive has two effects The assembler aligns the SPC on a boundary within the current section _j The assembler sets a flag that forces the linker to
333. mat COFF which helps you to use the TMS320C55x tools more efficiently Read Chapter 2 Introduction to Common Object File Format before using the assembler and linker Assembler description contains detailed information about using the mnemonic and algebraic assemblers This section explains how to invoke the assemblers and discusses source statement format valid constants and expressions assembler output and assembler directives It also describes macro elements Additional assembly language tools describes in detail each of the tools provided with the assembler to help you create assembly language source files For example Chapter 9 explains how to invoke the linker how the linker operates and how to use linker directives Chapter 13 explains how to use the hex conversion utility Notational Conventions Notational Conventions Reference material provides supplementary information This section contains technical data about the internal format and structure of COFF object files It discusses symbolic debugging directives thatthe C compiler uses Finally it includes hex conversion utility examples assembler and linker error messages and a glossary This document uses the following conventions Program listings program examples and interactive displays appear in a special typeface Examples use a bold version of the special typeface for emphasis interactive displays use a bold version ofthe special typeface to dist
334. me file Nested macros are discussed in Section 5 9 Using Recursive and Nested Macros on page 5 22 A macro definition is a series of source statements in the following format macname macro parameter parametern model statements or macro directives mexit endm macname names the macro You must place the name in the source statement s label field Only the first 32 characters of a macro name are significant The assembler places the macro name in the internal opcode table replacing any instruction or previous macro definition with the same name macro identifies the source statement as the first line of a macro definition You must place macro in the opcode field parameters are optional substitution symbols that appear as operands for the macro directive Parameters are discussed in Section 5 3 Macro Parameters Substitution Symbols on page 5 6 model statements are instructions or assembler directives that are executed each time the macro is called macro directives are used to control macro expansion mexit functions as a goto endm statement The mexit directive is useful when error testing confirms that macro expansion will failand completing the rest of the macro is unnecessary endm terminates the macro definition Macro Language 5 3 Defining Macros Example 5 1 Macro Definition Call and Expansion 5 4 If you want to include comments with your macro definition but do
335. ment Format 3 6 4 Operand Field The operand field is a list of operands that follow the mnemonic field An operand can be a constant see Section 3 7 Constants on page 3 21 a symbol see Section 3 9 Symbols on page 3 25 or a combination of con stants and symbols in an expression see Section 3 10 Expressions on page 3 31 You must separate operands with commas Operand Prefixes for Instructions The assembler allows you to specify that a constant symbol or expres sion should be used as an address an immediate value or an indirect value The following rules apply to the operands of instructions B prefix the operand is an immediate value If you use the sign as a prefix the assembler treats the operand as an immediate value This is true even when the operand is a register or an address the assembler treats the address as a value instead of using the contents of the address This is an example of an instruction that uses an oper and with the prefix Label ADD 123 ACO The operand 123 is an immediate value The assembler adds 123 decimal to the contents of the specified accumulator B prefix the operand is an indirect address If you use the sign as a prefix the assembler treats the operand as an indirect address that is it uses the contents of the operand as an address This is an example of an instruction that uses an operand with the prefix Label MOV AR4 ACO The operand AR4 specif
336. mmand line option and the directive the directive takes precedence The scope of the cb4cm onand cb54cm off directives is static and not subject to the control flow of the assembly program All assembly code between the cb4cm on and cb4cm off directives is assembled in C54x compatibility mode In C54x compatibility mode ARO is used instead of TO in memory operands For example AR5 TO is invalid in C54x compatibility mode AR5 ARO should be used Assembler Directives 4 35 clink Conditionally Leave Section Out of COFF Output Syntax Description Example 4 36 Clink section name The clink directive sets up conditional linking for a section by setting the STYP_CLINK flag in the type field for section name The clink directive can be applied to initialized or uninitialized sections If clink is used without a section name it applies to the current initialized section If clink is applied to an uninitialized section the section name is required The section name is significant to 200 characters and must be en closed in double quotes A section name can contain a subsection name in the form of section name subsection name The STYP_CLINK flag tells the linker to leave the section out of the final COFF output of the linker if there are no references found to any symbol in the section A section in which the entry point of a C program is defined cannot be marked as a conditionally linked section In th
337. mple suppose the current directory contains the library object lib Assume thatthis library defines symbols that are referenced in the file file1 obj This is how you link the files lnk55 filel obj object lib If you want to use a library that is not in the current directory use the l lowercase L linker option The syntax for this option is l filename The filename is the name of an archive library the space between and the filename is optional You can augment the linker s directory search algorithm by using the i linker option or the C DIR or C55X C DIR environment variables The linker searches for object libraries in the following order 1 It searches directories named with the i linker option 2 lt searches directories named with C DIR and C55X C DIR 3 IfC DIRand C55X C DIR are notset it searches directories named with the assembler s environment variables C55X_A DIR and A DIR 4 It searches the current directory Linker Description 9 13 Linker Options 9 4 9 1 Name an Alternate Library Directory i Option The i option names an alternate directory that contains object libraries The syntax for this option is i dir The dir names a directory that contains object libraries the space between i and the directory name is optional When the linker is searching for object libraries named with the option it searches through directories named with i first Each i option specifies only
338. ms into global symbol table create 3 dim templates Declare Structure Types Struct endstruct tag Example 4 1 000000 data 1 BIT REC struct Stag 2 0000 STREAM string 64 3 0040 BIT7 field 7 bitsl 64 4 0040 BIT9 field 9 bits2 64 5 0041 BIT10 field 10 bits3 65 6 0042 X INT sint X int 66 7 0043 BIT LEN endstruct length 67 8 9 BITS tag BIT REC 10 000000 text 11 000000 D600 ADD 8 BITS BIT7 ACO ACO move into acc 000002 00 12 000003 187F AND 127 ACO mask off garbage bits 000005 00 1 3 14 000000 bss BITS BIT REC Assembler Directives 4 95 tab Define Tab Size Syntax tab size Description The tab directive defines the tab size Tabs encountered in the source input are translated to size spaces in the listing The default tab size is eight spaces Example Each of the following lines consists of a single tab character followed by an NOP instruction Source file default tab size OP OP OP O mm Q QOO N Listing file default tab size 000000 20 NOP 000001 20 NOP 000002 20 NOP 000003 20 NOP 000004 20 NOP 000005 20 NOP coo 101 5 C ho ES ie 12 000006 20 NOP 13 000007 20 NOP 14 000008 20 NOP 4 96 Syntax Description Assemble Into text Section text text The text directive tells the assembler to begin assembling into the text sec tion The assembler assumes that the text section contains executable code The secti
339. must be a decimal octal or hexadecimal constant that is a power of 2 greater than or equal to 8 When using the memwidth parameter you must also specify the paddr parameter for each section in the SECTIONS directive specifies a fill value to use forthe range In image mode the hex conversion utility uses this value to fill any holes between sections in a range The value must be a decimal octal or hexadecimal constant with a width equal to the target width Any value you specify here overrides the fill option When using fill you must also use the image command line option See subsection 13 8 2 Specifying a Fill Value on page 13 26 The ROMS Directive files identifies the names of the output files that correspond to this range Enclose the list of names in curly braces and order them from least significant to most significant output file The number of file names should equal the number of output files that the range will generate To calculate the number of output files refer to Section 13 4 4 ROM Width on page 13 10 The utility warns you if you list too many or too few file names Unless you are using the image option all of the parameters defining a range are optional the commas and equals signs are also optional A range with no origin or length defines the entire address space In image mode an origin and length are required for all ranges Ranges on the same page must not overlap and must be listed in order
340. n Index 11 Index overlay page defined E 6 described 9 50 to p 54 using the SECTIONS directive 9 52 to 9 53 overlaying sections 9 45 to 9 47 paddr SECTIONS specification 13 22 page directive k 19 4 83 PAGE option MEMORY directive 9 28 to 9 30 9 53 to 9 55 9 57 PAGE ROMS specification pages overlay 9 50 to 9 54 PAGE syntax p 53 to p 55 parallel instructions differences 7 19 rules parentheses in expressions 3 31 partial linking defined described to path See alternate directories environment variables precedence groups predefined names d assembler option prefixes for operands program counters See SPC program memory 9 28 pstring directive 4 14 q absolute lister apticn 10 3 archiver option assembler option 3 6 cross reference M Tl disassembler E linker option 9 17 Index 12 qq disassembler option 12 3 quiet run B 6 defined E 6 linker 9 17 archiver command assembler option R MEMORY attribute 9 30 RAM model autoinitialization defined ref directive 4 54 identifying external symbols 2 19 register symbols registers C54x to C55x mapping 7 6 C55x temporaries relational operators relocatable output module relocation at runtime capabilities 9 8 to 9 9 defined sections 2 15 to 2 16 structuring information A 9 to A 10 reserved words in C55x 6 6 linker 9 25 resetting local labels 4 79 RETE in
341. n If you are using a linker command file check that MEMORY and SECTIONS directives allow enough room to ensure that no sections are being placed in unconfigured memory missing filename on 1 use lt filename gt Description No filename operand is supplied for the lowercase L option misuse of DOT symbol in assignment instruction Description The symbol is used in an assignment statement that is out side the SECTIONS directive no allocation allowed for uninitialized UNION member Description A load address was supplied for an uninitialized section in a union An uninitialized section in a union gets its run address from the UNION statement and has no load address so no load allocation is valid for the member Linker Error Messages no allocation allowed with a GROUP allocation for section ignored Description A section in a group was specified for individual allocation The entire group is treated as one unit so the group may be aligned or bound to an address but the sections making up the group cannot be handled individually no input files Description No COFF files were supplied The linker cannot operate with out at least one input COFF file no load address specified for using run address Description No load address is supplied for an initialized section If an ini tialized section has a run address only the section is allo cated to run and load at the same address no run allocati
342. n The option directive selects several options for the assembler output listing Option list is a list of options separated by vertical lines each option selects a listing feature These are valid options limits the listing of byte directives to one line limits the listing of long directives to one line turns off macro expansions in the listing resets the B M T and W options limits the listing of string directives to one line limits the listing of word directives to one line produces a symbol cross reference listing You can also obtain a cross reference listing by invoking the assembler with the x option xz4amzru Options are not case sensitive Assembler Directives 4 81 option Select Listing Options Example This example shows how to limit the listings of the byte word long and String directives to one line each il 2 Limit the listing of byte word 3 long and string directives ER 4 KR to 1 line each ER 5 6 option B W L T 7 000000 data 8 000000 00BD byte C OBOh 5 9 000004 AABB long OAABBCCDDh 536 A 10 000008 15AA word 5546 78h 11
343. n The input file may be corrupt Action If the input file is corrupt try reassembling it load address for uninitialized section ignored Description A load address is supplied for an uninitialized section Unini tialized sections have no load addresses only run address es load address for UNION ignored Description UNION refers only to the section s run address load allocation required for initialized UNION member Description Aload address is supplied for an initialized section in a union UNIONS refer to runtime allocation only You must specify the load address for all sections within a union separately m flag does not specify a valid filename Description You did not specify a valid filename for the file you are writing the output map file to making aux entry filename for symbol n out of sequence Description The input file may be corrupt Action If the input file is corrupt try reassembling it Linker Error Messages D 9 Linker Error Messages memory area for redefined Description More than one named memory allocation is supplied for an output section memory page for redefined Description More than one page allocation is supplied for a section memory attributes redefined for Description More than one set of memory attributes is supplied for an out put section memory types and on page overlap Description Memory ranges on the same page overlap Actio
344. n a value and they can be used in expressions Built in substitution symbol functions are especially useful in conditional assembly expressions Parameters to these functions are substitution symbols or character string constants Macro Parameters Substitution Symbols In the function definitions shown in Table 5 1 aand bare parameters that rep resent substitution symbols or character string constants The term string re fers to the string value of the parameter The symbol ch represents a character constant Function symlen a symcmp a b firstch a ch lastch a ch isdefed a ismember a b iscons a isname a isreg a t structsz a structacc a Table 5 1 Functions and Return Values Return Value length of string a lt Oifa lt b Oifa b gt O0ifa gt b index of the first occurrence of character constant ch in string a index of the last occurrence of character constant ch in string a 1 if string a is defined in the symbol table 0 if string a is not defined in the symbol table top member of list b is assigned to string a 0 if bis a null string 1 if string ais a binary constant 2 if string a is an octal constant 3 if string a is a hexadecimal constant 4 if string a is a character constant 5 if string a is a decimal constant 1 if string a is a valid symbol name 0 if string a is not a valid symbol name 1 if string ais a valid predefined register name 0 if string a is not a valid predefin
345. n the list Operands that are omitted or empty assume a null value These lines of C source produce the sym directives shown below C source struct s int memberl member2 str int ext int array 5 10 long ptr int strcmp main argl arg2 int argl char arg2 register r1 Define a Symbol sym Resulting assembly language code global array bss _array 50 0 0 sym _array _array 244 2 800 5 10 global _ptr bss _ptr 1 0 0 sym ptf ptr 21 2 15 global str bss str 2 070 sym Str Str 87 27 3275 global ext bss _ext 1 0 0 Sym _ext _ext 4 2 16 Symbolic Debugging Directives B 11 Appendix C Assembler Error Messages When the assembler completes its second pass it reports any errors that it encountered during the assembly It also prints these errors in the listing file if one is created An error is printed following the source line that incurred it You should attempt to correct the first error that occurs in your code first A single error condition can cause a cascade of spurious errors If you have received an assembler error message use this appendix to find possible solutions to the problem you encountered First locate the error message class number Then locate the error message that you encountered within that class Each class number has an alphabetical list of error messages that are associated with it Each class has a Description of the problem and an Action that
346. n then specify the object library as linker input The linker will search the library and include members that resolve external references You can also use the archiver to build macro libraries You can create several source files each of which contains a single macro and use the archiver to collect these macros into a single functional group The mlib assembler directive lets you specify the name of a macro library during the assembly process the assembler will search the specified library for the macros that you call Chapter 5 Macro Language discusses macros and macro libraries in detail Archiver Development Flow 8 2 Archiver Development Flow Figure 8 1 shows the archiver s role in the assembly language development process Both the assembler and the linker accept libraries as input Figure 8 1 Archiver Development Flow C Source files Macro Source files C compiler Areniver Assembler source Macro library Library build utility Runtime support library Library of object files Linker Debugging tools Executable COFF file Cross reference lister Hex conversion utility Scere Absolute lister processor Archiver Description 8 3 Invoking the Archiver 8 3 Invoking the Archiver To invoke the archiver enter ar55 command option libname filename filename ar55 command is the command tha
347. n which XXXX is a 4 digit 16 bit hexadecimal address The address records are present only in the following situations DD When discontinuities occur When the byte stream does not begin at address 0 You can avoid all discontinuities and any address records by using the image and zero options The output created is a list of byte values 13 38 Description of the Object Formats 13 11 2 Intel MCS 86 Object Format i Option Figure 13 11 Start character Address The Intel object format supports 16 bit addresses and 32 bit extended addresses Intel format consists of a 9 character 4 field prefix which defines the start of record byte count load address and record type the data and a 2 character checksum suffix The 9 character prefix represents three record types Record Type Description 00 Data record 01 End of file record 04 Extended linear address record Record type 00 the data record begins with a colon andis followed by the byte count the address of the first data byte the record type 00 and the checksum Note that the address is the least significant 16 bits of a 32 bit address this value is concatenated with the value from the most recent 04 extended linear address record to create a full 32 bit address The checksum is the 2s complement in binary form of the preceding bytes in the record including byte count address and data bytes Record type 01 the end of file record also b
348. named sections Although uninitialized sections have section headers notice thatthey have no raw data relocation information or line number entries This is because the bss and usect directives simply reserve space for uninitialized data uninitialized sections contain no actual code Figure A 2 COFF Object File file header text section header data section header bss section header section headers lt named gt section section header text raw data data raw data raw data lt named gt section raw data text relocation information data i relocation relocation information information lt named gt section relocation information text line numbers data line number line numbers entries lt named gt section line numbers symbol table string table Common Object File Format A 3 File Header Structure A 2 File Header Structure The file header contains 22 bytes of information that describe the general format of an object file Table A 1 shows the structure of the COFF file header Table A 1 File Header Contents Byte Number Type Description 0 1 Unsigned short integer Version ID indicates version of COFF file structure 2 3 Unsigned short integer Number of section headers 4 7 Long integer Time and date stamp indicates when the file was created 8 11 Long integer File pointer contains the symbol table s starting a
349. nd label EXAMP END load address of section end For more information about assigning runtime and loadtime addresses in the linker see Section 9 10 Specifying a Section s Runtime Address on page 9 41 Assembler Directives 4 65 length width Set Listing Page Size Syntax Description Example length page length Width page width The length directive sets the page length of the output listing file It affects the current and following pages You can reset the page length with another ength directive DD Default length 60 lines DD Minimum length 1 line DD Maximum length 32 767 lines The width directive sets the page width of the output listing file It affects the next line assembled and the lines following you can reset the page width with another width directive DD Default width 80 characters Minimum width 80 characters DD Maximum width 200 characters The width refers to a full line in a listing file the line counter value SPC value and object code are counted as part of the width of a line Comments and other portions of a source statement that extend beyond the page width are trun cated in the listing The assembler does not list the width and length directives In this example the page length and width are changed
350. ndif 11 12 000003 MSG EX i aL E Ssymlen parml 0 1 emsg ERROR MISSING PARAMETER emsg asm ERROR at line 12 USER ERROR ERROR MISSING PARAMETER 1 else 1 ADD parmil ACO ACO 1 endif 1 Error No Warnings In addition the following messages are sent to standard output by the assembler TMS32055xx COFF Assembler Version x xx Copyright c 2000 Texas Instruments Incorporated PASS 1 PASS 2 emsg asm ERROR at line 12 USER ERROR ERROR MISSING PARAMETER emsg ERROR MISSING PARAMETER 1 Error No Warnings Errors in source Assembler Aborted Assembler Directives 4 47 end End Assembly Syntax Description Example 4 48 end The end directive is optional and terminates assembly It should be the last source statement of aprogram The assembler ignores any source statements that follow a end directive This directive has the same effect as an end of file character You can use end when you re debugging and would like to stop assembling at a specific point in your code This example shows how the end directive terminates assembly If any source statements follow the end directive the assembler ignores them Source File data START Space TEMP Set bss data ABS ACO 300 15 LOC1 48h ACO ADD 4TEMP ACO ACO MOV ACO end byte word Listing file 00000
351. nditional expressions For more information about relational operators see subsection 3 10 4 Conditional Expressions on page 3 33 Assembler Directives 4 21 Assembly Time Symbol Directives 4 8 Assembly Time Symbol Directives Assembly time symbol directives equate meaningful symbol names to con stant values or strings L The asg directive assigns a character string to a substitution symbol The value is stored in the substitution symbol table When the assembler encounters a substitution symbol it replaces the symbol with its character string value Substitution symbols can be redefined asg 10 20 30 40 coefficients byte coefficients The eval directive evaluates an expression translates the results into a character and assigns the character string to a substitution symbol This directive is most useful for manipulating counters asg ES loop byte x 10h break x 4 eval x 1 x endloop The label directive defines a special symbol that refers to the loadtime address within the current section This is useful when a section loads at one address but runs at a different address For example you may want to load a block of performance critical code into slower off chip memory to save space and move the code to high speed on chip memory to run The set and equ directives set a value to a symbol The symbol is stored in the symbol table and cannot be refined For example bval Set 0100h int
352. nds DAGEN tag combination does not allow parallelism illegal instruction specified with far illegal instruction specified with local indirect memory or coef operand expected invalid parallel pair cannot use soft dual encoding invalid use of readport qualifier invalid use of writeport qualifier mmap expects direct memory operand neither instruction has parallel enable E bit neither instruction is a monodipatch instruction NOP is disallowed as the first instruction in a parallel pair same operator used by both instructions same bus resource used by both instructions Smem address mode illegal for soft dual encoding this instruction cannot be used in a parallel pair two qualifier instructions in parallel Repeat block too deeply nested This instruction is illegal inside a repeat single loop This instruction is illegal inside a conditional repeat single loop This instruction is illegal as target of a conditional execute This instruction is illegal inside a localrepeat block Description These are errors about parallel or branch instructions These errors are normally target specific Action Correct the source per the error message text Assembler Error Messages C 11 Assembler Error Messages Too many parallel instructions Description This error is caused by having too many instructions in parallel Action Check the source for parallel instruction problems and correct per the error message text Cannot change version after 1s
353. ne information you can use the hex conversion utility ROMS and SECTIONS directives in a command file To invoke the hex conversion utility enter hex55 options filename hex55 is the command that invokes the hex conversion utility options supplies additional information that controls the hex conversion process You can use options on the command line or in a com mand file DD All options are preceded by a dash and are not case sensi tive Several options have an additional parameter that must be separated from the option by at least one space DD Options with multicharacter names must be spelled exactly as shown in this document no abbreviations are allowed Options are not affected by the order in which they are used The exception to this rule is the q option which must be used before any other options filename names a COFF object file or a command file for more informa tion on command files see Section 13 3 Command Files on page 13 6 Hex Conversion Utility Description 13 3 Invoking the Hex Conversion Utility Table 13 1 Hex Conversion Utility Options a General options The general options control the overall operation of the hex conversion utility Option Description page byte Number bytes sequentially 13 35 map filename Generate a map file o filename Specify an output filename q Run quietly when used it must appear before 13 6 other options b Image option
354. nition Conditional Assembly Directives 4 7 Conditional Assembly Directives Conditional assembly directives enable you to instruct the assembler to assemble certain sections of code according to a true or false evaluation of an expression Two sets of directives allow you to assemble conditional blocks of code The if elseif else endif directives tell the assembler to conditionally assemble a block of code according to the evaluation of an expression Af expression marks the beginning of a conditional block and assembles code if the if condition is true elseif expression marks a block of code to be assembled if the if condition is false and elseif is true else marks a block of code to be assembled if the if condition is false endif marks the end of a conditional block and termi nates the block The loop break endloop directives tell the assembler to repeatedly assemble a block of code according to the evaluation of an expression loop expression marks the beginning a block of code that is assembled repeatedly up to the number of times indicated by the expression The expressionis the loop count break expression tells the assembler to continue to repeatedly assemble when the break expression is false and to go to the code immediately after endloop when the expression is true endloop marks the end of a repeatable block The assembler supports several relational operators that are useful for co
355. nker directives Linker directive formats are discussed in later sections Example 9 2 Command File With Linker Directives 9 24 a obj b obj c obj Input filenames o prog out m prog map Options MEMORY MEMORY directive RAM origin 100h length 0100h ROM origin 01000h length 0100h SECTIONS SECTIONS directive CEE gt ROM data gt RAM bss RAM Linker Command Files Reserved Names in Linker Command Files The following names are reserved as keywords for linker directives Do not use them as symbol or section names in a command file align GROUP origin ALIGN lowercase L ORIGIN attr len page ATTR length PAGE block LENGTH range BLOCK load run COPY LOAD RUN DSECT MEMORY SECTIONS f NOLOAD spare fill o type FILL org TYPE group UNION 9 6 2 Constants in Command Files Constants can be specified with either of two syntax schemes the scheme used for specifying decimal octal or hexadecimal constants used in the assembler see Section 3 7 Constants on page 3 21 or the scheme used for integer constants in C syntax Examples Decimal Octal Hexadecimal Assembler Format 32 40q 20h C Format 32 040 0x20 Linker Description 9 25 Object Libraries 9 7 Object Libraries An object library is a partitioned archive file that contains complete object files as members Usually a group of related modules are grouped together into a library When you s
356. nstructions The data in the second column characterizes the assembly of an imaginary file containing an instance of every C54x instruction However the instruc tions that assemble as more than two instructions are not commonly used The data in the third column characterizes the assembly of a file containing the most commonly used C54x instructions Exact percentages depend on the specific source file used Because of this compatibility masm55 can assemble C54x code to generate C55x object code with bit exact results This assembler feature preserves your C54x source code investment as you transition to the C55x This chapter does not explain how to take advantage of the new architecture features of the C55x For this type of information see the 7MS320C55x DSP Programmer s Guide Topic Page 6 1 C54x to C55x Development Flow eee 2 6 2 Understanding the Listing File 0 cece ee eee eee eee 6 3 Handling C55x Reserved Names 6 1 C54x to C55x Development Flow 6 1 C54x to C55x Development Flow To run a C54x application on the C55x you must Assemble each function with masm55 Your C54x application should al ready assemble without errors with the asm500 assembler DD Initialize the stack pointers SP and SSP See Section 6 1 1 Handle differences in memory placement See Section 6 1 2 To use ported C54x functions along with na
357. ntain unresolved refer ences but these references do not prevent creation of an output module The following example links file1 obj and file2 obj and creates a relocat able output module called a out lnk55 r filel obj file2 0bj The output file a out can be relinked with other object files or relocated at load time Linking a file that will be relinked with other files is called partial linking For more information see Section 9 19 Linker Example on page 9 73 Producing an Executable Relocatable Output Module ar If you invoke the linker with both the a and r options the linker produces an executable relocatable object module The output file contains the special linker symbols an optional header and all resolved symbol references however the relocation information is retained The following example links file1 obj and file2 obj and creates an executable relocatable output module called xr out lnk55 ar filel obj file2 obj o xr out You can string the options together Ink55 ar or enter them separately Ink55 a r Relocating or Relinking an Absolute Output Module The linker issues a warning message but continues executing when it encounters a file that contains no relocation or symbol table information Relinking an absolute file can be successful only if each input file contains no information that needs to be relocated that is each file has no unresolved references and is boundto the
358. nthis example code is assembled into the data word addressable and text byte addressable sections T kk occ ck ck ck ck ck ck ck ck 0k 0k 0k 0k 0k 00k kk kk ck ck ck ck ck ck ck ck Ck Pk kx KKK 2 Reserve space in data EK 3 4 000000 data 5 000000 Space OCCh 6 7 kc ck ck ck ck ck ck ck ck KKK KKK KKK KKK kk kk ck ck ck ck ck KKK KKK KKK 8 Assemble into text A 9 10 000000 text 11 INDEX Set 0 12 000000 3C00 MOV INDEX ACO 13 14 15 Assemble into data KAN 16 occ ck ck ck ck ck ck ck ck KKK KKK KKK KKK kk kk ko ck ko ck ck KKK KKK KKK 17 00000c data 18 00000d ffff Table word 1 Assemble 16 bit 19 constant into data 20 00000e O00ff byte OFFh Assemble 8 bit 21 Constant into data 22 kk cock ck ck ck ck ck ck ck KKK KKK KK KKK KKK kk kk ko ck ck ck ck KKK KKK KKK 23 Assemble into text tod 24
359. nventions from the original C54x code As shown in Section 7 2 3 some registers have new names If the runtime environment for your native C55x code differs from the environment defined for ported C54x code you must ensure that when switching between environments the proper adjustments are made for L preserving status bit field values L preserving registers DD how arguments are passed how results are returned Figure 7 1 Runtime Environments for Ported C54x Code and Native C55x Code Ported C54x Code Runtime Environment Environment rules from Section 7 2 1 Original C54x code runtime environment Native C55x Runtime Environment C55x runtime environment as defined by you or the C55x C compiler etc Migrating a C54x System to a C55x System 7 9 Using Ported C54x Functions with Native C55x Functions 7 2 06 Example of C Code Calling C54x Assembly This example describes a technique for handling a call from compiled C code to a C54x assembly routine In this example an additional function is inserted between the native C55x code and the ported C54x code This function referred to as a veneer function provides code to transition between the two runtime environments The compiler provides two pragmas C54X CALL and C54X FAR CALL for calling C54x assembly from C code This example assumes that this automatic solution does not exist Both the
360. o conserve memory GROUP and UNION Unioning sections causes the linker to allocate them to the same run address Grouping sections causes the linker to allocate them contiguously in memory 9 11 1 Overlaying Sections With the UNION Statement For some applications you may wantto allocate more than one section to run at the same address For example you may have several routines you want in on chip RAM at various stages of execution Or you may want several data objects that will not be active atthe same time to share a block of memory The UNION statement within the SECTIONS directive provides a way to allocate several sections at the same runtime address In Example 9 7 the bss sections from file1 obj and file2 obj are allocated at the same address in RAM In the memory map the union occupies as much space as its largest component The components of a union remain independent sections they are simply allocated together as a unit Example 9 7 The UNION Statement wn ECTIONS text load ROM UNION run RAM bssl filel obj bss bss2 file2 0bj bss bss3 run RAM globals obj bss Allocation of a section as part of a union affects only its run address Under no circumstances can sections be overlaid for loading If an initialized section is a union member an initialized section has raw data such as text its load allocation must be separately specified For example Example 9
361. o not answer this prompt the linker creates an object file with a default filename of a out B The options prompt is for additional options although you can also enter them in a command file Enter them with hyphens just as you would on the command line Invoking the Linker Putfilenames and options in a linker command file For example assume that the file linker cmd contains the following lines o link out filel obj file2 0bj Now you can invoke the linker from the command line specify the command filename as an input file lnk55 linker cmd When you use a command file you can also specify other options and files on the command line For example you could enter lnk55 m link map linker cmd file3 obj The linker reads and processes a command file as soon as it encounters the filename on the command line so it links the files in this order file1 obj file2 obj and file3 obj This example creates an output file called link out and a map file called link map Linker Description 9 5 Linker Options 9 4 Linker Options Linker options control linking operations They can be placed on the command line or in a command file Linker options must be preceded by a hyphen The order in which options are specified is unimportant except for the lowercase L and i options Options may be separated from arguments if they have them by an optional space The following summarize the linker options a Cr
362. o start on an address that is not aligned file3 obj text will not be aligned either Note that the symbol refers to the current run address not the current load address of the section Expressions that decrement are illegal For example it is invalid to use the operator in an assignment to The most common operators used in assignments to are and align If an output section contains all input sections of a certain type such as text you can use the following statements to create a hole at the beginning or end of the output section text 100h Hole at the beginning data data 100h Hole at the end 9 16 3 Filling Holes Creating and Filling Holes Another way to create a hole in an output section is to combine an uninitialized section with an initialized section to form a single output section n this case the linker treats the uninitialized section as a hole and supplies data for it The following example illustrates this method SECTIONS outsect filel obj text filel obj bss This becomes a hole Because the text section has raw data all of outsect must also contain raw data rule 1 Therefore the uninitialized bss section becomes a hole Uninitialized sections become holes only when they are combined with initialized sections If several uninitialized sections are linked together the resulting output section is als
363. o the beginning of the ISR If the conversion of inst1 is a single C55x instruction that is 4 bytes or less it can be placed in the vector However inst2 must be moved to the ISR Handling Interrupts Vector Contains the Entire ISR If the C54x vector contains the entire 4 word ISR as in the examples shown below example 1 insti inst2 inst3 RETE example 2 insti RETFD inst2 inst3 example 3 CALL routinel RETE nop you have to create the 4 word ISR as a stand alone routine You must then provide the address of that routine in the C55x vector table ivec new isr 7 1 2 Handling Interrupt Service Routines An interrupt service routine needs to be changed only if when ported to C55x itincludes C54x instructions that map to more than one C55x instruction and LJ one of the C55x instructions requires the use of a C55x register or bit as a temporary In this case the new C55x register needs to be preserved by the routine The registers need to be preserved in the ISRs as long as any ported C54x code remains in the application When all code has been changed to native C55x code it is no longer necessary to preserve the registers See Section 7 2 2 C55x Registers Used as Temporaries on page 7 6 for the list of C55x registers that can be used as temporaries in one to many instruction mappings Migrating a C54x System to a C55x System 7 3 Handling Interrupts
364. o the data memory local page pointer register DP The dma syntax is dma where dma can be a constant or a linktime known symbolic expression The assembler computes the difference between dma and the value in the DP register and encodes this difference into the output bits The assembler cannot track the value of the DP register however it must know the value of DP in order to assemble direct memory access operands Consequently you must use the dp directive to model the DP value Issue this directive immediately following any instruction that changes the value in the DP register The scope of the cpl on and cpl off directives is static and not subject to the control flow of the assembly program All assembly code between the cpl on line and the cpl off line is assembled in CPL mode Syntax Description Example Assign Character Strings to Substitution Symbols data data The data directive tells the assembler to begin assembling source code into the data section data becomes the current section The data section is normally used to contain tables of data or preinitialized variables On C55x data is word addressable The assembler assumes that text is the default section Therefore at the beginning of an assembly the assembler assembles code into the text section unless you use a section control directive For more information about COFF sections see Chapter 2 Introduction to Common Object File Format I
365. o uninitialized When a hole exists in an initialized output section the linker must supply raw data to fill it The linker fills holes with a 16 bit fill value that is replicated through memory until it fills the hole The linker determines the fill value as follows 1 Ifthe hole is formed by combining an uninitialized section with an initialized section you can specify a fill value for the uninitialized section Follow the section name with an sign and a 16 bit constant SECTIONS outsect filel obj text file2 obj bss OOFFh Fill this hole with OFFh 2 You can also specify a fill value for all the holes in an output section by supplying the fill value after the section definition SECTIONS outsect fill OFFOOh fills holes with OFFOOh 10h This creates a hole filel obj text filel obj bss This creates another hole Linker Description 9 65 Creating and Filling Holes 3 Ifyou do not specify an initialization value for a hole the linker fills the hole with the value specified by the f option For example suppose the command file link cmd contains the following SECTIONS directive SECTIONS text 100 Create a 100 byte hole Now invoke the linker with the f option lnk500 f OFFFFh link cmd This fills the hole with OFFFFh 4 Ifyou do not invoke the linker with the f option the linker fills holes with Os Whenev
366. ocate the section Generally the linker puts sections wherever they fit into configured memory You can override this default allocation for a section by defining it within a SECTIONS directive and providing instructions on how to allocate it You control allocation by specifying one or more allocation parameters Each parameter consists of a keyword an optional equal sign or greater than sign and a value optionally enclosed in parentheses If load and run allocation is separate all parameters following the keyword LOAD apply to load allocation and those following RUN apply to run allocation Possible allocation parameters are Binding allocates a section at a specific address text load 0x1000 Memory allocates the section into a range defined in the MEMORY directive with the specified name like ROM or attributes text load ROM Alignment uses the align keyword to specify that the section should start on an address boundary text align 0x80 To force the output section containing the assignment to also be aligned assign dot with an align expression For exam ple the following will align bar obj and it will force outsect to align on a 0x40 byte boundary SECTIONS outsect bar obj bss align 0x40 Linker Description 9 35 The SECTIONS Directive 9 9 3 1 Binding Blocking uses the block keyword to specify that the section must fit between two address boundaries if the section is too b
367. ocation within a section each section has its own SPC static A kind of variable whose scope is confined to a function or a program The values of static variables are not discarded when the function or pro gram is exited their previous value is resumed when the function or pro gram is re entered storage class Any entry in the symbol table that indicates how to access a symbol string table Atablethatstores symbol names that are longer than 8 charac ters symbol names of 8 characters or longer cannot be stored in the symbol table instead they are stored in the string table The name por tion 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 Glossary E 7 Glossary subsection A smaller section within a section offering tighter control of the memory map See also section symbol A string of alphanumeric characters that represents an address or a value symbolic debugging The ability of a software tool to retain symbolic infor mation so that it can be used by a debugging tool such as a simulator or an emulator symbol table A portion of a COFF object file that contains information about the symbols that are defined and used by the file tag An optional type name that can be assigned to a structure union or enumeration targetmemory Physical memory in a TMS320C55x system into which exe cuta
368. of ascending address 13 5 1 When to Use the ROMS Directive If you don t use a ROMS directive the utility defines a single default range that includes the entire program address space PAGE 0 This is equivalent to a ROMS directive with a single range without origin or length Use the ROMS directive when you want to Program large amounts of data into fixed size ROMs When you spe cify memory ranges corresponding to the length of your ROMs the utility automatically breaks the output into blocks that fit into the ROMs Restrict outputto certain segments You can also use the ROMS direc tive to restrict the conversion to a certain segment or segments of the tar get address space The utility does not convert the data that falls outside of the ranges defined by the ROMS directive Sections can span range boundaries the utility splits them at the boundary into multiple ranges If a section falls completely outside any of the ranges you define the utility does not convert that section and issues no messages or warnings In this way you can exclude sections without listing them by name with the SECTIONS directive However if a section falls partially in a range and partially in unconfigured memory the utility issues a warning and converts only the part within the range Use image mode When you use the image option you must use a ROMS directive Each range is filled completely so that each output file in arange contains data
369. on see subsection 9 4 8 Define Heap Size heap constant Option on page 9 12 subsection 9 4 15 Define Stack Size stack constant Option on page 9 18 or subsection 9 4 16 Define Secondary Stack Size sysstack on page 9 18 9 18 4 Autoinitialization ROM and RAM Models The C compiler produces tables of data for autoinitializing global variables These are in a named section called cinit The initialization tables can be used in either of two ways RAM Model cr option Variables are initialized at load time This enhances performance by reducing boot time and by saving memory used by the initialization tables You must use a smart loader i e one capable of initializing variables to take advantage of the RAM model of autoinitialization When you use cr the linker marks the cinit section with a special attri bute This attribute tells the linker notto load the cinit section into memory The linker also sets the cinit symbol to 1 this tells the C boot routine that initialization tables are not present in memory Thus no runtime initializa tion is performed at boot time When the program is loaded the loader must be able to m Detect the presence of the cinit section in the object file Bi Detect the presence of the attribute that tells it not to copy the cinit section B Understand the format of the initialization tables This format is described in the TMS320C55x Optimizing C Compiler User s Guide
370. on allowed for union member Description AUNION defines the run address for all of its members there fore individual run allocations are illegal no string table in file filename Description The input file may be corrupt Action If the input file is corrupt try reassembling it no symbol map produced not enough memory Description Available memory is insufficient to produce the symbol list This is a nonfatal condition that prevents the generation of the symbol list in the map file Linker Error Messages D 11 Linker Error Messages o flag does not specify a valid file name string Description The filename must follow the operating system file naming conventions origin missing for memory area Description An origin is not specified with the MEMORY directive An origin specifies the starting address of a memory range out of memory aborting Description Your system does not have enough memory to perform all required tasks Action Try breaking the assembly language files into multiple smaller files and do partial linking See Section 9 17 Partial Incre mental Linking on page 9 67 output file has no bss section Description This is a warning The bss section is usually present in a COFF file There is no requirement for it to be present output file has no data section Description This is a warning The data section is usually present in a COFF file There is no requirement for it to be p
371. on dependent value 9 15 1 Syntax of Assignment Statements The syntax of assignment statements in the linker is similar to that of assign ment statements in the C language symbol expression assigns the value of expression to symbol symbol expression adds the value of expression to symbol symbol z expression subtracts the value of expression from symbol symbol expression multiplies symbol by expression symbol expression divides symbol by expression The symbol should be defined externally If it is not the linker defines a new symbol and enters it into the symbol table The expression must follow the rules defined in subsection 9 15 3 Assignment Expressions Assignment statements mustterminate with a semicolon The linker processes assignment statements after it allocates all the output sections Therefore if an expression contains a symbol the address used for that symbol reflects the symbol s address in the executable output file For example suppose a program reads data from one of two tables identified by two external symbols Table1 and Table2 The program uses the symbol cur tabas the address ofthe currenttable cur tab must point to either Table1 or Table2 You could accomplish this in the assembly code but you would need to reassemble the program to change tables Instead you can use a linker assignment statement to assign cur tab at link time prog obj Input file cur tab Tablel
372. on program counter is set to 0 if nothing has yet been assembled into the text section If code has already been assembled into the text section the section program counter is restored to its previous value in the section Because the text section is a code section it is byte addressable Data sections are word addressable text is the default section Therefore at the beginning of an assembly the assembler assembles code into the text section unless you specify a different sections directive data or sect For more information about COFF sections see Chapter 2 Introduction to Common Object File Format Assembler Directives 4 97 lext Assemble Into text Sections Example 4 98 This example assembles code into the text and data sections The data sec tion contains integer constants and the text section contains executable code 1 Owe W PN Pe 1j Oo 13 14 15 16 17 18 19 20 21 22 23 000000 000000 000001 000002 000003 000004 000005 000000 000000 000002 000003 000005 000006 000006 000007 000008 000009 000006 000006 Begin assembling into data section
373. once the assembler issues a multiple definition error If you use a local label and newblock within a macro however the local label is used and reset each time the macro is expanded Up to ten local labels of the n form can be in effect at one time Local labels of the form name are not limited After you undefine a local label you can define it and use it again Local labels do not appear in the object code symbol table The maximum label length is shortened to allow for the unique suffix If the macro is expanded fewer than 10 times the maximum label length is 126 char acters If the macro is expanded from 10 to 99 times the maximum label length is 125 Example 3 4 demonstrates the name form of a local label Assembler Description 3 29 Symbols Example 3 4 name Local Labels First definition of local label mylab nop mylab nop B mylab Include file has second definition of mylab copy a inc Third definition of mylab reset upon exit from include mylab nop B mylab Fourth definition of mylab in macro macros use different namespace to avoid conflicts mymac macro mylab nop B mylab endm Macro invocation mymac Reference to third definition of mylab note that definition is not reset by macro invocation nor conflicts with same name defined in macro B mylab Changing section allowing fifth definition of mylab Sect Secto One nop data mylab
374. onstant equal to 149 or 146 11111000B Constant equal to 24849 or OF846 3 7 2 Octal Integers An octal integer constant is a string of up to 6 octal digits 0 through 7 prefixed with a 0 zero or suffixed with Q or q These are examples of valid octal constants 10Q Constant equal to 819 or 816 100000Q Constant equal to 32 76849 or 8 00046 226q Constant equal to 15049 or 9646 Or you can use C notation for octal constants 010 Constant equal to 849 or 816 0100000 Constant equal to 32 76849 or 8 00046 0226 Constant equal to 15049 or 9646 Assembler Description 3 21 Constants 3 7 3 Decimal Integers 3 7 4 Hexadecimal A decimal integer constant is a string of decimal digits ranging from 32 768 to 65 535 These are examples of valid decimal constants 1000 Constant equal to 100049 or 3E816 32768 Constant equal to 32 76849 or 8 00046 25 Constant equal to 2549 or 1946 Integers A hexadecimal integer constant is a string of up to four hexadecimal digits followed by the suffix H or h Hexadecimal digits include the decimal values 0 9 and the letters A F and a f A hexadecimal constant must begin with a decimal value 0 9 If fewer than four hexadecimal digits are specified the assembler right justifies the bits These are examples of valid hexadecimal constants 78h Constant equal to 12049 or 007846 OFH Constant equal to 1549 or 000F16 37ACh Constant equal to 14 25219 or 37AC46 Or you can use C notation for hex
375. oot table follow these steps Step 1 Step 2 Step 3 Step 4 Step 5 Link the file Each block of the boot table data corresponds to an initialized section in the COFF file Uninitialized sections are not con verted by the hex conversion utility see Section 13 6 The SECTIONS Directive on page 13 21 When you select a section for placement in a boot loader table the hex conversion utility places the section s load address in the des tination address field for the block in the boot table The section content is then treated as raw data for that block The hex conversion utility does not use the section run address When linking you need not worry about the ROM address or the construction of the boot table the hex conversion utility handles this Identify the bootable sections You can use the boot option to tell the hex conversion utility to configure all sections for boot loading Or you can use a SECTIONS directive to select specific sections to be configured see Section 13 6 The SECTIONS Directive on page 13 21 Note that if you use a SECTIONS directive the boot option is ignored Set the ROM address of the boot table Use the bootorg option to set the source address of the complete table For example if you are using the C55x and booting from memory location 8000h specify bootorg 8000h The address field in the the hex conversion utility output file will then start at 8000h If you use
376. or enumeration See note 2 Notes 1 Any type except T MOE Type Entry Derived Basic Type 1 Type DT NON T NULL DT NON T NULL DT NON T NULL DT NON T NULL DT FCN See note 1 DT ARY See note 1 DT NON T VOID DT NON T VOID DT PTR T STRUCT DT ARR T UNION DT NON T ENUM 2 C AUTO C STAT C MOS C MOU C TPDEF Auxiliary Entry Format Filename see Table A 18 Section see Table A 19 Tag name see Table A 20 End of structure see Table A 21 Function see Table A 22 Array see Table A 23 Beginning and end of a block see Table A 24 and Table A 25 Beginning and end of a function see Table A 24 and Table A 25 Name related to a structure union or enumeration see Table A 26 In Table A 17 tagname refers to any symbol name including the special symbol nfake Fcname and arrname refer to any symbol name A symbol that satisfies more than one condition in Table A 17 should have a union format in its auxiliary entry A symbol that satisfies none of these condi tions should not have an auxiliary entry Symbol Table Structure and Content A 7 8 1 Filenames Each of the auxiliary table entries for a filename contains a 14 character file name in bytes 0 13 Bytes 14 17 are unused Table A 18 Filename Format for Auxiliary Table Entries Byte Number Type Description 0 13 Character File name 14 17 Unused A 7 8 2 Sections Table A 19 illustrates the format of auxiliary table entries
377. or the run address The load address determines where a loader will place the raw data for the section Any references to the section such as labels in it refer to its run address The application must copy the section from its load address to its run address this does not happen automatically simply because you specify a separate run address For an example that illustrates how to move a block of code at runtime see Example 9 6 on page 9 43 If you provide only one allocation either load or run for a section the section is allocated only once and will load and run atthe same address If you provide both allocations the section is actually allocated as if it were two different sections of the same size Uninitialized sections such as bss are not loaded so the only significant address is the run address The linker allocates uninitialized sections only once if you specify both run and load addresses the linker warns you and ignores the load address For a complete description of runtime relocation see Section 9 10 Specifying a Section s Runtime Address on page 9 41 Introduction to Common Object File Format 2 17 Loading a Program 2 6 Loading a Program 2 18 The linker produces executable COFF object modules An executable object file has the same COFF format as object files that are used as linker input the sections in an executable object file however are combined and relocated so that they can be loaded directly
378. ord type byte count address data and checksum The record types are Record Type Description S0 Header record S1 Code data record for 16 bit addresses S1 format S2 Code data record for 24 bit addresses S2 format S3 Code data record for 32 bit addresses S3 format S7 Termination record for 32 bit addresses S3 format S8 Termination record for 24 bit addresses S2 format S9 Termination record for 16 bit addresses S1 format The byte count is the character pair count in the record excluding the type and byte count itself The checksum is the least significant byte of the 1s complement of the sum of the values represented by the pairs of characters making up the byte count address and the code data fields Figure 13 12 illustrates the Motorola S object format Figure 13 12 Motorola S Format I We S00B00004441544120492F4FF3 ze Sac ecor 1130000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFCd4 1130010FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFED Data S31130020FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDC Records 1130030F ECE S1130040FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBC S9030000FC Termination E el Record Byte T Checksum Address Count 13 40 Description of the Object Formats 13 11 4 Texas Instruments SDSMAC Object Format t Option The Tl Tagged object format supports 16 bit addresses It
379. orted C54x Functions with Native C55x Functions on page 7 5 15 16 0000162253 MOV T1 AC3 native C55x Running C54x Code on C55x 6 5 Handling Reserved C55x Names 6 3 Handling Reserved C55x Names Note that new C55x mnemonics and registers are reserved words Your C54x code should not contain symbol names that are now used as C55x mnemonics or registers For example you should not use T3 as a symbol name Your C54x code also should not contain symbol names that are reserved words in the C55x algebraic syntax For example you should not have a label named return The C55x mnemonic assembler issues an error message when it encounters a symbol name conflict Chapter 7 Migrating a C54x System to a C55x System After you ve ported your C54x code as described in Chapter 6 you must consider various system level issues when moving your C54x code to C55x This chapter describes Lj how to handle differences related to interrupts how to use ported C54x functions with native C55x functions DD non portable C54x coding practices Topic Page 7 1 Handling Interrupts ss nei rey ERG ETE DERE T 7 2 7 2 Using Ported C54x Functions with Native C55x Functions 7 5 7 3 Non portable C54x Coding Practices LL 7 17 Z4 Additional 654x 1388825509 0455 5000099000009 09 0099 7 1 Handling Interrupts 7 1 Handling Interrupts This section describes issues related
380. ory allocated by first bss direc tive 64 words left in the first page Hole in memory left because second bss directive required more than 64 Page words boundary 127 b Memory allocated by second bss di rective 58 words left in the second page Unused memory 256 Section directives for initialized sections text data and sect end the cur rent section and begin assembling into another section The bss directive however does not affect the current section The assembler assembles the bss directive and then resumes assembling code into the current section For more information about COFF sections see Chapter 2 Introduction to Common Object File Format Example Reserve Space in the bss Section bss In this example the bss directive is used to allocate space for two variables TEMP and ARRAY The symbol TEMP points to 4 words of uninitialized space at bss SPC 0 The symbol ARRAY points to 100 words of uninitialized space at bss SPC 04h this space must be allocated contiguously within a page Note that symbols declared with the bss directive can be referenced in the same manner as other symbols and can also be declared external FF S0 NHPOI0 Jo004U0 NP O1 17 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
381. os oe 5 3 Manipulating Substitution Symbols 0 5 4 Conditional Assembly an ese n 5 5 Producing Assembly Time Messages i 5 6 Formatting the Listing soa ins hap en cece eee eee eee III I hn 9 1 Operators Used in Expressions Precedence pp ee 18 1 Hex Conversion Utility Options pp 13 2 Boot Loader Options co ess ey Dre ee 13 3 Options for Specifying Hex Conversion Formats A 1 File Header Contents 0000 aa aa enn hn A 2 File Header Flags Bytes 18 and 19 0 0 cece eee A 3 Optional File Header Contents es A 4 Section Header Contents 0 A 5 Section Header Flags i A 6 Relocation Entry Contents a ccc cece eee nnn A 7 Relocation Types Bytes 8 and 9 cn A 8 Line Number Entry Format 0 A 9 Symbol Table Entry Contents 0 A 10 Special Symbols in the Symbol Table i A 11 Symbol Storage Classes pp A 12 Special Symbols and Their Storage Classes 00 cece cece e eens A 13 Symbol Values and Storage Classes pp A 14 Section Numbers 9 A 15 TD A 16 Derived Types i eei eed arturo aes ake Ud sea caf ren etta A 17 Auxiliary Symbol Table Entries Format i A 18 Filename Format for Auxiliary Table Entries i A 19 Section Format for Auxiliary Table Entries i A 20 Tag Name Format for Auxiliary Table Entries i Contents A 21 End of Structure Format for Auxiliary Table Entries A 22 Function Format for Auxiliary Table Entries A 23 Array Format for Auxiliary Table Entries ot A 24 End of Blocks Functions Format fo
382. ot printed but the line counter is increm ented The string is a quote enclosed title of up to 65 characters If you supply more than 65 characters the assembler truncates the string and issues a warning The assembler prints the title on the page that follows the directive and on sub sequent pages until another title directive is processed If you want a title on the first page the first source statement must contain a title directive In this example one title is printed on the first page and a different title on succeeding pages Source file title Fast Fourier Transforms title Floating Point Routines page Listing file COFF Assembler Version x xx Copyright c 2000 Texas Instruments Incorporated Fast Fourier Transforms PAGE 1 2 3 4 H x COFF Assembler Version x xx Copyright c 2000 Texas Instruments Incorporated Floating Point Routines PAGE 2 Assembler Directives 4 99 union endunion tag Declare Union Type Syntax Description 4 100 utag union expr mem element expr mem element expr mem tag utagn expri memy element exprw size endunion label tag utag The union directive assigns symbolic offsets to the elements of alternate data structure definitions to be allocated in the same memory space This enables you to define several alternate structures and then let the assembler calculate the element offse
383. out the effects of calling C the registers and status bits that may or may not be modified do not impact the code shown But these effects can impact the code around such a call For example consider the XAR1 register In the C54x compiler environment AR1 will not be modified by the call In the C55x compiler environment XAR1 may be modified If code before the call to C func loads a value into AR1 and code after the call reads AR1 for that value then the code as written will not work on C55x The best alternative is to use an XARn register that is saved by C routines such as XAR5 Non Portable C54x Coding Practices 7 3 Non Portable C54x Coding Practices Some C54x coding practices cannot be ported to the C55x The assembler will warn you of certain detectable issues but it cannot detect every issue The following coding practices are not portable d D D D vo Any use of a constant as a memory address For example B 42 ADD 42 A SUB symbol 10 b Memory initialized with constants that are later interpreted as code addresses For example table word 10 20 30 LD table A CALA Using data as instructions For example function word Oxabcd opcode for word OxdefO opcode for CALL function Out of order execution also known as pipeline tricking Code that creates or modifies code Repeat blocks spanning more than one file Branching calling unlabeled locations Or modifying the return a
384. pace For example S2 could also be specified as 92 t PAGE 2 2 s x F Because OVR MEM is the only memory on page 2 it is not necessary but acceptable to specify OVR MEM for the section 9 12 3 Page Definition Syntax To specify overlay pages as illustrated in Example 9 11 and Example 9 12 use the following syntax for the MEMORY directive MEMORY PAGE 0 name 1 attr origin constant length constant PAGE n name n attr origin constant length constant Each page is introduced by the keyword PAGE and a page number followed by a colon and a list of memory ranges the page contains Bold portions must be entered as shown Memory ranges are specified in the normal way You can define up to 255 overlay pages Because each page represents a completely independent address space memory ranges on different pages can have the same name Configured memory on any page can overlap configured memory on any other page Within a single page however all memory ranges must have unique names and must not overlap Linker Description 9 53 Overlay Pages Memory ranges listed outside the scope of a PAGE specification default to PAGE 0 Consider the following example MEMORY ROM org Oh len 1000h EPROM org 1000h len 1000h RAM org 2000h len OEOOOh PAGE1 XROM org Oh len 1000h XRAM org 2000h len OEOOOh The memory ranges ROM EPROM and RAM are all on
385. pe Entry Section Mnemonic Number Description N DEBUG 2 Special symbolic debugging symbol N_ABS 1 Absolute symbol N_UNDEF 0 Undefined external symbol N_SCNUM 1 text section typical N SCNUM 2 data section typical N SCNUM 3 bss section typical N SCNUM 4 32 767 Section number of a named section in the order in which the named sections are encountered If there were no text data or bss sections the numbering of named sections would begin with 1 If a symbol has a section number of 0 1 or 2 it is not defined in a section A section number of 2 indicates a symbolic debugging symbol which includes structure union and enumeration tag names type definitions and the filename A section number of 1 indicates that the symbol has a value but is not relocatable A section number of 0 indicates a relocatable external symbol that is not defined in the current file Bytes 14 15 of the symbol table entry define the symbol s type Each symbol has one basic type and one to six derived types Following is the format for this 16 bit type entry Derived Derived Derived Derived Derived Derived Basi Type Type Type Type Type Type s papa 6 5 4 3 2 1 yp Size in bits 2 2 2 2 2 2 4 Bits 0 3 of the type field indicate the basic type Table A 15 lists valid basic types Table A 15 Basic Types Mnemonic T_NULL T_CHAR T_SHORT T_INT T_LONG T_FLOAT T_DOUBLE T_STRUCT T_UNION T_ENUM T_MOE
386. pecify an object library as linker input the linker includes any members ofthe library that define existing unresolved symbol references You can use the archiver to build and maintain libraries Chapter 8 Archiver Description contains more information about the archiver Using object libraries can reduce link time and the size of the executable module Normally if an object file that contains a function is specified at link time it is linked whether it is used or not however if that same function is placed in an archive library it is included only if it is referenced The order in which libraries are specified is important because the linker includes only those members that resolve symbols that are undefined when the library is searched The same library can be specified as often as neces sary itis searched each time it is included Alternatively the x option can be used A library has a table that lists all external symbols defined in the library the linker searches through the table until it determines that it cannot use the library to resolve any more references The following examples link several files and libraries Assume that DD Input files f1 obj and f2 0bj both reference an external function named clrscr Input file f1 0bj references the symbol origin Input file f2 0bj references the symbol fillclr Member 0 of library libc lib contains a definition of origin Member 3 of library liba lib contains a definition of fillcl
387. ps performed equals the loop count given by loop This example illustrates how these directives can be used with the eval directive 1 000000 data 2 eval 0 x 3 LAB 1 loop 4 word x 100 5 eval x l X 6 break x 6 y endloop 1 000000 0000 word 0 100 1 eval O 1 x 1 break 1 6 1 000001 0064 word 1 100 1 eval Lely x 1 break 2 6 1 000002 00C8 word 2 100 1 eval 2 1 x 1 break 3 6 1 000003 012C word 3 100 n eval Stil X 1 break 4 6 1 000004 0190 word 4 100 1 eval 4 1 x 1 break 5 6 1 000005 01F4 word 5 100 1 eval 1 break 6 6 Assembler Directives 4 71 Macro Define Macro Syntax Description macname macro parameter parameter model statements or macro directives endm The macro directive is used to define macros You can define a macro anywhere in your program but you must define the macro before you can use it Macros can be defined at the beginning of a source file in an include copy file or in a macro library macname names the macro You must place the name in the source statement s label field macro identifies the source statement as the first line of a macro definition You must place macro in the op code field parameters are optional substitution symbols that appear as operands for the macro directive model statements are instructions or assembler directives that are ex ecuted each time the macro is called macro directive
388. ption 4 106 Var sym symo symg The var directive allows you to use substitution symbols as local variables within a macro With this directive you can define up to 32 local macro sub stitution symbols including parameters per macro The var directive creates temporary substitution symbols with the initial value of the null string These symbols are not passed in as parameters and they are lost after expansion For more information on macros see Chapter 5 Syntax Description Suppress Variable Length Instruction Resolution vli off vli on Vli off Vli on The vli_off and vli on directives affect the way the assembler handles vari able length instructions The vli off directive is equivalent to using the mv command line option In the case of a conflict between the command line op tion and the directive the directive takes precedence By default vli on the assembler will attempt to resolve all stand alone vari able length instructions to their smallest possible size Size resolution is performed on the following instruction groups d goto L6 L16 P24 if cond d call L16 P24 if cond goto 14 if cond d goto L8 L16 P24 d call L16 P24 In some cases you may want the assembler to keep the largest P24 form of certain instructions The P24 versions of certain variable length instructions execute in fewer cycles than the smaller version of the same instructions Use the vli off
389. ption 13 43 Appendix A Common Object File Format The compiler assembler and linker create object files in common object file format COFF COFF is an implementation of an object file format of the same name that was developed by AT amp T for use on UNIX based systems This for mat is used because it encourages modular programming and provides more powerful and flexible methods for managing code segments and target system memory Sections are a basic COFF concept Chapter 2 Introduction to Common Object File Format discusses COFF sections in de tail If you understand section operation you will be able to use the assembly language tools more efficiently This appendix contains technical details about COFF object file structure Much of this information pertains to the symbolic debugging information that is produced by the C compiler The purpose of this appendix is to provide sup plementary information about the internal format of COFF object files Topic Page Ad GOFF Elle Structuren nea AURI T anes amen cain A 2 A File Header Str ct re etr IRR A 3 Optional File Header Format Lsseeeuueeee A4 Section Header Structure 0 ccccnueensecncnsneseennnnenes A 5 Structuring Relocation Information A 6 Line Number Table Structure es A 11 A 7 Symbol Table Structure and Content A 13 A 1 COFF File Structure A 1 COFF File Stru
390. ptional conditional assembly block End conditional assembly Begin repeatable block assembly Optional repeatable block assembly f End repeatable block assembly Macro Language 5 25 Macro Directives Summary Table 5 5 Producing Assembly Time Messages Mnemonic and Syntax emsg wmsg mmsg Table 5 6 Formatting the Listing Mnemonic and Syntax fclist fcnolist mlist mnolist sslist ssnolist 5 26 Description Send error message to standard output Send warning message to standard output Send warning or assembly time message to standard output Description Allow false conditional code block listing default Inhibit false conditional code block listing Allow macro listings default Inhibit macro listings Allow expanded substitution symbol listing Inhibit expanded substitution symbol listing default Chapter 6 Running C54x Code on C55x In addition to accepting C55x source code the C55x mnemonic assembler masm55 also accepts C54x mnemonic assembly The C54x instruction set contains 211 instructions the C55x mnemonic instruction set is a superset of the C54x instruction set The table below contains statistics on how the C54x instructions assemble with masm55 original C54x instruction of total C54x 96 of commonly used assembles as instruction set C54x instructions one C55x instruction 85 95 99 two C55x instructions 10 1 3 more than two C55x 5 0 2 i
391. put Section Information w Option 9 4 19 Exhaustively Read Libraries x Option i Byie Word Addressing ig cede iore oc om dox eda eR ed d bte Ico see 9 21 Linker Command Files 4 9 6 1 Reserved Names in Linker Command Files i 9 6 2 Constants in Command Files i Object Libraries se sed ed E bed rece bade ed une i a hae est a The MEMORY Directive 006 e 9 841 Default Memory Model es 9 8 2 MEMORY Directive Syntax ssn pe cece eee The SECTIONS Directive sis enenatis uni cece nee eee 9 9 1 Default Configuration sn eg eo ed i 9 9 2 SECTIONS Directive Syntax 0 9 9 9 Allocations s date Soe a E itte a SCR P eR BEN etu a EA Specifying a Section s Runtime Address i 9 10 1 Specifying Load and Run Addresses i 9 10 2 Uninitialized Sections 0 9 10 3 Referring to the Load Address by Using the label Directive Using UNION and GROUP Statements i 9 11 1 Overlaying Sections With the UNION Statement 000005 9 11 2 Grouping Output Sections Together i 9 11 3 Nesting UNIONs and GROUPS 000 i de 9 11 4 Checking the Consistency of Allocators i Overldy Pages ic sss de ar peg ade en odo Re Peed en a T 9 12 1 Using the MEMORY Directive to Define Overlay Pages 9 12 2 Using Overlay Pages With the SECTIONS Directive 9 12 3 Page Definition Syntax 00 ds ed de ea i in Default Allocation Algorithm sa arn 9 13 1 Allocation Algorithm i 9 13 2 General Rules for O
392. r C D O L Member 1 of both libraries defines clrscr For example if you enter the following the references are resolved as shown 1nk55 fl obj liba lib f2 0bj libc lib J Member 1 of liba lib satisfies both references to clrscr because the library is searched and clrscr is defined before f2 0bj references it DD Member 0 of libc lib satisfies the reference to origin Member 3 of liba lib satisfies the reference to fillclr Object Libraries If however you enter the following all the references to clrscr are satisfied by member 1 of libc lib lnk55 fl obj 2 obj libc lib liba lib If none of the linked files reference symbols defined in a library you can use the u option to force the linker to include a library member The next example creates an undefined symbol rout1 in the linker s global symbol table lnk55 u routl libc lib If any member of libc lib define rout the linker includes those members It is not possible to control the allocation of individual library members members are allocated according to the SECTIONS directive default allocation algorithm Subsection 9 4 9 Alter the Library Search Algorithm i dir Option C DIR on page 9 13 describes methods for specifying directories that contain object libraries Linker Description 9 27 The MEMORY Directive 9 8 The MEMORY Directive The linker determines where output sections should be allocated in memory it must have a model of t
393. r Auxiliary Table Entries i A 25 Beginning of Blocks Functions Format for Auxiliary Table Entries A 26 Structure Union and Enumeration Names Format for Auxiliary Table Entries xviii bu II DP TI P Tqa OoanrRWNHHAN OTH OW N qe qmm eee ect e od I o a I CD 5 14 5 15 5 16 Examples Using Sections Directives sissen re ed er a ei a aa aa A rh Code That Generates Relocation Entries ot C55x Data Example acris nannini A td C55x Code Example a aE a i a a bud oecalbabels ee ito cix actui ocr gree uae a haa area Puree ines name Local Labels 0 0 cc ccc cee rre Well Defined Expressions ss es a ed dd Assembler Listing sn en korissa ERES EUR squat LASTELE TEETAR sane Sample Cross Reference Listing pp Sections Directives 1 Macro Definition Call and Expansion s sess ee Calling a Macro With Varying Numbers of Arguments pp The asg Directive ick ate osuere d spe ner stunde ke bd n a da ca dta The eval Direetlve sg a eret ea hr eR edem ed a Vn bein Gehan Using Built In Substitution Symbol Functions i Recursive Substitution ass g ieira as biia ba otk teen eee eae Using the Forced Substitution Operator i Using Subscripted Substitution Symbols to Redefine an Instruction Using Subscripted Substitution Symbols to Find Substrings 055 The loop break endloop Directives pp Nested Conditional Assembly Directives i Built In Substi
394. r Strings to Substitution Symbols sect sect section name The sect directive defines a named section that can be used like the default text and data sections The sect directive begins assembling source code into the named section The section name identifies a section that the assembler assembles code into The name can be up to 200 characters and must be enclosed in double quotes A section name can contain a subsection name in the form section name sub section name For more information about COFF sections see Chapter 2 Introduction to Common Object File Format This example defines a special purpose section named Vars and assembles code into it T 2 AU Begin assembling into text section EA 3 KEK KKK KK KKK KKK KKK KKK KKK KKK ck ck kk kk ck kk KKK KK KK KKK 4 000000 text 5 000000 7600 MOV 120 ACO Assembled into text 000002 7808 6 000004 7B00 ADD 54 ACO Assembled into text 000006 3600 7 8 KR Begin assembling into Vars section ae 9
395. r combines all such input sections that have the same name into an output section with that name For example suppose the files f1 obj and f2 0bj both contain named sections called Vectors and that the SECTIONS directive does not define an output section for them The linker combines the two Vectors sections from the input files into a single output section named Vectors allocates it into memory and includes it in the output file After the linker determines the composition of all output sections it must allo cate them into configured memory The MEMORY directive specifies which portions of memory are configured if there is no MEMORY directive the linker uses the default configuration The linker s allocation algorithm attempts to minimize memory fragmentation This allows memory to be used more efficiently and increases the probability that your program will fit into memory This is the algorithm 1 Output sections for which you have supplied a specific binding address are placed in memory at that address 2 Output sections that are included in a specific named memory range or that have memory attribute restrictions are allocated Each output section is placed into the first available space within the named area considering alignment where necessary Default Allocation Algorithm 3 Any remaining sections are allocated in the order in which they are defined Sections not defined ina SECTIONS directive are allocated in the order in
396. r constant loc memory address n if N 2 0 1 1 loc 1 else loc N n gt 2 so store n at loc decrement n and do the eval N 1 N factorial of n 1 factl call factl with current environment endif endm factl macro if Nol T3 loc multiply present factorial HI AC2 T3 by present position ACO AC2 N loc ACO save result eval N 1 N decrement position factl recursive call endif endm 5 24 5 10 Macro Directives Summary Table 5 2 Creating Macros Mnemonic and Syntax Macro Directives Summary Description Define macro macname macro parameter parameter mlib filename mexit endm Identify library containing macro definitions Go to endm End macro definition Table 5 3 Manipulating Substitution Symbols Mnemonic and Syntax Description asg character string substitution symbol eval well defined expression substitution symbol Assign character string to substitution symbol Perform arithmetic on numeric substitution symbols Var substitution symbol substitution symbol Table 5 4 Conditional Assembly Mnemonic and Syntax Af well defined expression Define local macro symbols Description Begin conditional assembly elseif well defined expression else endif loop well defined expression break well defined expression endloop Optional conditional assembly block O
397. r in a string represents a separate value Values are not packed or sign extended In word addressable data sections each byte occupies the 8 least significant bits of a full 16 bit word The assem bler truncates values greater than 8 bits You can use up to 100 value parame ters If you use a label it points to the location where the assembler places the first byte Note that when you use these directives in a struct endstruct sequence they define a member s size they do not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 In this example 8 bit values 10 1 abc and a are placed into consecutive words in memory The label strx has the value 100h which is the location of the first initialized word 1 000000 data 2 000000 Space 100h 16 3 000100 000a STRX byte 10 1 abc a 000101 00ff 000102 0061 000103 0062 000104 0063 000105 0061 Syntax Description Specify C54x Compatibility Mode c54cm_on c54cm_ off c54cm_on cb4cm off The c5b4cm on and cb4cm off directives signify that a region of code has been translated from C54x code The cb4cm on and cb4cm off directives model the C54CM status bit The cb4cm on directive models the C54CM sta tus bit set to 1 it is equivalent to using the ml command line option The cb4cm off directive models the C54CM status bit set to 0 In the case of a con flict between the co
398. range may be one to eight characters in length The name has no sig nificance to the program it simply identifies the range Dupli cate memory range names are allowed Hex Conversion Utility Description 13 15 The ROMS Directive 13 16 origin length romwidth memwidth fill specifies the starting address of a memory range It can be entered as origin org or o The associated value must be a decimal octal or hexadecimal constant If you omit the origin value the origin defaults to 0 The following table summarizes the notation you can use to specify a decimal octal or hexadecimal constant Constant Notation Example Hexadecimal Ox prefix or h suffix 0x77 or 077h Octal 0 prefix 077 Decimal No prefix or suffix 77 specifies the length of a memory range as the physical length of the ROM device It can be entered as length len or The value must be a decimal octal or hexadecimal constant If you omit the length value it defaults to the length of the entire address space specifies the physical ROM width of the range in bits see subsection 13 4 4 ROM Width on page 13 10 Any value you specify here overrides the romwidth option The value must be a decimal octal or hexadecimal constant that is a power of 2 greater than or equal to 8 specifies the memory width of the range in bits see subsection 13 4 3 Memory Width on page 13 9 Any value you specify here overrides the memwidth option The value
399. ranges in the ROMS directive and use the bootorg option to specify the starting address 13 9 4 Booting From a Device Peripheral 13 30 You can choose to boot from a serial or parallel port by using the SERIAL or PARALLEL keyword with the bootorg option Your selection of a keyword depends on the target device and the channel you want to use For example to boot a C55x from its serial port specify bootorg SERIAL on the command line or in a command file To boot a C55x from one of its parallel ports specify bootorg PARALLEL c n PM MEM JJ B 7 Note On Chip Boot Loader Concerns Possible memory conflicts When you boot from a device peripheral the boot table is not actually in memory it is being received through the device peripheral However as explained in Step 3 on page 13 29 a memory address is assigned If the table conflicts with a nonboot section put the boot table on a different page Use the ROMS directive to define a range on an unused page and the bootpage option to place the boot table on that page The boot table will then appear to be at location 0 on the dummy page Why the System Might Require an EPROM Format for a Peripheral Boot Loader Address In a typical system a parent processor boots a child processor through that child s peripheral The boot loader table itself may occupy space in the memory map oft
400. re program that allows you to collect several individual files into a single file called an archive library The archiver also allows you to delete extract or replace members of the archive library as well as to add new members ASCII American Standard Code for Information Exchange A standard computer code for representing and exchanging alphanumeric informa tion assembler A software program that creates a machine language program from a source file that contains assembly language instructions direc tives and macro directives The assembler substitutes absolute opera tion 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 E 1 Glossary assignment statement A statement that assigns a value to a variable autoinitialization The process of initializing global C variables contained in the cinit section before beginning program execution auxiliary entry The extra entry that a symbol may have in the symbol table and that contains additional information about the symbol whether it is a filename a section name a function name etc binding A process in which you specify a distinct address for an output sec tion or a symbol block A set of declarations and statements that are grouped together with braces bss One of the default COFF sections You can use the bss directive
401. reated as part of the label name If you don t use a label the first character position must contain a blank a semicolon or an asterisk When you use a label its value is the current value of the section program counter the label points to the statement it s associated with If for example you use the word directive to initialize several words a label would point to the first word In the following example the label Start has the value 40h 5 000000 data 6 00000000 Assume other code was assembled 7 8 ace 9 000040000A Start word 0Ah 3 7 000041 0003 0000420007 A label on a line by itself is a valid statement The label assigns the current value of the section program counter to the label this is equivalent to the fol lowing directive statement label set provides the current value of the SPC When a label appears on a line by itself it is assigned to the address of the instruction on the next line the SPC is not incremented 3 000043 Here 4 000043 0003 word 3 3 6 3 Mnemonic Field In mnemonic assembly the mnemonic field follows the label field The mne monic field must not start in column 1 if it does it will be interpreted as a label The mnemonic field can contain one of the following opcodes Machine instruction mnemonic such as ABS MPYU STH Assembler directive such as data list set Macro directive such as macro var mexit Macro call D O O L 3 18 Source State
402. resent output file has no text section Description This is a warning The text section is usually present in a COFF file There is no requirement for it to be present output file not executable Description The output file created may have unresolved symbols or other problems stemming from other errors This condition is not fa tal overwriting aux entry filename of symbol n Description The input file may be corrupt Action If the input file is corrupt try reassembling it Linker Error Messages PC relative displacement overflow at address in file Description The relocation of a PC relative jump resulted in a jump dis placement too large to encode in the instruction r incompatible with s s ignored Description Both the r option and the s option were used Since the s option strips the relocation information and r requests a relo catable object file these options are in conflict with each oth er relocation entries out of order in section of file Description The input file may be corrupt Action If the input file is corrupt try reassembling it relocation symbol not found index section file Description The input file may be corrupt Action If the input file is corrupt try reassembling it section at overlays at address Description Two sections overlap and cannot be allocated Action If you are using a linker command file chec
403. rflow precedence of operators 3 31 underflow well defined 3 33 external symbols 2 19 defined E 3 f linker option fclist directive 4 18 listing control 4 45 use in macros fcnolist directive listing control 4 18 4 45 use in macros field defined field directive file copy identification include file header defined E 3 structure file symbolic debugging directive filenames as character strings copy include files extensions changing defaults 10 3 list file macros in macro libraries object code files ROMS specification 13 17 Index fill MEMORY specification ROMS specification 13 16 value default p d explicit initialization b 66 setting p ti fill hex conversion utility option fill value See zn float directive floating point aS ss func symbolic ie id pn function definitions A 16 A 25 A ele functions built in assembler option linker option global defined symbols global directive identifying external symbols 2 19 GROUP defined linker directive 9 47 h assembler option disassembler option 12 2 linker option half directive limiting listing with option directive 4 18 hc assembler option heap linker option sysmem section described help assembler option linker option hex conversion utility command file to 13 7 controlling the ROM device address 13 33 to 13 36 Index 7 Index hex conversion u
404. rogram that converts COFF object files into Intel format or Tektronix format object files Glossary E 5 Glossary object library An archive library made up of individual object files operands The arguments or parameters of an assembly language instruction assembler directive or macro directive optional header A portion of a COFF object file that the linker uses to perform relocation at download time options Command parameters that allow you to request additional or specific functions when you invoke a software tool output module A linked executable object file that can be downloaded and executed on a target system output section A final allocated section in a linked executable module overlay page A section of physical memory that is mapped into the same address range as another section of memory A hardware switch deter mines which range is active partial linking The linking of a file that will be linked again quiet run Suppresses the normal banner and the progress information RAM model An autoinitialization model used by the linker when linking C code The linker uses this model when you invoke the linker with the cr option The RAM model allows variables to be initialized at load time instead of runtime raw data Executable code or initialized data in an output section relocation A process in which the linker adjusts all the references to a sym bol when the symbol s address changes ROM
405. rol the starting address of the EPROM with your EPROM programmer you could create holes within the EPROM The programmer will burn the data starting at location 0x0200 instead of 0x0100 To solve this you can Use the paddr parameter of the SECTIONS directive This forces a sec tion to start at the specified value Figure 13 9 shows a command file that can be used to avoid the hole at the beginning of sec1 Figure 13 9 Hex Command File for Avoiding a Hole at the Beginning of a Section 13 36 i a out map a map ROMS ROM org 0x0100 length 0x200 romwidth 8 memwidth 8 SECTIONS secl paddr 0x100 Note If your file contains multiple sections and if one section uses a paddr parameter then all sections must use the paddr parameter Use the bootorg option or use the ROMS origin parameter for boot loading only As described on page 13 34 when you are boot loading the EPROM address of the entire boot loader table can be controlled by the bootorg option or by the ROMS directive origin Description of the Object Formats 13 11 Description of the Object Formats The hex conversion utility converts a COFF object file into one of five object formats that most EPROM programmers accept as input ASCII Hex Intel MCS 86 Motorola S Extended Tektronix or Tl Tagged Table 13 3 specifies the format options _j If you use more than one of these options the last one you list overri
406. rpose commands that control the actions and functions of a software tool as opposed to assembly language instruc tions which control the actions of a device emulator A hardware development system that emulates TMS320C55x operation entry point The starting execution point in target memory executable module An object file that has been linked and can be executed in a TMS320C55x 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 is defined in a different program module field Forthe TMS320C55x a software configurable data type whose length can be programmed to be any value in the range of 1 16 bits file header A portion of a COFF object file that contains general information about the object file such as the number of section headers the type of system the object file can be downloaded to the number of symbols in the symbol table and the symbol table s starting address global A kind of symbol that is either 1 defined in the current module and accessed in another or 2 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 Glossary E 3 Glossary hex conversion utility A program that accepts COFF files and converts them into one of several standard A
407. rt endif eval 0 pos eval 153 eval Ssymlen strgl LEN1 eval symlen strg2 LEN2 loop break i LEN2 LEN1 1 asg strg2 i LEN1 TMP if symcmp strgl TMP 0 eval i pos break else eval xou lyi endif endloop endm asg 0 pos asg arl ar2 ar3 ar4 regs substr 1 ar2 regs pos data word pos 5 3 6 Substitution Symbols as Local Variables in Macros If you want to use substitution symbols as local variables within a macro you can use the var directive to define up to 32 local macro substitution symbols including parameters per macro The var directive creates temporary substi tution symbols with the initial value of the null string These symbols are not passed in as parameters and they are lost after expansion Var sym symo symga The var directive is used in Example 5 8 and Example 5 9 Macro Language 5 13 Macro Libraries 5 4 Macro Libraries One way to define macros is by creating a macro library A macro library is a collection of files that contain macro definitions You must use the archiver to collect these files or members into a single file called an archive Each member of a macro library contains one macro definition The files in a macro library must be unassembled source files The macro name and the member name must be the same and the macro filename s extension must be asm For example Macro Name Filename in Macro Library simple simple asm
408. s The image options create a continuous image of a range of target memory Option Description page fill value Fill holes with value image Specify image mode 13 25 zero Reset the address origin to zero 13 34 c Memory options The memory options configure the memory widths for your output files Option Description Page memwidth value Define the system memory word width default 16 13 9 bits order LS MS Specify the memory word ordering 13 13 romwidth value Specify the ROM device width default depends on 13 10 format used Invoking the Hex Conversion Utility Table 13 1 Hex Conversion Utility Options Continued d Output formats The output formats specify the format of the output file Option Description Page a Select ASCII Hex 13 38 j Select Intel m1 Select Motorola S1 m2 or m Select Motorola S2 default 13 40 m3 Select Motorola S3 13 40 Select Tl Tagged X Select Tektronix 13 42 e Boot loader options for all C55x devices The boot loader options for all C55x devices control how the hex conversion utility builds the boot table Option Description Page boot Convert all sections into bootable form use instead 13 28 of a SECTIONS directive bootorg PARALLEL Specify the source of the boot loader table as the 13 28 parallel port bootorg SERIAL Specify the source of the boot loader table as the 13 28 serial port bootorg value Specify the sour
409. s 4 71 MOOD Mw ppp a a a 4 71 DSS os lug Rs 4 31 IniacrO coerceri qa 4 72 byte ubyte 4 34 MUD acsi ttt in Rs 4 73 cb4cm on cb4cm off 4 35 mmregs a bd ss dn Ld 4 76 char uchar oeio ss ss 4 34 Hine EET 4 46 CNK t eee ee 4 36 0 Em 4 75 COPY sai nd a meres 4 37 imnollSt janice sds do a eet 4 75 cpl ONCpL off sas es 4 40 newblock 4 79 ET 4 41 noremark 4 80 nl 4 54 jnollSE sien ea 4 67 Ho olU 6 ER 4 42 0 6 11 01 0 WE NE SE E anes ese ar 4 81 OD ones ER guts 4 44 page eorr EIE peeled 4 83 drlist essere 4 45 pstring slices 4 90 JOMONSE 202 gems ena pies A 45 7 4 54 ielse ee n c s 4 59 sblock 4 cscs iro 4 84 elseif 0 A 59 SOC o orbi raae adn ana E 4 85 I ET 4 46 t en 4 86 GNA oo prs Ee 4 48 short ushort 0 4 57 PNA pene ne 4 59 Clerc PR EE 4 87 endloop sssss 4 71 SslisE Leid iem 4 88 endmM ss seve ee ceeds coke ee ee 4 48 ssnolist G00 illc des 4 88 endstruct issues 4 92 SUMING oue iere hmc 4 90 endunion 4 100 SSUUCL e erines PR ER a 4 92 jedes cosi ccbo oxi 4 86 aD ee 4 96 Val xxt Br de es 4 29 lag x cene e hee Rees 4 92 EVEN i ha Re 4 27 TEXT nieve ERR den hes 4 97 felist sn ee eee 4 49 tile oo eee 4 99 cnollst sen a IRR 4 49 UNION i ea a 4 100 Meld eessen Bechet ace cd xe 4 50 SUCI p 4 103 Bio ee ss 4 53 Nli on vli off 4 107 Olobal S00 nde nv 4 54 Width inserenda 4 66 ha
410. s are used to control macro expansion endm terminates the macro definition Macros are explained in further detail in Chapter 5 Macro Language Syntax Description Define Macro Library mlib mlib filename The mlib directive provides the assembler with the name of a macro library A macro library is a collection of files that contain macro definitions These files are bound into a single file called a library or archive by the archiver Each member of a macro library may contain one macro definition that corresponds to the name of the file Macro library members must be source files not object files The filename of a macro library member must be the same as the macro name and its extension must be asm The filename must follow host operating sys tem conventions it may be enclosed in double quotes You can specify a full pathname for example c dsp macs lib If you do not specify a full pathname the assembler searches for the file in 1 The directory that contains the current source file 2 Any directories named with the i assembler option 3 Any directories specified by the environment variable A DIR For more information about the i option and the environment variable see Section 3 5 Naming Alternate Directories for Assembler Input on page 3 14 When the assembler encounters a mlib directive it opens the library and creates a table of the library s contents The assembler enters the names of th
411. s defined in a dummy section are relocated normally They appear in the output module s symbol table with the same value they would have if the DSECT had actually been loaded These sym bols can be referenced by other input sections m Undefined external symbols found in a DSECT cause specified archive libraries to be searched B The section s contents relocation information and line number information are not placed in the output module In the preceding example none of the sections from f1 obj are allocated but all of the symbols are relocated as though the sections were linked at byte address 2000h The other sections can refer to any of the global symbols in sec1 ACOPY section is similar to a DSECT section except that its contents and associated information are written to the output module The cinit section that contains initialization tables for the TMS320C55x C compiler has this attribute under the RAM model ANOLOAD section differs from a normal output section in one respect the section s contents relocation information and line number information are not placed in the output module The linker allocates space for it and it appears in the memory map listing Assigning Symbols at Link Time 9 15 Assigning Symbols at Link Time Linker assignment statements allow you to define external global symbols and assign values to them at link time You can use this feature to initialize a variable or pointer to an allocati
412. s equiva lent to inserting name set value at the beginning of the assembly file If value is omitted the symbol is set to 1 For more information see subsection 3 9 3 Defining Symbolic Constants d Option on page 3 26 suppresses the assembler s default behavior of adding a asm extension to a source file name that does not al ready include an extension enables assembler source debugging in the C source debugger Line information is output to the COFF file for every line of source in the assembly language source file Note that you cannot use the g option on assembly code that already contains line directives i e code that was generated by the C compiler run with g any of these options displays a listing of the available assembler options hcfilename tells the assembler to copy the specified file for the assembly module The file is inserted before source file statements The copied file appears in the assembly listing files hifilename tells the assembler to include the speci fied file for the assembly module The file is included before source file statements The included file does not appear in the assembly listing files specifies a directory where the assembler can find files named by the copy include or mlib directives The for mat of the i option is ipathname For more information see subsection 3 5 1 i Assembler Option on page 3 14 lowercase L produces a listing file A
413. s listing The option directive controls certain features in the listing file This directive has the following operands A turns on listing of all directives and data and subsequent expan sions macros and blocks limits the listing of byte directives to one line turns off the listing of certain directives same effect as drnolist limits the listing of half and short directives to one line limits the listing of long directives to one line turns off macro expansions in the listing zar rog turns off listing performs nolist Directives That Format the Output Listing turns on listing performs list resets the B M T and W options limits the listing of string directives to one line limits the listing of word directives to one line x z4mm50 produces a symbol cross reference listing You can also obtain a cross reference listing by invoking the assembler with the x option The page directive causes a page eject in the output listing The sslist and ssnolist directives allow and suppress substitution symbol expansion listing These directives are useful for debugging the expansion of substitution symbols The tab directive defines tab size The title directive supplies a title that the assembler prints at the top of each page The width directive controls the page width of the listing file You can use this directive to adjust listings for various output devices Assembler Dire
414. s reference lister cross reference listing defined by the assembler P 19 to 2 2d by the linker only for C support 64 described 2 19 to 2 20 3 25 external global number of statements that reference 3 40 predefined reserved words setting to a constant value 3 25 statement number that defines 3 40 substitution unresolved used as labels value assigned syntax assignment statements 9 59 source statement 3 17 SYSmem section __SYSMEM_SIZE Sysstack sysstack linker option SYSSTACK SIZE system stack System stack secondary dA archiver command 8 4 disassembler option 12 3 hex conversion utility option 13 41 tab directive Index tag defined tag directive target memory defined target width Tektronix object format text directive linker definition text section defined E 8 TI Tagged object format 13 41 title Groote Fakes type entry u assembler option linker option ubyte directive uchar directive uhalf directive 4 13 4 57 uint directive ulong directive unconfigured memory defined described DSECT type underflow in an expression uninitialized sections to 2 5 bss 2 5 4 31 Usect 2 5 defined described initialization of 9 66 specifying a run address ae UNION Eq defined linker directive 9 45 to 9 49 union tag 4 23 4 100 defined Ea symbolic Mr oe B 9 union directive 4 23 4
415. se source asm is in the current directory Then the assembler searches in the directory named with the i option 3 5 2 Using Environment Variables C55X A DIR and A DIR An environment variable is a system symbol that you define and assign a string to The assembler uses the environment variables C55X A DIR and A DIR to name alternate directories that contain copy include files or macro libraries The assembler looks for the C55X A DIR environment variable first and then reads and processes it If it does not find this variable it reads the A DIR envi ronment variable and processes it If both variables are set the settings of the processor specific variable are used The processor specific variable is useful when you are using Texas Instruments tools for different processors at the same time The command for assigning the environment variable is as follows Operating System Enter Windows set A DIR pathname another pathname UNIX setenv A DIR pathname another pathname The pathnames are directories that contain copy include files or macro libraries You can separate the pathnames with a semicolon or with blanks In assembly source you can use the copy include or mlib directive without specifying path information If the assembler doesn t find the file in the direc tory that contains the current source file or in directories named by i it searches the paths named by the environment variable For example assume t
416. sed Table 3 3 Symbol Attributes Character or Name REF UNDF Cross Reference Listings Meaning External reference global symbol Undefined Symbol defined in a text section Symbol defined in a data section Symbol defined in a sect section Symbol defined in a bss or usect section Assembler Description 3 41 Chapter 4 Assembler Directives Assembler directives supply data to the program and control the assembly process Assembler directives enable you to do the following Assemble code and data into specified sections Reserve space in memory for uninitialized variables Control the appearance of listings Initialize memory Assemble conditional blocks Declare global variables Specify libraries from which the assembler can obtain macros Examine symbolic debugging information D D UD D C DL LU This chapter is divided into two parts the first part Sections 4 1 through 4 9 describes the directives according to function and the second part Section 4 10 is an alphabetical reference Topic Page 41 Directives Summary lt eee eee ee a 1 2 4 2 Directives That Define Sections Luuluueeeee 4 3 Directives That Initialize Constants sees 4 4 Directives That Align the Section Program Counter 4 5 Directives That Format the Output Listing 4 6 Directives That Reference Other Files 4 7 Conditional Assembly Dire
417. sembler source Macro library Library build utility Runtime support library Library of object files Linker Executable COFF file Hex conversion utility EPROM programmer Tools Descriptions 1 2 Tools Descriptions The following list describes the tools that are shown in Figure 1 1 m The C compiler translates C source code into C55x assembly language source code The compiler package includes the library build utility with which you can build your own runtime libraries The C compiler is not shipped with the assembly language tools package The assembler translates assembly language source files into machine language COFF object files The TMS320C55x tools include two assemblers The mnemonic assembler accepts C54x and C55x mnemonic assembly source files The algebraic assembler accepts C55x algebraic assembly source files Source files can contain instructions assembler directives and macro directives You can use assembler direc tives to control various aspects of the assembly process such as the source listing format data alignment and section content The linker combines relocatable COFF object files created by the assembler into a single executable COFF object module As it creates the executable module it binds symbols to memory locations and resolves all references to those symbols It also accepts archiver library members and o
418. ser s Guide literature number SPRU296 explains how to use the Code Composer development environment to build and debug embedded real time DSP applications HP UX is a trademark of Hewlett Packard Company Solaris and SunOS are trademarks of Sun Microsystems Inc UNIX is a registered trademark in the United States and other countries licensed exclusively through X Open Company Limited Windows and Windows NT are registered trademarks of Microsoft Corporation Motorola S is a trademark of Motorola Inc Tektronix is a trademark of Tektronix Inc Contents Introduction eure game ed cad ieee mE ERE ae dur Ed eu eee eset Provides an overview of the software development tools 1 14 Software Development Tools Overview pp 12 Tools DBSCTHDBONS 0d i ee ded ee ee Introduction to Common Object File Format i PH Discusses the basic COFF concept of sections and how they can help you use the assembler and linker more efficiently Common object file format or COFF is the object file format used by the tools nD er nee re oe a eee oe eee E eT 2 2 How the Assembler Handles Sections pp 2 2 4 Uninitialized Sections 26000 oa nania eee eens 2 2 2 Initialized Sections 0 sn a eet 22 3 Named Sections ices ssn Ln aa Lk fated Le heated RR dcos dos 2 2 4 Subsections po om ped sd a nent teens 2 2 5 Section Program Counters i 2 2 6 An Example That Uses Sections Directives 2 3 How the Linker Handles Sections i 2 3 4 Default Memory Alloc
419. sg errct AR2 register 2 yasgq REN INC indirect auto increment casg kem DEC indirect auto decrement Symbols When you are using macros substitution symbols are important because macro parameters are actually substitution symbols that are assigned a macro argument The following code shows how substitution symbols are used in macros add2 macro ADDRA ADDRB add2 macro definition MOV ADDRA ACO ADD ADDRB ACO ACO MOV ACO ADDRB endm add2 invocation add2 LOC1 LOC2 the macro will be expanded as follows MOV LOC1 ACO ADD LOC2 ACO ACO MOV ACO LOC2 For more information about macros see Chapter 5 Macro Language Assembler Description 3 27 Symbols 3 9 6 Local Labels Local labels are special labels whose scope and effect are temporary A local label can be defined in two ways J n where nis a decimal digit in the range of 0 9 For example 4 and 1 are valid local labels gJ name where name is any legal symbol name as described above The assembler replaces the question mark with a period followed by a unique number When the source code is expanded you will not see the unique number in the listing file Your label appears with the question mark as it did in the macro definition You cannot declare this label as global Normal labels must be unique they can be declared only once and they can be used as constants in the operand field Local labels however can be undefined and
420. ss reference lister is a debugging tool This utility accepts linked object files as input and produces a cross reference listing as output This listing shows symbols their definitions and their references in the linked source files Topic Page 11 1 Producing a Cross Reference Listing 11 2 11 2 Invoking the Cross Reference Lister 11 3 11 3 Cross Reference Listing Example 55 11 4 Producing a Cross Reference Listing 11 1 Producing a Cross Reference Listing Figure 11 1 Cross Reference Lister Development Flow 11 2 Step 1 Assembler source file Cross reference lister Cross reference listing First invoke the assembler with the x option This option produces a cross reference table in the listing file and adds to the object file cross reference information By default the assembler cross references only global sym bols If you use the s option when invoking the assembler it will cross reference local variables as well Link the object file obj to obtain an execut able object file out Invoke the cross reference lister The follow ing section provides the command syntax for invoking the cross reference lister utility Invoking the Cross Reference Lister 11 2 Invoking the Cross Reference Lister To use the cross reference utility the file must be assembled with the correct options and then linked
421. ssages to the standard output device The wmsg directive functions in the same manner as the emsg directive but increments the warning count rather than the error count It does not affect the creation of the object file The following directives relate to C55x memory modes Lj The arms on directive begins a block of code for which the assembler will use indirect access modifiers targeted to code size optimization These modifiers are short offset modifiers The arms off directive ends the block of code The cpl on directive begins a block of code in which direct memory ad dressing DMA is relative to the stack pointer By default DMA is relative to the data page The cpl off directive ends the block of code The c54cm on directive signifies to the assembler that the following block of code has been converted from C54x code The c5b4cm off directive ends the block of code Assembler Directives 4 25 Directives Reference 4 10 Directives Reference The remainder of this chapter is a reference Generally the directives are organized alphabetically one directive per page Related directives Such as Af else endif however are presented together on one page Directive Page Directive Page align i ood double 0 eee eee arms on arms off 4 28 length ccc cee ee eee 4 66 ASO ia dete rated des 4 29 NIST orco Der er I EPIS D S erae cxx 4 87 long ulong 4 69 Dreak snap
422. ssembler could not find the matching directive Action Correct the source per the error message text Conditional nesting is too deep Loop count out of range Description These are errors about conditional assembly loops Condi tional block nesting cannot exceed 32 levels Action Correct the macro endmacro if elseif else endif or loop break endloop source Bad use of access directive Matching struct directive is not present Matching union directive is not present Description These are errors about unmatched structure definition direc tives In a struct endstruct sequence a directive was encountered that requires a matching directive but the assembler could not find the matching directive Action Check the source for mismatched structure definition direc tives and correct Assembler Error Messages C 5 Assembler Error Messages C 6 Cannot apply bitwise NOT to floats Illegal struct union reference dot operator Missing structure union member or tag Section name is not an initialized section Structure or union tag symbol expected Structure or union tag symbol not found Description These are errors about an illegally used operator The opera tor specified was not legal for the given operands Action Correct the source per the error message text so that all required operands are declared Label missing Label required setsym requires a label Description These are errors about required labels The g
423. st be linked into data memory in block ONCHIP Tables of coefficients in the data sections of demo obj tables obj and fft obj must be linked into RAM block ONCHIP in data memory A hole is created with a length of 100 bytes and a fill value of 07A1Ch The remain der of block ONCHIP must be initialized to the value 07A1Ch The bss sections from demo obj tables obj and fft obj which contain variables must be linked into block RAM PG of program RAM The unused part of this RAM must be initialized to OFFFFh The xy section from demo obj which contains buffers and variables will have the default linking into block ONCHIP of data RAM since it was not explicitly linked Example 9 14 shows the linker command file for this example Example 9 15 shows the map file Linker Description 9 73 Linker Example Example 9 14 Linker Command File demo cmd 9 74 BORK KK KK KKK I RA A AAA A ko ko ke ke ke oe e ex f PEER Specify Linker Options EER e coeff Define the program entry point o demo out Name the output file E m demo map Create an output map BORK KK KK KK ECKE KC ECKCKCK CK KC KC ECKE K ECKE KC ECKE KC ECKE KC Kk Kk kk ke ke ke ko ke ke ke o ke e e x f JE Speci
424. st follow operating system conventions m filename o filename stack size sysstack size u symbol W Linker Options Produce a map or listing of the input and output sec tions including holes and place the listing in filename Name the executable output module The default file name is a out The directory or filename must follow operating system conventions Request a quiet run suppress the banner Produce a relocatable output module Strip symbol table information and line number entries from the output module Set the primary stack size to size bytes and define a global symbol that specifies the stack size The default size is 1000 bytes Set the secondary C system stack size to size bytes and define a global symbol that specifies the secon dary system stack size The default size is 1000 bytes Place an unresolved external symbol into the output module s symbol table Displays a message when an undefined output sec tion is created Force rereading of libraries Resolves back refer ences Linker Description 9 7 Linker Options 9 4 1 Relocation Capabilities Ca and r Options The linker performs relocation which is the process of adjusting all references to a symbol when the symbol s address changes The linker supports two options a and r that allow you to produce an absolute or a relocatable output module If neither a nor r is specified the linker acts as if
425. st overlay memory area and the rest of data memory space PAGE 2 defines another area of overlay memory for data space Both OVR_MEM ranges cover the same address range This is possible because each range is on a different page and therefore represents a different memory space Figure 9 5 shows overlay pages defined by the MEMORY directive in Example 9 11 and the SECTIONS directive in Example 9 12 Figure 9 5 Overlay Pages Defined by Example 9 11 and Example 9 12 Program Memory Data Memory Data Memory Page 0 Page 1 Page 2 OVR_MEM f1 0bj text f3 obj text f2 0bj text f4 obj text 2C00h DATA Linker Description 9 51 Overlay Pages 9 12 2 Using Overlay Pages With the SECTIONS Directive Assume that you are using the MEMORY directive as shown in Example 9 11 Further assume that your code consists of besides the usual sections four modules of code that you want to load in data memory space but that you intend to run in the on chip RAM in program memory space Example 9 12 shows how to use the SECTIONS directive overlays accordingly Example 9 12 SECTIONS Directive Definition for Overlays in Figure 9 5 SECTIONS UNION run ONCHIP S1 load OVR MEM PAGE 1 si load 0A00h sl start fl obj text f2 0bj text sl length s1 start S2 load OVR MEM PAGE 2 s2 load 0A00h s2 start f3 0bj text f4 obj text S2 length s2 start
426. sting 3 37 formats address bits ASCII Hex 13 38 Intel Motorola S 13 40 output width Tektronix Tl Tagged library altering search algorithm 9 14 defined E 6 described D 26 to 9 27 runtime support 9 69 using the archiver to build B 4 object file defined object format converter defined octal integer constants 3 21 on chip boot om boot table booting dene E 13 30 sad 32 booting from EPROM booting from the parallel port booting from the serial port ES 13 34 13 33 controlling ROM device address description 13 27 13 31 to modes 13 31 Index on chip boot loader continued options e summary setting the entry point using the boot loader 13 31 to 13 33 operands defined field immediate addressing label 3 25 local label prefixes source statement format operator precedence order 3 32 option directive optional header defined format A 5 options absolute lister 10 3 archiver 8 5 assembler erc lister 111 3 defined da hex conversion ai A to 1 linker 9 6 to 9 20 i4 pes order hex conversion utility option 13 14 ordering memory words 13 13 to origin MEMORY specification ROMS specification output executable 9 8 to 9 9 hex conversion utility 13 23 linker module defined name section allocation pale defined E 6 displaying a message 9 19 rules bd output listing to 4 19 See also listing overflow in an expressio
427. structions 7 4 ROM device address 13 33 to 13 36 model autoinitialization 9 71 defined width defined dened 13 10 to 13 12 tion 13 15 romname ROMS specifica ROMS hex conversion utilit directive 13 15 to 13 20 romwidth ROMS specification RPT differences 7 19 rts lib run address run linker keyword 9 41 to 9 43 runtime environment for ported C54x code switching between C54x and C55x runtime initialization and support s archiver option section header defined described A 6tolA 8 section number A 20 section program counter defined SECTIONS hex conversion utility directive 19 21 to 13 22 linker directive alignment allocation binding blocking default allocation to 9 5 default model described to 9 40 fill value GROUP input sections 9 38 to 9 40 label directive 9 42 to load allocation 9 33 memory to 9 76 overlay pages 8 50 to reserved words 9 run allocation 9 34 Index SECTIONS linker directive continued section specifications section type 9 33 specifying 17 to g 44 uninitialized sections UNION 45 to 9 49 use with MEMORY directive sections allocation 9 55 to p 57 COFF 2 2 to 2 3 creating your own defined in the linker SECTIONS directive 9 33 initialized named 2 21 overlaying with UNION directive 9 45 to p 47 program counters See SPC relocation 2 17 special types 9 58 specifications
428. symbol well defined expression This method of subscripting evaluates to a character string with one character symbol well defined expression well defined expressions In this method expression represents the substring s starting position and expressions represents the substring s length You can specify exactly where to begin subscripting and the exact length of the resulting character string The index of substring characters begins with 1 not 0 Example 5 8 and Example 5 9 show built in substitution symbol functions used with subscripted substitution symbols In Example 5 8 subscripted substitution symbols redefine the add instruction so that it handles short immediates Example 5 8 Using Subscripted Substitution Symbols to Redefine an Instruction ADDX macro ABC Var TMP asg ABC 1 TMP f symcmp TMP 0 ADD ABC ACO ACO else emsg Bad Macro Parameter endif endm ADDX 100 macro call ADDX AR1 macro call Macro Parameters Substitution Symbols In Example 5 9 the subscripted substitution symbol is used to find a substring strg1 beginning at position start in the string strg2 The position of the substring strg1 is assigned to the substitution symbol pos Example 5 9 Using Subscripted Substitution Symbols to Find Substrings substr macro start strgl strg2 pos Var LEN1 LEN2 1 TMP lf Ssymlen start 0 eval 1 sta
429. t Reference Guides The assembler may swap two instructions in order to make parallelism legal For example both sets of instructions below are legal and will be encoded into identical object bits ACO AC1 TO T1 0x3333 TO T1 0x3333 ACO AC1 3 4 3 Variable Length Instruction Size Resolution 3 10 By default the assembler will attempt to resolve all stand alone variable length instructions to their smallest possible size For instance the assembler will try to choose the smallest possible of the three available unconditional branch to address instructions d goto L8 d goto L16 d goto P24 If the address used in a variable length instruction is not known at assembly time for example if it is a symbol defined in another file the assembler will choose the largest available form of the instruction In the example shown above d goto P24 will be picked Size resolution is performed on the following instruction groups goto L7 L16 P24 if cond goto 14 L8 L16 or P24 call L16 or P24 if cond call L16 or P24 In some cases you may want the assembler to keep the largest P24 form of certain instructions The P24 versions of certain instructions execute in fewer cycles than the smaller version of the same instructions For example goto P24 uses 4 bytes and 3 cycles while goto L6 uses 2 bytes but 4 cycles Use the mv assembler option or the vli off directive to keep the following
430. t This is similar to a C union The union directive does not allocate any memory it merely creates a symbolic template that can be used repeatedly A struct definition may contain a union definition and structs and unions may be nested The endunion directive terminates the union definition The tag directive gives structure or union characteristics to a abel simplifying the symbolic representation and providing the ability to define structures or unions that contain other structures or unions The tag directive does not allo cate memory The structure or union tag of a tag directive must have been pre viously defined utag expr memp element eXxprm Size Declare Union Type union endunion tag is the union s tag Its value is associated with the beginning of the union If no utag is present the assembler puts the union members in the global symbol table with the value of their abso lute offset from the top of the union In this case each member must have a unique name is an optional expression indicating the beginning offset of the union Unions default to start at 0 is an optional label for a member of the union This label is abso lute and equates to the present offset from the beginning of the union A label for a union member cannot be declared global is one of the following descriptors byte char double field float half int long short string ubyte uchar uhalt uint
431. t in the file TEXT Section text 0x8 bytes at 0x0 000000 START 000000 2298 MOV AR1 ARO 000002 4010 ADD 1 ACO 000004 last 000004 7b000000 ADD 0 ACO ACO DATA Section data 0x3 words at 0x0 000000 0004 word 0x0004 000001 foo 000001 0001 word 0x0001 000002 0000 word 0x0000 To create a standard disassembly listing of an executable file enter dis55 q test out TEXT Section text OxB bytes at 0x100 000100 START 000100 2298 MOV AR1 ARO 000102 4010 ADD 1 ACO 000104 last 000104 75006400 ADD 100 ACO ACO 000108 FUNC 000108 4804 RET 00010a 20 NOP 00010b etext 00010b etext DATA Section data 0x3 words at 0x8000 008000 0004 word 0x0004 008001 foo 008001 0001 word 0x0001 008002 0108 word 0x0108 The disassembly listing displays the addresses used by the instructions and data as well as the resolved symbol values in the ADD instruction and in the final word directive Notice that the word directive contains the correct address of the function The NOP in the text section is used to pad the section Disassembler Description 12 5 Chapter 13 Hex Conversion Utility Description The TMS320C55x assembler and linker create object files that are in common object file format COFF COFF is a binary object file format that encourages modular programming and provides more powerful and flexible methods for managing code segments and target system memor
432. t instruction Cannot change parsing mode after 1st instruction Can t include a file inside a loop or macro Illegal structure member Illegal structure definition contents Illegal union member Illegal union definition contents Invalid load time label Invalid structure union contents setsect only valid if absolute listing produced use a option setsym only valid if absolute listing produced use a option var allowed only within macro definitions Description These are errors about illegally used directives Specific directives were encountered where they are not permitted because they will cause a corruption of the object file Many directives are not permitted inside of structure or union defini tions Action Correct the source per the error message text Include Copy file not found or opened Description The specified filename cannot be found Action Check spelling pathname environment variables etc Assembler Error Messages Copy limit has been reached Exceeded limit for macro arguments Macro nesting limit exceeded Description These errors are about general assembler limits that have been exceeded The nesting of copy include files in limited to 10 levels Macro arguments are limited to 32 parameter Macro nesting is limited to 32 levels Action Check the source to determine how limits have been exceeded Pass conflict Description This is an internal assembler error If it occurs repeatedly the ass
433. t invokes the archiver tells the archiver how to manipulate the library members A command can be preceded by an optional hyphen You must use one of the following commands when you invoke the archiver but you can use only one command per invocation Valid archiver commands are adds the specified files to the library This command does not replace an existing member that has the same name as an added file it simply appends new members to the end of the archive deletes the specified members from the library replaces the specified members in the library If you don t specify filenames the archiver replaces the library mem bers with files of the same name in the current directory If the specified file is not found in the library the archiver adds it instead of replacing it prints a table of contents of the library If you specify file names only those files are listed If you don t specify any filenames the archiver lists all the members in the speci fied library extracts the specified files If you don t specify member names the archiver extracts all library members When the archiver extracts a member it simply copies the mem ber into the current directory it doesn t remove it from the library option libname filename q S V Invoking the Archiver tells the archiver how to function Specify as many of the following options as you want quiet suppresses the banner and status messages
434. t likely be incorrect for C55x Consider rewriting the code to use a similar C55x instruction thatloads stores the contents of a port address into a register MOV port 100 ACO for PORTR MOV AC1 port 200 for PORTW C54x directive ignored Description Action C 20 Some C54x assembler directives are not needed on the C55x This message occurs when you use such a directive version c mode far mode Remove this directive from your code or simply ignore this message Appendix D Linker Error Messages This appendix lists the the linker error messages in alphabetical order accord ing to the error message In these listings the symbol represents the name of an object that the linker is attempting to interact with when an error occurs absolute symbol being redefined Description An absolute symbol cannot be redefined Action Check the syntax of all expressions and check the input di rectives for accuracy adding name to multiple output sections Description The input section is mentioned twice in the SECTIONS direc tive ALIGN illegal in this context Description Alignment of a symbol is performed outside of a SECTIONS directive alignment for must be a power of 2 Description Section alignment was not a power of 2 Action Make sure that in hexadecimal all powers of 2 consist of the integers 1 2 4 or 8 followed by a series of zero or more Os D 1 Linker Error
435. t on the line To improve readability labels and comments are not shown as part of the directive syntax For some directives however a label is required and will be shown in the syntax Table 4 1 Assembler Directives Summary a Directives that define sections Mnemonic and Syntax Description Page bss symbol size in words blocking Reserve size words in the bss uninitialized data 4 31 alignment section clink section name Enables conditional linking for the current or specified 4 36 section data Assemble into the data initialized data section sect section name Assemble into a named initialized section 4 85 text Assemble into the text executable code section 4 97 symbol usect section name size in words Reserve size words in a named uninitialized section 4 103 blocking alignment Directives Summary Table 4 1 Assembler Directives Summary Continued b Directives that initialize constants data and memory Mnemonic and Syntax bes size in bits byte value values char value values double value values ldouble value value field value size in bits float value value half value values Short value valuen int value value long value valuen pstring string string space size in bits String string stringg ubyte value v
436. t variable C55X C DIR environment variable p 13 to 9 16 char directive character constant string Cinit section _ 9 70 to 9 71 tables cinit symbol 9 70 to 9 71 clink directive COFF auxiliary entries A 22 to A 26 conversion to hexadecimal format 13 1 to 13 44 See also hex conversion utility default allocation defined file structure A 2 to A 3 headers file A 4 optional A 5 section B 6 to A 8 in the development flow initialized sections 2 6 line number entries linker 9 1 loading a program 2 18 COFF continued object file example relocation 2 15 to 2 16 runtime relocation sections allocation assembler t 2 11 described P 2 to 2 3 linker P 12 to 2 14 named P 7 9 63 specialtypes p uninitialized storage classes symbol table structure and content to A 28 symbol values symbolic debugging technical details to type entry uninitialized sections 2 4 to 2 5 command file defined hex conversion utility 13 6 to linker byte addresses in constants in 9 25 p 22 to 9 25 described examples _9 73 to 9 76 invoking 9 4 reserved words 9 25 comments defined extending past page width field Bad in a linker command file 9 23 in assembly language source code 3 20 in macros 5 19 common object file format See COFF conditional blocks assembly directives listing of false conditional blocks 4 49 conditional processing assembly directi
437. te address associated with the directive not the data word address as with other directives The address specifies the address of the interrupt service routine If an ad dress is not specified 0 is used L Youcan specify a stack mode only for the reset vector which must be the first ivec in the interrupt vector table The stack mode can be identified as follows C54X STK This value specifies the 32 bit stack needed by con verted C54x code This is the default if no value is given for the stack mode USE RETA This value specifies 16 bit plus register fast return mode This is used by the C55x compiler NO RETA This value specifies 16 bit slow return mode More information on the stack modes can be found in the TMS320C55x DSP CPU Reference Guide You can write these symbolic names in either upper or lower case The ivec directive aligns the SPC on an 8 byte boundary so that you are not forced to place an instruction between two ivec entries Any space added for this alignment is filled with NOP instructions In general a section that contains other data defining directives such as word is characterized as a data section A data section is word addressable and cannot contain code A section containing the ivec directive is character ized as a code section byte addressable and can include other instructions Like an instruction ivec cannot be mixed with other data defining directives The assembler issues
438. tes Each character in a string represents a separate value p M AEDDODEAAUAAAAAUAUuAUAUOUOOOULUE Note Use These Directives in Data Sections Because code and data sections are addressed differently the use of half uhalf short and ushort directives in a section that includes C55x instruc tions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections The values can be either absolute or relocatable expressions If an expression is relocatable the assembler generates a relocation entry that refers to the appropriate symbol the linker can then correctly patch relocate the refer ence This allows you to initialize memory with pointers to variables or labels The assembler truncates values greater than 16 bits You can use as many values as fit on a single line but the total line length cannot exceed 200 charac ters If you use a label it points to the first initialized word When you use half uhalf short or ushort in a struct endstruct sequence they define a member s size they do not initialize memory For more information about struct endstruct see Section 4 8 Assembly Time Symbol Directives on page 4 22 Assembler Directives 4 57 half uhalf short ushort Initialize 16 bit Integer Example In this example the half directive is used to pl
439. th run and load addresses the linker warns you and ignores the load address Otherwise if you specify only one address the linker treats it as a run address regardless of whether you call it load or run The example below specifies load and run addresses for an uninitialized section bss load 0x1000 run RAM A warning is issued load is ignored and space is allocated in RAM All of the following examples have the same effect The bss sectionis allocated in RAM bss load RAM bss run RAM bss RAM 9 10 3 Referring to the Load Address by Using the label Directive Normally any reference to a symbol in a section refers to its runtime address However it may be necessary at runtime to refer to a load time address Specifically the code that copies a section from its load address to its run address must have access to the load address The label directive defines a special symbol that refers to the section s load address Thus whereas normal symbols are relocated with respect to the run address label symbols are relocated with respect to the load address For more information on the label directive see page 4 65 Example 9 6 shows the use of the label directive Specifying a Section s Runtime Address Example 9 6 Copying a Section From ROM to RAM define a section to be copied from ROM to RAM sect fir label fir src load address of section fir run address of section code here cod
440. the bootorg option Use either memwidth 8 or memwidth 16 For example the command file in Figure 13 8 allows you to boot the text section of abc out from a byte wide EPROM at location 0x8000 Figure 13 8 Sample Command File for Booting From a C55x EPROM abc out input file o abc i output file i Intel format if memwidth 8 8 bit memory romwidth 8 outfile is bytes not words bootorg 0x8000 external memory boot amp f SECTIONS text BOOT 13 32 Controlling the ROM Device Address 13 10 Controlling the ROM Device Address The hex conversion utility output address field corresponds to the ROM device address The EPROM programmer burns the data into the location specified by the hex conversion utility output file address field The hex conversion utility offers some mechanisms to control the starting address in ROM of each sec tion and or to control the address index used to increment the address field However many EPROM programmers offer direct control of the location in ROM in which the data is burned 13 10 1 Controlling the Starting Address Depending on whether or not you are using the boot loader the hex conversion utility output file controlling mechanisms are different Non boot loader mode The address field of the hex conversion utility output file is controlled by the following mechanisms listed from low to high priority 1 Thelinker command file By default t
441. tility continued initialized section data width defined E 4 defined described described initialized sections development flow data error messages 13 43 image mode 13 25 to 13 26 invoking 13 3 to 13 5 memory width 13 9 to 13 10 ipt object formats 13 37 TIERS f link 9 26 9 27 on chip boot loader ner OG ee options 13 4 to 13 5 fi 1 ordering memory words 13 13 to 13 14 defined aa to e ad int directive Intel object format interrupt service routines modifying for C55x interrupt vector table differences between C54x SECTIONS directive target width 13 9 13 21 to 13 22 to hex55 command 13 3 and C55x hexadecimal integer constants 3 22 ivec directive hi assembler option high level language debugging defined I3 hole deed Ed RR NOU defined keywords fil value linker SECTIONS directive 9 39 allocation parameters filling fo e5 to 9 66 in uninitialized sections i assembler option in XT sections seene 17 9 41 to 9 43 assembler option 3 5 cross reference lister option 11 3 disassembler option 12 2 linker option hex conversion utiy option 13 39 label linker option case sensitivity 3 5 MEMORY attribute 9 30 cross reference list 3 40 defined if directive ihc field in macros use ac in assembly language source 3 18 image hex conversion utility option 13 25 local include directive symbols used as 3 25 include files syntax incremental l
442. tion or use the option directive The assembler will append the cross reference to the end of the source listing Note that when the assembler generates a cross reference listing for an assembly file that contains include directives it keeps a record of the include file and line number in which a symbol is defined referenced It does this by assigning a letter reference A B C etc for each include file The letters are assigned in the order in which the include directives are encountered in the assembly source file Example 3 7 Sample Cross Reference Listing LABEL VALUE DEFN REF INTO 000004 25 5 INT1 000008 27 5 INT2 00000c 29 5 ISRO REF 9 25 ISR1 REF 9 27 ISR2 REF 9 29 RINT 000004 37 7 RSE 000000 23 5 TI 000000 35 7 XINT 0000084 39 7 init 000010 45 23 Label column contains each symbol that was defined or referenced during the assembly Value column contains a hexadecimal number which is the value assigned to the symbol ora name that describes the symbol s attributes A value may also be followed by a character that describes the symbol s attributes Table 3 3 lists these char acters and names Definition DEFN column contains the statement number that defines the symbol This column is blank for undefined symbols Reference REF column lists the line numbers of statements that refer ence the symbol A blank in this column indicates that the sym bol was never u
443. tions with relocatable addresses The syntax for these directives is shown below symbol usect section name size in words blocking flag alignment flag sect section name The section name parameter is the name of the section You can create up to 32 767 separate named sections A section name can be up to 200 charac ters For the sect and usect directives a section name can refer to a subsec tion see subsection 2 2 4 Subsections for details Each time you invoke one of these directives with a new name you create a new named section Each time you invoke one of these directives with a name that was already used the assembler assembles code or data or reserves space into the section with that name You cannot use the same names with different directives That is you cannot create a section with the usect direc tive and then try to use the same section with sect Introduction to Common Object File Format 2 7 How the Assembler Handles Sections 2 2 4 Subsections Subsections are smaller sections within larger sections Like sections subsections can be manipulated by the linker Subsections give you tighter control of the memory map You can create subsections by using the sect or usect directive The syntax for a subsection name is section name subsection name A subsection is identified by the base section name followed by a colon then the name of the subsection A subsection c
444. tive C55x functions see Section 7 2 Using Ported C54x Functions with Native C55x Functions on page 7 5 6 1 1 Initializing the Stack Pointers When you execute ported C54x code from reset the appropriate runtime environment is already in place However it is still necessary to initialize the stack pointers SP primary stack and SSP secondary system stack For example stack size set 0x400 stack usect stack section stack size sysstack usect stack section stack size AMOV stack stack size XSP MOV 4 sysstack stack size SSP The stacks grow from high addresses to low addresses so the stack pointers must be initialized to the highest address The primary stack and the secondary system stack must be within the same 64K word page of memory Code that initializes the SP can be ported However the assembler cannot di rectly recognize the code as an SP initialization and will not warn you that the SSP must also be initialized Code that indirectly accesses the SP can also be ported But as above the assembler will not warn you that the SSP must also be initialized 6 1 2 Handling Differences in Memory Placement This section describes the limitations on where you can place your code in memory For ported C54x code a page of memory must be defined as a range of 64K 0x10000 bytes that begins on a 64K byte boundary Edit your linker command file accordingly All data must be placed on page 0 C54x to
445. to reserve a specified amount of space in the memory map that can later be used for storing data The bss section is uninitialized C compiler A program that translates C source statements into assembly language source statements COFF Common object file format A binary object file format that promotes modular programming by supporting the concept of sections command file A file that contains options filenames directives or com ments for the linker or hex conversion utility comment A source statement or portion of a source statement that is used to document or improve readability of a source file Comments are not compiled assembled or linked they have no effect on the object file common object file format See COFF 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 numeric value that can be used as an operand 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 Glossary data One of the default COFF 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 pu
446. tution Symbol Functions Used in a Conditional Assembly Code BICK s 22 2 4 bae RR eR ERSTE ESEERERCE RR ERE RCEER eda Oe ds es Unique Labels in a Macro ne Producing Messages in a Macro ssssssssseees nh Using Nested Macros sa Using Recursive Macros sp a i a ee i C Prototype of Called Function a viset a i i nee ee Assembly Function _firlat_veneer 0 Prototype of Called C Function sees i i a Original C54x Assembly Function pp Modified Assembly Function se Linker Command File ani ee Rr Command File With Linker Directives ot The MEMORY Directive ix rasti ep eure capo dated a poder beer d e Dd ee The SECTIONS Directive griis issii siaaa eee eens Contents xix Contents PPPPPPPPPP oo loO OO XX The Most Common Method of Specifying Section Contents i Copying a Section From ROM to RAM 0 00 cece cece n The UNION Stale Men ze se ratte abe EnA AEEA E e Sd RR TR HR RR T sS Separate Load Addresses for UNION Sections i Allocate Sections Together 0 Nesting GROUP and UNION statements 000 cece eee eee Memory Directive With Overlay Pages i SECTIONS Directive Definition for Overlays in Figure 9 5 i Default Allocation for TMS320C55x Devices i Linker Command File demo cmd i Output Map File demo map ssssssssseesees n eee teen eens A ROMS Directive Example i Map File Output From Example 13 1 Showing Memory Ranges Chapter 1 Introduction The TMS320C55x DSPs are supported b
447. ubjectto align ment and blocking restrictions To refer to groups and unions linker diagnostic messages use the notation GROUP n UNION n In this notation n is a sequential number beginning at 1 that represents the lexical ordering of the group or union in the linker control file without regard to nesting Groups and unions each have their own counter Using UNION and GROUP Statements 9 11 4 Checking the Consistency of Allocators The linker checks the consistency of load and run allocations specified for unions groups and sections The following rules are used m Run allocations are only allowed for top level sections groups or unions sections groups or unions that are not nested under any other groups or unions The linker uses the run address of the top level structure to compute the run addresses of the components within groups and unions As discussed in Section 9 11 1 the linker does not accept a load allocation for UNIONs As discussed in Section 9 11 1 the linker does not accept a load allocation for uninitialized sections In most cases you must provide a load allocation for an initialized section However the linker does not accept a load allocation for an initialized sec tion that is located within a group that already defines a load allocator As a shortcut you can specify a load allocation for an entire group to de termine the load allocations for every initialized section or subgroup nest
448. ucing a file that you will relink Ll LJ Intermediate files must have relocation information Use the r option when you link the file the first time Intermediate files must have symbolic information By default the linker retains symbolic information in its output Do not use the s option if you plan to relink a file because s strips symbolic information from the output module Intermediate link steps should be concerned only with the formation of out put sections and not with allocation All allocation binding and MEMORY directives should be performed in the final link step If the intermediate files have global symbols that have the same name as global symbols in other files and you wish them to be treated as static visible only within the intermediate file you must link the files with the h option See subsection 9 4 7 Make All Global Symbols Static h and 9 global symbol Options on page 9 12 If you are linking C code don t use c or cr until the final link step Every time you invoke the linker with the c or cr option the linker will attempt to create an entry point The following example shows how you can use partial linking Step 1 Link the file filef com use the r option to retain relocation information in the output file tempout1 out lnk55 r o tempoutl filel com file1 com contains SECTIONS sisi fl obj f2 0bj fn obj Linker Description 9 67 Partial In
449. udes C55x instructions will likely lead to the generation of an invalid access to the data at execution Consequently Texas Instruments highly recommends that these directives be issued only within data sections The bes and space directives reserve a specified number of bits in the current section The assembler fills these reserved bits with Os You can reserve words by multiplying the desired number of words by 16 B When you use a label with space it points to the first byte in a code section or word in a data section that contains reserved bits m When you use a label with bes it points to the ast byte in a code section or word in a data section that contains reserved bits Figure 4 1 shows the space and bes directives Assume the following code has been assembled for this example 1 2 space and bes directives 3 000000 data 4 000000 0100 word 100h 200h 000001 0200 5 000002 Res 1 space 17 6 000004 000F word 15 7 000006 Res 2 bes 20 8 000007 00BA word OBAh 9 reserve 3 words 10 000008 Res 3 Space 3 16 11 00000b 000A word 10 Res 1 points to the first word in the space reserved by space Res 2 points to the last word in the space reserved by bes Assembler Directives 4 11 Directives That Initialize Constants Figure 4 1 The space and bes Directives Res 1 02h 17 bits reserved 20 bits reserved Res 2 06h The byte ubyte char
450. undary in code sections or a word boundary in data sections If the SPC is already aligned at the selected boundary it is not incremented Operands for the align directive must equal a power of 2 between 20 and 216 The align directive with no operands defaults to a 128 byte boundary in a code section and a 128 word page boundary in a data section The even directive aligns the SPC so that it points to the next word in code sections or long word in data sections boundary Itis equivalent to specifying the align directive with an operand of 2 Any unused bits in the current byte or word are filled with Os Figure 4 4 demonstrates the align directive Assume that the following code has been assembled 1 000000 data 2 000000 4000 field 2 3 3 000000 4160 field 11 8 4 align 2 5 000002 0045 string Errorcnt 000003 0072 000004 0072 000005 006f 000006 0072 000007 0063 000008 006e 000009 0074 6 align 7 000080 0004 word 4 Directives That Align the Section Program Counter Figure 4 4 The align Directive a Result of align 2 00h b New SPC 02h after ad 2 words i a Current 02h T ad SPC a align 00h directive b Result of align without an argument 00h ce 128 a Current words b New SPC SPC 80h after assembling 80h a align directive Assembler Directives 4 17 Directives That Format the Output Listing 4 5 Directives That Format the Output Listing The
451. ure tag stag of a tag directive must have been previously defined stag expr is the structure s tag Its value is associated with the beginning of the structure If no stag is present the assembler puts the structure members in the global symbol table with the value of their absolute offset from the top of the structure Stag is optional for struct but required for tag is an optional expression indicating the beginning offset of the structure Structures default to start at 0 Declare Structure Type struct endstruct tag memp is an optional label for a member of the structure This label is absolute and equates to the present offset from the beginning of the structure A label for a structure member cannot be declared global element is one of the following descriptors byte char double field float half int long short string ubyte uchar uhalt uint ulong ushort uword and word An element can also be a com plete declaration of a nested structure or union or a structure or union declared by its tag Following a struct directive these directives describe the element s size They do not allocate memory expin is an optional expression for the number of elements described This value defaults to 1 A string elementis considered to be one word in size and a field element is one bit size is an optional label for the total size of the structure rr Note Directives That Can Appear in a
452. ute listing file defined described development flow 10 2 example 10 5 to 10 10 invoking options absolute listing E3 a assembler option producing absolute output module producing 9 8 relocatable 9 9 addressing byte vs word Index algebraic defined align directive 4 16 4 27 alignment 4 16 to 4 17 4 27 defined E 1 linker allocation alignment binding 9 36 to 9 76 blocking default algorithm 9 55 to 9 57 defined memory default sections 9 35 to 9 40 UNION alternate directories linker 9 14 naming with i option naming with A_DIR naming with directives ar linker option 9 9 ar55 command 8 4 archive library alternate directory 9 13 back referencing defined exhaustively reading macros object 9 26 to 9 27 types of files archiver commands defined examples in the development flow invoking options 8 5 overview to 3 16 Index 1 Index arithmetic operators arms_on directive array definitions ARMS mode 38 13 3 13 4 25 ASCII defined arms off directive 3 13 ASCII Hex object format 13 38 assembler built in functions character strings 3 24 constants Bato 2 cross reference listings defined described error messages handling COFF sections in the development flow invoking macros 5 1 to 5 26 options 3 4 additional usage information 14 3 26 B 36 B 4q output listing directive listing to to 4
453. utput Sections i Special Section Types DSECT COPY and NOLOAD i Assigning Symbols at Link Time cece dn ds 9 15 1 Syntax of Assignment Statements i 9 15 2 Assigning the SPC to a Symbol i 9 15 3 Assignment Expressions 0 00 eee eee 9 15 4 Symbols Defined by the Linker i 9 15 5 Symbols Defined Only For C Support c or cr Option Creating and Filling Holes es 9 16 1 Initialized and Uninitialized Sections i 9 16 2 Creating Holes monita meta aia Ra kaiaa aa aaa D ot ia a oet D aioi 9103 Filling Floles isse sese rr ee hy ue xD RE Rx ue EY x ERG 9 16 4 Explicit Initialization of Uninitialized Sections i Partial Incremental Linking sese LINKING C COS D 9 66 9 67 9 69 IJ Contents xi Contents 10 11 12 13 xii 9 18 1 Runtime Initialization 000 c cee eee 9 18 2 Object Libraries and Runtime Support pp 9 18 3 Setting the Size of the Stack and Heap Sections 9 18 4 Autoinitialization ROM and RAM Models 9 18 5 The c and cr Linker Options pp 9 19 Linker Example 1 5 ooi eder RR ere or hee ates Oe eR RR dawns Absolute Lister Description seeeeeeeeeeee III HI nh Explains how to invoke the absolute lister to obtain a listing of the absolute addresses of an object file 10 1 Producing an Absolute Listing 0 cece I 0 2 10 2 Invoking the Absolute Lister 0 0 3 10 3 Absolute Lister Example pp 0 5 Cross Re
454. utput modules created by a previous linker run Linker directives allow you to combine object file sections bind sections or symbols to addresses or within memory ranges and define or redefine global symbols The archiver collects a group of files into a single archive file For example you can collect several macros into a macro library The assembler searches the library and uses the members that are called as macros by the source file You can also use the archiver to collect a group of object files into an object library The linker includes in the library the members that resolve external references during the link The library build utility builds your own customized C runtime support library Standard runtime support library functions are provided as source code in rts src and as object code in rts55 lib The TMS320C55x DSP accepts COFF files as input but most EPROM programmers do not The hex conversion utility converts a COFF object file into Tl tagged Intel Motorola or Tektronix object format The converted file can be downloaded to an EPROM programmer Introduction 1 3 Tools Descriptions The absolute lister accepts linked object files as input and creates abs files as output You assemble abs files to produce a listing that contains absolute rather than relative addresses Without the absolute lister producing such alisting would be tedious and require many manual opera tions The cross reference lister uses o
455. val directive performs arithmetic on substitution symbols which are stored in the substitution symbol table This directive evaluates the expression and assigns the string value of the result to the substitution symbol The eval directive is especially useful as a counter in loop endloop blocks Ll The well defined expression is an alohanumeric expression consisting of legal values that have been previously defined so that the result is an ab solute The substitution symbol must be a valid symbol name The substitution symbol may be 32 characters long and must begin with a letter Remaining characters of the symbol can be a combination of alphanumeric characters the underscore and the dollar sign Assembler Directives 4 29 asg eval Assign Character Strings to Substitution Symbols Example This example shows how asg and eval can be used 1 Sslist show expanded sub symbols 2 3 asg eval example 4 5 asg INC 6 asg ARO FP 7 8 000000 7b00 ADD 100 ACO 000002 6400 9 000004 b403 AMAR FP AMAR ARO 10 11 12 000000 data 13 asg 0 x 14 loop 5 15 eval xtl x 16 word x 17 endloop 1 eval xil x eval O 1 x 1 000000 0001 word x word 1 1 eval x 1 x eval 141 x 1 000001 0002 word x word 2 1 eval xt1 x eval 2 1 x 1 000002 0003 word x word 3 1 eval xl x eval 341 x 1 000003 0004 word x word 4 1 eval x 1 x eval 4 1 x 1 000004 0005 word x word 5 4 30
456. ve but does not set the error count or prevent the creation of an object file sends warning messages to the listing file The wmsg directive functions in the same manner as the emsg directive but it increments the warning count and does not prevent the generation of an object file Macro comments are comments that appear in the definition of the macro but do not show up in the expansion of the macro An exclamation point in column 1 identifies a macro comment If you want your comments to appear in the macro expansion precede your comment with an asterisk or semicolon Example 5 14 shows user messages in macros Macro Language 5 19 Producing Messages in Macros Example 5 14 Producing Messages in a Macro PRPRPPRPRPRPRPRPRPEE PR ee 01 5 CO 15 16 0000 0000 0000 0000 TT 18 0000 US Error testparam 00 00 A004 02 A102 04 2401 06 ER RROR KKKKK o Warnings macro x y if Ssymlen x 0 n emsg ERROR Missing Parameter mexit elseif symlen y 0 emsg I mexit else MOV y ACO MOV x ACO ADD ACO AC1 endif endm ERROR Missing Parameter testparam 1 2 if symlen x 0 7 emsg mexit ERROR Missing Parameter elseif Ssymlen y 0 emsg 1 mexit else MOV 2 ACO MOV 1 AC1 ADD ACO AC1 endif ERROR Missing Parameter testparam if symlen x 0 ems
457. ve to model the DP value Issue this directive immediately following any instruction that changes the value in the DP register If the assembler is not informed of the value of the DP register it assumes that the value is O Syntax Description Example Controls Listing of Directives drlist drnolist drlist drnolist Two directives enable you to control the printing of assembler directives to the listing file The drlist directive enables the printing of all directives to the listing file The drnolist directive suppresses the printing of the following directives to the listing file asg break emsg g eval DD fclist DL D O O LI fcnolist mlist mmsg mnolist SSlist D ssnolist var J wmsg By default the assembler acts as if the drlist directive had been specified This example shows how drnolistinhibits the listing of the specified directives Source file asg 0 x loop 2 eval xt t1 x endloop drnolist asg l x loop 3 eval x 1 x endloop Listing file 1 asg 0 x 2 loop 2 3 eval xl x 4 endloop I eval O 1 x I eval Lady X 5 6 drnolist 7 9 loop 3 10 eval xtl x 11 endloop Assembler Directives 4 45 emsg mmsg wmsg Define Messages Syntax Description Example emsg string mmsg string wmsg string These directives allow you to define your own error and warning messages The assembler tracks the number of errors and
458. ves in macros b 15 to 5 16 maximum nesting levels defined expressions Index configured memory defined described const constant assembly time 4 86 binary integers character 3 22 decimal integers 3 22 defined described floating point hexadecimal integers in command files octal integers 3 21 symbolic 3 25 3 26 copy directive 3 14 4 20 4 37 copy file copy directive hc assembler option cross reference lister creating the cross reference listing example in the development flow 11 2 moka 3 options 11 3 symbol attributes 11 6 cross reference listing assembler option defined coined Ea producing with the option directive producing with the cross reference lister 11 1 to csect section d archiver command assembler option 3 5 3 26 disassembler option 12 2 data directive Index 5 Index data memory data section defined symbols decimal integer constants def directive identifying external symbols 2 19 default allocation 9 55 fill value for holes memory allocation MEMORY configuration MEMORY model 9 28 section See COFF sections SECTIONS configuration development flow 1 2j 8 3 9 3 tools 1 2 directives See also assembler directives defined linker MEMORY 19 28 to 9 31 SECTIONS E 12 9 32 to g 4d symbolic debugging B 3 to B 13 directory search algorithm assembler 3 14 linker 9 13 dis55 command
459. w the Assembler Handles Sections As Figure 2 2 shows the file in Example 2 1 creates five sections text data vectors bss newvars contains 17 bytes of object code contains seven words of object code is a named section created with the sect directive it contains two words of initialized data reserves 10 words in memory is a named section created with the usect directive itreserves eight words in memory The second column shows the object code that is assembled into these sections the first column shows the line numbers of the source statements that generated the object code Figure 2 2 Object Code Generated by the File in Example 2 1 Line Numbers 19 20 21 21 36 37 38 38 39 39 6 6 6 14 26 26 26 44 45 10 30 31 Section text data 0011 vectors 0033 bss 10 words reserved No data newvars eight words reserved Introduction to Common Object File Format 2 11 How the Linker Handles Sections 2 3 How the Linker Handles Sections 2 12 The linker has two main functions related to sections First the linker uses the sections in COFF object files as building blocks it combines input sections when more than one file is being linked to create output sections in an execut able COFF output module Second the linker chooses memory addresses for the output sections Two linker directives support these functions J The MEMORY directive allows you to de
460. want to call a macro several times with different data each time you can assign parameters within the macro The macro language supports a special symbol called a substitution symbol which is used for macro parameters Macro parameters are substitution symbols that represent a character string These symbols can also be used outside of macros to equate a character string to a symbol name Valid substitution symbols can be up to 32 characters long and must begin with a letter The remainder of the symbol can be a combination of alphanumeric characters underscores and dollar signs Substitution symbols used as macro parameters are local to the macro they are defined in You can define up to 32 local substitution symbols including substitution symbols defined with the var directive per macro For more information about the var directive see subsection 5 3 6 Substitution Symbols as Local Variables in Macros on page 5 13 During macro expansion the assembler passes arguments by variable to the macro parameters The character string equivalent of each argument is assigned to the corresponding parameter Parameters without corresponding arguments are set to the null string If the number of arguments exceeds the number of parameters the last parameter is assigned the character string equivalent of all remaining arguments If you pass a list of arguments to one parameter or if you pass a comma or semicolon to a parameter you must surroun
461. xas Instruments Incorporated FILE NAME SIZE DATE sine obj 248 Mon Nov 19 01 25 44 2000 cos obj 248 Mon Nov 19 01 25 44 2000 flt obj 248 Mon Nov 19 01 25 44 2000 lf you want to add new members to the library enter ar55 as function atan obj TMS320C55x Archiver Version x xx Copyright c 2000 Texas Instruments Incorporated gt symbol defined symbol name gt symbol defined symbol name gt building archive function lib Because this example doesn t specify an extension for the libname the archiver adds the files to the library called function lib If function lib didn t exist the archiver would create it The s option tells the archiver to list the global symbols that are defined in the library If you want to modify a library member you can extract it edit it and re place it In this example assume there s a library named macros lib that contains the members push asm pop asm and swap asm ar55 x macros push asm The archiver makes a copy of push asm and places it in the current directory but it doesn t remove push asm from the library Now you can edit the extracted file To replace the copy of push asm in the library with the edited copy enter ar55 r macros push asm 8 6 Chapter 9 Linker Description The TMS320C55x linker creates executable modules by combining COFF object files The concept of COFF sections is basic to linker operation Chapter 2 Introduction to Common Object File
462. y Most EPROM programmers do not accept COFF object files as input The hex conversion utility converts a COFF object file into one of several standard ASCII hexadecimal formats suitable for loading into an EPROM programmer The utility is also useful in other applications requiring hexadecimal conversion of a COFF object file for example when using debuggers and loaders This utility also supports the on chip boot loader built into the target device automating the code creation process for the C55x The hex conversion utility can produce these output file formats ASCII Hex supporting 16 bit addresses Extended Tektronix Tektronix Intel MCS 86 Intel Motorola Exorciser Motorola S supporting 16 bit 24 bit and 32 bit addresses Texas Instruments SDSMAC TI Tagged supporting 16 bit addresses Topic Page 13 1 Hex Conversion Utility Development Flow 13 2 Invoking the Hex Conversion Utility sese 13 3 133 Command Ello ee ee he eter eee E ES re 13 4 Understanding Memory Widths 13 8 13 5 The ROMS Directive ee 13 15 13 6 The SECTIONS Directive 1 2 5 222 232 29 799 22 ccovPUS 13 21 13 7 Output Filenames ee ben S NU ace eee one 13 23 13 8 Image Mode and the fill Option ee 13 25 13 9 Building a Table for an On Chip Boot Loader 13 27 13 10 Controlling the ROM Device Address Lue 13 11 Description of the Obje
463. y the following assembly language tools Assembler Archiver Linker Absolute lister Cross reference utility Hex conversion utility D D UD D D L This chapter shows how these tools fit into the general software tools develop ment flow and gives a brief description of each tool For convenience it also summarizes the C compiler and debugging tools For detailed information on the compiler and debugger and for complete descriptions of the TMS320C55x devices refer to the books listed in Related Documentation From Texas Instruments on page vi The assembly language tools create and use object files in common object file format COFF to facilitate modular programming Object files contain separate blocks called sections of code and data that you can load into C55x memory spaces You can program the C55x more efficiently if you have a basic understanding of COFF Chapter 2 Introduction to Common Object File Format discusses this object format in detail Topic Page 1 1 Software Development Tools Overview esee 1 2 1 2 Tools Descriptions correxi eran rete Inner arenis ns eal Software Development Tools Overview 1 1 Software Development Tools Overview Figure 1 1 illustrates the C55x software development flow The shaded portion of the figure highlights the most common path of software development the other portions are optional Figure 1 1 TMS320C55x Software Development Flow As
464. ym 0004000h end setsym 0004068h end setsym 0004068h Setsect text 0002000h setsect data 0004000h Setsect bss 0004000h laist text Copy modulel asm module2 abs nolist array setsym 0004000h dflag setsym 0004064h offset setsym 0004066h data setsym 0004000h data setsym 0004000h edata setsym 0004000h edata setsym 0004000h text Setsym 0002000h text setsym 0002000h etext setsym 000200fh etext setsym 000200fh bss Setsym 0004000h __bss_ Setsym 0004000h end setsym 0004068h end setsym 0004068h Setsect text 02006n Setsect data 04000h Setsect bss 04066h list text Copy module2 asm Absolute Lister Description 10 7 Absolute Lister Example Step 4 These files contain the following information that the assembler needs when you invoke it in step 4 They contain setsym directives which equate values to global symbols Both files contain global equates for the symbol dflag The symbol dflag was defined in the file globals def which was included in module1 asm and module2 asm They contain setsect directives which define the absolute addresses for sections They contain copy directives which tell the assembler which assembly language source file to include The setsym and setsect directives are not useful in normal assembly they are useful only for creating absolute listings Finally assemble the abs files created by the
465. ystem 7 15 Using Ported C54x Functions with Native C55x Functions Example 7 5 Modified Assembly Function 7 16 declare data as shown previously Assembly routine starts callsce ported C54x code Call C function Change to C55x compiler environment AMOV buffer ARO pass 1st ptr arg in ARO MOV BUFLEN TO pass 1st int arg in TO compiler code needs C54CM 0 ARMS 1 BCLR C54C Clear C54x compatibility mode BSET ARMS set AR mode CALL C func no delayed call instruction Effects of calling C May modify ACO AC3 XARO XAR4 TO T1 May modify RPTC CSR BRCx BRS1 RSAx REAx Will not modify XAR5 XAR7 T2 T3 RETA May modify ACOV 0 3 CARRY TC1 C2 SATD FRCT ASM H SATA SMUL Will not modify other status bits MOV TO result Result is in TO could use absl16 result if all globals are in the same 64K word page of data Change back to ported C54x environment BSET C54CM reset C54x compatibility mode BCLR ARMS disable AR mode ported C54x code RE The arguments are passed according the calling conventions described in the Runtime Environment chapter of the TMS320C55x Optimizing C Compiler User s Guide The status bits modified are the only ones that differ between the C54x ported runtime environment and the native C55x environment in this case as defined by the C55x C compiler The comments ab
466. ze of the field to be patched and describes how to calculate the patched value The type field depends on the addressing mode that was used to generate the relocatable reference In the preceding example the actual address of the referenced symbol X will be placed in a 16 bit field in the object code This is a 16 bit direct relocation so the relocation type is R RELWORD Table A 7 lists the relocation types Table A 7 Relocation Types Bytes 8 and 9 Mnemonic Flag R ABS 0000h R RELBYTE 000Fh R REL13 002Ah R RELWORD 0010h R PARTLS7 0028h R PARTMS9 0029h Relocation Type No relocation 8 bit direct reference to symbol s address 13 bit direct reference 16 bit direct reference to symbol s address 7 LSBs of an address 9 MSBs of an address Line Number Table Structure A 6 Line Number Table Structure The object file contains a table of line number entries that are useful for symbolic debugging When the C compiler produces several lines of assembly language code it creates a line number entry that maps these lines back to the original line of C source code that generated them Each single line number entry contains 6 bytes of information Table A 8 shows the format of a line number entry Table A 8 Line Number Entry Format Byte Number Type Description 0 3 Long integer This entry may have one of two values 1 If itis the first entry in a block of line number entries it points to a symbol entry in the symbol tabl

TMS320C55x Assembly Language Tools User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents