PropWare  3.0.0.224
C++ objects and CMake build system for Parallax Propeller
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
PropWare::SD Class Reference

A simple SD driver communicating over the SPI protocol. More...

#include <PropWare/memory/sd.h>

+ Inheritance diagram for PropWare::SD:
+ Collaboration diagram for PropWare::SD:

Public Types

enum  ErrorCode {
  NO_ERROR = 0,
  BEG_ERROR = SPI::END_ERROR + 1,
  INVALID_CMD = BEG_ERROR,
  READ_TIMEOUT,
  INVALID_NUM_BYTES,
  INVALID_RESPONSE,
  INVALID_INIT,
  INVALID_DAT_START_ID,
  CMD8_FAILURE,
  END_ERROR = CMD8_FAILURE
}
 

Public Member Functions

 unpack_sd_pins ((uint32_t *) pins)
 
this m_spi set_mosi (pins[0])
 
this m_spi set_miso (pins[1])
 
this m_spi set_sclk (pins[2])
 
this m_cs set_mask (pins[3])
 
this m_cs set ()
 
this m_cs set_dir_out ()
 
 SD (SPI &spi, const Port::Mask mosi, const Port::Mask miso, const Port::Mask sclk, const Port::Mask cs)
 Construct an SD object with the given SPI parameters. More...
 
PropWare::ErrorCode start () const
 Initialize SD card communication over SPI for 3.3V configuration. More...
 
uint16_t get_sector_size () const
 Return the size of a sector (also known as a "block") for the given storage device. More...
 
uint8_t get_sector_size_shift () const
 Determine the number of shifts required to multiply or divide a number by the sector size. More...
 
PropWare::ErrorCode read_data_block (const uint32_t address, uint8_t buf[]) const
 Read a block of data from the device into RAM. More...
 
PropWare::ErrorCode write_data_block (uint32_t address, const uint8_t dat[]) const
 Write data to a storage device. More...
 
uint16_t get_short (const uint16_t offset, const uint8_t buf[]) const
 Read two bytes from a buffer. More...
 
uint32_t get_long (const uint16_t offset, const uint8_t buf[]) const
 Read four bytes from a buffer. More...
 
void write_short (const uint16_t offset, uint8_t buf[], const uint16_t value) const
 Write two bytes to a buffer. More...
 
void write_long (const uint16_t offset, uint8_t buf[], const uint32_t value) const
 Write four bytes to a buffer. 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...
 
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...
 
void write_byte (const uint16_t offset, uint8_t buf[], const uint8_t value) const
 Write a byte to a buffer. More...
 

Static Public Member Functions

static void print_error_str (const Printer &printer, const ErrorCode err)
 Create a human-readable error string. More...
 
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)
 

Public Attributes

 __pad0__: m_spi(&spi) { Pin::Mask pins[4]
 Use the default SPI instance and pins for connecting to the SD card. More...
 

Detailed Description

A simple SD driver communicating over the SPI protocol.

When using PropWare's default SPI class, this allows the entire SPI/SD card/FAT functionality to run in a single cog.

Examples
FileReader_Demo.cpp, and FileWriter_Demo.cpp.

Definition at line 56 of file sd.h.

Member Enumeration Documentation

◆ ErrorCode

Error codes - preceded by SPI

Enumerator
NO_ERROR 

No error

BEG_ERROR 

First SD error code

INVALID_CMD 

SD Error 0

READ_TIMEOUT 

SD Error 1

INVALID_NUM_BYTES 

SD Error 2

INVALID_RESPONSE 

SD Error 3

INVALID_INIT 

SD Error 4

INVALID_DAT_START_ID 

SD Error 5

CMD8_FAILURE 

SD Error 6

END_ERROR 

Last SD error code

Definition at line 61 of file sd.h.

Constructor & Destructor Documentation

◆ SD()

PropWare::SD::SD ( SPI spi,
const Port::Mask  mosi,
const Port::Mask  miso,
const Port::Mask  sclk,
const Port::Mask  cs 
)

Construct an SD object with the given SPI parameters.

Parameters
[in]*spiAddress of a SPI instance. Its clock frequency and mode will be modified to fit the SD card's needs
[in]mosiPin mask for data line leaving the Propeller
[in]misoPin mask for data line going in to the Propeller
[in]sclkPin mask for clock line
[in]csPin mask for chip select

Definition at line 110 of file sd.h.

Member Function Documentation

◆ flush()

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

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
inherited

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()

uint32_t PropWare::SD::get_long ( const uint16_t  offset,
const uint8_t  buf[] 
) const
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

Implements PropWare::BlockStorage.

Definition at line 198 of file sd.h.

◆ get_sector_size()

uint16_t PropWare::SD::get_sector_size ( ) const
virtual

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

Returns
Bytes in a single sector

Implements PropWare::BlockStorage.

Definition at line 149 of file sd.h.

◆ get_sector_size_shift()

uint8_t PropWare::SD::get_sector_size_shift ( ) const
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)

Implements PropWare::BlockStorage.

Definition at line 153 of file sd.h.

◆ get_short()

uint16_t PropWare::SD::get_short ( const uint16_t  offset,
const uint8_t  buf[] 
) const
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

Implements PropWare::BlockStorage.

Definition at line 194 of file sd.h.

◆ 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 
)
staticinherited

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 
)
staticinherited

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:

◆ print_error_str()

static void PropWare::SD::print_error_str ( const Printer printer,
const ErrorCode  err 
)
static

Create a human-readable error string.

Parameters
[in]printerPrinter used for logging the message
[in]errError number used to determine error string

Definition at line 220 of file sd.h.

◆ read_data_block() [1/2]

PropWare::ErrorCode PropWare::SD::read_data_block ( const uint32_t  address,
uint8_t  buf[] 
) const
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

Special error handling is needed to ensure that, if an error is thrown, chip select is set high again before returning the error

Implements PropWare::BlockStorage.

Definition at line 157 of file sd.h.

+ Here is the call graph for this function:

◆ read_data_block() [2/2]

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

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
inherited

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()

PropWare::ErrorCode PropWare::SD::start ( ) const
virtual

Initialize SD card communication over SPI for 3.3V configuration.

Returns
Returns 0 upon success, error code otherwise

Implements PropWare::BlockStorage.

Definition at line 127 of file sd.h.

+ Here is the call graph for this function:

◆ write_byte()

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

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]

PropWare::ErrorCode PropWare::SD::write_data_block ( uint32_t  address,
const uint8_t  dat[] 
) const
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

Implements PropWare::BlockStorage.

Definition at line 177 of file sd.h.

+ Here is the call graph for this function:

◆ write_data_block() [2/2]

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

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()

void PropWare::SD::write_long ( const uint16_t  offset,
uint8_t  buf[],
const uint32_t  value 
) const
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

Implements PropWare::BlockStorage.

Definition at line 207 of file sd.h.

◆ write_short()

void PropWare::SD::write_short ( const uint16_t  offset,
uint8_t  buf[],
const uint16_t  value 
) const
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

Implements PropWare::BlockStorage.

Definition at line 202 of file sd.h.

Member Data Documentation

◆ __pad0__

PropWare::SD::__pad0__

Use the default SPI instance and pins for connecting to the SD card.

If a board configuration file has been predefined in PropGCC (such as dna.cfg for the Propeller DNA board), then an instance of PropWare::SD can be constructed without any arguments. This is very convenient for anyone using a common Propeller board that comes pre-equipped with an SD card adapter.

Parameters
[in]spiSPI instance. Its pins, clock frequency and mode will be modified to fit the SD card's needs

Definition at line 87 of file sd.h.


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