===================================== Recent Manual Updates for XLINK V4.XX ===================================== Updated: 25/Jan/2000 [Grzm] Release of XLINK 4.51P Archived: $Revision: 1.44 $ This document is a supplement to the XLINK Release Notes, XLINK.TXT, and contains recent changes to the XLINK manual. Each section or sub-section is marked with the XLINK version of its most recent change. No attempt is made to represent a history of changes in this file. It documents only the current state of affairs. If you are using XLINK in the Embedded Workbench integrated development environment, you may need a newer version of the Embedded Workbench for the relevant target in order to take full advantage of recently added features. ======== Contents ======== 1. [4.51J] Added Output Formats 2. [4.51P] IEEE-695 Details 3. [4.48J] XCOFF78K Details 4. [4.51M] Checksums and Fillers (-H -J -h) 5. [4.49C] Code Duplication (-K) 6. [4.48J] Pack Segments (-P) 7. [4.51F] Revised Segment Placement (-Z -P -b) 8. [4.51A] Expanded Segment Placement Range Syntax (-Z -P) 9. [4.51A] Function/Variable Level Linking 10. [4.51M] ELF details 11. [4.51D] Address Expressions 12. [4.51E] UBROF Versions 13. [4.51E] Address Translation (-M) 14. [4.51J] COFF Details 15. [4.51K] Scatter Loading (-Q) 16. [4.51N] Diagnostics Control (-w) E. [4.51K] New Errors W. [4.51E] New Warnings L. [4.51C] Log of Minor Changes ========================== 1. Added Output Formats ========================== When using the command line version of XLINK, the output format is selected with the -F command line option. In the Embedded Workbench it is selected on the XLINK Output Settings page. * 4.51J COFF XLINK can now generate COFF format output. See the COFF section of this document for more information about this format. * 4.51C ELF XLINK can now generate ELF format output with DWARF format debug information. See the ELF section of this document for more information about this format. * 4.51A IEEE695-M IEEE695-IS IEEE695-IE These three new output formats produce one output file in the IEEE-695 format and one in, respectively, the MOTOROLA, INTEL-STANDARD or INTEL-EXTENDED output format. If there is a need to supply format variant options for the second format, these can be added to the "-y" option after a comma. Example: -Fieee695-ie -ygbr,1 This will output an IEEE-695 file using the format variant "-ygbr" and an INTEL-EXTENDED file using the format variant "-y1" (or "-Y1"). * 4.49J AOMF80251 The output format AOMF80251 is an Intel object format for 80251 processors. XLINK follows the "Object Module Format 251 Specification" revision 1.7. * 4.51D UBROF UBROF5 UBROF6 UBROF7 UBROF8 The IAR Universal Binary Relocatable Object Format, UBROF, has been updated to version 8.0.0. This means that XLINK will now output UBROF 8 files when given UBROF 8 input. The UBROF format is used by IAR's C-SPY debugger and a number of other debuggers/emulators. The new version of the output format can, in addition to a number of other smaller improvements, result in a very significant reduction in the size of the output file. In conjunction with this several new output formats have been added to XLINK: -Fubrof5 Output UBROF 5 even if any input was UBROF 6 -Fubrof6 Output UBROF 6 even if no input was UBROF 6 -Fubrof7 Output UBROF 7 even if no input was UBROF 7 -Fubrof8 Output UBROF 8 even if no input was UBROF 8 -Fubrof Output UBROF (a synonym for -Fdebug) If you are using a debugger/emulator that reads UBROF and the output file cannot be loaded, a new format version could be the cause. In that case try using one of the -FubrofX variants or contact the supplier of your debugger/emulator. Also be sure to check the compiler release notes for any pertinent information on this issue. * 4.49A SIMPLE The SIMPLE output format is a very simple binary output format. Source code for a SIMPLE reader is provided to make it easy to handle particular output requirements at a customer site. See the SIMPLE subdirectory. * 4.48J IEEE695 The output format IEEE-695 is supported only for certain combinations of processors and debuggers/emulators. See the IEEE-695 section of this document for more information about this and other issues regarding the IEEE-695 format. * 4.48B XCOFF78K The output format xcoff78k is a NEC proprietary format and is supported only for the NEC 78k series of processors. See the xcoff78k section of this document for more information about this format. * 4.48F MSP430_TXT The output format msp430_txt is a simple output format used in Texas Instruments Starter Kits. ====================== 2. IEEE-695 Details ====================== * 4.51A Format Variant Modifiers. XLINK supports a number of format variant modifiers that govern particular subtleties in the IEEE-695 output format through the use of the -y command line option. Combinations of format variant modifiers can be used by specifying more than one flag character in a single -y command line option. For example, -ygl makes XLINK output global types both globally and in each module. The available format variant modifiers for IEEE-695 are: -yg Output global types globally Output globally visible types in a BB2 block at the beginning of the output file. -yl Output global types in each module Output the globally visible types in a BB1 block at the beginning of each module in the output file. -yb Treat bit sections as byte sections XLINK supports the use of IEEE-695 'based variables' to represent bit variables, and the use of bit addresses for bit-addressable sections. Turning on this modifier makes XLINK treat these as if they were byte variables/sections. -ym Adjust output for Mitsubishi PDB30 debugger Turning on this modifier adjusts the output in some particular ways for the Mitsubishi PDB30 debugger. Note that you will need to use the 'l' and 'b' modifiers as well (-ylbm). -ye No block-local constants Using this modifier will cause XLINK to not emit any block-local constant in the output file. One way these can occur is if an enum is declared in a block. -yv Handle variable life times Use the 'variable life time' support in IEEE-695 to output more accurate debug information for variables whose location varies. -ys Output stack adjust records Output IEEE-695 'stack adjust' records to indicate the offset from the stack pointer of a virtual frame pointer. -ya Output module locals in BB10 block Output information about module local symbols in BB10 (assembler level) blocks as well as in the BB3 (high level) blocks, if any. -yr Last return refers to end of function Change the source line information for the last return statement in a function to refer to the last line of the function instead of the line it is on. -yd No #define constants Do not emit any '#define constant' records. This can sometimes drastically reduce the size of the output file. * 4.51P Recommended settings for some combinations of cpus and debuggers are: 6812 Noral debugger -ygvs 68HC16 Microtek debugger -ylb? 740 Mitsubishi PD38 -ylbma 7700 HP RTC debugger -ygbr 7700 Mitsubishi PD77 -ylbm H8300 HP RTC debugger -ygbr H8300H HP RTC debugger -ygbr H8S HP RTC debugger -ygbr M16C HP RTC debugger -ygbr M16C Mitsubishi PD30/PDB30/KDB30 -ylbm T900 Toshiba RTE900 m25 -ygbe T900 Toshiba RTE900 m15 -ygbed ====================== 3. XCOFF78K Details ====================== * 4.48J Format Variant Modifiers. XLINK supports a number of format variant modifiers that govern particular subtleties in the xcoff78k output format through the use of the -y command line option. Combinations of format variant modifiers can be used by specifying more than one flag character in a single -y command line option. For example, -ysp makes XLINK truncate symbols to 31 characters and strip source file paths. The available format variant modifiers for xcoff78k are: -ys Truncate symbols to 31 characters Symbols names longer than 31 characters will be truncated to be exactly 31 characters. Irrespective of the setting of this modifier, section names are always truncated to 7 characters if longer and module names are truncated to 31 characters. -yp Strip source file paths Strip the path, if any, from source file references, leaving only the name and the extension. -ye Include module enums Normally XLINK will not output module local constants in the xcoff78k file. The way IAR compilers currently work these include all #define constants as well as all SFRs. Turn on this modifier to get them included. -yl Hobble line number info When outputting debug information, ignore any source file line number references that are not in a strictly increasing order within a function. ====================================== 4. Checksums and Fillers (-H -J -h) ====================================== * 4.51G Filler Bytes The command line option "-H" can be used to generate filler bytes: -Hhexstring Fill all linker-introduced gaps between segment parts with the repeated hexstring. The linker can introduce gaps because of alignment restrictions, or to fill ranges given in segment placement options. The normal behavior, when no -H option is given, is that these gaps are not given a value in the output file. The ranges that are filled are all the ranges into which segments with any content (code or constant data bytes) are placed. For a more explicit way to specify which ranges are filled, see the explanation of -h below. Example: -HBEEF Fill all the gaps with the value 0xbeef. Even bytes will get the value 0xbe, and odd bytes will get the value 0xef. * 4.49A Checksum Generation The command line option "-J" can be used to generate a checksum in the linker image: -Jsize,algorithm[,complement] Checksum all generated raw data bytes. size can be one of: 1 One byte of checksum 2 Two bytes of checksum 4 Four bytes of checksum algorithm can be one of: sum Simple arithmetic sum crc16 CRC16 (generating polynomial 0x11021) crc32 CRC32 (generating polynomial 0x4C11DB7) crc=n CRC with a generating polynomial of n complement can be one of: 1 One's complement 2 Two's complement In all cases it is the least significant 1, 2 or 4 bytes of the result that will be output, in the natural byte order for the processor. The CRC checksum is calculated as if the following code was called for each bit in the input, augmented with size (1, 2 or 4) bytes of zeros, starting with a crc of 0: unsigned long crc(int bit, unsigned long oldcrc) { unsigned long newcrc = (oldcrc << 1) ^ bit; if (oldcrc & 0x80000000) newcrc ^= POLY; return newcrc; } POLY is the generating polynomial. The checksum is the result of the final call to this routine. If complement is given, the checksum is the one's or two's complement of the result. Note that the above routine is not a very time efficient way to calculate the checksum. See any text on crc calculation for faster ways. For checksums of size 2 or 1, the needed precision in the calculations will also be correspondingly lower. Also note that the checksum is calculated over the bytes in the input plus a number of zero bytes equal to the checksum size. The linker will place the checksum byte(s) at the label __checksum in the segment CHECKSUM. This segment must be placed using the segment placement options like any other segment. Example: -J4,crc32,1 Calculate a 4 byte checksum using the generating polynomial 0x4C11DB7 and output the one's complement of the calculated value. * 4.51M Fill ranges The command line option -h can be used to specify the ranges to fill. Normally, all ranges given in segment placement commands (-Z -P) into which any actual content (code or constant data) is placed are filled. For example: -Z(CODE)INTVEC=0-FF -Z(CODE)RCODE,CODE,CDATA0=0-7FFF,F800-FFFF -Z(DATA)IDATA0,UDATA0=8000-8FFF If INTVEC contains anything the range 0-FF will be filled. If RCODE, CODE or CDATA0 contains anything the ranges 0-7FFF and F800-FFFF will be filled. IDATA0 and UDATA0 are normally only place holders for variables, which means that the range 8000-8FFF will not be filled. The command line option -h can be used to explicitly specify which ranges to fill. Its syntax is: -h[()]{}+ That is, it can have an optional segment type (which can be used to specify address space for architectures with multiple address spaces) and one or more address ranges. For example: -h(CODE)0-FFFF or, equivalently, as segment type CODE is the default, -h0-FFFF This will cause the range 0-FFFF to be filled, regardless of what ranges are specified in segment placement commands. Under many circumstances the use of -h will not be needed. -h can be specified more than once, in order to specify fill ranges for more than one address space. -h does not currently restrict the ranges used for checksum calculation. This may change in a future revision. =========================== 5. Code Duplication (-K) =========================== * 4.49C A new option to do code duplication has been added: -Ksegments=increment,count Duplicate any raw data bytes from the segments `count' times, adding increment to the addresses each time. In order for this to be useful, the segments should likely be mentioned in a "-Z" segment placement option. The count can optionally be specified as '*', which means to duplicate the segments enough times to match the highest number of banks actually used in a bank segment placement option. This can be used to make part of a PROM be non-banked even though the entire PROM is physically banked. Use "-b" or "-P" to place the banked segments into the rest of the PROM. Example: -KRCODE0,RCODE1=20000,4 Duplicate the contents of the RCODE0 and RCODE1 segments 4 times, using addresses 0x20000 higher each time. This will place 5 copies of each of the bytes from the segments into the output file, at the addresses x, x+0x20000, x+0x40000, x+0x60000 and x+0x80000. ======================== 6. Pack Segments (-P) ======================== * 4.48J A new option "-P" is available, as a complement to "-Z" (segment definition) and "-b" (banked segment definition). It has the syntax: -P[(type)]segments=start-end[,start-end]... The linker attempts to pack the segment parts from the segments given in a "-P" option into the ranges given. In order to do this it splits each segment into its segment parts and forms new segments for each of the ranges. All the ranges have to be closed (have both a start and an end). The segment parts will not be placed in any specific order into the ranges. A segment part is the smallest linkable unit. Prior to UBROF 7 each module could have at most one segment part for a particular segment. Beginning with UBROF 7 a module can make several separate contributions to a segment. Attempting to get the start and end (using the SFB/SFE assembler operators) of a segment that has been split and reformed will not work. =============================== 7. Revised Segment Placement =============================== * 4.51F Segment placement is now both more convenient and more powerful while preserving compatibility with the old scheme. In the new scheme, -Z (sequential placement) and -P (packed placement) are the recommended segment placement command line options. -b (banked placement) is now deprecated, though it will likely stay around for a long time for compatibility reasons. -P now supports the functionality of -b in a more convenient and powerful fashion. Previously, the memory ranges given to segment placement options basically had to be disjunct, since each placement option would place segment in isolation from all other placement options (with the exception of bit memory placement). In the new scheme, all -Z and -P commands are considered in the order in which they were given, taking into account any memory occupied by previously placed segments, including segment duplication and anything placed at absolute addresses by the input files. This makes it possible to place segments with less rigorous requirements in what is left over from placing segments with more strict requirements. For example, if we have two segments (Z1, Z2) that must be placed in the zero page (0-FF) and three (A1, A2, A3) that can be placed anywhere in available RAM (0-1FFF), we can now place them like this: -Z(DATA)Z1,Z2=0-FF -Z(DATA)A1,A2,A3=0-1FFF This will place Z1 and Z2 from 0 up, giving an error if they do not fit into the range given, and then place A1, A2 and A3 from the first address not used by Z1 and Z2. -P differs from -Z in that it does not necessarily place the segments (or segment parts) sequentially. See above for more information about -P. With -P it is possible to put segment parts into holes left by earlier placements. Use -Z when you need to keep a segment in one consecutive chunk, when you need to preserve the order of segment parts in a segment, or, more unlikely, when you need to put segments in a specific order. There can be several reasons to do this, but most of them are fairly obscure. The most important is to keep variables and their initializers in the same order and in one block. Beginning with UBROF 7 the segments used for this have attributes that direct the linker to do the right thing, so -Z is no longer needed for these segments. Use -P when you need to put things into several ranges, for instance when doing banking. Bit segments are always placed first, regardless of where their placement commands are given. Placement into far memory (FAR, FARCODE, FARCONST segment types) is the odd man out. In the old scheme, -Z placed segment parts consecutively, moving a segment part past a 64K boundary if needed. In the new scheme, -Z places the segments that fit entirely into the first page and range sequentially, and then places the rest using a special variant of sequential placement that can move an individual segment part into the next range if it did not fit. This means, as before, that far segments can be split into several memory ranges, but it is guaranteed that a far segment has a well-defined start and end. ============================================= 8. Expanded Segment Placement Range Syntax ============================================= * 4.51A The syntax for address ranges in the -Z and -P segment placement command line options has been extended to make it more convenient to specify repeating ranges. 1) Ranges with a repeat count [SSS-EEE]*NNN+XXX This repeats the range SSS-EEE NNN times, adding XXX each repition. The +XXX part is optional, and defaults to the length of the range. For example: [1000-1FFF]*3+2000 is the same as 1000-1FFF,3000-3FFF,5000-5FFF and [1000-1FFF]*3 is the same as 1000-1FFF,2000-2FFF,3000-3FFF 2) Paged ranges [SSS-EEE]/PPP This is the entire range SSS-EEE, split into pages of size and alignment PPP. For example: [50-77F]/200 is the same as 50-1FF,200-3FF,400-5FF,600-77F Note that the start and end of the range do not have to coincide with a page boundary. All numbers in segment placement command line options are interpreted as hexadecimal unless preceded by a '.'. That is, the numbers written as "10" and by ".16" both mean the number sixteen. ===================================== 9. Function/Variable Level Linking ===================================== * 4.51A Linking now takes place in two steps. XLINK first does module level linking and then segment part level linking. Compilers/assemblers producing UBROF 7 or later can put individual functions/variables into separate segment parts, and can represent all dependencies between segment parts in the object file. This enables XLINK to exclude unneeded functions/variables from a build. Object files in UBROF 6 or earlier cannot represent this information and thus do not take advantage of the new feature. Module level linking starts by including all PROGRAM modules. Then enough LIBRARY modules are included so as to satisfy all external symbol references, if possible. When more than one LIBRARY module exports a certain symbol, preference is given to the module that is specified first on the command line. Segment part level linking then starts by including all ROOT segment parts in included modules, and then adds enough other segment parts to satisfy all dependencies. Dependencies are either references to external symbols defined in other modules or intra-module segment part references. ROOT segment parts are normally the root of the C runtime boot process and any interrupt vector elements. ================= 10. ELF details ================= * 4.51I Format Version XLINK output conforms to ELF as described in "Executable and Linkable Format (ELF)", and DWARF version 2, as described in "DWARF Debugging Information Format" revision 2.0.0 (July 27, 1993), both part of the Tools Interface Standard Portable Formats Specification, Version 1.1. * 4.51M Supported Targets The ELF format is currently supported for the 6811, 6812, 6816, SH and v850 target processors. * 4.51K Format Variant Modifiers The available format variant modifiers for ELF/DWARF are: -yn Suppress DWARF debug output Output an ELF file with no debug information. -yp Multiple Elf program sections Output one Elf program section for each segment, instead of one for all segments combined. As of version 4.51K of XLINK, ELF/DWARF format output includes module local symbols. The command line option -n can be used to suppress module local symbols in any output format. ========================= 11. Address Expressions ========================= * 4.51D Symbolic Addresses Addresses in command line options can now use symbolic values defined in earlier "-D" command line options. If the symbol can be confused with a (hexadecimal) number it must be enclosed in quote ("'") characters. Example: -Dfoo=1000 -Dfee=1FFF -Z(CODE)CODE=foo-'fee' The last line is equivalent to: -Z(CODE)CODE=1000-1FFF Note that the symbol "fee" must be quoted since "fee" is a legal hexadecimal number. * 4.51D Address Expressions Addresses in command line options can now be given as expressions. Expressions must be enclosed in parentheses. Available operators are binary "*", "/", "%", "+", "-", "<<", ">>", "&", "^" and "|", with the same priorities as in C. Parentheses can be used for sub-expressions. Example: -Dfoo=1000 -Dlen=1000 -Z(CODE)CODE=foo-(foo+len-1) The last line is equivalent to: -Z(CODE)CODE=1000-1FFF ==================== 12. UBROF versions ==================== * 4.51E UBROF UBROF, Universal Binary Relocatable Object Format, is an object format used by IAR's tools for both relocatable (into the linker) and absolute (out of the linker) object files. * 4.51E Brief History UBROF has evolved through a number of revisions. The latest version of UBROF is UBROF 8. 1986 UBROF 3 Assembler level linking. First release of this XLINK. 1988 UBROF 4 Adds C information - types, source info, etc. 1992 UBROF 5 Adds support for expanded set of IAR keywords. 1997 UBROF 6 Source references. More compact representation for files with many modules. Also adds detailed version info. 1998 UBROF 7 Further expanded type system for new generation of compilers. 1999 UBROF 8 Adds support for Embedded C++. * 4.51E Supported Versions XLINK reads all UBROF versions from UBROF 3 onwards, and can output all UBROF versions from UBROF 5 onwards. There is also support for outputting something called "Old UBROF" which is an early version of UBROF 5, close to UBROF 4. Normally XLINK outputs the same version of UBROF as used in its input files. More exactly, it uses the latest version found in the input files. If you have a debugger that does not support this version of UBROF, XLINK can be directed to use another version. This is done by using one of the command line options -Fubrof5 -Fubrof6 -Fubrof7 -Fubrof8 Old UBROF can be selected by using -Fdebug and the format variant option "-Y#". For IAR's debugger, C-SPY, this is not a problem, which means that the command line option -r, which apart from specifying UBROF output also selects C-SPY specific library modules from the IAR standard library, always uses the same UBROF version as found in the inputs. When XLINK outputs a version of UBROF that is earlier than the one used in its inputs there is almost always some form of debug information loss, though this can be minor if the input files do not make critical use of new features in the newer version of UBROF. This debug information loss can consist of some of the following items. For each version this list contains information that cannot be represented, or not fully represented, in earlier versions of UBROF. UBROF 5 Up to 16 memory keywords resulting in different pointer types and different function calling conventions. UBROF 6 Source in header files. Assembler source debug. UBROF 7 Support for up to 255 memory keywords. Support for target type and object attributes. Enum constants connected to enum types. Arrays with more than 65535 elements. Anonymous structs/unions. Slightly more expressive variable tracking info. UBROF 8 Embedded C++ object names. Added base types. Typedefs used in the actual types. Embedded C++ types: references and pointers to members. Class members. Target defined base types. In each case, XLINK attempts to convert the information to something that is representable in an earlier version of UBROF, but this conversion is, by necessity, incomplete and can cause inconsistencies. In many cases, though, notably when not much use is made of the new features, the conversion will result in something that is almost indistinguishable from the original as far as debugging is concerned. ========================= 13. Address Translation ========================= * 4.51E XLINK can now do logical to physical address translation on output for some output formats. Logical addresses are the addresses as seen by the program, and these are the addresses used in all other XLINK command line options. Normally these addresses are also used in the output object files, but by using a new command line option, "-M", a mapping from the logical addresses to physical addresses, as used in the output object file can be established. The syntax of the -M command line option is: -M[(segment_type)]logical_ranges=physical_ranges This is very similar to a segment placment command line option (-Z and -P), except that both logical_ranges and physical_ranges are lists of address ranges. Each occurrence of -M defines a linear mapping from a list of logical address ranges to a list of physical address ranges, in the order given, byte by byte. For example: -M0-FF,200-3FF=1000-11FF,1400-14FF will define a mapping logical addresses 000-0FF map to physical addresses 1000-10FF " " 200-2FF " " " 1100-11FF " " 300-3FF " " " 1400-14FF Several -M command line options can be given to establish a more complex mapping. Address Translation can be useful in banked systems. Assume a code bank at address 0x8000 of size 0x4000, replicated 4 times, occupying a single physical ROM. If we want all the banks using physically contiguous addresses in the output file, we can use: -P(CODE)BANKED=[8000-BFFF]*4+10000 // Place banked code -M(CODE)[8000-BFFF]*4+10000=10000 // Single ROM at 0x10000 This means that the new segment placement commands (-P, -Z) can now replace all uses of the old banked segment placement command (-b). The last significant remaining feature of -b to support was the limited address translation provided by -b@ and -b#. Address translation is a more general and more powerful replacement. Address translation only works for some output formats, primarily the simple formats with no debug information. This is the current list of supported output formats: aomf80196 aomf8051 aomf8096 ashling ashling-6301 ashling-64180 ashling-6801 ashling-8080 ashling-8085 ashling-z80 extended-tekhex hp-code intel-extended intel-standard millenium motorola mpds-symb pentica-a pentica-b pentica-c pentica-d rca symbolic ti7000 typed zax ================== 14. COFF Details ================== * 4.51J Supported Targets XLINK currently supports COFF output for the PIC target processor, tailored to work with the MPLAB debugger. MPLAB needs both an intel-hex file and a COD file. To convert the file from COFF to COD use the MP2COD program supplied in the Microchip MPLAB distribution. The way to use COFF output for Microchip MPLAB is to use the option -Fcoff to set the primary output format, and then add the option -Ointel-standard=.hex (or intel-extended) to the linker file to generate both formats at the same time. The ICCPIC linker files has the -O option added to produce intel-hex files by default. XLINK does not support debug info for include files, and for assembler files with multiple modules, may generate multiple instances of the source files in the absolute listing file produced by MP2COD. XLINK also generates a varying number of dummy files that will generate a warning from MP2COD that it cannot find the file specified. All these files have names beginning with $$. The warnings can safely be ignored. ========================== 15. Scatter Loading (-Q) ========================== * 4.51K XLINK can now do automatic setup for copy initialization of segments (scatter loading). The new command line option -Q uses the following syntax: -Qsegment=initializer_segment This will cause the linker to generate a new segment `initializer_segment' into which it will place all data content of the segment `segment'. Everything else, for instance symbols and debugging information, will still be associated with the segment `segment'. The intent is that startup code in the application will then at runtime copy the contents of `initializer_segment' (in ROM) to `segment' (in RAM). This is very similar to what compilers do for initialized variables and is primarily intended to be used for code that needs to be in RAM memory. The segment `initializer_segment' must be placed like any other segment using the segment placement commands. Here's an example. Assume that the code in the segment RAMCODE should be executed in RAM. Scatter loading can be used to make the linker transfer the contents of segment RAMCODE (which will be in RAM) into the (new) segment ROMCODE (which will be in ROM), like this: -QRAMCODE=ROMCODE Then RAMCODE and ROMCODE need to be placed, using the usual segment placement commands. RAMCODE needs to be placed in the relevant part of RAM, and ROMCODE in ROM. Something like this: -Z(DATA)RAM segments,RAMCODE,Other RAM segments=0-1FFF -Z(CODE)ROM segments,ROMCODE,Other ROM segments=4000-7FFF This will reserve room for the code in RAMCODE somewhere between address 0 and address 0x1FFF, the exact address depending on the size of other segments placed before it. Similarly, ROMCODE (which now contains all the original contents of RAMCODE) will be placed somewhere between 0x4000 and 0x7FFF, depending on the other stuff being placed into ROM. At some time before executing the first code in RAMCODE, the contents of ROMCODE will need to be copied into it. This can be done as part of the startup code (in CSTARTUP) or in some other part of the code. ============================== 16. Diagnostics Control (-w) ============================== * 4.51N Diagnostic IDs As the severity of diagnostic messages can now be changed, the identity of a particular diagnostic now includes its original severity as well as its number. That is, diagnostic messages will typically be output as: Warning[w6]: Type conflict for external/entry ... Error[e1]: Undefined external ... * 4.51N Severity Control for Diagnostics The -w option can now, in addition to its other uses, be used to change the severity of particular diagnostic messages using the following syntax: -w[=] is the id of a diagnostic message, which is the letter 'e' followed by an error number, the letter 'w' followed by a warning number, or just a warning number. is one of 'i, 'w' or 'e'. If omitted it defaults to 'i'. i Ignore this diagnostic. No diagnostic output. w Emit a warning for this diagnostic. e Emit an error for this diagnostic. -w can be used several times in order to change the severity of more than one diagnostic. Fatal errors are not affected by this option. Some examples: -w26 Turn off warning 26 -ww26 " -ww26=i " -we106=w Make error 106 be a warning ================ E. New Errors ================ * 4.51K 128 Segments cannot be mentioned more than once in a copy init command: "-Q`args'" Each segment can only be either the source or the target of a copy init command. 127 Segment placement command "`command'" provides no address range, but the last address range(s) given are not of the proper kind (bit addresses versus byte addresses). This error will occur if something like this is entered: -Z(DATA)SEG=1000-1FFF -Z(BIT)BITVARS= Note that the first uses byte addresses and the second needs bit addresses. To avoid this, provide address ranges for both. * 4.51J 126 Runtime Model Attribute "__cpu" not found. Please enter at least one line in your assembly code that contains the following statement: RTMODEL "__cpu","16C61". Replace 16C61 with your chosen CPU. The CPU must be in uppercase. The "__cpu" runtime model attribute is needed when producing COFF output. The compiler always supplies this attribute, so this error can only occur for programs consisting entirely of assembler modules. At least one of the assembler modules must supply this attribute. * 4.51D 124 Segment conflict for segment `segment'. In module "`mod1'" there is a segment part that is of type `type1', while in module "`mod2'" there is a segment part that is of type `type2' All segment parts for a given segment must be of the same type. One reason for this conflict can be that a COMMON segment is mistakenly declared RSEG (relocatable) in one module. Another way this can happen is if COMMON and RELOCATABLE segments are given in the same -P segment placement command. 123 The output format `format' does not support address translation (-M, -b# or -b@) Address translation is not supported for all output formats. 122 The address `address' is too large to be represented in the output format `format' The chosen output format `format' cannot represent the address `address'. For example, the output format INTEL-STANDARD can only represent addresses in the range 0-FFFF. 121 Segment part or absolute content at logical addresses `start' - `end' would be translated into more than one physical address range The current implementation of address translation does not allow logical addresses from one segment part (or the corresponding range for absolute parts from assembler code) to end up in more than one physical address range. If for example, -M0-1FFF=10000 and -M2000-2FFF=20000 are used, it is not ok for a single segment part to straddle the boundary at address 2000. 120 Overlapping address ranges for address translation. `address type' address `address' is in more than one range The address `address' (of type logical or physical) is the source or target of more than one address translation command. If, for example, both -M0-2FFF=1000 and -M2000-3FFF=8000 are given, this error may be given for any of the logical addresse in the range 2000-2FFF, for which two separate translation commands have been given. 119 Cannot handle C++ identifiers in this output format The output format chosen is one that does not support the use of C++ identifiers (block-scoped names or names of C++ functions). * 4.50A 118 Incompatible runtime models. Module `module1' specifies that 'attribute' must be 'value', but module `module2' specifies no value for this attribute These modules cannot be linked together. They were compiled with settings that resulted in incompatible runtime models. 117 Incompatible runtime models. Module `module1' specifies that 'attribute' must be 'value1', but module `module2' has the value 'value2' These modules cannot be linked together. They were compiled with settings that resulted in incompatible runtime models. 116 Definition of `symbol' in module `module1' is not compatible with definition of `symbol' in module `module2' The symbol `symbol' has been tentatively defined in one or both of the modules. Tentative definitions must match other definitions. * 4.49J 115 Unmatched '"' in extended command file or XLINK_ENVPAR When parsing an extended command file or the environment variable XLINK_ENVPAR, XLINK found an unmatched quote character. For filenames with quote characters you need to put a backslash before the quote character. For example, writing c:\iar\"A file called \"file\"" will cause XLINK to look for a file called A file called "file" in the c:\iar directory. * 4.49F 113 Corrupt input file: "`symptom'" in module `module' ( `file' ) The input file indicated appears to be corrupt. This can occur either because for some reason the file has been corrupted after it was created, or because of a problem in the compiler/assembler used to create it. If the latter appears to be the case, please contact IAR. * 4.49E 112 The module `module' is for an unknown cpu (tid = `tid'). Either the file is corrupt or you need a later version of XLINK The version of XLINK used has no knowledge of the cpu that the file was compiled/assembled for. * 4.49C 111 The file "file" is not a UBROF file The contents of the file are not in a format that XLINK can read. 110 Function `function' mentioned as caller in -a# does not make indirect calls Only functions that actually make indirect calls can be specified to do so in an indirect call option. 109 Function `function' mentioned as callee in -a# is not indirectly called Only functions that actually can be called indirectly can be specified to do so in an indirect call option. 108 Cannot find function `function' mentioned in -a# All the functions specified in an indirect call option must exist in the linked program. 107 Banked segments do not fit into the number of banks specified The linker did not manage to fit all of the contents of the banked segments into the banks given. * 4.49A 106 Syntax error or bad argument in `option' There was an error when parsing the command line argument given. * 4.48K 105 Recursion not allowed for this system. Check module map for recursive functions The runtime model used does not support recursion. Each function determined by the linker to be recursive is marked as such in the module map part of the linker list file. * 4.48J 104 Failed to fit all segments into specified ranges. Problem discovered in segment `seg' The packing algorithm used in the linker didn't manage to fit all the segments. Consider making smaller segment parts (moving things into different input files), or decreasing the total size of the segments, to make the packing easier. 103 Ranges must be closed in `option' The '-P' option requires all memory ranges to have an end. 102 No such segment type: `option' The segment type given is not a valid one. 101 Segment already defined: "`seg'" in `option' The segment has already been mentioned in a segment definition option. 100 Segment name too long: "`seg'" in `option' The segment name exceeded the maximum length (255 characters). 99 Syntax error in segment definition: `option' There was a syntax error in the option. 98 Unmatched /* comment in extended command file No matching '*/' was found in the .xcl-file. 97 Unmatched -! comment in extended command line variable XLINK_ENVPAR As error 96, but for the environment variable XLINK_ENVPAR. 96 Unmatched -! comment in extended command file An odd number of '-!' (comment) options were seen in an .xcl-file. 95 Module `mod' ( `file' ) uses source file references, which are not available in UBROF 5 output This feature cannot be filtered out by the linker when producing UBROF 5 output. Use "-re" or "-ri" to the compiler to turn it off. * 4.48G 94 Unknown flag `x' in local symbols option `-nx' The character `x' is not a valid flag in the local symbols option. 93 Non-existant warning number `no', (valid numbers are 0-`max') An attempt to suppress a warning that does not exist gives this error. 92 Cannot use this format with this cpu Some formats need cpu-specific information and are only supported for some cpus. 88 Wrong library used ( compiler version or memory model mismatch ). Problem found in `mod' ( `file' ). Correct library tag is `tag' Code from this compiler needs a matching library. A library belonging to a later or earlier version of the compiler may have been used. 87 Function with F-index `i' has not been defined before tiny_func referenced in module `mod' ( `file' ) Check that all tiny functions are defined before they are used in a module. 86 The definition for far/farc segment `name' can't be downwards or have a range Segments in far memory cannot be allocated from higher addresses, nor can they have a range given in the segment option -Z. 85 The far/farc segment `name' in module `mod' ( `file' ), is larger than `size' The segment `name' is too large to be a far segment. ================== W. New Warnings ================== * 4.51E 53 Some untranslated addresses overlap translation ranges. Example: Address `addr1' (untranslated) conflicts with logical address `addr2' (translated to `addr1') This can be caused by something like this: -Z(CODE)SEG1=1000-1FFF -Z(CODE)SEG2=2000-2FFF -M(CODE)1000=2000 This will place SEG1 at logical address 1000 and SEG2 at logical address 2000. However, the translation of logical address 1000 to physical address 2000 and the absence of any translation for logical address 1000 will mean that in the output file, both SEG1 and SEG2 will appear at physical address 1000. * 4.51D 52 More than one definition for the byte at address `address' in common segment `segment' The most probable cause of this is that more than one module defines the same interrupt vector. 51 Some source reference debug info was lost when translating to UBROF 5 (example: statements in "`function'" in module `module') UBROF 6 file references can handle source code in more than one source file for a module. This is not possible in UBROF 5 embedded source, so any references to files not included have been removed. 50 There was a problem when trying to embed the source file "`source'" in the object file This warning is given if the file `source' could not be found or if there was an error reading from it. XLINK searches for source files in the same places it searches for object files, so including the directory where the source file is located in the XLINK include directories ("-I" command line option) could solve the first problem. * 4.51A 49 Using SFB/SFE in module `module' ( `file' ) for segment `segment', which has no included segment parts SFB/SFE (assembler directives for getting the start or end of a segment) has been used on a segment for which no segment parts were included. 48 Corrupt input file: "`symptom'" in module `module' ( `file' ) The input file indicated appears to be corrupt. This warning is used in preference to Error 113 when the problem is not serious, and is unlikely to cause trouble. * 4.50A 47 Range error in module `module' ( `file' ), segment `segment' at address `address'. Value `value', in tag `tag', is out of bounds `bounds' This replaces error 18 when -Rw is specified. 46 External function `function' in module `module' ( `file' ) has no global definition This replaces error 68. 45 Memory attribute info mismatch between modules `module1' ( `file1' ) and `module2' ( `file2' ) The UBROF 7 memory attribute information in the given modules is not the same. * 4.49E 44 C library routine localtime failed. Timestamps will be wrong XLINK is unable to determine the correct time. This primarily affects the dates in the list file. This problem has been observed on one host platform if the date is after the year 2038. * 4.49C 43 The function `function' in module `module' ( `file' ) is indirectly called but is not mentioned in the right part of any -a# declaration If any -a# indirect call options are given they must, taken together, specify the complete picture. 41 The function `function' in module `module' ( `file' ) makes indirect calls but is not mentioned in the left part of any -a# declaration If any -a# indirect call options are given they must, taken together, specify the complete picture. 40 The module `module' contains obsolete type information that will not be checked by the linker This kind of type information was replaced in 1988. 39 The function `function' in module `module' ( `file' ) does not appear to be called. No static overlay area will be allocated for its params and locals As far as XLINK can tell, there are no callers for the function, so no space is needed for its params and locals. To make XLINK allocate space anyway use -a(function). 38 There are indirect calls both from interrupts and from the main program. This can make the static overlay system unreliable. Using -ai will avoid this If a function is called from an interrupt while it is already running its params and locals will be overwritten. 37 More than one interrupt function makes indirect calls. This can make the static overlay system unreliable. Using -ai will avoid this If a function is called from an interrupt while it is already running its params and locals will be overwritten. 36 There are indirectly called functions doing indirect calls. This can make the static overlay system unreliable XLINK does not know what functions can call what functions in this case, which means that it cannot make sure static overlays are safe. * 4.48J 35 There is more than one definition for the struct/ union type with tag `tag' Two or more different structure/union types with the same tag exist in the program. If these types were meant to be the same, it is likely that the declarations differ slightly. There will then also very likely be one or more warnings about type conflicts (warning 6). If they were not meant to be the same, consider turning off this warning. 34 The 20 bit segmented variant of the INTEL EXTENDED format cannot represent the addresses specified. Consider using -Y1 (32 bit linear addressing). The program uses addresses higher than 0xFFFFF, and the segmented variant of the chosen format cannot handle this. The linear addressing variant can handle full 32 bit addresses. 33 Using "-r" overrides format option. Using UBROF The "-r" option specifies UBROF format and C-SPY library modules. It overrides any "-F" (format) option 32 Format option set more than once. Using `format' format The format option can only be given once. The linker uses the format `format'. * 4.48G 31 Modules have been compiled with possibly incompatible settings: `more info' According to the contents of the modules, they are not compatible. 30 Module `name' is compiled for `cpu1', expected `cpu2' You are building an executable for cpu `cpu2', but module `name' is compiled for cpu `cpu1'. 29 Parts of segment `name' are inited, even though it is of type `type' Initing DATA memory is not useful if the result of linking is to be promable. 28 Parts of segment `name' are inited, parts not This is not useful if the result of linking is to be promable. 27 No code at start address found in reset vector Failed in determining the LOCATION setting for XCOFF output format for the 78400 processor, because no code was found at the address specified in the reset vector. 26 No reset vector found Failed in determining the LOCATION setting for XCOFF output format for the 78400 processor, because no reset vector was found. 25 Using "-Y#" discards and distorts debug information. Use with care. If possible, find an updated debugger that can read modern UBROF Using the UBROF format modifier -Y# is not recommended. 24 `num' counts of 'warning' total For each warning of type 23 actually emitted, a summary is provided at the end. 23 `limitation specific warning' Due to some limitation in the chosen output format, or in the information available, XLINK cannot produce the correct output. Only one warning for each specific limitation is given. ========================== L. Log of Minor Changes ========================== * 4.51C New Default for Intel Extended The INTEL-EXTENDED output format has been changed to use the 32-bit linear variant ("-Y1") by default on new targets. To get the 20-bit segmented variant for one of these targets use the format variant option "-Y0". * 4.51A Changes to the Map File The map file now includes information about segment type for addresses. On many processors this is used to determine the address space of an address (ie CODE/DATA on Harvard architectures). To make place for this, two uninteresting columns have been removed from the Segment Map table in the map file. Obsolete Command Line Options XLINK now ignores the command line options "-m" and "-t", if given. The new behavior is in essence as if "-m" was used, and "-t" was not used. Extra Space in Segments When using segment placement with extra space (eg CSTACK+100), the extra space is added only if there is at least one segment part actually included from this segment (ie, if the segment was actually needed for anything). * 4.50A Make Range Errors Be Warnings The command line option -R has gained a flag, "w". As before, specifying -R makes XLINK ignore range errors. Now, specifying -Rw makes XLINK treat range errors as warnings. * 4.49C Maximum Number of Banks in -b It is now possible to specify the number of banks in the bank segment placement option (-b). The syntax is now: -b[addrtype][(type)]segments=first,length,incr[,count] where the optional `count' is a decimal count of the number of banks available. * 4.49A No End Address Restriction for Far Segment Placement The restriction on address ranges for far segments has been removed. It is now allowed to have an end address (or even several ranges) in a "-Z" segment placement command line option dealing with far (FAR, FARCONST or FARCODE) segments. * 4.49A Downwards Allocation End Address Changed To Be More Consistent The meaning of a single address in a "-Z" option with downwards ("#") allocation has changed. It used to be that the address given was the first address not to be used. It is now considered to be the last address to be used. This is the same as when specifying a range. Example: -Z(CODE)CODE#5000 This used to mean the same as -Z(CODE)CODE#0-4FFF but is now the same as -Z(CODE)CODE#0-5000 * 4.48N Turn Off Detailed Type Conflict Information A new command line option "-wt" has been added. When "-wt" is given the detailed type information output for warnings 6 (type conflict) and 35 (multiple structs with same tag) is suppressed. * 4.48K Return Status Control A new command line option "-ws" has been added. It affects the return status of XLINK as follows: Condition No -ws -ws --------- ------ --- No errors or warnings 0 0 Warnings, but no errors 0 1 One or more errors 2 2 "-ws" thus only affects the return status when there is one or more warnings but no errors. * 4.48J List Output Directory Option A new option "-L" is available. Its syntax is: -Lprefix Generate a list on: <.lst> A useful special case of this is to use "-L" with no arguments to get a list file in the current directory. * 4.48D Suppress Compiler Generated Module-Local Symbols The -n option can now take a modifier 'c' to only suppress compiler generated module-local symbols. These are usually jump or constant labels, at best of fairly marginal interest, and even then only when debugging at assembly level. Example: -nc