elftosb::EncoreBootImage::BootCommand Class Referenceabstract

Abstract base class for all bootloader commands. More...

`#include <EncoreBootImage.h>`

Inheritance diagram for elftosb::EncoreBootImage::BootCommand:
[legend]
Collaboration diagram for elftosb::EncoreBootImage::BootCommand:
[legend]

## Public Member Functions

| BootCommand ()
| Default constructor.
virtual | ~BootCommand ()
| Destructor.
virtual void | initFromData (const cipher_block_t *blocks, unsigned count, unsigned *consumed)=0
| Read the command contents from raw data. More...
Header
virtual uint8_t | getTag () const =0
| Pure virtual method to return the tag value for this command.
virtual void | fillCommandHeader (boot_command_t &header)=0
| Pure virtual method to construct the header for this boot command.
virtual uint8_t | calculateChecksum (const boot_command_t &header)
| Calculates the checksum for the given command header. More...
Cipher blocks
virtual unsigned | getBlockCount () const
| Returns the total number of cipher blocks. More...
virtual unsigned | getBlocks (unsigned offset, unsigned maxCount, cipher_block_t *data)
| Returns the contents of up to maxCount cipher blocks. More...
Data blocks
virtual unsigned | getDataBlockCount () const
| Returns the number of data cipher blocks that follow this command. More...
virtual unsigned | getDataBlocks (unsigned offset, unsigned maxCount, cipher_block_t *data)
| Returns the contents of up to maxCount data blocks. More...
Public Member Functions inherited from elftosb::EncoreBootImage::CipherBlockGenerator
virtual void | debugPrint () const
| Print out a string representation of the object.

## Static Public Member Functions

static BootCommand * | createFromData (const cipher_block_t *blocks, unsigned count, unsigned *consumed)
| Creates the correct subclass of BootCommand for the given raw data. More...

## Protected Types

enum | { CMD_TAG_FIELD = 1, CMD_FLAGS_FIELD = 2, CMD_ADDRESS_FIELD = 4, CMD_COUNT_FIELD = 8, CMD_DATA_FIELD = 16 }
| The flag bit values for the whichFields parameter of validateHeader().

## Protected Member Functions

void | validateHeader (const boot_command_t *modelHeader, const boot_command_t *testHeader, unsigned whichFields)

## Detailed Description

Abstract base class for all bootloader commands.

## Member Function Documentation

uint8_t EncoreBootImage::BootCommand::calculateChecksum | ( | const boot_command_t & | header | ) |

virtual

Calculates the checksum for the given command header.

The checksum algorithm is totally straightforward, except that the initial checksum byte value is set to 0x5a instead of 0.

EncoreBootImage::BootCommand * EncoreBootImage::BootCommand::createFromData | ( | const cipher_block_t * | blocks,
|  | unsigned | count,
|  | unsigned * | consumed
| ) |  |

static

Creates the correct subclass of BootCommand for the given raw data.

Parameters

  | blocks | Pointer to the raw data blocks.
  | count | Number of blocks pointed to by blocks.
  [out] | consumed | On exit, this points to the number of cipher blocks that were occupied by the command. Should be at least 1 for every command. This must not be NULL on entry!

Returns
  A new boot command instance.

Return values

  NULL | The boot command pointed to by blocks was not recognized as a known command type.

Exceptions

  std::runtime_error | This exception indicates that a command was recognized but contained invalid data. Compare this to a NULL result which indicates that no command was recognized at all.

unsigned EncoreBootImage::BootCommand::getBlockCount | ( |  | ) | const

virtual

Returns the total number of cipher blocks.

The default implementation returns 0, indicating that no blocks are available.

Reimplemented from elftosb::EncoreBootImage::CipherBlockGenerator.

unsigned EncoreBootImage::BootCommand::getBlocks | ( | unsigned | offset,
|  | unsigned | maxCount,
|  | cipher_block_t * | data
| ) |  |

virtual

Returns the contents of up to maxCount cipher blocks.

Up to maxCount cipher blocks are copied into the buffer pointed to by the data argument. The index of the first block to copy is held in the offset argument.

