bin2obj.h

/**
 * @file bin2obj.h
 * @author Zhang Zhuo
 * @brief Helper macros for using embedded binary data
 * 
 * This header provides convenient macros for declaring symbols
 * generated by bin2obj.py or bin2obj.cmake
 * 
 * Compatible with incbin.h conventions
 */

#ifndef BIN2OBJ_H
#define BIN2OBJ_H

#include <stddef.h>

/**
 * BIN2OBJ_EXTERN - Declare an embedded binary data symbol
 * 
 * @param name: The symbol name used when generating the object file
 * 
 * This declares three symbols (incbin-compatible naming):
 *   - <name>_data: Start of binary data (array)
 *   - <name>_end: End marker (used for compatibility, not always a valid pointer)
 *   - <name>_size: Size of data in bytes
 * 
 * Note: For bin2obj.py generated .obj files, alignment is already
 * embedded in the object file, so no alignment attribute is needed
 * in the extern declaration. The linker uses the alignment from .obj.
 * 
 * IMPORTANT: On some platforms (e.g., Windows COFF), name_end may not be
 * a valid pointer. Always use BIN2OBJ_END() macro which computes the
 * correct end pointer as (data + size).
 * 
 * The macro automatically uses extern "C" when included in C++ code,
 * preventing name mangling issues.
 * 
 * Example:
 *   BIN2OBJ_EXTERN(my_data);
 *   
 *   printf("Size: %zu\n", BIN2OBJ_SIZE(my_data));
 *   for (size_t i = 0; i < BIN2OBJ_SIZE(my_data); i++) {
 *       printf("%02x ", BIN2OBJ_DATA(my_data)[i]);
 *   }
 */
#ifdef __cplusplus
#define BIN2OBJ_EXTERN(name) \
    extern "C" { \
        extern const unsigned char name##_data[]; \
        extern const unsigned char name##_end[]; \
        extern const size_t name##_size; \
    }
#else
#define BIN2OBJ_EXTERN(name) \
    extern const unsigned char name##_data[]; \
    extern const unsigned char name##_end[]; \
    extern const size_t name##_size
#endif

/**
 * Helper macro to get pointer to embedded data
 */
#define BIN2OBJ_DATA(name) ((const unsigned char*)(name##_data))

/**
 * Helper macro to get the end pointer of embedded data
 */
#define BIN2OBJ_END(name) ((const unsigned char*)(name##_end))

/**
 * Helper macro to get the size of embedded data
 */
#define BIN2OBJ_SIZE(name) (name##_size)

#endif /* BIN2OBJ_H */