FAT16/32 SD card interface. More...

#include <sd.h>

Public Member Functions
	~SD ()
	Stops the SPI driver cog. More...

void	Mount (const int basepin)
	Mounts a volume. More...

void	Mount (const int pin_do, const int pin_clk, const int pin_di, const int pin_cs)
	Mount a volume with explicit pin numbers. More...

void	Unmount (void)
	Closes any open files, and unmounts the SD card. More...

void	Open (const char *filename, const char file_mode)
	Close any currently open file, and open a new one with the given file name and mode. More...

void	Close (void)
	Flush and close the currently open file if any. More...

int	Get (void)
	Read and return a single character from the currently open file. More...

int	Get (char *read_buffer, int bytes_to_read_count)
	Read bytes into a buffer from currently open file. More...

int	Put (const char C)
	Write a single character to the file. More...

int	Put (const char *B)
	Write a null-terminated string to the file. More...

int	Put (const char *buffer, int byte_count)
	Write bytes from buffer into the currently open file. More...

void	OpenRootDirectory (void)
	Set up for a directory file listing. More...

bool	NextFile (char *filename)
	Find the next file in the root directory and extract its (8.3) name into filename. More...

int	Seek (const int position)
	Change the read pointer to a different position in the file. More...

int	SetDate (const int year, const int month, const int day, const int hour, const int minute, const int second)
	Set the current date and time for file creation and last modified. More...

bool	HasError (void) const
	If there was an error in the SD routines then this function will return an error code. More...

void	ClearError (void)
	Resets the error flag to kNoError. More...

int	GetError (void) const
	Get the error code. More...

int	GetClusterSize (void) const
	Get the FAT cluster size. More...

int	GetClusterCount (void) const
	Get the current FAT cluster count. More...

int	GetFilesize (void) const

Static Public Attributes
static const int	kNoError = SDSafeSPI::kNoError

static const int	kErrorNotFatVolume = -20

static const int	kErrorBadBytesPerSector = -21

static const int	kErrorBadSectorsPerCluster = -22

static const int	kErrorNotTwoFats = -23

static const int	kErrorBadFatSignature = -24

static const int	kErrorBufNotLongwordAligned = -512

static const int	kErrorFileNotFound = -1

static const int	kErrorNoEmptyDirectoryEntry = -2

static const int	kErrorBadArgument = -3

static const int	kErrorNoWritePermission = -6

static const int	kErrorEofWhileFollowingChain = -7

static const int	kErrorBadClusterValue = -9

static const int	kErrorBadClusterNumber = -26

static const int	kErrorFileNotOpenForWriting = -27

static const int	kErrorCardNotReset = SDSafeSPI::kErrorCardNotReset

static const int	kError3v3NotSupported = SDSafeSPI::kError3v3NotSupported

static const int	kErrorOcrFailed = SDSafeSPI::kErrorOcrFailed

static const int	kErrorBlockNotLongAligned = SDSafeSPI::kErrorBlockNotLongAligned

static const int	kErrorAsmNoReadToken = -SDSafeSPI::kErrorAsmNoReadToken

static const int	kErrorAsmBlockNotWritten = -SDSafeSPI::kErrorAsmBlockNotWritten

static const int	kErrorSpiEngineNotRunning = SDSafeSPI::kErrorSpiEngineNotRunning

static const int	kErrorCardBusyTimeout = SDSafeSPI::kErrorCardBusyTimeout

Detailed Description

FAT16/32 SD card interface.

This class is based on the Spin version of FSRW 2.6 by Rokicki and Lonesock. Thanks!

This object provides FAT16/32 file read/write access on a block device. Only one file can be open at a time. Open modes are 'r' (read), 'a' (append), 'w' (write), and 'd' (delete). Only the root directory is supported. No long filenames are supported. This object also supports traversing the root directory.

This object requires pullup resistors on the four SD card I/O lines. The pullup resistors should be approximately 10kOhms each.

The SPI DO, DI, and CLK lines can be shared with other SPI devices, as long as the Release() command is called after doing SD card activities and before doing other SPI activities. Note: this has not been tested at all.

Cluster size: If it's not 32768, it should be (32K clusters). To format a drive with FAT32 with 32K clusters, use the following command under linux: sudo fdisk -l sudo mkdosfs /dev/sdX -s 64 -F 32 -I

