foboot/sw/include/toboot-api.h

109 lines
4.1 KiB
C
Raw Normal View History

#ifndef TOBOOT_API_H_
#define TOBOOT_API_H_
#include <stdint.h>
/// Store this configuration struct at offset 0x94 from the start
/// of your binary image.
/// You may set all RESERVED values to 0. as they will be calculated
/// when the program is written to flash.
struct toboot_configuration {
/// Set to 0x907070b2 to indicate a valid configuration header.
uint32_t magic;
/// Reserved value. Used as a generational counter. Toboot will
/// overwrite this value with a monotonically-increasing counter
/// every time a new image is burned. This is used to determine
/// which image is the newest.
uint16_t reserved_gen;
/// The starting page for your program in 1024-byte blocks.
/// Toboot itself sets this to 0. If this is nonzero, then it
/// must be located after the Toboot image. Toboot is currently
/// under 5 kilobytes, so make sure this value is at least 6.
uint8_t start;
/// Configuration bitmask. See below for values.
uint8_t config;
/// Set to 0x18349420 to prevent the user from entering Toboot manually.
/// Use this value with caution, as it can be used to lockout a Tomu.
uint32_t lock_entry;
/// A bitmask of sectors to erase when updating the program. Each "1"
/// causes that sector to be erased, unless it's Toboot itself. Bit values
/// determine flash blocks 0-31.
uint32_t erase_mask_lo;
/// A bitmask of sectors to erase when updating the program. Each "1"
/// causes that sector to e erased. Use these two values to e.g. force
/// private keys to be erased when updating. Bit values determine flash
/// blocks 32-63.
uint32_t erase_mask_hi;
/// A hash of the entire header, minus this entry. Toboot calculates
/// this when it programs the first block. A Toboot configuration
/// header MUST have a valid hash in order to be considered valid.
uint32_t reserved_hash;
} __attribute__((packed));
/// Toboot V1.0 leaves IRQs enabled, mimicking the behavior of
/// AN0042. Toboot V2.0 makes this configurable by adding a
/// bit to the configuration area.
#define TOBOOT_CONFIG_FLAG_ENABLE_IRQ_MASK 0x01
#define TOBOOT_CONFIG_FLAG_ENABLE_IRQ_SHIFT 0
#define TOBOOT_CONFIG_FLAG_ENABLE_IRQ (1 << 0)
#define TOBOOT_CONFIG_FLAG_DISABLE_IRQ (0 << 0)
/// When running a normal program, you won't want Toboot to run.
/// However, when developing new software it is handy to have
/// Toboot run at poweron, instead of jumping straight to your
/// program. Set this flag to enter your program whenever the
/// system has just powered on.
#define TOBOOT_CONFIG_FLAG_AUTORUN_MASK 0x02
#define TOBOOT_CONFIG_FLAG_AUTORUN_SHIFT 1
#define TOBOOT_CONFIG_FLAG_AUTORUN (1 << 1)
#define TOBOOT_CONFIG_FLAG_AUTORUN_DISABLED (0 << 1)
/// When we create a fake header, this flag will be set. Otherwise,
/// leave the flag cleared. This field has no meaning in user
/// applications, and is only used internally.
#define TOBOOT_CONFIG_FAKE_MASK 0x04
#define TOBOOT_CONFIG_FAKE_SHIFT 2
#define TOBOOT_CONFIG_FAKE (1 << 2)
/// Various magic values describing Toboot configuration headers.
#define TOBOOT_V1_MAGIC 0x6fb0
#define TOBOOT_V1_MAGIC_MASK 0x0000ffff
#define TOBOOT_V2_MAGIC 0x907070b2
#define TOBOOT_V2_MAGIC_MASK 0xffffffff
/// This value is used to prevent manual entry into Toboot.
#define TOBOOT_LOCKOUT_MAGIC 0x18349420
/// The seed value for the hash of Toboot's configuration header
#define TOBOOT_HASH_SEED 0x037a5cf1
/// This is the runtime part that lives at the start of RAM.
/// Running programs can use this to force entry into Toboot
/// during the next reboot.
struct toboot_runtime {
/// Set this to 0x74624346 and reboot to enter bootloader,
/// even if LOCKOUT is enabled.
uint32_t magic;
/// Set this to 0 when your program starts.
uint8_t boot_count;
/// The bootloader should set this to 0x23 for Tomu.
uint8_t board_model;
/// Unused.
uint16_t reserved;
};
/// Set runtime.magic to this value and reboot to force
/// entry into Toboot.
#define TOBOOT_FORCE_ENTRY_MAGIC 0x74624346
#endif /* TOBOOT_API_H_ */