motorola digital signal processing development software motorola dsp linker/librarian reference manual motorola, incorporated semiconductor products sector dsp division 6501 william cannon drive west austin, tx, 78735-8598 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 . . .
,] requires the comma to be specified if the optional element is selected. preface 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 . . .
or a linker expression a numeric constant a string of ascii characters enclosed in quotes a delimiter character a linker option or a linker symbol supporting publications dsp56000 family manual. motorola, inc. 1992. dsp96002 users manual. motorola, inc. 1989. dsp56100 family manual. motorola, inc. 1993. dsp56300 family manual. motorola, inc. 1995. dsp56800 family manual. motorola, inc. 1996. motorola dsp simulator reference manual. motorola, inc. 1996. motorola dsp assembler reference manual. motorola, inc. 1996. 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 . . .
where: [options] any of the following command line options. these can be in any order, but must precede the list of source filenames. some options can be given more 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 . . .
] this option specifies that an object file is to be created for linker output. can be any legal operating system filename, including an optional pathname. a hyphen also may be used as an argument to indicate that the object file should be sent to the standard output. if a pathname is not specified, the file will be created in the current directory. if no filename is specified, or if the -b option is not present, the linker will use the basename (filename without extension) of the first filename encoun- tered in the input file list and append .cld to the basename. if the -i option is present (see below) an explicit filename must be given. this is because if the linker followed the default action it possibly could overwrite one of the existing input files. the -b option should be specified only once. if the file named in the -b option already exists, it will be overwritten. example: dsplnk -b filter.cld main.cln fft.cln fio.cln in this example, the files main.cln, fft.cln, and fio.cln are linked together to produce the absolute executable file filter.cld. -ea -ew these options allow the standard error output file to be reassigned on hosts that do not support error output redirection from the command line. must be present as an argument, but can be any legal operating system file- name, including an optional pathname. the -ea option causes the standard error stream to be written to ; if exists, the output stream is appended to the end of the file. the -ew option also writes the standard error stream to ; if exists it is rewound (truncated to zero), and the output stream is written from the be- 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 . . .
indicates that the linker should read command line input from . can be any legal operating system filename, including an optional pathname. is a text file containing further options, arguments, and filenames to be passed to the linker. the arguments in the file need be sep- arated only by some form of white space (blank, tab, newline). a semicolon ( ; ) on a line following white space makes the rest of the line a comment. the -f option was introduced to circumvent the problem of limited line lengths in some host system command interpreters. it may be used as often as desired, including within the argument file itself. command options may also be supplied using the dsplnkopt environment variable. see the dis- cussion of dsplnkopt under [options] at the beginning of this section. example: dsplnk -f opts.cmd invoke the linker and take command line options and input filenames from the command file opts.cmd. -g send source file line number information to the object file. the generated line number information can be used by debuggers to provide source-level debugging. example: dsplnk -b -g myprog.cln link the file myprog.cln and send source file line number infor- mation to the resulting object file myprog.cld. -i the linker ordinarily produces an absolute executable file as output. when the -i option is given the linker combines the input files into a single relocat- able object file suitable for reprocessing by the linker. no absolute ad- dresses are assigned and no errors are issued for unresolved external references. note that the -b option must be used when performing incre- 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 . . .
the linker ordinarily processes a list of input files which each contain a sin- gle relocatable code module. if the -l option is encountered the linker treats the following argument as a library file and searches the file for any outstanding unresolved references. if a module is found in the library that resolves an outstanding external ref- erence, the module is read from the library and included in the object file out- put. the linker continues to search a library until all external references are resolved or no more references can be satisfied within the current library. the linker searches a library only once, when it is encountered on the com- mand line. therefore, the position of the -l option on the command line is significant. example: dsplnk -b filter main fir -l io this example illustrates linking with a library. the files main.cln and fir.cln are combined with any needed modules in the library io.lib to create the file filter.cld. -m [] this option indicates that a map file is to be created. can be any legal operating system filename, including an optional pathname. a hyphen also may be used as an argument to indicate that the map file should be sent to the standard output. if a pathname is not specified, the file will be created in the current directory. if no filename is specified, the linker will use the basename (filename with- out extension) of the first filename encountered in the input file list and ap- pend .map to the basename. if the -m option is not specified, then the linker will not generate a map file. the -m option should be specified only once. if the file named in the -m option already exists, it will be over- written. example: dsplnk -m -- filter.cln gauss.cln in this example, the files filter.cln and gauss.cln are linked together to produce a map file. because no filename was given with the -m option, the output file will be named using the basename of the 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 . . .
[][]: by default the linker generates instructions and data for the output file be- ginning at absolute location zero for all dsp memory spaces. this option allows the programmer to redefine the start address for any memory space and associated location counter. is one of the single-character memory space identifiers (x, y, l, p). the letter may be upper or lower case. the optional is a letter indicat- ing the high ( h ) or low ( l ) location counters. if no counter is specified the default counter is used. is also optional and signifies the desired physical mapping for all relocatable code in the given memory space. it may be i for internal memory, e for external memory, r for rom, a for port a, and b for port b. if is not supplied, then no explicit mapping is pre- sumed. the is a hexadecimal number signifying the new relocation address for the given memory space. the -o option may be specified as many times as needed on the command line. this option has no effect if incremental linking is being done (see the -i option). example: dsplnk -ope:200 myprog -lmylib this will initialize the default p memory counter to hex 200 and map the program space to external memory. -p when the linker encounters input files, the current directory (or the directory given in the library specification) is first searched for the file. if it is not found and the -p option is specified, the linker prefixes the filename (and optional pathname) of the file specification with and searches the newly formed directory pathname for the 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 . . .
] this option indicates that a memory control file is to be read to determine the placement of sections in dsp memory and other linker control func- tions. can be any legal operating system filename, including an op- tional pathname. if a pathname is not specified, an attempt will be made to open the file in the current directory. if no filename is specified, the linker will use the base- name (filename without extension) of the first filename encountered in the link input file list and append .ctl to the basename. if the -r option is not specified, then the linker will not use a memory control file. the -r option should be specified only once. example: dsplnk -r proj filter.cln gauss.cln in this example, the files filter.cln and gauss.cln are linked together using the memory file proj.ctl. -u allows the declaration of an unresolved reference from the command line. must be specified. this option is useful for creating an undefined external reference in order to force linking entirely from a library. example: dsplnk -u start -l proj.lib declare the symbol start undefined so that it will be resolved by code within the library proj.lib. 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 . . .
[,,...,] the -x option provides for link time options that alter the standard operation of the linker. the options are described below (* means default). all op- tions may be preceded by no to reverse their meaning. the -x se- quence can be repeated for as many options as desired. option meaning abc* perform address bounds checking aec* check form of address expressions asc enable absolute section bounds checking csl cumulate section length data (see chapter 3, sizsym set size symbol) eso do not allocate memory below ordered sections ovlp warn on section overlap psb* preserve sign bit in twos-complement negative operands ro allow region overlap rsc* enable relative section bounds checking svo preserve object file on errors wex add warning count to exit status example: dsplnk -x wex filter.cln fft.cln fio.cln have the linker add the warning count to the exit status so that a project build will abort on warnings as well as errors. 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 . . .
a list of operating system compatible filenames (including optional path- names). if no extension is supplied for a given file, the linker first will at- tempt to open the file using the filename as supplied. if that is not successful the linker appends .cln to the filename and attempts to open the file again. if no pathname is specified for a given file, the linker will look for that file in the current directory. the list of files will be processed sequentially in the order given and all files will be used to generate the object file and map list- ing. for more details on linker operation in a particular machine environment see appendix g, host-dependent information, in the motorola dsp assembler 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 . . .
: memx = :.. attr = | scm = [][] sme = [][(exp)] spc = x|y|l|p ctr =l|h map = i|e|r|a|b exp = expression 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 . . .
[,...,] the balign directive auto-aligns circular buffers within a particular region. all relocat- able buffers found in any section within the region are relocated independently for optimal placement in memory. code and data around the buffer is made contiguous in order to fill in previously occupied space. the argument indicates where in memory the align- ment should begin. example: balign xe:$200,ye:$200 ; realign x and y external buffers 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 . . .
[,...,] the base directive indicates where to begin the location counter for the given memory region. this will be the base link address for all specified memory areas and all linked code and data within the region except for sections relocated absolutely via a memory file section directive. code and data not explicitly relocated will originate from this ad- dress. the base directive is analogous to the linker -o command line option. example: base xe:$200,ye:$200,pi:$200 ; set memory base addresses 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 . . .
[;] the ident directive functions similarly to the assembler ident directive by identifying the name, version number, and revision number of the absolute or incrementally linked output module. the information is sent to the resulting output file. the adheres to the rules for assembly language labels, so that it must begin with an alphabetic character and consist only of alphanumeric characters or the underscore up to a length of 255. the version number and revision number must be absolute expressions. if a com- ment follows the version and revision numbers it will be copied into the output file as well. example: ident mymodule 1 2 ; mymodule, version 1, revision 2 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 . . .
the include directive provides for insertion of separate files containing other linker control directives. file inclusion can be convenient for always including a set of master directives in several different configuration files. must be in quotes. example: include main.ctl ; include master control 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 . . .
[,[,[,[,]]]] the map page modifier works similarly to the assembler page directive, and causes the .map file to be printed on the page according to the parameters supplied. if no map page appears in the memory control file, the linker produces a map file with a column width of 80, a physical page length of 66 lines, and no blank lines at top and bottom. example: map page 132,,3,3 the above map page directive indicates a column width of 132, a physical page length of 66 lines (default), with three blank lines at the top and bottom of each page. 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 . . .
[, ,..., ] the map opt modifier determines the content of the output in the linker map file. the following map opt options are available: globmap - produce global map by memory space noconst - do not list symbols without a memory space attribute noglobsym - omit symbols from global map nolocal - do not list non-global symbols (e.g. symbols which are local to a section) nosecaddr - do not list sections by address nosecname - do not list sections by name nosymname - do not list symbols by name nosymval - do not list symbols by value nounused - do not list unused memory blocks if no map opt is found in the memory control file, the linker will list all symbols and sec- tions by name, address, and value. example: map opt noconst,nosymval the above map opt directive specifies no constants in the map listing and no symbols by value. 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 . . .
[,...,] the memory directive establishes a maximum high memory address for locating code and data in the given memory region. if the linker attempts to relocate a block beyond the address specified in the memory directive, an error will occur. this directive is use- ful for reflecting the true physical memory limits of the target system. example: memory pe:$1fff ; external program memory ends at hex 1fff 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 . . .
[[,...,]] . . . endr the region directive defines a region of memory in which to locate sections. the region name identifies the region. the optional parameter gives an absolute region size. the region directive is used in conjunction with existing control directives to specify a bounds for placing sections in memory. for example, a base directive used within a re- gion/endr pair defines the base address for that region only . likewise a memory di- rective within a region scope indicates the high address for the enclosing region. example: region internal_rom x:$256,y:$256 base x:0,y:0 ; base for internal_rom region only section buffers endr 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 . . .
[,...,] the reserve directive sets aside a block of memory which the linker will not use for relocation. the expression field in the parameter takes the form of a range n..m , where n is the low reserve address and m is the high reserve address. this directive can be used to protect rom locations, system code, or uninitialized buffer areas. example: reserve pi:$0..$1ff ; protect interrupt vectors 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 . . .
[,...,] the sbalign directive auto-aligns circular buffers within a named section. all relocat- able buffers found in the section are relocated independently for optimal placement in memory. code and data around the buffer is made contiguous in order to fill in previously occupied space. the argument indicates where in memory the alignment should begin. example: sbalign mysec xe:$200 ; realign x external buffers 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 . . .
[[,...,]] the secsize directive provides a mechanism for padding a section to a particular length despite its code or data content. the value field in the mem parameter is an expression which can either be an absolute size expressed as an integer, or a floating point value rep- resenting a percentage to pad. example: secsize padsec x:$1000,y:$1000 ; x and y absolute size secsize padsec p:150.0 ; increase size by one half 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 . . .
[[,...,]] the section directive either assigns a section of code or data to an absolute location in dsp memory, or implies an ordering if no address specification is present. the addresses serve as the base for the corresponding memory spaces and counters in the named sec- tion. any memory areas not indicated in the section directive are relocated relative to the global starting load address given by the -o command line option or the memory file base directive. if there is no -o option or base directive, unassigned areas are placed in memory relative to location zero. if the section directive appears with only a section name and no address, it means that the linker should locate this section in memory before handling any other default sec- tions. thus given a set of sections a, b, c, and d, if b and c were listed in section directives without a corresponding address, the linker would place b and c in memory before a and d. this provides a means for ordering sections in memory. example: section abs x:$2000,y:$2000 ; x and y absolute base section ord ; ordered 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 . . .
{ | } the set directive is a synonym for the symbol directive, described below. it is useful for sharing counter declaration files between the assembler and linker since the syntax is compatible. example: set pctr 5 ; set p memory counter number 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 . . .
:[] the sizsym directive makes it possible to declare an arbitrary symbol to hold section length data. this is useful when the programmer needs a cumulative section length for overlay handling. it is analogous to the symbol directive, in that the symbol so defined may be employed to resolve an external reference in a source file. if no section name is supplied the linker returns the length of all sections for the memory space and counter specified. ordinarily the linker retains length data only for relocatable sections; use csl (see -x option) to cumulate length data for absolute and buffer sections as well. note that sizsym symbols are valued after the memory control file is read, so that attempting to reference the symbol value within the memory control file itself may cause erroneous results. example: sizsym xlen x: ; assign length of x memory to xlen 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 . . .
the start directive gives an alternative start address to which the program will jump at runtime. this value is ordinarily given by the assembler end directive. the expression may consist of an absolute value or a global symbol whose value will be adjusted during link processing. example: start begin ; jump to location begin after loading 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 . . .
{ | } the symbol directive allows the programmer to specify a value for an otherwise unre- solved reference. the named symbol must not have been defined during link processing. the symbol is stored as an absolute global symbol. the symbol value may be either in- teger or floating point. if the value is an address it may contain a memory space reference and optionally a counter and mapping designation. example: symbol target x:$200 ; set target to hex 200 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 . . .
] [] where: [options] any one of the following command line options. the single option must pre- cede the library name. option letters may be specified in either upper or low- er case. if no option is supplied, the librarian operates as if the update ( -u ) option were given. 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 . . .
-ew these options allow the standard error output file to be reassigned on hosts that do not support error output redirection from the command line. must be present as an argument, but can be any legal operating system file- name, including an optional pathname. the -ea option causes the standard error stream to be written to ; if exists, the output stream is appended to the end of the file. the -ew option also writes the standard error stream to ; if exists it is rewound (truncated to zero), and the output stream is written from the be- ginning of the file. example: dsplib -ew errors -a fftlib fft16.cln fft512.cln ditfft.cln redirect the standard error output to the file errors. if the file al- ready exists, it will be overwritten. 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 . . .
indicates that the librarian should read command line input from . can be any legal operating system filename, including an optional pathname. is a text file containing module names to be passed to the librarian. the arguments in the file need be separated only by some form of white space (blank, tab, newline). a semicolon ( ; ) on a line following white space makes the rest of the line a comment. the -f option was introduced to circumvent the problem of limited line lengths in some host system command interpreters. example: dsplib -f opts.cmd invoke the librarian and take command line filenames from the com- mand file opts.cmd. -l list library contents. this option lists the module name as contained in the library header, the module size (less library overhead), and the date and time the file was stored into the library. the listing output is routed to stan- dard output so that it may be redirected to a file if desired. example: dsplib -l fftlib > fftlib.lst this example lists the contents of the library fftlib.lib. the output is redirected to the file fftlib.lst. -q on some hosts the librarian displays a banner on the console when invoked. this option inhibits the banner display. it has no effect on hosts where the signon banner is not displayed by default. example: dsplib -aq mylib.clb myprog.cln add the file myprog.cln to the library mylib.clb, but do not dis- play the signon banner. -r this option replaces the named modules in the given library. the modules must already be present in the library file. example: dsplib -r fftlib fft512.cln ditfft.cln this example replaces the files fft512.cln and ditfft.cln in the library fftlib.lib. 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 . . .
an operating system compatible filename (including optional pathname) specifying the library file to create or access. if no extension is supplied, the librarian will automatically append .lib to the filename. if no pathname is specified, the librarian will look for the library in the current directory. the librarian also has an interactive mode, where commands can be en- tered repeatedly without reloading the librarian program for each operation. if the librarian is invoked without arguments, it prompts for a command string. the interactive commands correspond to those given above, and the syntax is similar to that of the command line. because interactive input is taken from the standard input channel of the host environment, it is possible to create a batch of librarian commands and feed them to the program for execution via redirection. enter help or ? at the prompt for more information on the librarian interactive mode. a list of operating system compatible filenames separated by blanks. if no pathname is specified for a given file, the librarian will look for that file in the 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 . . .
where: [options] any of the following command line options. the options must precede the file names. option letters may be specified in either upper or lower case. 5.4 srec options -a use as the s-record address length. a value of 2 indicates a two- byte address and will generate s1 records. a value of 3 indicates a three- byte address and will generate s2 records. a value of 4 indicates a four- byte address and will generate s3 records. this option overrides any s- record address length implied by the processor type. address truncation 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 . . .
can ac- commodate. example: srec -a 4 prog the file prog.cld is translated to s-records using the s3-s7 record format. -b use byte addressing when transferring load addresses to s-record address- es. this means that object file start addresses are multiplied by the number of bytes per target dsp word and subsequent s1/s3 record addresses are computed based on the data byte count. example: srec -b prog in this example, the file prog.cld is translated to s-record format using byte addressing. the load addresses will be multiplied by the number of bytes per dsp word. a separate output file will be pro- duced for each dsp memory space (x, y, l, p, or e) represented in the input file. -l use double-word addressing when transferring load addresses from l space to s-record addresses. this means that object file records for l space data are moved unchanged and subsequent s1/s3 record addresses are computed based on the data word count divided by 2. this option should always be used when the object file contains sections in l memory space. example: srec -l filter.cld convert the file filter.cld into separate s-record files for each memory space in the object file. convert l space load addresses to long addresses in the s-record file. -m split each dsp word into bytes and store the bytes in parallel s-records. the -m and -s options are mutually exclusive. example: srec -m main for each memory space in the file main.cld create multiple s- record files that correspond to each byte in the target dsp word. for example, if main.cld contained only references to p memory and the target dsp is the dsp56000, then srec would produce the files main.p0, main.p1, and main.p2. 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 . . .
: add to s-record addresses in memory space. is one of the valid memory space specifiers: x, y, l, p, or e. must be given in hexadecimal. example: srec -o p:100 prog the file prog.cld is translated to s-record format with the value 100 hexadecimal added to all p memory addresses. -p assume object file format. this makes a difference in the type of s-type data records produced. is one of the motorola dsp pro- cessor numbers, e.g. 56000, 96000, etc. this option overrides the object file machine id. it is useful for handling object files from programs that do not generate target machine information. example: srec -p 56000 prog the file prog.cld is translated to s-record format with the assump- tion that the target processor is in the dsp56000 family of proces- sors. -q on some hosts srec displays a banner on the console when invoked. this option inhibits the banner display. it has no effect on hosts where the signon banner is not displayed by default. example: srec -q myprog.cld translate the file myprog.cld to s-record format but do not dis- play the signon banner on the console. -r write bytes high to low, rather than low to high. this option has no effect when used with the -m option. example: srec -r prog the file prog.cld is translated to s-record format with bytes writ- ten high to low. a separate output file will be produced for each dsp memory space (x, y, l, p, or e) represented in the input 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 . . .
use as the target word length. a value of 2 indicates a two-byte word length. a value of 3 indicates a three-byte word length. a value of 4 indi- cates a four-byte word length. this option overrides any target word length implied by the processor type, and therefore may lead to value padding or truncation. example: srec -t 4 prog the file prog.cld is translated to s-records using four-byte data words. -u write words high to low, rather than low to high when processing l memory data records. this option has no effect when used with the -x option. example: srec -u prog the file prog.cld is translated to s-record format with l memory words written high to low. a separate output file will be produced for each dsp memory space (x, y, l, p or e) represented in the input file. -w use word addressing when transferring load addresses to s-record ad- dresses. this means that object file start addresses are moved unchanged and subsequent s1/s3 record addresses are computed based on the data word count. example: srec -w main in this example, the file main.cld is translated to s-record format using word addressing. a separate output file will be produced for 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 . . .
a list of operating system compatible filenames separated by blanks. if no pathname is specified for a given file, srec will look for that file in the cur- rent directory. if the special character - is used as a filename srec will read from the standard input stream. the list of files will be processed se- quentially in the order given. 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 . . .
. where < basename > is the filename of the input object file without extension and is the memory space specifier (x, y, l, or p) for this set of data words. note that a separate file is created for each memory space encountered in the input file; thus the maximum number of output files in the default mode is 4. 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 . . .
.<#> where < basename > is the filename of the input object file without extension, < m > is the memory space specifier (x, y, l, p, or e) for this set of data words, and < # > is one of the digits 0, 1, or 2 corresponding to low, middle, and high bytes, respectively. note that a separate set of byte-wide files is created for each memory space encountered in the input file. thus the number of output files generated is (number of memory spaces in input * size of dsp word). the -s option writes all information to a single file, storing the memory space information in the address field of the s0 header record. the values stored in the address field and their correspondence to the dsp memory spaces are as follows: value dsp memory space 1x 2y 3l 4p 5e when the memory space changes in the object file section record, a new s0 header record is generated. the resulting output file is named .s , where motorola dsp s-record conversion utility (srec) s-record file format 5-8 dsp linker/librarian reference manual motorola name> is the filename of the input object file without extension. the -m and -s options are mutually exclusive. address fields in dsp section records are copied as is to the appropriate s1, s2, or s3 record. subsequent s1, s2, or s3 record addresses are byte incremented until a new sec- tion is encountered or end-of-file is reached. in some cases the starting s1/s2/s3 record address must be adjusted for byte addressing by multiplying the section start address by the number of bytes in a dsp word. when the -b option is given, any section address fields are adjusted to begin on a byte-multiple address. if the -w option is specified (the default) byte-incrementing is not done when generating s-record addresses, e.g. the s- record addresses are word-oriented rather than byte-oriented. the -b and -w options have no effect when used in conjunction with the -m mode, since in that case byte and word address mappings are 1:1. section records for l space memory contain words which are loaded into adjacent x and y memory locations. in these cases performing the default strict word addressing may be inappropriate. the -l option may be given to indicate that double-word addressing should be used to generate subsequent s1/s2/s3 addresses after the initial load address. in ad- dition the -l option should be used when doing byte addressing since the initial load ad- dresses must be adjusted to account for double-word addressing in the object file. in general, it is a good idea to use the -l option whenever the input object file contains sec- tions which refer to l memory space. 5.6 s-record file format an s-record file consists of a sequence of specially formatted ascii character strings. these character strings are made up of several fields which identify the record type, record length, memory address, code or data, and checksum. each byte of binary data is encoded as a 2-character hexadecimal number, the first character representing the high-order 4 bits, and the second the low-order 4 bits of the byte. 5.6.1 s-record content an s-record consists of 5 distinct fields: the type field, the record length , ad- dress field, code/data , and the checksum field. 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 . . .
where: [options] any of the following command line options. the options must precede the file name. option letters may be specified in either upper or lower case. if no option is supplied the entire input file is dumped. 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 . . .
this option specifies that a dump file is to be created for cofdmp output. can be any legal operating system filename, including an optional pathname. if the -d option is not specified, then the program will route dump output to the standard output (usually the console or terminal screen) by default. the -d option should be specified only once. if the file named in the -d option already exists, it will be overwritten. example: cofdmp -d filter.dmp filter.cld in this example, the absolute load file filter.cld will be dumped to the output file filter.dmp. -f dump the file header of the specified file. example: cofdmp -f fft16.cln in this example, the file header is listed from the relocatable object file fft16.cln. -h dump the section headers of the specified file. example: cofdmp -h fft16.cld in this example, the section headers are listed from the absolute ob- ject file fft16.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 . . .
a list of operating system compatible filenames. if no pathname is specified for a file, the program will look for that file in the current directory. an explicit filename must be provided; there is no default extension for the input file. 6.5 cofdmp processing the cofdmp program reads the input file and writes a formatted dump of the file con- tents to the standard output (unless the -d command line option is given). i/o redirection may be used to send the output to a file if the host operating system supports it. the program currently will not dump individual modules from library files; they must be ex- tracted and then dumped. also note that if the file has been stripped some information may no longer be available in the file, such as relocation information, line number entries, and symbol and string table data. the input file must be a motorola dsp coff object file, either absolute or relocatable. see appendix e in the motorola dsp assembler reference manual , motorola dsp object file format, for more information on motorola dsp coff object files. 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 . . .
already in library in an add operation a module with the same name as the one specified already ex- ists in the library. not in library the named module was not found in the specified library. this error can occur for example during a replace operation. ambiguous command the interactive command issued at the librarian prompt was not unique to the set of characters entered. cannot open module file the named module file could not be open. either the file does not exist or there was an i/o error. command requires library name all interactive commands require that the library name follow the command name on the input line. duplicate module name the same module name was entered twice on the command line. invalid command the librarian did not recognize an interactive command. 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 . . .
an error occurred while attempting to rename a library file. cannot save command file arguments the librarian could not obtain enough memory to store the module names given in the command line option file. cannot stat module the librarian could not obtain date and time information for the named 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 . . .
not altered this is an informative message indicating that the named library was not changed because of previous fatal errors. file i/o error an i/o error occurred while either reading or writing a file. improper module header format a module header in the library file has been corrupted, or the specified file is not a library file. library file already exists in a create operation the named library file already exists. missing command filename the required argument on a -f command line option was missing. out of memory - librarian aborted there is not enough internal memory to perform dynamic allocation. since the li- brarian stores all working information in memory, there is the possibility that mem- ory will be exhausted if many modules are processed in a single library operation. 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 . . .
