ROSE  0.9.12.19
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
Rose::BinaryAnalysis::SRecord Class Reference

Description

S-Record hexadecimal data formats.

An S-Record is a simple ASCII-based format for conveying binary information, usually used for loading code and data onto an embedded processor. Multiple versions of S-Record formats exist, with the most popular being a Motorola syntax and an Intel syntax.

The Motorola S-Record format is also known as SRECORD, SREC, S19, S28, and S37. The "S19" name comes from the fact that record types 1 and 9 are used, allowing for 16-bit addresses; "s28" are record types 2 and 8 which allow 24-bit addresses; and "s37" are record types 3 and 7 which allow 32-bit addresses.

The Intel HEX format is another variant of S-Records. The sub-formats "I8HEX", "I16HEX", and "I32HEX" describe the address sizes that are supported, namely 16-bit, 20-bit, and 32-bit (note that the number in the format name doesn't actually match the address width in the first two cases).

ROSE's S-Record parser doesn't restrict which record types can appear within a file – it just parses whatever you hand it and returns a vector of SRecord objects. In fact, it will even allow the input to contain a mixture of Motorola and Intel syntax, although it will mark the less frequently-occuring syntax as errors. If any parsing errors are encountered, they are indicated within the individual SRecord objects.

Definition at line 25 of file SRecord.h.

#include <SRecord.h>

Classes

class  RunLengthEncoding
 Run-length encoding information. More...
 

Public Types

enum  Syntax {
  SREC_MOTOROLA,
  SREC_INTEL,
  SREC_UNKNOWN_SYNTAX
}
 Syntax of the S-Record. More...
 
enum  Type {
  SREC_M_HEADER,
  SREC_M_DATA16,
  SREC_M_DATA24,
  SREC_M_DATA32,
  SREC_M_RESERVED,
  SREC_M_COUNT16,
  SREC_M_COUNT24,
  SREC_M_START32,
  SREC_M_START24,
  SREC_M_START16,
  SREC_I_DATA,
  SREC_I_END,
  SREC_I_EXTENDED_SA,
  SREC_I_START_SA,
  SREC_I_EXTENDED_LA,
  SREC_I_START_LA,
  SREC_UNKNOWN_TYPE
}
 Type of S-Record. More...
 

Public Member Functions

 SRecord ()
 Construct an empty S-Record. More...
 
std::string toString () const
 Convert an S-Record to a string. More...
 
Syntax syntax () const
 Property: syntax family. More...
 
 SRecord (Type type, rose_addr_t addr, const std::vector< uint8_t > data)
 Construct an S-Record with data.
 
 SRecord (Type type, rose_addr_t addr, const uint8_t *buffer, size_t bufsz)
 Construct an S-Record with data.
 
Type type () const
 Property: record type.
 
SRecordtype (Type type)
 Property: record type.
 
rose_addr_t address () const
 Property: record starting address. More...
 
SRecordaddress (rose_addr_t addr)
 Property: record starting address. More...
 
const std::vector< uint8_t > & data () const
 Property: record data.
 
std::vector< uint8_t > & data ()
 Property: record data.
 
SRecorddata (const std::vector< uint8_t > &data)
 Property: record data.
 
const std::string & error () const
 Property: record error messsage.
 
SRecorderror (const std::string &error)
 Property: record error messsage.
 

Static Public Member Functions

static SRecord parse (const std::string &)
 Construct an S-Record by parsing a string. More...
 
static std::vector< SRecordparse (std::istream &)
 Construct S-Records by parsing a file. More...
 
static AddressIntervalSet dataAddresses (const std::vector< SRecord > &)
 Addresses occupied by all data. More...
 
static Sawyer::Optional< rose_addr_t > load (const std::vector< SRecord > &, const MemoryMap::Ptr &, bool createSegments=true, unsigned accessPerms=MemoryMap::READABLE|MemoryMap::WRITABLE|MemoryMap::EXECUTABLE, const std::string &newSegmentNames="S-Records")
 Load S-Records into a memory map. More...
 
static std::vector< SRecordcreate (const MemoryMap::Ptr &, Syntax, size_t bytesPerRecord=28, size_t preferredAddrSize=4)
 Create S-Records from a memory map. More...
 
static SRecord parseMotorola (const std::string &)
 Construct a Motorola S-Record by parsing a string. More...
 
static SRecord parseIntel (const std::string &)
 Construct an Intel S-Record by parsing a string. More...
 
static Sawyer::Optional< rose_addr_t > parseBigEndianInteger (const std::string &, size_t start, size_t nChars)
 Parse a hexadecimal string to an unsigned integer. More...
 
static unsigned bigEndian (const std::vector< uint8_t > &data, size_t nBytes)
 Convert the first few bytes of the buffer to a big-endian integer. More...
 
static size_t addressNBytes (Type)
 Size of address in bytes. More...
 
static uint8_t checksum (Syntax, const std::string &, size_t start, size_t n)
 Compute a checksum for part of a record. More...
 
void print (std::ostream &) const
 Print an S-Record to a stream.
 
std::ostream & operator<< (std::ostream &, const SRecord &)
 Print an S-Record to a stream.
 

Member Enumeration Documentation

Syntax of the S-Record.

Enumerator
SREC_MOTOROLA 

Motorola syntax S-Record.

SREC_INTEL 

Intel syntax S-Record.

SREC_UNKNOWN_SYNTAX 

Unknown or no syntax.

Definition at line 28 of file SRecord.h.

Type of S-Record.

Enumerator
SREC_M_HEADER 

Motorola vendor-specific header, usually NUL-terminated ASCII.

SREC_M_DATA16 

Motorola data with 16-bit address.

SREC_M_DATA24 

Motorola data with 24-bit address.

SREC_M_DATA32 

Motorola data with 32-bit address.

SREC_M_RESERVED 

Motorola reserved.

SREC_M_COUNT16 

Motorola 16-bit count of data records.

SREC_M_COUNT24 

Motorola 24-bit count of data records.

SREC_M_START32 

Motorola 32-bit starting address.

SREC_M_START24 

Motorola 24-bit starting address.

SREC_M_START16 

Motorola 16-bit starting address.

SREC_I_DATA 

Intel data record.

SREC_I_END 

Intel end record.

SREC_I_EXTENDED_SA 

Intel extended segment address.

SREC_I_START_SA 

Intel starting segment address.

SREC_I_EXTENDED_LA 

Intel extended linear address.

SREC_I_START_LA 

Intel starting linear address.

SREC_UNKNOWN_TYPE 

Not a valid S-Record.

Definition at line 35 of file SRecord.h.

Constructor & Destructor Documentation

Rose::BinaryAnalysis::SRecord::SRecord ( )
inline

Construct an empty S-Record.

Definition at line 70 of file SRecord.h.

Member Function Documentation

static SRecord Rose::BinaryAnalysis::SRecord::parse ( const std::string &  )
static

Construct an S-Record by parsing a string.

This parses either a Motorola or Intel syntax S-Record.

static std::vector<SRecord> Rose::BinaryAnalysis::SRecord::parse ( std::istream &  )
static

Construct S-Records by parsing a file.

Returns a vector with one element per line of input. Lines that did not contain an S-Record or which had trailing characters other than white space are reported as SRecord objects of type SREC_NONE and an error message.

static AddressIntervalSet Rose::BinaryAnalysis::SRecord::dataAddresses ( const std::vector< SRecord > &  )
static

Addresses occupied by all data.

The specified S-Records are scanned in order to create the set of memory addresses that the data will occupy, and this set is returned.

static Sawyer::Optional<rose_addr_t> Rose::BinaryAnalysis::SRecord::load ( const std::vector< SRecord > &  ,
const MemoryMap::Ptr ,
bool  createSegments = true,
unsigned  accessPerms = MemoryMap::READABLE|MemoryMap::WRITABLE|MemoryMap::EXECUTABLE,
const std::string &  newSegmentNames = "S-Records" 
)
static

Load S-Records into a memory map.

The specified S-Records are loaded into the memory map. If createSegments is true then a minimal number of segments are created to hold the S-Record data, otherwise the destinations must already be mapped or a MemoryMap::NotMapped exception is thrown. When new segments are created they are given access permissions specified by accessPerms and the name specified by newSegmentNames (or "S-Records"). Access permissions are not consulted and do not cause errors when writing S-Record data into the map.

Returns the starting execution address if one is specified. If multiple starting execution addresses are specified, then only the last one is returned.

static std::vector<SRecord> Rose::BinaryAnalysis::SRecord::create ( const MemoryMap::Ptr ,
Syntax  ,
size_t  bytesPerRecord = 28,
size_t  preferredAddrSize = 4 
)
static

Create S-Records from a memory map.

std::string Rose::BinaryAnalysis::SRecord::toString ( ) const

Convert an S-Record to a string.

Syntax Rose::BinaryAnalysis::SRecord::syntax ( ) const

Property: syntax family.

This is a read-only property computed from the record type.

rose_addr_t Rose::BinaryAnalysis::SRecord::address ( ) const
inline

Property: record starting address.

Note that Intel S-Record addresses are only partially specified in the individual S-Records; the actual full address depends on the S-Records that came before it. This property is only the partial address for Intel S-Records.

See also, RunLengthEncoding::dataAddress to get the fully specified address.

Definition at line 155 of file SRecord.h.

SRecord& Rose::BinaryAnalysis::SRecord::address ( rose_addr_t  addr)
inline

Property: record starting address.

Note that Intel S-Record addresses are only partially specified in the individual S-Records; the actual full address depends on the S-Records that came before it. This property is only the partial address for Intel S-Records.

See also, RunLengthEncoding::dataAddress to get the fully specified address.

Definition at line 156 of file SRecord.h.

static SRecord Rose::BinaryAnalysis::SRecord::parseMotorola ( const std::string &  )
static

Construct a Motorola S-Record by parsing a string.

static SRecord Rose::BinaryAnalysis::SRecord::parseIntel ( const std::string &  )
static

Construct an Intel S-Record by parsing a string.

static Sawyer::Optional<rose_addr_t> Rose::BinaryAnalysis::SRecord::parseBigEndianInteger ( const std::string &  ,
size_t  start,
size_t  nChars 
)
static

Parse a hexadecimal string to an unsigned integer.

The parsing looks at characters of the string starting at the specified offset and continuing for the specified number of characters. Each character in that range must be a valid hexadecimal digit representing four bits of the result in big-endian order. Returns the unsigned value if successful, or nothing if a syntax error, short read, or overflow is encountered.

static unsigned Rose::BinaryAnalysis::SRecord::bigEndian ( const std::vector< uint8_t > &  data,
size_t  nBytes 
)
static

Convert the first few bytes of the buffer to a big-endian integer.

static size_t Rose::BinaryAnalysis::SRecord::addressNBytes ( Type  )
static

Size of address in bytes.

The address is encoded in twice as many ASCII characters.

static uint8_t Rose::BinaryAnalysis::SRecord::checksum ( Syntax  ,
const std::string &  ,
size_t  start,
size_t  n 
)
static

Compute a checksum for part of a record.

Given a string, compute the checksum for the hexadecimal characters starting with the specified start offset and continuing for n characters. All characters in the range must be hexadecimal digits, and n must be even.


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