GBDK 2020 Docs  4.3.0
API Documentation for GBDK 2020
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;
unsigned char uint8_t
Definition: stdint.h:51

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

Parameters
VARNAMEName 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
VARNAMEName 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
VARNAMEName 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
VARNAMEVariable name to use
FILEPATHPath 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.