View DSPASMRM_2934968.PDF datasheet online --- IC-ON-LINE

[global | static | local] . . section source statements . . endsec all symbols that are defined within a section have the

associated with them. this serves to protect them from like-named symbols elsewhere in the program. by default, a symbol defined inside any given section is private to that section unless the global or local qualifiers accompany the section directive. more information on the global and local qualifiers can be found in sections and data hiding, below. any code or data inside a section is considered an indivisible block with respect to relo- cation. code or data associated with a section is independently relocatable within the memory space to which it is bound, unless the static qualifier follows the section di- rective on the instruction line. more information on the static qualifier is available in sections and relocation, below. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management sections and data hiding 4-2 dsp assembler reference manual motorola 4.3 sections and data hiding symbols within a section are generally distinct from other symbols used elsewhere in the source program, even if the symbol name is the same. this is true as long as the section name associated with each symbol is unique, the symbol is not declared public ( xdef or global ), and the global or local qualifiers are not used in the section declaration (see below). symbols that are defined outside of a section are considered global symbols and have no explicit section name associated with them. global symbols may be refer- enced freely from inside or outside of any section, as long as the global symbol name does not conflict with another symbol by the same name in a given section. consider the fol- lowing example: sym1 equ 1 sym2 equ 2 section example sym1 equ 3 move #sym1,r0 move #sym2,r1 endsec move #sym1,r2 sym1 and sym2 are global symbols, initially defined outside of any section. then in sec- tion example another instance of sym1 is defined with a different value. because sym1 was redefined inside the section, the value moved to r0 will be 3. since sym2 is a global symbol the value moved to r1 will be 2. the last move to r2 is outside of any section and thus the global instance of sym1 is used; the value moved to r2 is 1. 4.3.1 sections and symbols symbols may be shared among sections through use of the xdef and xref directives. the xdef directive instructs the assembler that certain symbol definitions that occur within the current section are to be accessible by other sections: xdef ,,..., the xref directive instructs the assembler that all references to within the cur- rent section are references to a symbol that was declared public within another section with the xdef directive: xref ,,..., f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management sections and data hiding motorola dsp assembler reference manual 4-3 xdef ed symbols by default are recognized only in other sections which xref them. they can be made fully global (recognizable by sections which do not xref them) by use of the xr option (see the opt directive, chapter 6). alternatively the global directive (see chapter 6) may be used within a section to make the named symbols visible outside of the section. both the xdef and xref directives must be used before the symbols to which they refer are defined or used in the section. here is another example: sym1 equ 1 section sect1 xdef sym2 sym1 equ 2 sym2 equ 3 endsec section sect2 xref sym2 move #sym1,r0 move #sym2,r1 endsec move #sym2,r2 sym1 is first defined outside of any section. then in section sect1 sym2 is declared public with an xdef directive. sym1 is also defined locally to section sect1. in section sect2 sym2 is declared external via the xref directive, followed by a move of sym1 to r0. since sym1 was defined locally to section sect1, the assembler uses the global value and moves a 1 to r0. because sym2 was declared external in section sect1 the value moved to r1 is 3. if sym2 had not been xref ed in section sect2 the value moved to r1 would have been unknown at this point. in the last instruction it is not known what value will be moved to r2 since sym2 was not defined outside of any section or was not declared global within a section. if the global qualifier follows the

in the section directive, then all symbols defined in the section until the next endsec directive are considered global. the effect is as if every symbol in the section were declared with the global directive. this is useful when a section needs to be independently relocatable, but data hiding is not required. if the local qualifier follows the

in the section directive, then all sym- bols defined in the section until the next endsec directive are visible to the immediately enclosing section. the effect is as if every symbol in the section were defined within the parent section. this is useful when a section needs to be independently relocatable, but data hiding within an enclosing section is not required. symbols that are defined with the set directive can be made visible with xdef only in absolute mode, and the section name associated with the symbol will be the section name of the section where the symbol was first defined. this will be true even if the symbol value is changed in another section. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management sections and data hiding 4-4 dsp assembler reference manual motorola 4.3.2 sections and macros the division of a program into sections controls not only labels and symbols, but also mac- ros and define directive symbols. macros defined within a section are private to that section and are distinct from macros defined in other sections even if they have the same macro name. macros defined outside of sections are considered global and may be used within any section. similarly, define directive symbols defined within a section are pri- vate to that section and define directive symbols defined outside of any section are glo- bally applied. there are no directives that correspond to xdef for macros or define symbols, therefore macros and define symbols defined in a section can never be ac- cessed globally. if global accessibility is desired, the macros and define symbols should be defined outside of any section. here is an example: define defval '1' section sect1 define defval '2' move #defval,r0 endsec move #defval,r1 the second definition of defval is visible only inside sect1, so the value moved to r0 will be 2. however, the second move instruction is outside the scope of sect1 and will therefore use the initial definition of defval. this means that the value 1 will be moved to r1. 4.3.3 nested and fragmented sections sections can be nested to any level. when the assembler encounters a nested section, the current section is stacked and the new section is used. when the endsec directive of the nested section is encountered, the assembler restores the old section and uses it. the endsec directive always applies to the most recent section directive. nesting sections provides a measure of scoping for symbol names, in that symbols defined within a given section are visible to other sections nested within it. for example, if section b is nested inside section a, then a symbol defined in section a can be used in section b with- out xdef ing in section a or xref ing in section b. this scoping behavior can be turned off and on with the nons and ns options respectively (see the opt directive, chapter 6). sections may also be split into separate parts. that is,

can be used mul- tiple times with section and endsec directive pairs. if this occurs, then these separate (but identically named) sections can access each others symbols freely without the use of the xref and xdef directives. if the xdef and xref directives are used within one section, they apply to all sections with the same section name. the reuse of the section name is allowed to permit the program source to be arranged in an arbitrary manner (for example, all statements that reserve x space storage locations grouped together), but re- tain the privacy of the symbols for each section. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management sections and relocation motorola dsp assembler reference manual 4-5 4.4 sections and relocation when the assembler operates in relative mode (the default), sections act as the basic grouping for relocation of code and data blocks. for every section defined in the source a set of location counters is allocated for each dsp memory space. these counters are used to maintain offsets of data and instructions relative to the beginning of the section. at link time sections can be relocated to an absolute address, loaded in a particular order, or linked contiguously as specified by the programmer. sections which are split into parts or among files are logically recombined so that each section can be relocated as a unit. sections may be relocatable or absolute. in the assembler absolute mode (command line -a option) all sections are considered absolute. in relative mode, all sections are initially relocatable. however, a section or a part of a section may be made absolute either im- plicitly by using the org directive, or explicitly through use of the mode directive. if the assembler encounters an org directive with an absolute runtime address specifi- cation it switches to absolute mode and begins generating absolute addresses within the enclosing section. note that the mode change is effective only if the assembler was start- ed in relative mode; if the -a command line option is used the assembler always gener- ates absolute addresses. the assembler continues to generate absolute code until an endsec directive is encountered, or the mode is explicitly changed via the mode direc- tive. the mode directive allows for arbitrary switching between absolute and relocatable code generation: mode the mode directive may be issued at any time in the assembly source to alter the set of location counters used for section addressing. code generated while in absolute mode will be placed in memory at the location determined during assembly. relocatable code and data within a section are combined at link time, even if absolute blocks are inter- f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment 4-6 dsp assembler reference manual motorola spersed among relocatable blocks. the mode directive has no effect when the com- mand line -a option is active. the following is an example: section example ; relocatable section ; code/data generated here is relocatable mode absolute ; code/data generated here is absolute; it will be ; placed in memory at the location specified during ; assembly mode rel ; back to relocatable; code/data generated here ; will be combined with the previous relocatable block, ; as long as memory space and mappings are compatible org p:$200 ; code/data generated here will be absolute ; until endsec directive is found endsec more information on the org and mode directives can be found in address assignment and under the individual directive descriptions in chapter 6. if the static qualifier follows the

