PropWare  3.0.0.224
C++ objects and CMake build system for Parallax Propeller
Classes | Public Member Functions | Static Public Member Functions | List of all members
PropWare::BlockStorage Class Referenceabstract

Any device that uses blocks as hardware level abstraction. More...

#include <PropWare/memory/blockstorage.h>

+ Inheritance diagram for PropWare::BlockStorage:

Classes

struct  Buffer
 In-memory buffer containing a single block of data. More...
 
struct  MetaData
 Metadata for a block of data. More...
 

Public Member Functions

virtual ErrorCode start () const =0
 Initialize and power up a storage device. More...
 
virtual ErrorCode read_data_block (uint32_t address, uint8_t buf[]) const =0
 Read a block of data from the device into RAM. More...
 
ErrorCode read_data_block (uint32_t address, const BlockStorage::Buffer *buffer) const
 
ErrorCode reload_buffer (const BlockStorage::Buffer *buffer) const
 Use a buffer's metadata to determine the address and read data from the storage device into memory. More...
 
virtual ErrorCode write_data_block (uint32_t address, const uint8_t dat[]) const =0
 Write data to a storage device. More...
 
ErrorCode write_data_block (uint32_t address, const BlockStorage::Buffer *buffer) const
 
ErrorCode flush (Buffer *buffer) const
 Flush the contents of a buffer and mark as unmodified. More...
 
uint8_t get_byte (const uint16_t offset, const uint8_t *buf) const
 Read a byte from a buffer. More...
 
virtual uint16_t get_short (const uint16_t offset, const uint8_t buf[]) const =0
 Read two bytes from a buffer. More...
 
virtual uint32_t get_long (const uint16_t offset, const uint8_t buf[]) const =0
 Read four bytes from a buffer. More...
 
void write_byte (const uint16_t offset, uint8_t buf[], const uint8_t value) const
 Write a byte to a buffer. More...
 
virtual void write_short (const uint16_t offset, uint8_t buf[], const uint16_t value) const =0
 Write two bytes to a buffer. More...
 
virtual void write_long (const uint16_t offset, uint8_t buf[], const uint32_t value) const =0
 Write four bytes to a buffer. More...
 
virtual uint16_t get_sector_size () const =0
 Return the size of a sector (also known as a "block") for the given storage device. More...
 
virtual uint8_t get_sector_size_shift () const =0
 Determine the number of shifts required to multiply or divide a number by the sector size. More...
 

Static Public Member Functions

static void print_block (const Printer &printer, const Buffer &buffer, const size_t words=512, const uint8_t wordsPerLine=16)
 Print the formatted contents of a buffer. More...
 
static void print_block (const Printer &printer, const uint8_t data[], const size_t words=512, const uint8_t wordsPerLine=16)
 

Detailed Description

Any device that uses blocks as hardware level abstraction.

Well suited for SD/MMC cards, floppy disk, CD drives, hard disk drives, solid state drives, and others. Ongoing work may be needed to remove lingering assumptions about generic block storage devices that I made based on my experience with SD cards.

Examples
FileReader_Demo.cpp, and FileWriter_Demo.cpp.

Definition at line 40 of file blockstorage.h.


Class Documentation

◆ PropWare::BlockStorage::Buffer

struct PropWare::BlockStorage::Buffer

In-memory buffer containing a single block of data.

Definition at line 71 of file blockstorage.h.

+ Collaboration diagram for PropWare::BlockStorage::Buffer:
Class Members
uint8_t * buf
MetaData * meta

Member Function Documentation

◆ flush()

ErrorCode PropWare::BlockStorage::flush ( Buffer buffer) const

Flush the contents of a buffer and mark as unmodified.

Parameters
[in]bufferBuffer to be written to the SD card - written only it was modified
Returns
0 upon success, error code otherwise

Definition at line 217 of file blockstorage.h.

◆ get_byte()

uint8_t PropWare::BlockStorage::get_byte ( const uint16_t  offset,
const uint8_t *  buf 
) const

Read a byte from a buffer.

Parameters
[in]offsetOffset from the beginning of the buffer
[in]*bufAddress of the buffer to read
Returns
Requested byte in the buffer

Definition at line 235 of file blockstorage.h.

◆ get_long()

virtual uint32_t PropWare::BlockStorage::get_long ( const uint16_t  offset,
const uint8_t  buf[] 
) const
pure virtual

Read four bytes from a buffer.

Devices such as SD cards use reverse byte order compared with the Propeller - this method should be implemented to ensure that the returned value is reversed if necessary. The user of this function should not need to worry about reversing bytes

Parameters
[in]offsetWhere in the buffer should the value be retrieved
[in]buf[]Address of the buffer to read
Returns
Requested bytes from the buffer

Implemented in PropWare::SD.

◆ get_sector_size()

virtual uint16_t PropWare::BlockStorage::get_sector_size ( ) const
pure virtual

Return the size of a sector (also known as a "block") for the given storage device.

Returns
Bytes in a single sector

Implemented in PropWare::SD.

◆ get_sector_size_shift()

virtual uint8_t PropWare::BlockStorage::get_sector_size_shift ( ) const
pure virtual

Determine the number of shifts required to multiply or divide a number by the sector size.

Because the Propeller does not have a hardware multiply/divide instruction, having the log_2(SECTOR_SIZE) can be helpful when you need to multiply or divide a number the sector size. Simply invoke this function and then shift left or right by the return value.

