IAR Linker and Library Tools Reference Guide XLINK-540 XLINK-540 COPYRIGHT NOTICE © 1987–2012 IAR Systems AB. No part of this document may be reproduced without the prior written consent of IAR Systems AB. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license. DISCLAIMER The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. In no event shall IAR Systems, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind. TRADEMARKS IAR Systems, IAR Embedded Workbench, C-SPY, visualSTATE, The Code to Success, IAR KickStart Kit, I-jet, IAR, and the logotype of IAR Systems are trademarks or registered trademarks owned by IAR Systems AB. Microsoft and Windows are registered trademarks of Microsoft Corporation. Adobe and Acrobat Reader are registered trademarks of Adobe Systems Incorporated. All other product names are trademarks or registered trademarks of their respective owners. EDITION NOTICE June 2012 Part number: XLINK-540 The IAR Linker and Library Tools Reference Guide replaces all versions of the IAR XLINK Linker™ and IAR XLIB Librarian™ Reference Guide. XLINK-540 Contents Tables ........................................................................................................................ 7 Preface ...................................................................................................................... 9 Who should read this guide ................................................................. 9 How to use this guide ............................................................................. 9 What this guide contains ..................................................................... 10 Document conventions ........................................................................ 10 Typographic conventions ................................................................... 11 Naming conventions .......................................................................... 11 Part 1: The IAR XLINK Linker ........................................... 13 Introduction to the IAR XLINK Linker ............................................... 15 Key features .............................................................................................. 15 Large Address Awareness .................................................................. 15 Linking protected files ....................................................................... 16 MISRA C ........................................................................................... 16 The linking process ............................................................................... 16 Object format ..................................................................................... 17 XLINK functions ............................................................................... 17 Libraries ............................................................................................ 17 Output format ..................................................................................... 18 Input files and modules ........................................................................ 18 Libraries ............................................................................................. 19 Formatters for printf and scanf ........................................................... 20 Segments ............................................................................................ 20 Segment control ..................................................................................... 21 Address translation ............................................................................. 22 Allocation segment types ................................................................... 22 Memory segment types ...................................................................... 22 Overlap errors ................................................................................... 23 Range errors ...................................................................................... 24 3 XLINK-540 Contents Segment placement examples ............................................................ 25 Listing format ........................................................................................... 26 Header ................................................................................................ 26 Cross-reference .................................................................................. 26 Checksummed areas and memory usage ........................................... 33 Checksum calculation ........................................................................... 33 Checksum calculation by the linker ................................................... 34 Adding a checksum function to your source code ............................. 34 Things to remember ........................................................................... 36 Checksum value symbol .................................................................... 36 Bytewise and mirrored initial checksum values ........................ 37 Bitwise initial values .......................................................................... 37 Bytewise initial values ....................................................................... 38 Mirroring ............................................................................................ 38 XLINK options .................................................................................................. 41 Setting XLINK options ......................................................................... 41 Summary of options .............................................................................. 41 Descriptions of XLINK options ........................................................ 43 XLINK output formats .................................................................................. 77 Single output file ..................................................................................... 77 UBROF versions ............................................................................... 79 Two output files ...................................................................................... 80 Output format variants ........................................................................ 81 IEEE695 ............................................................................................. 82 ELF ..................................................................................................... 84 XCOFF78K ........................................................................................ 86 Restricting the output to a single address space ..................... 87 XLINK environment variables ................................................................... 89 Summary of XLINK environment variables ............................... 89 IAR Linker and Library Tools 4 Reference Guide XLINK-540 Contents XLINK diagnostics ........................................................................................... 93 Introduction .............................................................................................. 93 XLINK warning messages ................................................................. 93 XLINK error messages ...................................................................... 93 XLINK fatal error messages .............................................................. 93 XLINK internal error messages ......................................................... 93 Error messages ........................................................................................ 94 Warning messages ............................................................................... 113 Part 2: The IAR Library Tools ............................................ 125 Introduction to the IAR Systems library tools ............................... 127 Libraries .................................................................................................... 127 IAR XAR Library Builder and IAR XLIB Librarian ............... 127 Choosing which tool to use .............................................................. 128 Using libraries with C/C++ programs .......................................... 128 Using libraries with assembler programs .................................. 128 The IAR XAR Library Builder .................................................................. 131 Using XAR ............................................................................................... 131 Basic syntax .................................................................................... 131 Summary of XAR options ............................................................... 131 Descriptions of XAR options ........................................................... 132 XAR diagnostics .............................................................................................. 133 XAR messages ....................................................................................... 133 IAR XLIB Librarian options ......................................................................