To check the filesystem under linux: sudo dosfsck -v /dev/sdX

Note: the mkdosfs command will format the entire disk, and erase all information on it.

If an exceptional error occurs then the HasError() function will return true. To see what went wrong, query the GetError() function. After you fix the error, clear it with ClearError(); Every function may set the error, although you're generally OK with just checking after Mount() and Open()

Warning: Untested with multiple instances!!!; The various Get() and Put() methods don't check to make sure that a file is open. It's up to your code to make sure that a file is successfully opened before you need to use it.

Author: SRLM (srlm@.nosp@m.srlm.nosp@m.produ.nosp@m.ctio.nosp@m.ns.co.nosp@m.m)

Possible improvements: Write a function that gets a string: int Get(char * Ubuf, char EndOfStringChar);

Constructor & Destructor Documentation

SD::~SD ( )

inline

Stops the SPI driver cog.

Here is the call graph for this function:

Member Function Documentation

void SD::ClearError ( void )

inline

Resets the error flag to kNoError.

Here is the call graph for this function:

void SD::Close ( void )

inline

Flush and close the currently open file if any.

Clears any errors.

Also reset the pointers to valid values. Also, releases the SD pins to tristate.

Here is the call graph for this function:

int SD::Get ( void )

inline

Read and return a single character from the currently open file.

Returns: -1 if the end of the file is reached. Otherwise, returns the character in the lower byte.

int SD::Get	(	char *	read_buffer,
		int	bytes_to_read_count
	)

inline

Read bytes into a buffer from currently open file.

Note that this function does not null terminate a string.

Parameters

read_buffer	The buffer to store the data. The buffer may be as large as you want.
bytes_to_read_count	The number of bytes to read.

Returns: Returns the number of bytes successfully read, or a negative number if there is an error. If the end of file has been reached, then this may be less than bytes_to_read_count.

int SD::GetClusterCount ( void ) const

inline

Get the current FAT cluster count.

What does this mean? I (SRLM) don't know. I also don't know how to test it, so it is not tested.

Returns: the cluster count.

int SD::GetClusterSize ( void ) const

inline

Get the FAT cluster size.

Returns: the size of the cluster, in bytes.

int SD::GetError ( void ) const

inline

Get the error code.

Returns: The error code.

Here is the call graph for this function:

int SD::GetFilesize ( void ) const

inline

Returns: The size of the current (read) file, in bytes.

bool SD::HasError ( void ) const

inline

If there was an error in the SD routines then this function will return an error code.

Returns: The error code.

Here is the call graph for this function:

void SD::Mount ( const int basepin)

inline

Mounts a volume.

Closes any open files (if this is a remount). Requires a cog for the SD SPI driver.

Parameters

basepin

pins must be in the following order, from basepin up:

Basepin +0: DO
Basepin +1: CLK
Basepin +2: DI
Basepin +3: CS

void SD::Mount	(	const int	pin_do,
		const int	pin_clk,
		const int	pin_di,
		const int	pin_cs
	)

inline

Mount a volume with explicit pin numbers.

Does not require adjacent pins.

Parameters

pin_do	The SPI Data Out pin (ouput relative to Propeller).
pin_clk	The SPI Clock pin.
pin_di	The SPI Data In pin (input relative to Propeller).
pin_cs	The Chip Select pin.

Here is the call graph for this function:

bool SD::NextFile ( char * filename)

inline

Find the next file in the root directory and extract its (8.3) name into filename.

The buffer must be sized to hold at least 13 characters (8 + 1 + 3 + 1).

Parameters

filename The extracted filename

Returns: true if there is a valid filename, false otherwise.

void SD::Open	(	const char *	filename,
		const char	file_mode
	)

inline

Close any currently open file, and open a new one with the given file name and mode.

