# SFBBootBlock Struct Reference

The exactly-64-byte-long SFB 'boot block' contents. More...

`#include <SFBBootBlock.h>`

## Data Fields
u8 | version
| V1: The version of the bootblock goes in the first byte.
u8 | writeTag
| V1: Determines which bootblock copy is newer.
u16 | flags
| V1: Boot-related and miscellaneous flags.
u32 | bootCount
| V1: The number of times the tertiary bootloader has booted a sketch.
u32 | burnCount
| V1: The number of times the tertiary bootloader has burned a sketch.
u32 | ownerId
| V2: The owner of this board, displayed in B36, 0xffffffff illegal.
u32 | boardId
| V2: The name or id of this board, displayed in B36, 0xffffffff illegal.
u32 | powerOnHours
| V3: The count of full uptime hours on this board, excluding any fractions lost to reboots.
u8 | initialPower
| V4: The bits determining which faces should provide/accept power at boot time.
u8 | watchdogResets
| V5: Which of last eight boots (LSB: most recent) involved watchdog resets.
u8 | reservedPadding [30]
| Reserved for future use; currently undefined; should not be read.
SFBChecksum | cs
| The checksum of the first 60 bytes of this block.

## Detailed Description

The exactly-64-byte-long SFB 'boot block' contents.

The SFBBootBlock structure is more complicated than it otherwise might be, to make it possible for an older tertiary bootloader to interoperate with a newer bootblock format in a reasonably sane way. In particular, an older tertiary bootloader should be able to verify the newer format, and get at the old fields that it knows about, without messing up newer fields it doesn't understand.

In addition, we reserve room in EEPROM for two SFBBootBlock, which are written to alternately, so that dying during a bootblock write will cause rollback to the prior bootblock, rather than the complete loss of all bootblock information. The value of the writeTag field determines which copy is 'current' and which is 'backup'.

This drastically reduces the chances that the (overall, redundant) boot block will be accidentally corrupted, even if a power failure occurs during a boot block update. Typically, in such a case, all that will happen is that interrupted update will be lost, and the backup, still-uncorrupted boot block will be treated as current instead.

Attention:

Although it is not documented with each method, note that all the SFBBootBlock methods have the potential to:

Blinks:
  E_API_EEPROM_ADDRESS or E_API_EEPROM_RESPONSE or E_API_EEPROM_DATA if there are problems accessing the EEPROM device.

## Field Documentation

u8 SFBBootBlock::initialPower

V4: The bits determining which faces should provide/accept power at boot time.

u32 SFBBootBlock::powerOnHours

V3: The count of full uptime hours on this board, excluding any fractions lost to reboots.

Note that maintaining this field involves an EEPROM write once an hour. This does age the EEPROM, although with the dual bootblocks it will take over two centuries to perform a million write operations. Nonetheless, if desired for whatever reason, incrementing of the powerOnHours can be suppressed by calling

     SET_REFLEX_FLAGS(RF_LESS_EEPROM);

.

u8 SFBBootBlock::version

V1: The version of the bootblock goes in the first byte.

If bootblock-handling code of a given version accesses a bootblock of a newer version, that older code must look only at the fields it understands (while faithfully double-buffering the entire block, however).

On the flip side, all future versions of the bootblock code must

1. be able to upgrade all prior bootblock versions, and
2. during such an upgrade process must change nothing in any preexisting field, except for the version.

u8 SFBBootBlock::writeTag

V1: Determines which bootblock copy is newer.

If both bootblocks are valid, as they typically will be, then the 'more ahead' (in the sense of IS_LATER, except on 8 bits) writeTag value wins.

The documentation for this struct was generated from the following file:

- src/include/SFBBootBlock.h