Converting memory initialization files in the ARM Cortex-M1 FPGA Development Kit Altera Edition

Application Note 215



                                                                        Release information

Change history

Date

Issue

Change

September 2008

A

First release

                                                                        Proprietary notice

Words and logos marked with Ó and Ô are registered trademarks owned by ARM Limited, except as otherwise stated below in this proprietary notice. Other brands and names mentioned herein may be the trademarks of their respective owners.

Neither the whole nor any part of the information contained in, or the product described in, this document may be adapted or reproduced in any material form except with the prior written permission of the copyright holder.

Altera is a trademark and service mark of Altera Corporation in the United States and other countries. Altera products contain intellectual property of Altera Corporation and are protected by copyright laws and one or more U.S. and foreign patents and patent applications.

The product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by ARM in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. ARM Limited shall not be liable for any loss or damage arising from the use of any information in this document, or any error or omission in such information, or any incorrect use of the product.

                                                                        Confidentiality status

This document is Non-Confidential. The right to use, copy and disclose this document may be subject to license restrictions in accordance with the terms of the agreement entered into by ARM and the party that ARM delivered this document to.

Unrestricted Access is an ARM internal classification.

                                                                        Feedback on this Application Note

If you have any comments on this Application Note, please send email to errata@arm.com giving:

·                     the document title

·                     the document number

·                     the page number(s) to which your comments refer

·                     an explanation of your comments.

General suggestions for additions and improvements are also welcome.

                                                                        ARM web address

http://www.arm.com

 


1.     Introduction

The ARM Cortex-M1 FPGA Development Kit includes the Keil RealView Microcontroller Development Kit (MDK), which you can use to create embedded software projects.

RealView MDK creates software image files in two different formats:

·         an ARM AXF file which contains debugging information in addition to the executable image;

·         an Intel Hexadecimal (Hex) file, which is an ASCII representation of the software image and can be read by many 3rd-party memory programming utilities.

Some tools may require memory images in different formats or place various constraints on the input files.  The RealView MDK memory images need to be converted before such tools can use them.  For example, you may need to split the RealView MDK software image into separate files for different memories.

RealView MDK uses the ARM RealView Compiler Tools, which contains the fromelf utility that can convert the project’s AXF file into a variety of different formats.  It can also create different files for each load region in the AXF image.  The RealView MDK project’s Intel Hexadecimal file is created using fromelf using the combined-Intel Hexadecimal output format, which means that the single Hex image will contain all load regions in the AXF image.

Note
For information about how to use the fromelf utility, refer to the ARM RealView Compilation Tools for µVision Linker and Utilities Guide.  You can access this document through the RealView MDK online help system.

The ARM Cortex-M1 FPGA Development Kit also contains a hex2hex memory image conversion utility.  You can use this utility to convert and transform RealView MDK project Hex files into different formats that can be used for memory initialization with the Altera Quartus II toolchain.  The remainder of this document describes how to use the hex2hex utility to create different types of memory initialization files from the RealView MDK project Hex file, including those required to initialize the ARM Cortex-M1 processor’s Tightly Coupled Memories (TCMs).

This Application Note assumes that you are familiar with the ARM Cortex-M1 FPGA Development Kit and Keil RealView MDK software.  It applies to the following software versions:

·         ARM Cortex-M1 FPGA Development Kit version 1.1

·         Keil RealView MDK version 3.22a

·         Altera Quartus II version 8.0

You should refer to the documentation for each tool for information about how to use the software.  You may also refer to the ARM Cortex-M1 FPGA Development Kit Cortex-M1 User Guide for more information about the ARM Cortex-M1 processor in the ARM Cortex-M1 FPGA Development Kit.

 


2.     Using the hex2hex conversion utility

2.1      Purpose

The hex2hex conversion utility converts and transforms the Intel Hexadecimal files that are created by Keil RealView MDK into files that can be used for memory initialization in Altera Quartus II.  This format can be used to initialize the ARM Cortex-M1 processor TCMs and other Altera on-chip memories, and to initialize software into flash memory using the flash programmer feature in Quartus II.

You can also use the hex2hex utility to:

·         split a single input image into multiple output images for initializing several memories;

·         re-base the image to a new address;

·         insert padding in the output image to make its size match the memory size.

2.2      Starting hex2hex

The hex2hex utility is a command-line tool that can be started from the Windows command prompt or any other utility that has a command-line interface.  It is provided in the Utilities subdirectory of the ARM Cortex-M1 FPGA Development Kit installation directory and is started using the hex2hex.bat wrapper script.

For example:

hex2hex.bat --infile=input.hex --outfile=output.hex

