Keil Logo

ARM: Include a binary image into an application


Information in this knowledgebase article applies to:

  • MDK-ARM any version

QUESTION

Sometimes it is necessary to include the content of a binary data file into a microcontroller application so that it can be accessed from C program code. This might be calibration data, lookup tables, FPGA images or any other data generated by external tools. How can such an image be included into a microcontroller application with MDK-ARM?

ANSWER

There are several ways to do this. This article and its attached µVision project explain how this is done within an assembly source file and a C-source file. The assembly source file method includes file MyBinFile1.bin. The C-source file method includes the file MyBinFile2.bin file.

Download the attached ZIP file and extract it into a new folder. In order to build this project, you also need to download the free Windows version of the tool SRecord version 1.64 or later (https://sourceforge.net/projects/srecord/files/srecord-win32) and extract it into the SRecord folder of this example project.

Assembly Source File:

The ARM assembler supports the directive INCBIN which can directly include binary images into an assembly source file. In the attached example, the assembly source file MyBinFile1.s defines the symbol MyBinaryImage1, includes the binary data of the file MyBinFile1.bin and defines the symbol MyBinaryImage1_length which holds the size of the binary data. Both symbols, MyBinaryImage1 and MyBinaryImage1_length are also exported so that they can be used in the C-source file Main.c.

        AREA    MyBinFile1_Section, DATA, READONLY
        EXPORT  MyBinaryImage1

; Includes the binary file MyBinFile1.bin from the current source folder
MyBinaryImage1
        INCBIN  MyBinFile1.bin
MyBinaryImage1_End

; Use a relative or absolute path to other folders if necessary
;       INCBIN  c:\project\MyBinFile1.bin
; Add further binary files to merge them if necessary
;       INCBIN  MyBinFile2.bin

; define a constant which contains the size of the image above
MyBinaryImage1_length
        DCD     MyBinaryImage1_End - MyBinaryImage1

        EXPORT  MyBinaryImage1_length

        END

The C declarations for these variables are defined at the beginning of main.c:

// these variables are defined in the assembler source file MyBinFile1.s and
// represent the data from MyBinFile1.bin
extern const unsigned char MyBinaryImage1[];
extern const unsigned long MyBinaryImage1_length;
...

C Source File with converter:

The ARM C compiler does not provide a direct way to include binary data, but there are free utilities which can convert a binary file into an initialized C const array. In this example, the tool SRecord (srec_cat.exe) is used to do the conversion. It is invoked in µVision as a user defined command Before Build/Rebuild. The necessary directives for this srec_cat.exe are defined in the command file MyBinFile2ConvCmd. With these commands srec_cat.exe creates the file MyBinFile2.c and MyBinFile2.h. The former is added to the µVision project and the latter is included in main.c.

MyBinFile2ConvCmd: Command file for srec_cat. See the comments in the command file and the user's manual of the SRecord toolset for more details.

MyBinFile2.bin -Binary              # input file has binary format
-o MyBinFile2.c                     # output file name
-C-Array MyBinaryImage2 -INClude    # generate C-array with the name MyBinaryImage2
                                    # and an include file

Resulting file MyBinFile2.c

const unsigned char MyBinaryImage2[] =
{
0xFF, 0xFE, 0xFD, 0xFC, 0xFB, 0xFA, 0xF9, 0xF8, 0xF7, 0xF6, 0xF5, 0xF4,
0xF3, 0xF2, 0xF1, 0xF0, 0xEF, 0xEE, 0xED, 0xEC, 0xEB, 0xEA, 0xE9, 0xE8,
...
...
0x03, 0x02, 0x01, 0x00,
};
const unsigned long MyBinaryImage2_termination = 0x00000000;
const unsigned long MyBinaryImage2_start       = 0x00000000;
const unsigned long MyBinaryImage2_finish      = 0x00000400;
const unsigned long MyBinaryImage2_length      = 0x00000400;

#define MYBINARYIMAGE2_TERMINATION 0x00000000
#define MYBINARYIMAGE2_START       0x00000000
#define MYBINARYIMAGE2_FINISH      0x00000400
#define MYBINARYIMAGE2_LENGTH      0x00000400

The generated file MyBinFile2.h contains the declarations for the two variables MyBinaryImage2[] and MyBinaryImage2_length. This file is included in Main.c.

MORE INFORMATION

ATTACHED FILES

Request the files attached to this knowledgebase article.

Last Reviewed: Tuesday, July 17, 2018


Did this article provide the answer you needed?
 
Yes
No
Not Sure
 
  Arm logo
Important information

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies.

Change Settings

Privacy Policy Update

Arm’s Privacy Policy has been updated. By continuing to use our site, you consent to Arm’s Privacy Policy. Please review our Privacy Policy to learn more about our collection, use and transfers
of your data.