Parameters

  offset | Starting block number to copy. Zero means the first available block.
  maxCount | Up to this number of blocks may be copied into data. Must be 1 or greater.
  data | Buffer for outgoing cipher blocks. Must have enough room to hold maxCount blocks.

Returns
  The number of cipher blocks copied into data.

Return values

  0 | No more blocks are available and nothing was written to data.

Exceptions

  std::out_of_range | If offset is invalid.

Reimplemented from elftosb::EncoreBootImage::CipherBlockGenerator.

virtual unsigned elftosb::EncoreBootImage::BootCommand::getDataBlockCount | ( |  | ) | const

inlinevirtual

Returns the number of data cipher blocks that follow this command.

The default implementation returns 0, indicating that no data blocks are available.

Reimplemented in elftosb::EncoreBootImage::LoadCommand.

virtual unsigned elftosb::EncoreBootImage::BootCommand::getDataBlocks | ( | unsigned | offset,
|  | unsigned | maxCount,
|  | cipher_block_t * | data
| ) |  |

inlinevirtual

Returns the contents of up to maxCount data blocks.

Up to maxCount data blocks are copied into the buffer pointed to by the data argument. This is only a request for maxCount blocks, the subclass implementation of this method is free to return any number of blocks from 0 up to maxCount. A return value of 0 indicates that no more blocks are available. The index of the first block to copy is held in the offset argument.

Parameters

  offset | Starting block number to copy. Zero means the first available block.
  maxCount | Up to this number of blocks may be copied into data. Must be 1 or greater.
  data | Buffer for outgoing data blocks. Must have enough room to hold maxCount blocks.

Returns
  The number of data blocks copied into data.

Return values

  0 | No more blocks are available and nothing was written to data.

Reimplemented in elftosb::EncoreBootImage::LoadCommand.

virtual void elftosb::EncoreBootImage::BootCommand::initFromData | ( | const cipher_block_t * | blocks,
|  | unsigned | count,
|  | unsigned * | consumed
| ) |  |

pure virtual

Read the command contents from raw data.

The subclass implementations should validate the contents of the command, including the fields of the command header in the first block. It should be assumed that only the tag field was examined to determine which subclass of BootCommand should be created.

Parameters

  | blocks | Pointer to the raw data blocks.
  | count | Number of blocks pointed to by blocks.
  [out] | consumed | On exit, this points to the number of cipher blocks that were occupied by the command. Should be at least 1 for every command. This must not be NULL on entry!

Implemented in elftosb::EncoreBootImage::MemEnableCommand, elftosb::EncoreBootImage::ResetCommand, elftosb::EncoreBootImage::JumpCommand, elftosb::EncoreBootImage::ProgramCommand, elftosb::EncoreBootImage::EraseCommand, elftosb::EncoreBootImage::ModeCommand, elftosb::EncoreBootImage::FillCommand, elftosb::EncoreBootImage::LoadCommand, elftosb::EncoreBootImage::TagCommand, and elftosb::EncoreBootImage::NopCommand.

void EncoreBootImage::BootCommand::validateHeader | ( | const boot_command_t * | modelHeader,
|  | const boot_command_t * | testHeader,
|  | unsigned | whichFields
| ) |  |

protected

The checksum field of testHeader is always computed and checked against itself. All other fields are compared to the corresponding value set in modelHeader if the appropriate flag is set in whichFields. For example, the m_address fields in testHeader and modelHeader are compared when the CMD_ADDRESS_FIELD bit is set in whichFields. An exception is thrown if any comparison fails.

Parameters

  modelHeader | The baseline header to compare against. Only those fields that have corresponding bits set in whichFields need to be set.
  testHeader | The actual command header which is being validated.

  whichFields

  A bitfield used to determine which fields of the boot command header are compared. Possible values are:
  - CMD_TAG_FIELD
  - CMD_FLAGS_FIELD
  - CMD_ADDRESS_FIELD
  - CMD_COUNT_FIELD
  - CMD_DATA_FIELD

Exceptions

  std::runtime_error | Thrown if any requested validation fails.

The documentation for this class was generated from the following files:

- EncoreBootImage.h
- EncoreBootImage.cpp