Returns
log_2(SECTOR_SIZE)

Implemented in PropWare::SD.

◆ get_short()

virtual uint16_t PropWare::BlockStorage::get_short ( const uint16_t  offset,
const uint8_t  buf[] 
) const
pure virtual

Read two bytes from a buffer.

Devices such as SD cards use reverse byte order compared with the Propeller - this method should be implemented to ensure that the returned value is reversed if necessary. The user of this function should not need to worry about reversing bytes

Parameters
[in]offsetWhere in the buffer should the value be retrieved
[in]buf[]Address of the buffer to read
Returns
Requested bytes from the buffer

Implemented in PropWare::SD.

◆ print_block() [1/2]

static void PropWare::BlockStorage::print_block ( const Printer printer,
const Buffer buffer,
const size_t  words = 512,
const uint8_t  wordsPerLine = 16 
)
static

Print the formatted contents of a buffer.

Parameters
[in]printerOutput console
[in]bufferData in this container will be printed
[in]wordsBytes in the buffer that should be printed
[in]wordsPerLineBytes to be printed before a newline

Definition at line 85 of file blockstorage.h.

◆ print_block() [2/2]

static void PropWare::BlockStorage::print_block ( const Printer printer,
const uint8_t  data[],
const size_t  words = 512,
const uint8_t  wordsPerLine = 16 
)
static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]printerOutput console
[in]data[]Array with data to be printed
[in]wordsBytes in the buffer that should be printed
[in]wordsPerLineBytes to be printed before a newline

Definition at line 100 of file blockstorage.h.

+ Here is the call graph for this function:

◆ read_data_block() [1/2]

virtual ErrorCode PropWare::BlockStorage::read_data_block ( uint32_t  address,
uint8_t  buf[] 
) const
pure virtual

Read a block of data from the device into RAM.

Parameters
[in]addressAddress of the block on the storage device
[out]buf[]Location in memory to store the block
Returns
0 upon success, error code otherwise

Implemented in PropWare::SD.

+ Here is the caller graph for this function:

◆ read_data_block() [2/2]

ErrorCode PropWare::BlockStorage::read_data_block ( uint32_t  address,
const BlockStorage::Buffer buffer 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]addressAddress of the block on the storage device
[out]*bufferAddress of the buffer to store data in
Returns
0 upon success, error code otherwise

Definition at line 169 of file blockstorage.h.

+ Here is the call graph for this function:

◆ reload_buffer()

ErrorCode PropWare::BlockStorage::reload_buffer ( const BlockStorage::Buffer buffer) const

Use a buffer's metadata to determine the address and read data from the storage device into memory.

Parameters
[in]*bufferAddress of a buffer
Precondition
Contents of the buffer will not be written to storage device prior to overwriting, so be sure it is flushed before invoking
Returns
0 if successful, error code otherwise

Definition at line 184 of file blockstorage.h.

+ Here is the call graph for this function:

◆ start()

virtual ErrorCode PropWare::BlockStorage::start ( ) const
pure virtual

Initialize and power up a storage device.

Returns
0 upon success, error code otherwise

Implemented in PropWare::SD.

◆ write_byte()

void PropWare::BlockStorage::write_byte ( const uint16_t  offset,
uint8_t  buf[],
const uint8_t  value 
) const

Write a byte to a buffer.

Parameters
[in]offsetAddress of the buffer to modify
[in]buf[]Buffer to modify
[in]valueValue to be written in the buffer

Definition at line 274 of file blockstorage.h.

◆ write_data_block() [1/2]

virtual ErrorCode PropWare::BlockStorage::write_data_block ( uint32_t  address,
const uint8_t  dat[] 
) const
pure virtual

Write data to a storage device.

Parameters
[in]addressBlock address on the storage device
[in]datArray of data to be written
Returns
0 upon success, error code otherwise

Implemented in PropWare::SD.

+ Here is the caller graph for this function:

◆ write_data_block() [2/2]

ErrorCode PropWare::BlockStorage::write_data_block ( uint32_t  address,
const BlockStorage::Buffer buffer 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]addressBlock address on the storage device
[in]*bufferAddress of the buffer that has data to be written
Returns
0 upon success, error code otherwise

Definition at line 206 of file blockstorage.h.

+ Here is the call graph for this function:

◆ write_long()

virtual void PropWare::BlockStorage::write_long ( const uint16_t  offset,
uint8_t  buf[],
const uint32_t  value 
) const
pure virtual

Write four bytes to a buffer.

Devices such as SD cards use reverse byte order compared with the Propeller - this method should be implemented to ensure that the parameter is reversed if necessary. The user of this function should not need to worry about reversing bytes

Parameters
[in]offsetAddress of the buffer to modify
[in]buf[]Buffer to modify
[in]valueValue to be written in the buffer

Implemented in PropWare::SD.

◆ write_short()

virtual void PropWare::BlockStorage::write_short ( const uint16_t  offset,
uint8_t  buf[],
const uint16_t  value 
) const
pure virtual

Write two bytes to a buffer.

Devices such as SD cards use reverse byte order compared with the Propeller - this method should be implemented to ensure that the parameter is reversed if necessary. The user of this function should not need to worry about reversing bytes

Parameters
[in]offsetAddress of the buffer to modify
[in]buf[]Buffer to modify
[in]valueValue to be written in the buffer

Implemented in PropWare::SD.


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