The command takes the input Intel Hexadecimal file input.hex and converts its contents into a format that is suitable for initializing Altera on-chip memories with the Altera Quartus II software, writing the results into the file output.hex.  The --infile and --outfile arguments are compulsory.

Note

·      The hex2hex.bat command requires a valid installation of the Altera Quartus II software.

·      RealView MDK writes the project Hex file to the obj subdirectory of the project directory.

More command-line arguments are available to control the format of the output file, and these arguments are described in the next section.

2.3      hex2hex command syntax

The command for invoking hex2hex is:

hex2hex.bat ‑‑infile=input_file ‑‑outfile=output_file [‑‑oformat=format] [‑‑width=width] [‑‑saddr=start_address] [‑‑eaddr=end_address | ‑‑osize=size] [‑‑oaddr=output_address] [‑‑padding] [‑‑no‑size‑limit] [‑‑help]

You can provide the arguments in any order.

2.3.1       --infile=input_file

Specifies the input file to be converted.  input_file must be in the Intel Hexadecimal format.

2.3.2       --outfile=output_file

Specifies the name of the output file that will be created.  The format of this file is selected using the --oformat option.

2.3.3       --oformat=format

Selects the output image format, where format is one of:

hex          Altera Quartus II Hexadecimal format for Altera on-chip memory initialization.  Use this format to create files that can be used to initialize the ARM Cortex-M1 TCMs and Altera on-chip memories.

ihex       Intel Hexadecimal format.  Use this format to transform the input Hex file into another Hex file, translated using the options given by the other arguments.  Intel Hexadecimal files can be used for flash memory initialization using the Altera Quartus II programming utility.

dat          Verilog memory model hexadecimal format.  Choose this format to create files that can be used to initialize Verilog memory models that use the $readmemh task.

If this option is not specified then the hex output format is used by default.

2.3.4       --width=width

Configures the width (word size) of the memory that will be initialized.  This value is specified in bytes and defaults to 4 when the option is not used.  For example, to configure a memory with a word size of 2 bytes, use:

  --width=2

This option has no effect on Intel Hexadecimal output files, because this type of file is byte addressed.

Note
For the hex and dat output formats, the size of the input data must be a multiple of the word size.

2.3.5       --saddr=start_address

Configures the input start address.  This option specifies that the output file will only contain data that has an address greater than or equal to address start_address in the input file.  The address is specified as a byte address.  For example, to create an output file filled with the data starting at address 0x20000000 in the input file, use:

  --saddr=0x20000000

When this option is not specified, input data is taken from address 0x00000000.

2.3.6       --eaddr=end_address

Configures the input end address.  This option specifies that the output file will only contain data that has an address less than or equal to address end_address in the input file.  The address is specified as a byte address.  For example, to create an output hex file filled with data up to and including address 0x2000FFFF, use:

  --eaddr=0x2000FFFF

This option cannot be used with the --osize option.

When this option is not specified, input data is taken until the end address of the input data file.

2.3.7       --oaddr=output_address

Configures the output start address.  This option is used to re-base the data in the input file to a different address in the output file.  When this option is used, the data at the input file start address will be translated to appear at address output_address in the output file and all other data will be translated by the same amount.

When this option is not specified, input data is re-based to address 0x00000000.  This makes the output file suitable for memory initialization tools that interpret addresses relative to the memory’s base address.

2.3.8       --osize=size

Configures the size of the output image, starting from the input start address.  This option cannot be used with the --eaddr argument; it is used to configure the size of the input data as a start address plus size rather than a start and end address.

The size is specified in bytes, or as a size specification composed of a number followed by either K for kilobytes or M for megabytes.  For example, to create an output image that is 0.5MB in size, use:

  --osize=0.5M; or

  --osize=512K; or

  --osize=524288

The size specification must resolve to an integer number of bytes.

Alternatively, use --osize=section to create a Hex file that contains data starting from the input start address until the end of the corresponding input section.  This means that input data will be converted until a new address record is encountered in the input Hex file.

2.3.9       --padding

Pads empty address space in the output file with zeroes.  This option can be used to force the creation of a file that contains data at every address in the target range.  By default, addresses in the input file that contain no data will also contain no data in the output file.  Padding these empty address spaces with zeroes can help to reduce synthesis warnings.

To prevent the accidental use of this option on input images that contain distant sections separated by very large, empty address ranges, which would result in very large zero-padded output files, there is a 5MB limit on zero-padded sections.  This restriction can be disabled by using the ‑‑no‑size‑limit option.

2.3.10  --no-size-limit

Disables the size limit on zero-padded sections.  When this option is used, care should be taken that the input image does not contain a large, empty region in the target address range.  Memory and disk space requirements might otherwise be excessive.