in the section directive, then all code and data defined in the section until the next endsec directive are relocated in terms of the immediately enclosing section. the effect with respect to relocation is as if all code and data in the section were defined within the parent section. this is useful when a sec- tion needs data hiding, but independent relocation is not required. 4.5 address assignment the motorola dsp assembler can support absolute address assignment at assembly time or generation of relocatable program addresses which are resolved during the linking phase. the org directive is used to specify memory space changes, mappings to phys- ical memory, and absolute address assignment. various memory layouts require special handling for data generation or location counter updating. in the case of l memory, two words of code or data are produced for each in- f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment motorola dsp assembler reference manual 4-7 crement of the location counter. there are many kinds of e memory depending on the characteristics of the ram devices used. in most cases e memory implies splitting the generated word into 8-bit triplets or 8 and 16-bit pairs on output, and adjusting the location counter appropriately. the assembler allows for two sets of program counters per memory space, a set of load counters and a set of runtime counters. the distinction between load and runtime counters is maintained so that the assembler can support overlays , or runtime transfers of code/data from one memory space to another. in these cases code or data might be loaded in one memory space at a given address, but then copied to a different memory space and address for execution. the assembler can produce output for either absolute or relocatable overlays. motorola dsps are capable of performing special-purpose addressing on data structures suited to digital signal processing applications. two such data structures are the modulo buffer and the reverse-carry buffer, collectively referred to as circular buffers . due to the way they are accessed and manipulated, these buffers generally are constrained to a par- ticular size or starting address. the assembler provides directives for aligning buffer base addresses, allocating buffer space, and initializing buffer contents. 4.5.1 the org directive the org directive specifies which memory space will be the runtime memory space and which counter (the h , l , default, or numbered runtime counter associated with that mem- ory space and section) will be the runtime location counter. at the same time, the org directive indicates which memory space will be the load memory space and which counter (the h , l , default, or numbered load counter associated with that memory space and sec- tion) will be used as the load location counter. in addition, the org directive can be used to specify a physical mapping to dsp memory and to assign initial values to the runtime and load location counters. the names of the counters ( h igh, l ow, and default) are symbolic only, and the assembler performs no checks to insure that the value assigned to the h igh counter is greater than the l ow. moreover, there is no inherent relationship among numbered counters, except that counters 0, 1, and 2 correspond to the default, l ow, and h igh counters, respectively. counters are useful for providing mnemonic links between runtime and load memory spaces or among individual memory blocks. separate counters can be used to obtain blocks within a common section which are accessed from one memory space but mapped to separate physical memories. also counters are necessary for handling relocatable overlays at link time, as the dsp linker does not support the notion of separate load and runtime counters. see the examples below for more information on location counter us- age. the org directive is organized as follows: org [][]:[][,[][]:[]] f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment 4-8 dsp assembler reference manual motorola or alternatively: org [][()]:[][,[][()]:[]] which memory space (x, y, l, p, or e) will be used as the runtime memory space. if the memory space is l , any allocated datum with a value greater than the target word size will be extended to two words; otherwise, it is trun- cated. if the memory space is e , then depending on the memory space qual- ifier, any generated words will be split into bytes, one byte per word, or a 16/ 8-bit combination. which runtime counter h, l, or default (if neither h or l is specified), that is associated with the will be used as the runtime location counter. indicates the runtime physical mapping to dsp memory: i - internal, e - ex- ternal, r - rom, a - port a, b - port b. if not present, no explicit mapping is done. non-negative absolute integer expression representing the counter number to be used as the runtime location counter. must be enclosed in parenthe- ses. should not exceed the value 65535. initial value to assign to the runtime counter used as the . if is a relative expression the assembler uses the relative location counter. if is an absolute expression the assembler uses the absolute loca- tion counter. if is not specified, then the last value and mode that the counter had will be used. which memory space (x, y, l, p, or e) will be used as the load memory space. if the memory space is l , any allocated datum with a value greater than the target word size will be extended to two words; otherwise, it is trun- cated. if the memory space is e , then depending on the memory space qual- ifier, any generated words will be split into bytes, one byte per word, or a 16/ 8-bit combination. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment motorola dsp assembler reference manual 4-9 which load counter, h, l, or default (if neither h or l is specified), that is as- sociated with the will be used as the load location counter. indicates the load physical mapping to dsp memory: i - internal, e - exter- nal, r - rom, a - port a, b - port b. if not present, no explicit mapping is done. non-negative absolute integer expression representing the counter number to be used as the load location counter. must be enclosed in parentheses. should not exceed the value 65535. initial value to assign to the load counter used as the . if is a relative expression the assembler uses the relative location counter. if is an absolute expression the assembler uses the absolute loca- tion counter. if is not specified, then the last value and mode that the counter had will be used. the org directive is useful in multi-programmer projects because it provides a means for the individual programmer to specify in which memory space and which segment of that memory space the code being written will be located without specifying an absolute ad- dress. absolute address assignment can be deferred until the various components of the program are brought together. the utility of the org directive is not limited to multi-pro- grammer projects. even in single programmer projects, the org directive supports ma- nipulation of overlays and the intermixing of label definition and code generation in multiple memory spaces without having to reinitialize a location counter every time the load memory space is changed. 4.5.2 overlays if the last half of the operand field in an org directive dealing with the load memory space and counter is not specified, then the assembler will assume that the load memory space and load location counter are the same as the runtime memory space and runtime loca- tion counter. in this case, object code is being assembled to be loaded into the address and memory space where it will be when the program is run, and is not an overlay. if the load memory space and counter are given in the operand field, then the assembler always generates code for an overlay. whether the overlay is absolute or relocatable de- pends upon the current operating mode of the assembler and whether the load counter value is an absolute or relative expression. if the assembler is running in absolute mode, or if the load counter expression is absolute, then the overlay is absolute. if the assembler f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment 4-10 dsp assembler reference manual motorola is in relative mode and the load counter expression is relative, the overlay is relocatable. runtime relocatable overlay code is addressed relative to the location given in the runtime location counter expression. this expression, if relative, may not refer to another overlay block. see section 1.7 for more information on location counters and overlays. the values and memory space attributes of both the load and runtime location counters can be accessed with the @lcv function (see section 3.8). this is particularly useful when assigning the load location counter value to a label as a reference point for the over- lay manager part of the program. the h igh, l ow, default, or numbered counter assign- ment can be determined by using the @ctr function (section 3.8). 4.5.3 address assignment examples some examples of the org directive are as follows: org p:$1000 sets the runtime memory space to p. selects the default runtime counter (counter 0) associated with p space to use as the runtime location counter and initializes it to $1000. the load memory space is implied to be p, and the load location counter is assumed to be the same as the runtime location counter. org phe: sets the runtime memory space to p. selects the h load counter (counter 2) as- sociated with p space to use as the runtime location counter. the h counter will not be initialized, and its last value will be used. code generated hereafter will be mapped to external (e) memory. the load memory space is implied to be p, and the load location counter is assumed to be the same as the runtime location counter. org pi:ovl1,y: indicates code will be generated for an overlay. the runtime memory space is p, and the default counter is used as the runtime location counter. it will be reset to the value of ovl1. if the assembler is in absolute mode via the -a command line option then ovl1 must be an absolute expression. if ovl1 is an absolute expres- sion the assembler uses the absolute runtime location counter. if ovl1 is a relo- catable value the assembler uses the relative runtime location counter. in this case ovl1 must not itself be an overlay symbol (e.g. defined within an overlay block). the load memory space is y. since neither h, l, nor any counter expression was specified as the load counter, the default load counter (counter 0) will be used as the load location counter. the counter value and mode will be whatever it was the last time it was referenced. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment motorola dsp assembler reference manual 4-11 org xl:,e8: sets the runtime memory space to x. selects the l counter (counter 1) associated with x space to use as the runtime location counter. the l counter will not be ini- tialized, and its last value will be used. the load memory space is set to e, and the qualifier 8 indicates a bytewise ram configuration. instructions and data will be generated eight bits per output word with byte-oriented load addresses. the de- fault load counter will be used and there is no explicit load origin. org p(5):,y:$8000 indicates code will be generated for an absolute overlay. the runtime memory space is p, and the counter used as the runtime location counter is counter 5. it will not be initialized, and the last previous value of counter 5 will be used. the load memory space is y. since neither h, l, nor any counter expression was specified as the load counter, the default load counter (counter 0) will be used as the load location counter. the default load counter will be initialized to $8000. if the last example shown was used in the following code sequence (assume the runtime counter associated with p space had a previous value of $0010), org p(5):,y:$8000 rlmul move x:(r0),d4.s y:(r4),d7.s fmpy.s d4,d7,d0 move d0.s,x:(r1) then the label rlmul would have a value of $0010 and a memory space attribute of p space; the code generated would load into y memory starting at $8000; and the runtime address associated with the code would start at $0010. 4.5.4 circular buffers to take advantage of the special dsp addressing capabilities a circular buffer must be aligned on an appropriate address boundary with respect to its size. for a buffer to be located properly in memory the lower bits of the starting address which encompass one less than the buffer size must be zero. for example, the lowest address greater than zero at which a buffer of size 32 may be located is 32 (20 hexadecimal). more generally, the buffer base address must be modulo the buffer size, or a multiple of 2 k , where 2 k is greater than or equal to the size of the buffer. buffers may be allocated manually or by using one of the assemblers special buffer di- rectives: org x:$100 buf1 ds 24 buf2 dsm 32 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management address assignment 4-12 dsp assembler reference manual motorola the org statement sets the origin to hexadecimal 100 in x memory. the first buffer buf1 is manually allocated with a size of 24. since the starting address is hex 100 the buffer is already suitably aligned. the label buf1 is assigned the runtime counter value at the beginning of the buffer. the second buffer is allocated using the dsm directive, which automatically sets the buffer starting address before reserving space. in this case, the first buffer ended at location 117 hexadecimal, so the assembler advances the pro- gram counter to location 120 hex before assigning a value to the buffer label buf2. buffers are special-purpose data structures, but they are named and accessed with labels like any other data block. they therefore adhere to the same rules governing data hiding in sections that any other segment of code or data would follow. a buffer allocated when the assembler is in absolute mode (either via -a or an absolute org or mode directive) is placed in memory according to the absolute value of the runtime location counter at as- sembly time. a buffer allocated in relative mode (a relocatable buffer ) is suitably aligned within its relocation section at assembly time. during the link phase a section enclosing any relocatable buffers is located based on the largest relocatable buffer it contains, un- less the buffers inside the section are auto-aligned. this insures that any smaller buffers within the section are properly aligned. if any buffers in the section are auto-aligned, they will be relocated independent of any other code or data in the section. note that reposi- tioning of any buffer, whether relocatable or absolute, may result in alignment gaps in memory depending on the layout of data surrounding the buffer blocks. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 1: multi-programmer environment motorola dsp assembler reference manual 4-13 4.6 example 1: multi-programmer environment typical multi-programmer projects are often split into tasks representing functional units. for discussion purposes, suppose a project has been divided into three tasks - i/o, filter, and main. each task will be written by a separate programmer as a separate section. for example, when the i/o task has been written, there will be a file called io.asm. this file will have the following form: section i_o xref i_port,o_port org xl: . . . . org p: . . . . endsec in this example, because the x space storage locations were defined within the section i_o, they will be private storage locations that are accessible only by the i_o handler, and cannot be referenced by other sections. if global memory resource management is de- sired, then the i_o section would not have defined any storage locations, and these would have been defined as xref . the x space data will be addressed through the l ow runtime counter. the p memory code is also private to the i_o section and uses the de- fault runtime location counter for address generation. in the discussion below, assume that the programmers responsible for the filter and main sections have similar program structures located in files named filter.asm and main.asm respectively. the program units can be combined either by invoking a final assembly step to assign absolute addresses, or by assembling the modules separately and then linking. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 1: multi-programmer environment 4-14 dsp assembler reference manual motorola 4.6.1 absolute mode implementation to assemble the entire project source code, a new file called project.asm would be created and would have the form: org xle:$0000 . . org yle:$0000 . . org yh:$ffc0 . . org xh:$ffc0 . . ; initialize internal low program memory location counter org pl:$1000 ; initialize external high program memory location counter org phe:$f000 include 'main.asm' include 'io.asm' include 'filter.asm' end entry this file provides the project manager with a mechanism to organize memory utilization to suit the application. for example, the external high p memory initialization statement might correspond to the memory location of an external eprom. after the location counters corresponding to the x, y, and p(rogram) memory spaces are initialized, the assembler is directed to take input from the main.asm file with the in- clude directive. within the main.asm file, the source statements are assembled and object code is generated. the x, y, l, and p(rogram) location counters (high, low) are advanced corresponding to the number of words generated for each memory space and location counter in use. when the end of the main.asm file is encountered, the assembler returns to the next se- quential statement in the project.asm file. this directs the assembler to start taking input from the io.asm file. within this file, the org pl: statement directs the assembler f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 1: multi-programmer environment motorola dsp assembler reference manual 4-15 to set the current memory space to p(rogram) and restore the last used p(rogram) l(ow) location counter. the shown previously will be assem- bled at the next available low program memory space. when the end of the io.asm file is encountered, the x, y, and p(rogram) location counters (high and low) will have been advanced corresponding to the number of words generated for each memory space. in a similar manner, the file filter.asm will be assembled. the last statement of the project.asm file informs the assembler that this is the last logical source statement, and the starting address for the object module will be a label called entry. in the exam- ple above, entry would have been a label defined in the section main and declared as global with the xdef directive. 4.6.2 relative mode implementation using the assembler default relative mode, each of the source files is assembled sepa- rately. for each section defined in the input files a separate set of location counters is maintained such that all memory spaces for each section begin at relative address zero. the linker is invoked to combine the files and establish base addresses: dsplnk -b -m -oxli:0 -oyli:0 -oyh:ffc0 -oxh:ffc0 \ -opl:1000 -ophe:a000 main io filter the linker reads the command input and sets up base values for all counters specified on the command line. in this example, the x and y low memory counters are initialized to ze- ro, whereas the x and y high memory counters are set to ffc0 hexadecimal. the pro- gram low and high memory counters are initialized similarly. when the linker creates the executable file it reads the input files and sets the starting address for all sections relative to the values obtained from the command line. as the main object file is read the linker increments the section counters for all appropriate memory spaces. after the main object file is processed, the io object file is read. the section named i_o contained an org directive indicating a switch to the low x data memory counter. recall that the assembler generated relocatable code for the i_o section source such that the low x data memory counter begins at zero. the linker adjusts the low x memory counter associated with section i_o to reflect any previous data generation performed in low x memory (e.g. in main). the filter module is linked in a similar fashion. another way for specifying base addresses, instead of lengthy command line options, is through a memory control file . the memory control file allows the programmer to indi- cate memory space starting addresses analogously to the command line approach. in ad- dition, the memory control file offers finer control over placement of sections in memory. see the motorola dsp linker/librarian reference manual for more information on the memory control file. the preceding examples described two methods for organizing a software project. refer to the descriptions of the org and section directives in chapter 6 for a more detailed discussion. see also the motorola dsp linker/librarian reference manual for more in- f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 2: overlays 4-16 dsp assembler reference manual motorola formation on relocation and linking. one other assembler directive that should be men- tioned (although not shown in the previous example) is the maclib directive which allows sections to share a common macro library. the maclib directive is discussed more fully in chapter 5. 4.7 example 2: overlays an overlay is a transfer of code or data from one memory space or address to another memory space or address at runtime. often the transfer involves copying different blocks of code or data over a common storage area as runtime circumstances dictate; hence the name overlay . overlays are useful for moving code into internal program memory from an external memory source such as eprom. they are also effective when implementing large programs with multiple segments which do not need to be accessed concurrently. consider the following program fragment contained in a file called over1.asm: section overlay1 xref ovlbase xdef ovl1,o1size org x: ovl1 org p:ovlbase,x: start . . . . end o1size equ end-start endsec this is a sample of overlay code bounded by a section directive. the overlay base, or the place to which this block of code will be moved for execution, is declared external at ovlbase (ovlbase is actually defined elsewhere). the label ovl1 is xdef ed to pro- vide a handle for moving the block at runtime, and o1size is also xdef ed so that the overlay management code knows how many words to move. note that the ovl1 label is placed before the org for the overlay so that it remains a valid address in x memory dur- ing execution. the overlay org directive insures that subsequent addresses will be based from ovlbase at runtime. the size of the overlay block (o1size) is computed by subtracting the start label value from the end label address. assume for purposes of discussion that there are other files containing similar overlay code with names over2.asm and over3.asm. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 2: overlays motorola dsp assembler reference manual 4-17 4.7.1 absolute mode implementation in order to avoid binding addresses within the individual overlay modules, the programmer could devise a preamble file called ovlproj.asm which sets the appropriate counters and establishes the overlay base address. note that the following code assumes a dsp96000, but similar instructions would apply for other target processors: section ovlproject xdef ovlbase xref ovl1,o1size xref ovl2,o2size xref ovl3,o3size org xe:$100 ; set absolute base for overlay sections org pi:$200 ; set absolute base address for overlay ovlbase ds $400 ; reserve space for overlay area moveov1 ; code to move first overlay segment move #ovl1,r0; load overlay code address move #ovlbase,r1; load overlay base address move #o1size,d1.m; load overlay code size do d1.m,_endloop; loop to move data words into p memory move x:(r0)+,d0.m; get word of overlay from data memory move d0.m,p:(r1)+; store word of overlay into p memory _endloop . . . endsec the overlay base address ovlbase is made global with the xdef statement. the over- lay segments and their sizes are made visible to the project section by using the xref directive. the first org establishes where the overlay segments will be placed in mem- ory contiguously at load time. the second org sets up the absolute base address for the overlay area common to all of the overlay segments. uninitialized space is allocated for the overlay area, immediately followed by code to move the overlay segments into the common area at runtime. the following assembler command line will process the header file and all overlay segments: asm96000 -a -b -l ovlproj over1 over2 over3 start the assembler is invoked in absolute mode ( -a option), and generates an executable and listing file. all files on the command line are processed as a single assembly run and all are used to produce the output. ovlproj.asm is read first and sets up the appropriate absolute addresses for later sections. then each overlay file is read and loaded one after the other at external x memory address 100 hexadecimal. however, since each overlay f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 2: overlays 4-18 dsp assembler reference manual motorola module was intended to run starting at ovlbase in p memory, all labels and jumps to those labels within the overlay code will be relative to the overlay base address. this means that the code in each of the overlay modules, when loaded by the overlay manage- ment code in the ovlproject section, will start executing at internal p memory address 200 hexadecimal. the file start.asm contains an end directive which indicates the program start address after loading. 4.7.2 relative mode implementation in relative mode each of the overlay files is assembled separately to create individual ob- ject files. the object files are combined to build a single executable file. a preamble file ovlproj.asm containing overlay management code might appear as follows. note that this code assumes a dsp96000, but similar instructions would apply for other target pro- cessors: section ovlproject xdef ovlbase xref ovl1,o1size xref ovl2,o2size xref ovl3,o3size org pi: ; set base address for overlay moveov1 ; code to move first overlay seg- ment move #ovl1,r0 ; load overlay code address move #ovlbase,r1 ; load overlay base address move #o1size,d1.m ; load overlay code size do d1.m,_endloop ; loop to move data words into p memory move x:(r0)+,d0.m ; get word of overlay from data memory move d0.m,p:(r1)+ ; store one word of overlay into p memory _endloop . . . ovlbase ds $400 ; reserve space for overlay area endsec f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 2: overlays motorola dsp assembler reference manual 4-19 note that the org to p space does not specify an absolute address. in order to obtain the same result from these files as in an absolute mode implementation the following link- er command line would be used: dsplnk -b -m -oxe:100 -opi:200 ovlproj over1 over2 over3 the linker scans the command line and sets the base addresses for x and p memory. here the x default counter is set to hex 100 and mapped to external memory; likewise the p default counter is set to hex 200 and mapped to internal memory. base addresses can also be established with the linker memory control file. the linker reads each input object file, placing the header file in internal p memory and combining the overlay modules into a contiguous block loaded into external x memory at location 100 hexadecimal. any labels or jumps within the overlay blocks are resolved to addresses relative to the relocatable symbol ovlbase. since ovlbase is the first load p memory address it is assigned the value 200 hexadecimal. the linker does not guaran- tee that a given symbol or section will begin at a particular location unless that information is explicitly specified in the linker memory control file. for more information on specific linker operations see the motorola dsp linker/librarian reference manual . f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 3: bootstrap overlay 4-20 dsp assembler reference manual motorola 4.8 example 3: bootstrap overlay many motorola dsp processors, specifically those with ram-based program memory, support a bootstrap mode of operation. this involves mapping a built-in rom-based boot- strap program into p memory, executing the program to move user-supplied code from another location (usually eprom) into program ram, then transferring control to the user program. because the user program is loaded in one location (e.g. eprom) but moved to another for execution, it is a natural application for assembly language overlay seman- tics. another wrinkle in bootstrap mode is that user instruction words are loaded in byte- wise fashion, such that the load location counter must be incremented by bytes rather than words. consider the following section fragments contained in two files called sect1.asm and sect2.asm respectively: section sect1 org pi(1):,pe(2) start1 . . . . end1 endsec . . . section sect2 org pi(1):,pe(2) start2 . . . . end2 endsec f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 3: bootstrap overlay motorola dsp assembler reference manual 4-21 4.8.1 absolute mode implementation in order to avoid binding addresses within the individual modules, the programmer could devise a preamble file called bootproj.asm which sets the appropriate options and establishes load and runtime base addresses: opt lb ; increment load counter by bytes org pi(1):$100,pe(2):$c000 ; set runtime ram address, ; bytewide load rom ad- dress the opt directive with the lb option indicates that the assembler should increment the load counter by the number of bytes in the target processor word. this guarantees that the eprom addresses will be correct for bytewide loading during bootstrap processing. in the org directive, the runtime location counter, tagged as 1 and mapped to internal memory, is set to hex 100. the load counter is tagged as 2, mapped to external memory, and set to hex c000, where the built-in bootstrap program will begin loading bytes after processor reset. the files are assembled using the command below: asm56100 -a -b -l bootproj sect1 sect2 the assembler is invoked in absolute mode ( -a option), and generates an executable and listing file. all files on the command line are processed as a single assembly run and all are used to produce the output. bootproj.asm is read first and sets up the appropriate absolute addresses for later sections. since no explicit base address was given in the sec- tion files, both load and runtime addresses will continue from one section to the other, e.g. they will be contiguous. for example, if only two words of instruction were between each of the start and end labels, the runtime value for end1 and start2 would be hex 102. however, the load address of the code associated with these labels, assuming a 16 bit target word size, would be c004 hexadecimal. similarly, the runtime value for end2 would be 104 hex and the corresponding load address would be c008 hexadecimal. 4.8.2 relative mode implementation in relative mode each of the source files is assembled separately to create individual ob- ject files. the object files are combined to build a single executable file. a preamble file is not necessary to handle bootstrap files in relative mode because the addresses are es- tablished at link time. in order to generate bytewide load addresses the lb option can be specified on the assembler command line using the -o command line option: asm56100 -b -l -olb sect1 this command assembles the file sect1.asm and creates a relocatable object file called sect1.cln. the listing file shows that the starting address of the section is zero; howev- er, because of the lb option on the command line the load counter will increment at twice the rate of the runtime counter (assuming a 16 bit dsp56100 family target processor). a f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
software project management example 3: bootstrap overlay 4-22 dsp assembler reference manual motorola similar command is used to assemble the sect2 module. the two files are linked as fol- lows: dsplnk -bbootproj.cld "-opi(1):100" "-ope(2):c000" sect1 sect2 the linker scans the command line and sets the base addresses for p internal and exter- nal memory. the quotes around the -o options are necessary to avoid interpretation of parentheses by some host command interpreters. here the p counter number 1 is set to hex 100 and mapped to internal memory; likewise the p counter number 2 is set to hex c000 and mapped to external memory. base addresses can also be established with the linker memory control file. since no explicit overlay base addresses were encountered in the source files, both load and runtime addresses for the sections will be adjacent and non-overlapping. assuming a code size of 2 for each section and a 16 bit word size, the value for label start1 will be hex 100 and the value for start2 will be hex 102; the corresponding load addresses will be c000 hex and c004 hex, respectively. the execut- able output will be written to the file bootproj.cld. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
motorola dsp assembler reference manual 5-1 chapter 5 macro operations and conditional assembly 5.1 macro operations programming applications frequently involve the coding of a repeated pattern or group of instructions. some patterns contain variable entries which change for each repetition of the pattern. others are subject to conditional assembly for a given occurrence of the in- struction group. in either case, macros provide a shorthand notation for handling these instruction patterns. having determined the iterated pattern, the programmer can, within the macro, designate selected fields of any statement as variable. thereafter by invoking a macro the programmer can use the entire pattern as many times as needed, substituting different parameters for the designated variable portions of the statements. when the pattern is defined it is given a name. this name becomes the mnemonic by which the macro is subsequently invoked (called). if the name of the macro is the same as an existing assembler directive or mnemonic opcode, the macro will replace the direc- tive or mnemonic opcode, and a warning will be issued. the warning can be avoided by the use of the rdirect directive, which is used to remove entries from the assemblers directive and mnemonic tables. if directives or mnemonics are removed from the assem- blers tables, then no warning will be issued when the assembler processes macros whose names are the same as the removed directive or mnemonic entries. however, if a macro is defined through the maclib directive which has the same name as an existing directive or opcode, it will not automatically replace that directive or opcode as previously described. in this case, the rdirect directive must be used to force the replacement. see the description of the maclib directive below. the macro call causes source statements to be generated. the generated statements may contain substitutable arguments. the statements produced by a macro call are rel- atively unrestricted as to type. they can be any processor instruction, almost any assem- bler directive, or any previously-defined macro. source statements resulting from a macro call are subject to the same conditions and restrictions that are applied to state- ments written by the programmer. to invoke a macro, the macro name must appear in the operation code field of a source statement. any arguments are placed in the operand field. by suitably selecting the ar- guments in relation to their use as indicated by the macro definition, the programmer causes the assembler to produce in-line coding variations of the macro definition. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly macro libraries 5-2 dsp assembler reference manual motorola the effect of a macro call is to produce in-line code to perform a predefined function. the code is inserted in the normal flow of the program so that the generated instructions are executed with the rest of the program each time the macro is called. an important feature in defining a macro is the use of macro calls within the macro defini- tion. the assembler processes such nested macro calls at expansion time only. the nesting of one macro definition within another definition is permitted. however, the nested macro definition will not be processed until the primary macro is expanded. the macro must be defined before its appearance in a source statement operation field. 5.2 macro libraries the motorola dsp assembler allows for the maintenance of macro libraries with the ma- clib directive. this directive is used to specify the pathname (as defined by the host op- erating system) of a directory that contains macro definitions. each macro definition must be in a separate file, and the file must be named the same as the macro with the extension .asm added. for example, blockmv.asm would be a file that contained the definition of the macro called blockmv. if a maclib directive has been specified in the source code and the assembler encoun- ters a name in the operation field that is not a previously defined macro or is not contained in the directive or mnemonic tables, the directory specified in the maclib directive will be searched for a file of that name (with the .asm extension added). if such a file is found, the current source line will be saved, and the file will be opened for input as an include file. when the end of the file is encountered, the source line is restored and processing is resumed. because the source line is restored, the processed file must have a macro definition of the unknown name, or an error will result when the source line is restored and processed. however, the processed file is not limited to macro definitions, and can include any legal source code statements. multiple maclib directives may be given, in which case the as- sembler will search each directory in the order in which they were specified. 5.3 macro definition the definition of a macro consists of three parts: the header, which assigns a name to the macro and defines the dummy arguments; the body, which consists of prototype or skel- eton source statements; and the terminator. the header is the macro directive, its label, and the dummy argument list. the body contains the pattern of standard source state- ments. the terminator is the endm directive. the header of a macro definition has the form: macro [][] f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly macro definition motorola dsp assembler reference manual 5-3 the required label is the symbol by which the macro will be called. the dummy argument list has the form: [[,,...,]] the dummy arguments are symbolic names that the macro processor will replace with ar- guments when the macro is expanded (called). each dummy argument must obey the same rules as global symbol names. dummy argument names that are preceded by an underscore are not allowed. dummy arguments are separated by commas. for example, consider the following macro definition: n_r_mul macro nmul,avec,bvec,result header ; ;this macro implements n real multiplies ;result(i) = avec(i) * bvec(i) i=1..nmul ;where ; nmul = number of multiplications ; avec = base address of array avec(i) ; bvec = base address of array bvec(i) ; result = base address of array result(i) ; move #avec,r0 body move #bvec,r4 move #result,r1 move x:(r0)+,d4.s y:(r4)+,d7.s do #nmul,_endloop fmpy.s d4,d7,d0 x:(r0)+,d4.sy:(r4)+,d7.s move d0.s,x:(r1)+ _endloop endm terminator when a macro call is executed, the dummy arguments within the macro definition (nmul,avec,bvec,result in the example above) are replaced with the correspond- ing argument as defined by the macro call. all local labels within a macro are considered distinct for the currently active level of macro expansion (unless the macro local label override is used, see below). these local labels are valid for the entire macro expansion and are not considered bounded by non-local la- bels. therefore, all local labels within a macro must be unique. this mechanism allows the programmer to freely use local labels within a macro definition without regard to the number of times that the macro is expanded. non-local labels within a macro expansion are considered to be normal labels and thus cannot occur more than once unless used with the set directive (see chapter 6). f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly macro calls 5-4 dsp assembler reference manual motorola when specifying a local label within the body of a macro, the programmer must be aware that the label symbol is valid for the entire body of the current level of macro expansion. it is not valid for any nested macros within the current level of expansion. the example above shows why the local label feature is useful. if the macro n_r_mul were called several times, there would be several _endloop labels resulting from the macro expan- sions. this is acceptable because each _endloop label is considered private to a par- ticular instance of macro expansion. it is sometimes desirable to pass local labels as macro arguments to be used within the macro as address references (e.g. move #_label,r0). the assembler effectively dis- allows this, however, since underscore label references within a macro invocation are re- garded as labels local to that expansion of the macro. a macro local label override is provided which causes local symbol lookup to have normal scope rather than macro call scope. if a circumflex ( ^ ) precedes an expression containing an underscore label, at ex- pansion the associated term will be evaluated using the normal local label list rather than the macro local label list. the operator has no effect on normal labels or outside a macro expansion. 5.4 macro calls when a macro is invoked the statement causing the action is termed a macro call . the syntax of a macro call consists of the following fields: [] [][] the argument field can have the form: [[,,...,]] the macro call statement is made up of three fields besides the comment field: the , if any, will correspond to the value of the location counter at the start of the macro expansion; the operation field which contains the macro name; and the operand field which contains substitutable arguments. within the operand field each calling argument of a macro call corresponds one-to-one with a dummy argument of the macro definition. for example, the n_r_mul macro defined earlier could be invoked for expansion (called) by the statement: n_r_mul cnt+1,vec1,vec2,out where the operand field arguments, separated by commas and taken left to right, corre- spond to the dummy arguments "n" through "result", respectively. these arguments are then substituted in their corresponding positions of the definition to produce a se- quence of instructions. macro arguments consist of sequences of characters separated by commas. although these can be specified as quoted strings, to simplify coding the assembler does not re- quire single quotes around macro argument strings. however, if an argument has an em- bedded comma or space, that argument must be surrounded by single quotes ('). an f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly dummy argument operators motorola dsp assembler reference manual 5-5 argument can be declared null when calling a macro. however, it must be declared ex- plicitly null. null arguments can be specified in four ways: by writing the delimiting com- mas in succession with no intervening spaces, by terminating the argument list with a comma and omitting the rest of the argument list, by declaring the argument as a null string, or by simply omitting some or all of the arguments. a null argument will cause no character to be substituted in the generated statements that reference the argument. if more arguments are supplied in the macro call than appear in the macro definition, a warning will be output by the assembler. 5.5 dummy argument operators the assembler macro processor provides for text substitution of arguments during macro expansion. in order to make the argument substitution facility more flexible, the assem- bler also recognizes certain text operators within macro definitions which allow for trans- formations of the argument text. these operators can be used for text concatenation, numeric conversion, and string handling. 5.5.1 dummy argument concatenation operator - \ dummy arguments that are intended to be concatenated with other characters must be preceded by the concatenation operator, ' \ ' to separate them from the rest of the charac- ters. the argument may precede or follow the adjoining text, but there must be no inter- vening blanks between the concatenation operator and the rest of the characters. to position an argument between two alphanumeric characters, place a backslash both be- fore and after the argument name. for example, consider the following macro definition: swap_reg macro reg1,reg2 ;swap reg1,reg2 using x0 as temp move r \ reg1,x0 move r \ reg2,r \ reg1 move x0,r \ reg2 endm if this macro were called with the following statement, swap_reg 0,1 then for the macro expansion, the macro processor would substitute the character 0 for the dummy argument reg1, and the character 1 for the dummy argument reg2. the concatenation operator ( \ ) indicates to the macro processor that the substitution charac- ters for the dummy arguments are to be concatenated in both cases with the character r. the resulting expansion of this macro call would be: move r0,x0 move r1,r0 move x0,r1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly dummy argument operators 5-6 dsp assembler reference manual motorola 5.5.2 return value operator - ? another macro definition operator is the question mark ( ? ) that returns the value of a sym- bol. when the macro processor encounters this operator, the ? sequence is converted to a character string representing the decimal value of the . for ex- ample, consider the following modification of the swap_reg macro described above: swap_sym macro reg1,reg2 ;swap reg1,reg2 using x0 as temp move r \? reg1,x0 move r \? reg2,r \? reg1 move x0,r \? reg2 endm if the source file contained the following set statements and macro call, areg set 0 breg set 1 swap_sym areg,breg then the sequence of events would be as follows: the macro processor would first substi- tute the characters areg for each occurrence of reg1 and breg for each occurrence of reg2. for discussion purposes (this would never appear on the source listing), the intermediate macro expansion would be: move r \? areg,x0 move r \? breg,r \? areg move x0,r \? breg the macro processor would then replace ? areg with the character 0 and ? breg with the character 1, since 0 is the value of the symbol areg and 1 is the value of breg. the resulting intermediate expansion would be: move r \ 0,x0 move r \ 1,r \ 0 move x0,r \ 1 next, the macro processor would apply the concatenation operator ( \ ), and the resulting expansion as it would appear on the source listing would be: move r0,x0 move r1,r0 move x0,r1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly dummy argument operators motorola dsp assembler reference manual 5-7 5.5.3 return hex value operator - % the percent sign ( % ) is similar to the standard return value operator except that it returns the hexadecimal value of a symbol. when the macro processor encounters this operator, the % sequence is converted to a character string representing the hexadecimal value of the . consider the following macro definition: gen_lab macro lab,val,stmt lab \% val stmt endm this macro generates a label consisting of the concatenation of the label prefix argument and a value that is interpreted as hexadecimal. if this macro were called as follows, num set 10 gen_lab hex,num,'nop' the macro processor would first substitute the characters hex for lab, then it would re- place % val with the character a, since a is the hexadecimal representation for the dec- imal integer 10. next, the macro processor would apply the concatenation operator ( \ ). finally, the string 'nop' would be substituted for the stmt argument. the resulting ex- pansion as it would appear in the listing file would be: hexa nop the percent sign is also the character used to indicate a binary constant. if a binary con- stant is required inside a macro it may be necessary to enclose the constant in parenthe- ses or escape the constant by following the percent sign by a backslash ( \ ). 5.5.4 dummy argument string operator - " another dummy argument operator is the double quote ( " ). this character is replaced with a single quote by the macro processor, but following characters are still examined for dummy argument names. the effect in the macro call is to transform any enclosed dummy arguments into literal strings. for example, consider the following macro definition: str_mac macro string dc " string " endm if this macro were called with the following macro expansion line, str_mac abcd then the resulting macro expansion would be: dc 'abcd' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly dummy argument operators 5-8 dsp assembler reference manual motorola double quotes also make possible define directive expansion within quoted strings. be- cause of this overloading of the double quotes, care must be taken to insure against inap- propriate expansions in macro definitions. since define expansion occurs before macro substitution, any define symbols are replaced first within a macro dummy argument string: define long 'short' str_mac macro string msg ' this is a long string ' msg " this is a long string " endm if this macro were invoked as follows, str_mac sentence then the resulting expansion would be: msg 'this is a long string' msg 'this is a short sentence' 5.5.5 macro local label override operator - ^ it may be desirable to pass a local label as a macro argument to be used as an address reference within the macro body. if a circumflex ( ^ ) precedes an expression containing an underscore label, during macro expansion the associated term will be evaluated with normal local label scope rather than macro call scope. such interpretation disables the usual local label semantics for this particular reference within the macro call. here is an example: load macro addr move p:^addr,r0 endm the macro local label override operator causes the addr argument to be interpreted as a local label outside the macro if the expanded argument has a leading underscore. if there is no leading underscore on the actual argument then the override operator has no effect. consider the following macro call: _local load _local without the local label override in the macro definition, an error would occur at the macro call because a symbol _local was not defined in the body of the macro. because the circumflex was used the value of _local gets moved to r0. note that any arbitrary string may be used as the actual parameter to the load macro. the override operator has an effect only with underscore labels. care must be exercised, however, in not defining a f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly dup, dupa, dupc, dupf directives motorola dsp assembler reference manual 5-9 macro label called _local and attempting to reference it as in the above example. in that case the macro local label override operator prevents the assembler from seeing the local label definition for that reference, and an error would result. 5.6 dup, dupa, dupc, dupf directives the dup , dupa , dupc , and dupf directives are specialized macro forms. they can be thought of as a simultaneous definition and call of an unnamed macro. the source state- ments between the dup , dupa , dupc , and dupf directives and the endm directive fol- low the same rules as macro definitions, including (in the case of dupa , dupc , and dupf ) the dummy operator characters described previously. for a detailed description of these directives, refer to chapter 6. 5.7 conditional assembly conditional assembly facilitates the writing of comprehensive source programs that can cover many conditions. assembly conditions may be specified through the use of argu- ments in the case of macros, and through definition of symbols via the define , set , and equ directives. variations of parameters can then cause assembly of only those parts necessary for the given conditions. the built-in functions of the assembler provide a ver- satile means of testing many conditions of the assembly environment (see section 3.8 for more information on the assembler built-in functions). conditional directives can also be used within a macro definition to ensure at expansion time that arguments fall within a range of allowable values. in this way macros become self-checking and can generate error messages to any desired level of detail. the conditional assembly directive if has the following form: if . . [ else ] (the else directive is optional) . . endif a section of a program that is to be conditionally assembled must be bounded by an if - endif directive pair. if the optional else directive is not present, then the source state- ments following the if directive and up to the next endif directive will be included as part of the source file being assembled only if the had a nonzero result. if the has a value of zero, the source file will be assembled as if those statements between the if and the endif directives were never encountered. if the else directive is present and has a nonzero result, then the statements between the if and else directives will be assembled, and the statements between the else and endif directives will be skipped. alternatively, if has a value of zero, then f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
macro operations and conditional assembly conditional assembly 5-10 dsp assembler reference manual motorola the statements between the if and else directives will be skipped, and the statements between the else and endif directives will be assembled. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
motorola dsp assembler reference manual 6-1 chapter 6 assembler significant characters and directives 6.1 introduction this chapter describes the directives that are recognized by the motorola dsp assem- bler. the assembler directives are instructions to the assembler rather than instructions to be directly translated into object code. in addition, this chapter describes special char- acters that are considered significant to the assembler. 6.2 assembler significant characters there are several one and two character sequences that are significant to the assembler. some have multiple meanings depending on the context in which they are used. special characters associated with expression evaluation are described in chapter 3. other as- sembler-significant characters are: ; - comment delimiter ;; - unreported comment delimiter \ - line continuation character or macro dummy argument concatenation operator ? - macro value substitution operator % - macro hex value substitution operator ^ - macro local label override operator " - macro string delimiter or quoted string define expansion character @ - function delimiter * - location counter substitution ++ - string concatenation operator [ ] - substring delimiter << - i/o short addressing mode force operator < - short addressing mode force operator > - long addressing mode force operator # - immediate addressing mode operator f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-2 dsp assembler reference manual motorola #< - immediate short addressing mode force operator #> - immediate long addressing mode force operator 6.3 assembler directives assembler directives can be grouped by function into seven types: 1. assembly control 2. symbol definition 3. data definition/storage allocation 4. listing control and options 5. object file control 6. macros and conditional assembly 7. structured programming 6.3.1 assembly control the directives used for assembly control are: comment - start comment lines define - define substitution string end - end of source program fail - programmer generated error message force - set operand forcing mode himem - set high memory bounds include - include secondary file lomem - set low memory bounds mode - change relocation mode msg - programmer generated message org - initialize memory space and location counters radix - change input radix for constants rdirect - remove directive or mnemonic from table scsjmp - set structured control branching mode scsreg - reassign structured control statement registers undef - undefine define symbol warn - programmer generated warning f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-3 6.3.2 symbol definition the directives used to control symbol definition are: endsec - end section equ - equate symbol to a value global - global section symbol declaration gset - set global symbol to a value local - local section symbol declaration section - start section set - set symbol to a value xdef - external section symbol definition xref - external section symbol reference 6.3.3 data definition/storage allocation the directives used to control constant data definition and storage allocation are: baddr - set buffer address bsb - block storage bit-reverse bsc - block storage of constant bsm - block storage modulo buffer - start buffer dc - define constant dcb - define constant byte ds - define storage dsm - define modulo storage dsr - define reverse carry storage endbuf - end buffer 6.3.4 listing control and options the directives used to control the output listing are: list - list the assembly lstcol - set listing field widths nolist - stop assembly listing opt - assembler options page - top of page/size page prctl - send control string to printer stitle - initialize program subtitle tabs - set listing tab stops title - initialize program title f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-4 dsp assembler reference manual motorola 6.3.5 object file control the directives used for control of the object file are: cobj - comment object code ident - object code identification record symobj - write symbol information to object file 6.3.6 macros and conditional assembly the directives used for macros and conditional assembly are: dup - duplicate sequence of source lines dupa - duplicate sequence with arguments dupc - duplicate sequence with characters dupf - duplicate sequence in loop endif - end of conditional assembly endm - end of macro definition exitm - exit macro if - conditional assembly directive maclib - macro library macro - macro definition pmacro - purge macro definition 6.3.7 structured programming the directives used for structured programming are: .break - exit from structured loop construct .continue - continue next iteration of structured loop .else - perform following statements when .if false .endf - end of .for loop .endi - end of .if condition .endl - end of hardware loop .endw - end of .while loop .for - begin .for loop .if - begin .if condition .loop - begin hardware loop .repeat - begin .repeat loop .until - end of .repeat loop .while - begin .while loop f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-5 individual descriptions of each of the assembler special characters and directives follow. they include usage guidelines, functional descriptions, and examples. structured pro- gramming directives are discussed separately in chapter 7. some directives require a label field, while in many cases a label is optional. if the descrip- tion of an assembler directive does not indicate a mandatory or optional label field, then a label is not allowed on the same line as the directive. in general, it is disallowed to use the label field of a data directive (such as ds , bsc , or buffer directives) in an expression used to define the space being allocated. this is because in some cases the label value cannot be determined until the operand field is fully evaluated. for example: badds ds badds the line above is invalid because the label badds cannot reasonably be determined in this context. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-6 dsp assembler reference manual motorola ; comment delimiter character any number of characters preceded by a semicolon ( ; ), but not part of a literal string, is considered a comment. comments are not significant to the assembler, but they can be used to document the source program. comments will be reproduced in the assembler output listing. comments are normally preserved in macro definitions, but this option can be turned off (see the opt directive, this chapter). comments can occupy an entire line, or can be placed after the last assembler-significant field in a source statement. a comment starting in the first column of the source file will be aligned with the label field in the listing file. otherwise, the comment will be shifted right and aligned with the comment field in the listing file. example: ; this comment begins in column 1 of the source file loop jsr compute ; this is a trailing comment ; these two comments are preceded ; by a tab in the source file f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-7 ;; unreported comment delimiter characters unreported comments are any number of characters preceded by two consecutive semi- colons ( ;; ) that are not part of a literal string. unreported comments are not considered significant by the assembler, and can be included in the source statement, following the same rules as normal comments. however, unreported comments are never reproduced on the assembler output listing, and are never saved as part of macro definitions. example: ;; these lines will not be reproduced ;; in the source listing f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-8 dsp assembler reference manual motorola \ line continuation character or macro argument concatenation character line continuation the backslash character ( \ ), if used as the last character on a line, indicates to the assem- bler that the source statement is continued on the following line. the continuation line will be concatenated to the previous line of the source statement, and the result will be pro- cessed by the assembler as if it were a single line source statement. the maximum source statement length (the first line and any continuation lines) is 512 characters. example: ; this comment \ extends over \ three lines macro argument concatenation the backslash ( \ ) is also used to cause the concatenation of a macro dummy argument with other adjacent alphanumeric characters. for the macro processor to recognize dum- my arguments, they must normally be separated from other alphanumeric characters by a non-symbol character. however, sometimes it is desirable to concatenate the argument characters with other characters. if an argument is to be concatenated in front of or be- hind some other symbol characters, then it must be followed by or preceded by the back- slash, respectively. example: suppose the source input file contained the following macro definition: swap_reg macro reg1,reg2 ;swap reg1,reg2 using d4.l as temp move r \ reg1,d4.l move r \ reg2,r \ reg1 move d4.l,r \ reg2 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-9 the concatenation operator ( \ ) indicates to the macro processor that the substitution char- acters for the dummy arguments are to be concatenated in both cases with the character r. if this macro were called with the following statement, swap_reg 0,1 the resulting expansion would be: move r0,d4.l move r1,r0 move d4.l,r1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-10 dsp assembler reference manual motorola ? return value of symbol character the ? sequence, when used in macro definitions, will be replaced by an ascii string representing the value of . this operator may be used in association with the backslash ( \ ) operator. the value of must be an integer (not floating point). example: consider the following macro definition: swap_sym macro reg1,reg2 ;swap reg1,reg2 using d4.l as temp move r \? reg1,d4.l move r \? reg2,r \? reg1 move d4.l,r \? reg2 endm if the source file contained the following set statements and macro call, areg set 0 breg set 1 swap_sym areg,breg the resulting expansion as it would appear on the source listing would be: move r0,d4.l move r1,r0 move d4.l,r1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-11 % return hex value of symbol character the % sequence, when used in macro definitions, will be replaced by an ascii string representing the hexadecimal value of . this operator may be used in as- sociation with the backslash ( \ ) operator. the value of must be an integer (not floating point). example: consider the following macro definition: gen_lab macro lab,val,stmt lab \% val stmt endm if this macro were called as follows, num set 10 gen_lab hex,num,'nop' the resulting expansion as it would appear in the listing file would be: hexa nop f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-12 dsp assembler reference manual motorola ^ macro local label override the circumflex ( ^ ), when used as a unary expression operator in a macro expansion, will cause any local labels in its associated term to be evaluated at normal scope rather than macro scope. this means that any underscore labels in the expression term following the circumflex will not be searched for in the macro local label list. the operator has no effect on normal labels or outside of a macro expansion. the circumflex operator is useful for passing local labels as macro arguments to be used as referents in the macro. note that the circumflex is also used as the binary exclusive or operator. example: consider the following macro definition: load macro addr move p: ^ addr,r0 endm if this macro were called as follows, _local load _local the assembler would ordinarily issue an error since _local is not defined within the body of the macro. with the override operator the assembler recognizes the _local symbol outside the macro expansion and uses that value in the move instruction. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-13 " macro string delimiter or quoted string define expansion character macro string the double quote ( " ), when used in macro definitions, is transformed by the macro pro- cessor into the string delimiter, the single quote ( ' ). the macro processor examines the characters between the double quotes for any macro arguments. this mechanism allows the use of macro arguments as literal strings. example: using the following macro definition, cstr macro string dc " string " endm and a macro call, cstr abcd the resulting macro expansion would be: dc 'abcd' quoted string define expansion a sequence of characters which matches a symbol created with a define directive will not be expanded if the character sequence is contained within a quoted string. assembler strings generally are enclosed in single quotes ( ' ). if the string is enclosed in double f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-14 dsp assembler reference manual motorola quotes ( " ) then define symbols will be expanded within the string. in all other respects usage of double quotes is equivalent to that of single quotes. example: consider the source fragment below: define long 'short' str_mac macro string msg ' this is a long string ' msg " this is a long string " endm if this macro were invoked as follows, str_mac sentence then the resulting expansion would be: msg 'this is a long string' msg 'this is a short sentence' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-15 @ function delimiter all assembler built-in functions start with the @ symbol. see section 3.8 for a full discus- sion of these functions. example: sval equ @ sqt(fval) ; obtain square root f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-16 dsp assembler reference manual motorola * location counter substitution when used as an operand in an expression, the asterisk represents the current integer value of the runtime location counter. example: org x:$100 xbase equ *+$20 ; xbase = $120 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-17 ++ string concatenation operator any two strings can be concatenated with the string concatenation operator ( ++ ). the two strings must each be enclosed by single or double quotes, and there must be no interven- ing blanks between the string concatenation operator and the two strings. example: 'abc' ++ 'def' = 'abcdef' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-18 dsp assembler reference manual motorola [ ] substring delimiter [ , ] square brackets delimit a substring operation. the argument is the source string. is the substring starting position within . is the length of the desired substring. may be any legal string combination, including another substring. an error is issued if either or exceed the length of . example: define id [ 'dsp56000',3,5 ] ; id = '56000' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-19 << i/o short addressing mode force operator many dsp instructions allow an i/o short form of addressing. if the value of an absolute address is known to the assembler on pass one, then the assembler will always pick the shortest form of addressing consistent with the instruction format. if the absolute address is not known to the assembler on pass one (that is, the address is a forward or external reference), then the assembler will pick the long form of addressing by default. if this is not desired, then the i/o short form of addressing can be forced by preceding the absolute address by the i/o short addressing mode force operator ( << ). example: since the symbol ioport is a forward reference in the following sequence of source lines, the assembler would pick the long absolute form of addressing by default: btst #4,y:ioport ioport equ y:$fff3 because the long absolute addressing mode would cause the instruction to be two words long instead of one word for the i/o short absolute addressing mode, it would be desirable to force the i/o short absolute addressing mode as shown below: btst #4,y: << ioport ioport equ y:$fff3 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-20 dsp assembler reference manual motorola < short addressing mode force operator many dsp instructions allow a short form of addressing. if the value of an absolute ad- dress is known to the assembler on pass one, or the force short directive is active, then the assembler will always pick the shortest form of addressing consistent with the instruction format. if the absolute address is not known to the assembler on pass one (that is, the address is a forward or external reference), then the assembler will pick the long form of addressing by default. if this is not desired, then the short absolute form of addressing can be forced by preceding the absolute address by the short addressing mode force operator ( < ). see also: force example: since the symbol datast is a forward reference in the following sequence of source lines, the assembler would pick the long absolute form of addressing by default: move d0.l,y:datast datast equ y:$23 because the long absolute addressing mode would cause the instruction to be two words long instead of one word for the short absolute addressing mode, it would be desirable to force the short absolute addressing mode as shown below: move d0.l,y: < datast datast equ y:$23 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-21 > long addressing mode force operator many dsp instructions allow a long form of addressing. if the value of an absolute ad- dress is known to the assembler on pass one, then the assembler will always pick the shortest form of addressing consistent with the instruction format, unless the force long directive is active. if this is not desired, then the long absolute form of addressing can be forced by preceding the absolute address by the long addressing mode force op- erator ( > ). see also: force example: since the symbol datast is a not a forward reference in the following sequence of source lines, the assembler would pick the short absolute form of addressing: datast equ y:$23 move d0.l,y:datast if this is not desirable, then the long absolute addressing mode can be forced as shown below: datast equ y:$23 move d0.l,y: > datast f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-22 dsp assembler reference manual motorola # immediate addressing mode the pound sign ( # ) is used to indicate to the assembler to use the immediate addressing mode. example: cnst equ $5 move # cnst,d0.l f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-23 #< immediate short addressing mode force operator many dsp instructions allow a short immediate form of addressing. if the immediate data is known to the assembler on pass one (not a forward or external reference), or the force short directive is active, then the assembler will always pick the shortest form of immediate addressing consistent with the instruction. if the immediate data is a forward or external reference, then the assembler will pick the long form of immediate addressing by default. if this is not desired, then the short form of addressing can be forced using the immediate short addressing mode force operator ( #< ). see also: force example: in the following sequence of source lines, the symbol cnst is not known to the assembler on pass one, and therefore, the assembler would use the long immediate addressing form for the move instruction. move #cnst,d0.l cnst equ $5 because the long immediate addressing mode makes the instruction two words long in- stead of one word for the immediate short addressing mode, it may be desirable to force the immediate short addressing mode as shown below: move #< cnst,d0.l cnst equ $5 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-24 dsp assembler reference manual motorola #> immediate long addressing mode force operator many dsp instructions allow a long immediate form of addressing. if the immediate data is known to the assembler on pass one (not a forward or external reference), then the as- sembler will always pick the shortest form of immediate addressing consistent with the in- struction, unless the force long directive is active. if this is not desired, then the long form of addressing can be forced using the immediate long addressing mode force oper- ator ( #> ). see also: force example: in the following sequence of source lines, the symbol cnst is known to the assembler on pass one, and therefore, the assembler would use the short immediate addressing form for the move instruction. cnst equ $5 move #cnst,d0.l if this is not desirable, then the long immediate form of addressing can be forced as shown below: cnst equ $5 move #> cnst,d0.l f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-25 baddr set buffer address baddr < m | r >, the baddr directive sets the runtime location counter to the address of a buffer of the given type, the length of which in words is equal to the value of . the buffer type may be either m odulo or r everse-carry. if the runtime location counter is not zero, this directive first advances the runtime location counter to a base address that is a mul- tiple of 2 k , where 2 k >= . an error will be issued if there is insufficient memory remaining to establish a valid base address. unlike other buffer allocation directives, the runtime location counter is not advanced by the value of the integer expression in the op- erand field; the location counter remains at the buffer base address. the block of memory intended for the buffer is not initialized to any value. the result of may have any memory space attribute but must be an abso- lute integer greater than zero and cannot contain any forward references (symbols that have not yet been defined). if a m odulo buffer is specified, the expression must fall within the range 2 <= <= m , where m is the maximum address of the target dsp. if a r everse-carry buffer is designated and is not a power of two a warning will be issued. a label is not allowed with this directive. see also: bsm , bsb , buffer , dsm , dsr example: org x:$100 m_buf baddr m,24 ; circular buffer mod 24 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-26 dsp assembler reference manual motorola bsb block storage bit-reverse [] bsb [,] the bsb directive causes the assembler to allocate and initialize a block of words for a reverse-carry buffer. the number of words in the block is given by the first expression, which must evaluate to an absolute integer. each word is assigned the initial value of the second expression. if there is no second expression, an initial value of zero is assumed. if the runtime location counter is not zero, this directive first advances the runtime location counter to a base address that is a multiple of 2 k , where 2 k is greater than or equal to the value of the first expression. an error will occur if the first expression contains symbols that are not yet defined (forward references) or if the expression has a value of less than or equal to zero. also, if the first expression is not a power of two a warning will be gener- ated. both expressions can have any memory space attribute. , if present, will be assigned the value of the runtime location counter after a valid base address has been established. only one word of object code will be shown on the listing, regardless of how large the first expression is. however, the runtime location counter will be advanced by the number of words generated. see also: bsc , bsm , dc example: buffer bsb bufsiz ; initialize buffer to zeros f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-27 bsc block storage of constant [] bsc [,] the bsc directive causes the assembler to allocate and initialize a block of words. the number of words in the block is given by the first expression, which must evaluate to an absolute integer. each word is assigned the initial value of the second expression. if there is no second expression, an initial value of zero is assumed. if the first expression contains symbols that are not yet defined (forward references) or if the expression has a value of less than or equal to zero, an error will be generated. both expressions can have any memory space attribute. , if present, will be assigned the value of the runtime location counter at the start of the directive processing. only one word of object code will be shown on the listing, regardless of how large the first expression is. however, the runtime location counter will be advanced by the number of words generated. see also: bsm , bsb , dc example: unused bsc $2fff- @ lcv(r),$ffffffff ; fill unused eprom f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-28 dsp assembler reference manual motorola bsm block storage modulo [] bsm [,] the bsm directive causes the assembler to allocate and initialize a block of words for a modulo buffer. the number of words in the block is given by the first expression, which must evaluate to an absolute integer. each word is assigned the initial value of the second expression. if there is no second expression, an initial value of zero is assumed. if the runtime location counter is not zero, this directive first advances the runtime location counter to a base address that is a multiple of 2 k , where 2 k is greater than or equal to the value of the first expression. an error will occur if the first expression contains symbols that are not yet defined (forward references), has a value of less than or equal to zero, or falls outside the range 2 <= <= m , where m is the maximum address of the target dsp. both expressions can have any memory space attribute. , if present, will be assigned the value of the runtime location counter after a valid base address has been established. only one word of object code will be shown on the listing, regardless of how large the first expression is. however, the runtime location counter will be advanced by the number of words generated. see also: bsc , bsb , dc example: buffer bsm bufsiz,$ffffffff ; initialize buffer to all ones f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-29 buffer start buffer buffer < m | r >, the buffer directive indicates the start of a buffer of the given type. data is allocated for the buffer until an endbuf directive is encountered. instructions and most data def- inition directives may appear between the buffer and endbuf pair, although buff- er directives may not be nested and certain types of directives such as mode , org , section , and other buffer allocation directives may not be used. the rep- resents the buffer size. if less data is allocated than the size of the buffer, the remaining buffer locations will be uninitialized. if more data is allocated than the specified size of the buffer, an error is issued. the buffer directive sets the runtime location counter to the address of a buffer of the given type, the length of which in words is equal to the value of . the buffer type may be either m odulo or r everse-carry. if the runtime location counter is not zero, this directive first advances the runtime location counter to a base address that is a mul- tiple of 2 k , where 2 k >= . an error will be issued if there is insufficient memory remaining to establish a valid base address. unlike other buffer allocation directives, the runtime location counter is not advanced by the value of the integer expression in the op- erand field; the location counter remains at the buffer base address. the result of may have any memory space attribute but must be an abso- lute integer greater than zero and cannot contain any forward references (symbols that have not yet been defined). if a m odulo buffer is specified, the expression must fall within the range 2 <= <= m , where m is the maximum address of the target dsp. if a r everse-carry buffer is designated and is not a power of two a warning will be issued. a label is not allowed with this directive. see also: baddr , bsm , bsb , dsm , dsr , endbuf example: org x:$100 buffer m,24 ; circular buffer mod 24 m_buf dc 0.5,0.5,0.5,0.5 ds 20 ; remainder uninitialized endbuf f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-30 dsp assembler reference manual motorola cobj comment object file cobj the cobj directive is used to place a comment in the object code file. the will be put in the object file as a comment (refer to the object format description in appendix e). a label is not allowed with this directive. see also: ident example: cobj 'start of filter coefficients' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-31 comment start comment lines comment . . the comment directive is used to define one or more lines as comments. the first non- blank character after the comment directive is the comment delimiter. the two delimit- ers are used to define the comment text. the line containing the second comment delim- iter will be considered the last line of the comment. the comment text can include any printable characters and the comment text will be reproduced in the source listing as it ap- pears in the source file. a label is not allowed with this directive. example: comment + this is a one line comment + comment * this is a multiple line comment. any number of lines can be placed between the two delimiters. * f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-32 dsp assembler reference manual motorola dc define constant [] dc [,,...,] the dc directive allocates and initializes a word of memory for each argument. may be a numeric constant, a single or multiple character string constant, a symbol, or an expression. the dc directive may have one or more arguments separated by com- mas. multiple arguments are stored in successive address locations. if multiple argu- ments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. if the dc directive is used in l memory, the arguments will be evaluated and stored as long word quantities. other- wise, an error will occur if the evaluated argument value is too large to represent in a sin- gle dsp word. , if present, will be assigned the value of the runtime location counter at the start of the directive processing. integer arguments are stored as is; floating point numbers are converted to binary values. single and multiple character strings are handled in the following manner: 1. single character strings are stored in a word whose lower seven bits repre- sent the ascii value of the character. example: 'r' = $000052 2. multiple character strings represent words whose bytes are composed of concatenated sequences of the ascii representation of the characters in the string (unless the nops option is specified; see the opt directive). if the number of characters is not an even multiple of the number of bytes per dsp word, then the last word will have the remaining characters left aligned and the rest of the word will be zero-filled. if the nops option is given, each character in the string is stored in a word whose lower seven bits represent the ascii value of the character. example: 'abcd' = $414243 $440000 see also: bsc , dcb example: table dc 1426,253,$2662,'abcd' chars dc 'a','b','c','d' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-33 dcb define constant byte [] dcb [,,...,] the dcb directive allocates and initializes a byte of memory for each argument. may be a byte integer constant, a single or multiple character string constant, a symbol, or a byte expression. the dcb directive may have one or more arguments sep- arated by commas. multiple arguments are stored in successive byte locations. if multi- ple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding byte location will be filled with zeros. , if present, will be assigned the value of the runtime location counter at the start of the directive processing. integer arguments are stored as is, but must be byte values (e.g. within the range 0-255); floating point numbers are not allowed. single and multiple character strings are handled in the following manner: 1. single character strings are stored in a word whose lower seven bits repre- sent the ascii value of the character. example: 'r' = $000052 2. multiple character strings represent words whose bytes are composed of concatenated sequences of the ascii representation of the characters in the string (unless the nops option is specified; see the opt directive). if the number of characters is not an even multiple of the number of bytes per dsp word, then the last word will have the remaining characters left aligned and the rest of the word will be zero-filled. if the nops option is given, each character in the string is stored in a word whose lower seven bits represent the ascii value of the character. example: 'ab',,'cd' = $414200 $434400 see also: bsc , dc example: table dcb 'two',0,'strings',0 chars dcb 'a','b','c','d' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-34 dsp assembler reference manual motorola define define substitution string define the define directive is used to define substitution strings that will be used on all follow- ing source lines. all succeeding lines will be searched for an occurrence of , which will be replaced by . this directive is useful for providing better documen- tation in the source program. must adhere to the restrictions for non-local la- bels. that is, it cannot exceed 512 characters, the first of which must be alphabetic, and the remainder of which must be either alphanumeric or the underscore(_). a warning will result if a new definition of a previously defined symbol is attempted. the assembler out- put listing will show lines after the define directive has been applied and therefore rede- fined symbols will be replaced by their substitution strings (unless the nodxl option in effect; see the opt directive). macros represent a special case. define directive translations will be applied to the macro definition as it is encountered. when the macro is expanded any active define directive translations will again be applied. define directive symbols that are defined within a section will only apply to that section. see the section directive. a label is not allowed with this directive. see also: undef example: if the following define directive occurred in the first part of the source program: define arraysiz '10 * samplsiz' then the source line below: ds arraysiz would be transformed by the assembler to the following: ds 10 * samplsiz f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-35 ds define storage [] ds the ds directive reserves a block of memory the length of which in words is equal to the value of . this directive causes the runtime location counter to be advanced by the value of the absolute integer expression in the operand field. can have any memory space attribute. the block of memory reserved is not initialized to any value. the expression must be an integer greater than zero and cannot contain any for- ward references (symbols that have not yet been defined). , if present, will be assigned the value of the runtime location counter at the start of the directive processing. see also: dsm , dsr example: s_buf ds 12 ; sample buffer f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-36 dsp assembler reference manual motorola dsm define modulo storage [] dsm the dsm directive reserves a block of memory the length of which in words is equal to the value of . if the runtime location counter is not zero, this directive first advances the runtime location counter to a base address that is a multiple of 2 k , where 2 k >= . an error will be issued if there is insufficient memory remaining to es- tablish a valid base address. next the runtime location counter is advanced by the value of the integer expression in the operand field. can have any memory space attribute. the block of memory reserved is not initialized to any given value. the result of must be an absolute integer greater than zero and cannot contain any for- ward references (symbols that have not yet been defined). the expression also must fall within the range 2 <= <= m , where m is the maximum address of the target dsp. , if present, will be assigned the value of the runtime location counter after a valid base address has been established. see also: ds , dsr example: org x:$100 m_buf dsm 24 ; circular buffer mod 24 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-37 dsr define reverse carry storage [] dsr the dsr directive reserves a block of memory the length of which in words is equal to the value of . if the runtime location counter is not zero, this directive first ad- vances the runtime location counter to a base address that is a multiple of 2 k , where 2 k >= . an error will be issued if there is insufficient memory remaining to establish a valid base address. next the runtime location counter is advanced by the value of the integer expression in the operand field. can have any memory space attribute. the block of memory reserved is not initialized to any given value. the result of must be an absolute integer greater than zero and cannot contain any for- ward references (symbols that have not yet been defined). since the dsr directive is use- ful mainly for generating fft buffers, if is not a power of two a warning will be generated. , if present, will be assigned the value of the runtime location counter after a valid base address has been established. see also: ds , dsm example: org x:$100 r_buf dsr 8 ; reverse carry buffer for 16 point fft f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-38 dsp assembler reference manual motorola dup duplicate sequence of source lines [] dup . . endm the sequence of source lines between the dup and endm directives will be duplicated by the number specified by the integer . can have any mem- ory space attribute. if the expression evaluates to a number less than or equal to 0, the sequence of lines will not be included in the assembler output. the expression result must be an absolute integer and cannot contain any forward references (symbols that have not already been defined). the dup directive may be nested to any level. , if present, will be assigned the value of the runtime location counter at the start of the dup directive processing. see also: dupa , dupc , dupf , endm , macro example: the sequence of source input statements, count set 3 dup count ; asr by count asr d0 endm would generate the following in the source listing: count set 3 dup count ; asr by count asr d0 asr d0 asr d0 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-39 note that the lines dup count ;asr by count endm will only be shown on the source listing if the md option is enabled. the lines asr d0 asr d0 asr d0 will only be shown on the source listing if the mex option is enabled. see the opt directive in this chapter for more information on the md and mex options. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-40 dsp assembler reference manual motorola dupa duplicate sequence with arguments [] dupa ,[<,,...,] . . endm the block of source statements defined by the dupa and endm directives will be repeat- ed for each argument. for each repetition, every occurrence of the dummy parameter within the block is replaced with each succeeding argument string. if the argument string is a null, then the block is repeated with each occurrence of the dummy parameter re- moved. if an argument includes an embedded blank or other assembler-significant char- acter, it must be enclosed with single quotes. , if present, will be assigned the value of the runtime location counter at the start of the dupa directive processing. see also: dup , dupc , dupf , endm , macro example: if the input source file contained the following statements, dupa value,12,32,34 dc value endm then the assembled source listing would show dupa value,12,32,34 dc 12 dc 32 dc 34 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-41 note that the lines dupa value,12,32,34 endm will only be shown on the source listing if the md option is enabled. the lines dc 12 dc 32 dc 34 will only be shown on the source listing if the mex option is enabled. see the opt directive in this chapter for more information on the md and mex options. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-42 dsp assembler reference manual motorola dupc duplicate sequence with characters [] dupc , . . endm the block of source statements defined by the dupc and endm directives will be repeat- ed for each character of . for each repetition, every occurrence of the dummy parameter within the block is replaced with each succeeding character in the string. if the string is null, then the block is skipped. , if present, will be assigned the value of the runtime location counter at the start of the dupc directive processing. see also: dup , dupa , dupf , endm , macro example: if input source file contained the following statements, dupc value,'123' dc value endm then the assembled source listing would show: dupc value,'123' dc 1 dc 2 dc 3 endm note that the lines dupc value,'123' endm will only be shown on the source listing if the md option is enabled. the lines dc 1 dc 2 dc 3 will only be shown on the source listing if the mex option is enabled. see the opt directive in this chapter for more information on the md and mex options. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-43 dupf duplicate sequence in loop [] dupf ,[],[,] . . endm the block of source statements defined by the dupf and endm directives will be repeat- ed in general ( - ) + 1 times when is 1. is the starting value for the loop index; represents the final value. is the increment for the loop index; it defaults to 1 if omitted (as does the value). the parameter holds the loop index value and may be used within the body of instructions. , if present, will be assigned the value of the runtime location counter at the start of the dupf directive processing. see also: dup , dupa , dupc , endm , macro example: if input source file contained the following statements, dupf num,0,7 move #0,r\num endm then the assembled source listing would show: dupf num,0,7 move #0,r0 move #0,r1 move #0,r2 move #0,r3 move #0,r4 move #0,r5 move #0,r6 move #0,r7 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-44 dsp assembler reference manual motorola note that the lines dupf num,0,7 endm will only be shown on the source listing if the md option is enabled. the lines move #0,r0 move #0,r1 move #0,r2 move #0,r3 move #0,r4 move #0,r5 move #0,r6 move #0,r7 will only be shown on the source listing if the mex option is enabled. see the opt directive in this chapter for more information on the md and mex options. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-45 end end of source program end [] the optional end directive indicates that the logical end of the source program has been encountered. any statements following the end directive are ignored. the optional ex- pression in the operand field can be used to specify the starting execution address of the program. may be absolute or relocatable, but must have a memory space attribute of p rogram or n one. the end directive cannot be used in a macro expansion. a label is not allowed with this directive. example: end begin ; begin is the starting execution address f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-46 dsp assembler reference manual motorola endbuf end buffer endbuf the endbuf directive is used to signify the end of a buffer block. the runtime location counter will remain just beyond the end of the buffer when the endbuf directive is en- countered. a label is not allowed with this directive. see also: buffer example: org x:$100 buf buffer r,64 ; uninitialized reverse-carry buffer endbuf f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-47 endif end of conditional assembly endif the endif directive is used to signify the end of the current level of conditional assembly. conditional assembly directives can be nested to any level, but the endif directive al- ways refers to the most previous if directive. a label is not allowed with this directive. see also: if example: if @rel() savepc set * ; save current program counter endif f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-48 dsp assembler reference manual motorola endm end of macro definition endm every macro , dup , dupa , and dupc directive must be terminated by an endm direc- tive. a label is not allowed with this directive. see also: dup , dupa , dupc , macro example: swap_sym macro reg1,reg ;swap reg1,reg2 using d4.l as temp move r\?reg1,d4.l move r\?reg2,r\?reg1 move d4.l,r\?reg2 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-49 endsec end section endsec every section directive must be terminated by an endsec directive. a label is not allowed with this directive. see also: section example: section coeff org y: values bsc $100 ; initialize to zero endsec f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-50 dsp assembler reference manual motorola equ equate symbol to a value equ [{ x: | y: | l: | p: | e: }] the equ directive assigns the value and memory space attribute of to the symbol . if has a memory space attribute of n one, then it can op- tionally be preceded by any of the indicated memory space qualifiers to force a memory space attribute. an error will occur if the expression has a memory space attribute other than n one and it is different than the forcing memory space attribute. the optional forcing memory space attribute is useful to assign a memory space attribute to an expression that consists only of constants but is intended to refer to a fixed address in a memory space. the equ directive is one of the directives that assigns a value other than the program counter to the label. the label cannot be redefined anywhere else in the program (or sec- tion, if section directives are being used). the may be relative or abso- lute, but cannot include a symbol that is not yet defined (no forward references are allowed). see also: set example: a_d_port equ x: $4000 this would assign the value $4000 with a memory space attribute of x to the symbol a_d_port. compute equ @ lcv(l) @lcv(l) is used to refer to the value and memory space attribute of the load location counter. this value and memory space attribute would be assigned to the symbol com- pute. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-51 exitm exit macro exitm the exitm directive will cause immediate termination of a macro expansion. it is useful when used with the conditional assembly directive if to terminate macro expansion when error conditions are detected. a label is not allowed with this directive. see also: dup , dupa , dupc , macro example: calc macro xval,yval if xval<0 fail 'macro parameter value out of range' exitm ; exit macro endif . . . endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-52 dsp assembler reference manual motorola fail programmer generated error fail [{|}[,{|},...,{|}]] the fail directive will cause an error message to be output by the assembler. the total error count will be incremented as with any other error. the fail directive is normally used in conjunction with conditional assembly directives for exceptional condition check- ing. the assembly proceeds normally after the error has been printed. an arbitrary num- ber of strings and expressions, in any order but separated by commas with no intervening white space, can be specified optionally to describe the nature of the generated error. a label is not allowed with this directive. see also: msg , warn example: fail 'parameter out of range' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-53 force set operand forcing mode force {short | long | none} the force directive causes the assembler to force all immediate, memory, and address operands to the specified mode as if an explicit forcing operator were used. note that if a relocatable operand value forced short is determined to be too large for the instruction word, an error will occur at link time, not during assembly. explicit forcing operators over- ride the effect of this directive. a label is not allowed with this directive. see also: < , > , #< , #> example: force short ; force operands short f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-54 dsp assembler reference manual motorola global global section symbol declaration global [,,...,] the global directive is used to specify that the list of symbols is defined within the cur- rent section, and that those definitions should be accessible by all sections. this directive is only valid if used within a program block bounded by the section and endsec di- rectives. if the symbols that appear in the operand field are not defined in the section, an error will be generated. a label is not allowed with this directive. see also: section , xdef , xref example: section io global loopa ; loopa will be globally accessible by other sections . . . endsec f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-55 gset set global symbol to a value gset gset the gset directive is used to assign the value of the expression in the operand field to the label. the gset directive functions somewhat like the equ directive. however, labels defined via the gset directive can have their values redefined in another part of the pro- gram (but only through the use of another gset or set directive). the gset directive is useful for resetting a global set symbol within a section, where the set symbol would otherwise be considered local. the expression in the operand field of a gset must be absolute and cannot include a symbol that is not yet defined (no forward references are allowed). see also: equ , set example: count gset 0 ; initialize count f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-56 dsp assembler reference manual motorola himem set high memory bounds himem []:[,...] the himem directive establishes an absolute high memory bound for code and data gen- eration. corresponds to one of the dsp memory spaces ( x , y , l , p , e ). is one of the letters r for runtime counter or l for load counter. the is an absolute integer value within the address range of the machine. if during assembly the specified location counter exceeds the value given by , a warning is issued. a label is not allowed with this directive. see also: lomem example: himem xr:$7fff,yr:$7fff ; set x/y run high mem bounds f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-57 ident object code identification record [] ident , the ident directive is used to create an identification record for the object module. if is specified, it will be used as the module name. if is not specified, then the filename of the source input file is used as the module name. is the ver- sion number; is the revision number. the two expressions must each evaluate to an integer result. the comment field of the ident directive will also be passed on to the object module. see also: cobj example: if the following line was included in the source file, ffilter ident 1,2 ; fir filter module then the object module identification record would include the module name (ffilter), the version number (1), the revision number (2), and the comment field (; fir filter module). f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-58 dsp assembler reference manual motorola if conditional assembly directive if . . [ else ] (the else directive is optional) . . endif part of a program that is to be conditionally assembled must be bounded by an if - endif directive pair. if the optional else directive is not present, then the source statements following the if directive and up to the next endif directive will be included as part of the source file being assembled only if the has a nonzero result. if the has a value of zero, the source file will be assembled as if those statements be- tween the if and the endif directives were never encountered. if the else directive is present and has a nonzero result, then the statements between the if and else directives will be assembled, and the statements between the else and endif di- rectives will be skipped. alternatively, if has a value of zero, then the state- ments between the if and else directives will be skipped, and the statements between the else and endif directives will be assembled. the must have an absolute integer result and is considered true if it has a nonzero result. the is false only if it has a result of 0. because of the nature of the directive, must be known on pass one (no forward references al- lowed). if directives can be nested to any level. the else directive will always refer to the nearest previous if directive as will the endif directive. a label is not allowed with this directive. see also: endif example: if @lst>0 dup @lst ; unwind list directive stack nolist endm endif f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-59 include include secondary file include | <> this directive is inserted into the source program at any point where a secondary file is to be included in the source input stream. the string specifies the filename of the secondary file. the filename must be compatible with the operating system and can include a direc- tory specification. if no extension is given for the filename, a default extension of .asm is supplied. the file is searched for first in the current directory, unless the <> syntax is used, or in the directory specified in . if the file is not found, and the -i option was used on the command line that invoked the assembler, then the string specified with the -i op- tion is prefixed to and that directory is searched. if the <> syntax is given, the file is searched for only in the directories specified with the -i option. refer to chapter 1, running the assembler. a label is not allowed with this directive. see also: maclib example: include 'headers/io.asm' ; unix example include 'storage\mem.asm' ; ms-dos example include ; do not look in current directory f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-60 dsp assembler reference manual motorola list list the assembly list print the listing from this point on. the list directive will not be printed, but the subse- quent source lines will be output to the source listing. the default is to print the source listing. if the il option has been specified, the list directive has no effect when encoun- tered within the source program. the list directive actually increments a counter that is checked for a positive value and is symmetrical with respect to the nolist directive. note the following sequence: ; counter value currently 1 list ; counter value = 2 list ; counter value = 3 nolist ; counter value = 2 nolist ; counter value = 1 the listing still would not be disabled until another nolist directive was issued. a label is not allowed with this directive. see also: nolist , opt example: if liston list ; turn the listing back on endif f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-61 local local section symbol declaration local [,,...,] the local directive is used to specify that the list of symbols is defined within the current section, and that those definitions are explicitly local to that section. it is useful in cases where a symbol is used as a forward reference in a nested section where the enclosing section contains a like-named symbol. this directive is only valid if used within a program block bounded by the section and endsec directives. the local directive must ap- pear before is defined in the section. if the symbols that appear in the operand field are not defined in the section, an error will be generated. a label is not allowed with this directive. see also: section , xdef , xref example: section io local loopa ; loopa local to this section . . . endsec f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-62 dsp assembler reference manual motorola lomem set low memory bounds lomem []:[,...] the lomem directive establishes an absolute low memory bound for code and data gen- eration. corresponds to one of the dsp memory spaces ( x , y , l , p , e ). is one of the letters r for runtime counter or l for load counter. the is an absolute integer value within the address range of the machine. if during assembly the specified location counter falls below the value given by , a warning is issued. a label is not allowed with this directive. see also: himem example: lomem xr:$100,yr:$100 ; set x/y run low mem bounds f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-63 lstcol set listing field widths lstcol [[,[,[,[,[,[,]]]]]]] sets the width of the output fields in the source listing. widths are specified in terms of column positions. the starting position of any field is relative to its predecessor except for the label field, which always starts at the same position relative to page left margin, pro- gram counter value, and cycle count display. the widths may be expressed as any pos- itive absolute integer expression. however, if the width is not adequate to accommodate the contents of a field, the text is separated from the next field by at least one space. any field for which the default is desired may be null. a null field can be indicated by two adjacent commas with no intervening space or by omitting any trailing fields altogether. if the lstcol directive is given with no arguments all field widths are reset to their default values. a label is not allowed with this directive. see also: page example: lstcol 40,,,,,20,20 ; reset label, x, and y data field widths f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-64 dsp assembler reference manual motorola maclib macro library maclib this directive is used to specify the (as defined by the operating system) of a directory that contains macro definitions. each macro definition must be in a separate file, and the file must be named the same as the macro with the extension .asm added. for example, blockmv.asm would be a file that contained the definition of the macro called blockmv. if the assembler encounters a directive in the operation field that is not contained in the directive or mnemonic tables, the directory specified by will be searched for a file of the unknown name (with the .asm extension added). if such a file is found, the current source line will be saved, and the file will be opened for input as an include file. when the end of the file is encountered, the source line is restored and processing is re- sumed. because the source line is restored, the processed file must have a macro defi- nition of the unknown directive name, or else an error will result when the source line is restored and processed. however, the processed file is not limited to macro definitions, and can include any legal source code statements. multiple maclib directives may be given, in which case the assembler will search each directory in the order in which it is encountered. a label is not allowed with this directive. see also: include example: maclib 'macros\mymacs\' ; ibm pc example maclib 'fftlib/' ; unix example f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-65 macro macro definition macro [] . . . . endm the dummy argument list has the form: [[,,...,]] the required label is the symbol by which the macro will be called. if the macro is named the same as an existing assembler directive or mnemonic, a warning will be issued. this warning can be avoided with the rdirect directive. the definition of a macro consists of three parts: the header, which assigns a name to the macro and defines the dummy arguments; the body, which consists of prototype or skel- eton source statements; and the terminator. the header is the macro directive, its label, and the dummy argument list. the body contains the pattern of standard source state- ments. the terminator is the endm directive. the dummy arguments are symbolic names that the macro processor will replace with ar- guments when the macro is expanded (called). each dummy argument must obey the same rules as symbol names. dummy argument names that are preceded by an under- score are not allowed. within each of the three dummy argument fields, the dummy ar- guments are separated by commas. the dummy argument fields are separated by one or more blanks. macro definitions may be nested but the nested macro will not be defined until the primary macro is expanded. chapter 5 contains a complete description of macros. see also: dup , dupa , dupc , dupf , endm example: swap_sym macro reg1,reg2 ;swap reg1,reg2 using x0 as temp move r\?reg1,x0 move r\?reg2,r\?reg1 move x0,r\?reg2 endm f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-66 dsp assembler reference manual motorola mode change relocation mode mode causes the assembler to change to the designated operational mode. the mode direc- tive may be given at any time in the assembly source to alter the set of location counters used for section addressing. code generated while in absolute mode will be placed in memory at the location determined during assembly. relocatable code and data are based from the enclosing section start address. the mode directive has no effect when the command line -a option is issued. see chapter 4 for more information on modes, sec- tions, and relocation. a label is not allowed with this directive. see also: org example: mode abs ; change to absolute mode f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-67 msg programmer generated message msg [{|}[,{|},...,{|}]] the msg directive will cause a message to be output by the assembler. the error and warning counts will not be affected. the msg directive is normally used in conjunction with conditional assembly directives for informational purposes. the assembly proceeds normally after the message has been printed. an arbitrary number of strings and expres- sions, in any order but separated by commas with no intervening white space, can be specified optionally to describe the nature of the message. a label is not allowed with this directive. see also: fail , warn example: msg 'generating sine tables' f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives 6-68 dsp assembler reference manual motorola nolist stop assembly listing nolist do not print the listing from this point on (including the nolist directive). subsequent source lines will not be printed. the nolist directive actually decrements a counter that is checked for a positive value and is symmetrical with respect to the list directive. note the following sequence: ; counter value currently 1 list ; counter value = 2 list ; counter value = 3 nolist ; counter value = 2 nolist ; counter value = 1 the listing still would not be disabled until another nolist directive was issued. a label is not allowed with this directive. see also: list , opt example: if listoff nolist ; turn the listing off endif f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
assembler significant characters and directives assembler directives motorola dsp assembler reference manual 6-69 opt assembler options opt

	To Download DSPASMRM Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .