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] buffer Buffer 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]	offset	Offset from the beginning of the buffer
[in]	*buf	Address 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]	offset	Where 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]	offset	Where 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]	printer	Output console
[in]	buffer	Data in this container will be printed
[in]	words	Bytes in the buffer that should be printed
[in]	wordsPerLine	Bytes 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]	printer	Output console
[in]	data[]	Array with data to be printed
[in]	words	Bytes in the buffer that should be printed
[in]	wordsPerLine	Bytes 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]

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]	address	Address of the block on the storage device
[out]	*buffer	Address 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:

◆ read_data_block() [2/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]	address	Address 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:

◆ 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] *buffer Address 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]	offset	Address of the buffer to modify
[in]	buf[]	Buffer to modify
[in]	value	Value to be written in the buffer

Definition at line 274 of file blockstorage.h.

◆ write_data_block() [1/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]	address	Block address on the storage device
[in]	*buffer	Address 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_data_block() [2/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]	address	Block address on the storage device
[in]	dat	Array 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_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]	offset	Address of the buffer to modify
[in]	buf[]	Buffer to modify
[in]	value	Value 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]	offset	Address of the buffer to modify
[in]	buf[]	Buffer to modify
[in]	value	Value to be written in the buffer

Implemented in PropWare::SD.

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

PropWare/memory/blockstorage.h

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Class Documentation

◆ PropWare::BlockStorage::Buffer

Member Function Documentation

◆ flush()

◆ get_byte()

◆ get_long()

◆ get_sector_size()

◆ get_sector_size_shift()

◆ get_short()

◆ print_block() [1/2]

◆ print_block() [2/2]

◆ read_data_block() [1/2]

◆ read_data_block() [2/2]

◆ reload_buffer()

◆ start()

◆ write_byte()

◆ write_data_block() [1/2]

◆ write_data_block() [2/2]

◆ write_long()

◆ write_short()