2.3.11  --help

Displays a summary of the command-line options and terminates.  All other options are ignored.

2.4      Output file addressing

By default, data in the output file starts at address 0x00000000.  The data at 0x00000000 corresponds to the start address of the input address range.  This is because memory initialization tools normally expect initialization data to be addressed relative to the target memory’s base address.

You can use the --oaddr option if you want your output data to start at a different address.


3.     Examples of hex2hex usage

This section contains examples of how to use the hex2hex utility in the ARM Cortex-M1 FPGA Development Kit to create common types of memory initialization files.

3.1      Creating an ITCM initialization file

If your software image contains code for the Instruction Tightly Coupled Memory (ITCM) and does not require any other initialized memory, you can convert the ITCM address range using the hex output format.  For example:

hex2hex.bat --infile=input.hex --outfile=itcm.hex ‑‑saddr=0x00000000 ‑‑osize=32K ‑‑oformat=hex ‑‑padding

This command:

·         reads input data from input.hex;

·         writes the output file to itcm.hex;

·         converts a 32KB data section starting at the ITCM address 0x00000000 in input.hex;

·         pads any empty address space in the output file with zeroes.

If your ITCM is not 32KB, you can provide a different size value to the --osize option.  If your memory image also contains data for other memory regions, you can convert these by running hex2hex again with a different target address range.

3.2      Creating a DTCM initialization file

If your software requires pre-initialized data in the Data Tightly Coupled Memory (DTCM), you can use a command line like the one in the following example to create a DTCM initialization file:

hex2hex.bat --infile=input.hex --outfile=dtcm.hex ‑‑saddr=0x20000000 ‑‑osize=16K ‑‑oformat=hex ‑‑padding

This command:

·         reads input data from input.hex;

·         writes the output file to dtcm.hex;

·         converts a 16KB data section starting at the DTCM base address 0x20000000 in input.hex;

·         re-bases the data in the output file to a base address of 0x00000000;

·         pads any empty address space in the output file with zeroes.

If the DTCM is not 16KB, you can provide a different size value to the --osize option.

The output data is re-based to a start address of 0x00000000.  During memory initialization, the addresses in the output file are interpreted as relative to the DTCM base address.  Therefore the data will appear at the correct address in the processor’s memory map at run-time.

3.3      Creating a flash memory initialization file

If your system contains flash memory and you want to initialize this memory with code or data, you can create an Intel Hexadecimal file containing the appropriate region from the RealView MDK project Hex file.

You can use a command like the one in the following example to create a Hex file that the Altera Quartus II flash programming utility can use to initialize flash memory:

hex2hex.bat --infile=input.hex --outfile=flash.hex ‑‑saddr=0x60000000 ‑‑osize=128K ‑‑oformat=ihex

This command:

·         reads input data from input.hex;

·         writes the output file to flash.hex;

·         converts a 128KB section starting at a base address of 0x60000000 in input.hex;

·         re-bases the data in the output file to a base address of 0x00000000.

The command assumes that the flash memory in your system starts at a base address of 0x60000000 in the processor’s address map and that your RealView MDK project has been configured to use this memory region.  You can change the value of the --saddr option if your flash memory is at a different base address, and you can change --osize to configure the size of the input region.

If your software requires the flash memory to be initialized, but the initialized region does not start at the flash base address, you can use a similar command that sets --saddr to the start of the region that must be initialized.  This region will be re-based to an address of 0x00000000 in the output file, and you must ensure that the flash programming tool places the section at the correct offset.  To do this, you can either:

·         set the flash programmer options to offset by the appropriate amount; or

·         use the --oaddr option with hex2hex to re-base the output to a non-zero address, representing the appropriate offset.

For example, to create an output file that contains 0.5MB of data from the input file, starting at address 0x60100000, and whose output address is a 1MB offset from 0x00000000, use:

hex2hex.bat --infile=input.hex --outfile=flash.hex ‑‑saddr=0x60100000 ‑‑osize=0.5M ‑‑oaddr=0x00100000 ‑‑oformat=ihex


4.     References

This Application Note refers to the following ARM documentation:

·         ARM Cortex-M1 FPGA Development Kit Altera Cyclone III Edition Cortex-M1 User Guide (ARM DUI 0395)

·         ARM RealView Compilation Tools for µVision Linker and Utilities Guide (ARM DUI 0377)

You can also refer to the following online resources for further related documentation:

·         http://infocenter.arm.com for access to ARM documentation

·         http://www.altera.com for access to Altera documentation

Copyright © 2010 ARM Limited. All rights reserved. ARM DAI0215A
Non-Confidential