incbin.h File Reference

#include <stdint.h>

Go to the source code of this file.

Macros
#define	INCBIN_EXTERN(VARNAME)
#define	INCBIN_SIZE(VARNAME)   ( (uint16_t) & __size_ ## VARNAME )
#define	BANK(VARNAME)   ( (uint8_t) & __bank_ ## VARNAME )
#define	INCBIN(VARNAME, FILEPATH)

Detailed Description

Allows binary data from other files to be included into a C source file.

It is implemented using asm .incbin and macros.

See the incbin example project for a demo of how to use it.

Macro Definition Documentation

INCBIN_EXTERN

#define INCBIN_EXTERN

(

VARNAME

)

Value:

extern const uint8_t VARNAME[]; \
extern const void __size_ ## VARNAME; \
extern const void __bank_ ## VARNAME;

Creates extern entries for accessing a INCBIN() generated variable and it's size in another source file.

Parameters

VARNAME

Name of the variable used with INCBIN

An entry is created for the variable and it's size variable.

INCBIN(), INCBIN_SIZE()

INCBIN_SIZE

#define INCBIN_SIZE

(

VARNAME

)

( (uint16_t) & __size_ ## VARNAME )

Obtains the size in bytes of the INCBIN() generated data

Parameters

VARNAME

Name of the variable used with INCBIN

Requires INCBIN_EXTERN() to have been called earlier in the source file

INCBIN(), INCBIN_EXTERN()

BANK

#define BANK

(

VARNAME

)

( (uint8_t) & __bank_ ## VARNAME )

Obtains the bank number of the INCBIN() generated data

Parameters

VARNAME

Name of the variable used with INCBIN

Requires INCBIN_EXTERN() to have been called earlier in the source file

INCBIN(), INCBIN_EXTERN()

INCBIN

#define INCBIN	(		VARNAME,
			FILEPATH
	)

Value:

void __func_ ## VARNAME(void) __banked __naked { \
__asm \
_ ## VARNAME:: \
1$: \
    .incbin FILEPATH \
2$: \
    ___size_ ## VARNAME = (2$-1$) \
    .globl ___size_ ## VARNAME \
    .local b___func_ ## VARNAME \
    ___bank_ ## VARNAME = b___func_ ## VARNAME \
    .globl ___bank_ ## VARNAME \
__endasm; \
}

Includes binary data into a C source file

Parameters

VARNAME	Variable name to use
FILEPATH	Path to the file which will be binary included into the C source file

filepath is relative to the working directory of the tool that is calling it (often a makefile's working directory), NOT to the file it's being included into.

The variable name is not modified and can be used as-is.

The INCBIN() macro will declare the BANK() and INCBIN_SIZE() helper symbols. Then if INCBIN_EXTERN() is used in the header then those helper macros can be used in the application code.

• INCBIN_SIZE() for obtaining the size of the included data.
• BANK() for obtaining the bank number of the included data.

Use INCBIN_EXTERN() within another source file to make the variable and it's data accessible there.

---