The filename should be in 8.3 format (up to eight characters, a period, and up to three characters. The filename will be converted to uppercase. Valid characters include A through Z, digits 0 through 9, space, and '$', '', '-', '_', '@', '~', '`', '!', '(', ')', '{', '}', '^', '#', '&' and a single '.'. Filenames can be shorter than 8.3. The behavior for invalid filenames is undefined.

Modes:

'd' Delete a file. Deleting a file will not result in kErrorFileNotFound, even if nothing was deleted.
'a' Append to a file. If the file exists then calls to Put() will add the bytes to the end of the file. Otherwise, the file is created.
'w' Write to a file. If the file exists, it will be replaced.
'r' Read from a file. If the file does not exist, then an error is set.

Parameters

filename	Filename in 8.3 format.
file_mode	one of the modes described above

Here is the call graph for this function:

void SD::OpenRootDirectory ( void )

inline

Set up for a directory file listing.

Close the currently open file, and set up the read buffer for calls to nextfile().

Here is the call graph for this function:

int SD::Put ( const char C)

inline

Write a single character to the file.

Parameters

C	The character to write.

Returns: 0 if successful, a negative number if an error occurred.

int SD::Put ( const char * B)

inline

Write a null-terminated string to the file.

Parameters

B	The null-terminated string to write. No size limitations. Does not write the null terminator.

Returns: the number of bytes successfully written, or a negative number if there is an error.

Here is the call graph for this function:

int SD::Put	(	const char *	buffer,
		int	byte_count
	)

inline

Write bytes from buffer into the currently open file.

Parameters

buffer	The buffer to pull the data from. The buffer may be as large as you want.
byte_count	the number of bytes to write.

Returns: the number of bytes successfully written, or a negative number if there was an error.

int SD::Seek ( const int position)

inline

Change the read pointer to a different position in the file.

Seek() works only in 'r' (read) mode.

Parameters

position The position to seek to, relative to the beginning of the file. Units?

Returns: 0 on success, a negative number on failure (such as seeking during write). Failures may include seeking outside the file size.

int SD::SetDate	(	const int	year,
		const int	month,
		const int	day,
		const int	hour,
		const int	minute,
		const int	second
	)

inline

Set the current date and time for file creation and last modified.

This date and time will remain constant until the next time SetDate() is called.

Warning: parameter limits are not checked. Ie, a month of 13 will not generate an error.

Parameters

year	The year (range 1980 - 2106, all 4 digits!)
month	The month (range 1-12)
day	The day (range 1-31)
hour	The hour (range 0-23)
minute	The minute (range 0-59)
second	The second (range 0-59)

Returns: the FAT16 date format (you can safely ignore the return in all cases, unless you want to test the correctness of the function).

void SD::Unmount ( void )

inline

Closes any open files, and unmounts the SD card.

Frees a cog.

Here is the call graph for this function:

Member Data Documentation

const int SD::kError3v3NotSupported = SDSafeSPI::kError3v3NotSupported

static

const int SD::kErrorAsmBlockNotWritten = -SDSafeSPI::kErrorAsmBlockNotWritten

static

const int SD::kErrorAsmNoReadToken = -SDSafeSPI::kErrorAsmNoReadToken

static

const int SD::kErrorBadArgument = -3

static

const int SD::kErrorBadBytesPerSector = -21

static

const int SD::kErrorBadClusterNumber = -26

static

const int SD::kErrorBadClusterValue = -9

static

const int SD::kErrorBadFatSignature = -24

static

const int SD::kErrorBadSectorsPerCluster = -22

static

const int SD::kErrorBlockNotLongAligned = SDSafeSPI::kErrorBlockNotLongAligned

static

const int SD::kErrorBufNotLongwordAligned = -512

static

const int SD::kErrorCardBusyTimeout = SDSafeSPI::kErrorCardBusyTimeout

static

const int SD::kErrorCardNotReset = SDSafeSPI::kErrorCardNotReset

static

const int SD::kErrorEofWhileFollowingChain = -7

static

const int SD::kErrorFileNotFound = -1

static

const int SD::kErrorFileNotOpenForWriting = -27

static

const int SD::kErrorNoEmptyDirectoryEntry = -2

static

const int SD::kErrorNotFatVolume = -20

static

const int SD::kErrorNotTwoFats = -23

static

const int SD::kErrorNoWritePermission = -6

static

const int SD::kErrorOcrFailed = SDSafeSPI::kErrorOcrFailed

static

const int SD::kErrorSpiEngineNotRunning = SDSafeSPI::kErrorSpiEngineNotRunning

static

const int SD::kNoError = SDSafeSPI::kNoError

static

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

sd.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation