#include <libpropeller/libpropeller/sd/sd.h>

Inheritance diagram for libpropeller::SD:

Collaboration diagram for libpropeller::SD:

Public Member Functions
	~SD ()

void	Mount (const int basepin)

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

void	Unmount (void)

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

void	Close (void)

int	Get (void)

int	Get (char *read_buffer, int bytes_to_read_count)

int	Put (const char C)

int	Put (const char *B)

int	Put (const char *buffer, int byte_count)

int	PutFormatted (const char *formatString,...)

void	OpenRootDirectory (void)

bool	NextFile (char *filename)

bool	NextFile (char *filename, int &filesize)

bool	NextFile (char *filename, int &filesize, int &year, int &month, int &day, int &hour, int &minute, int &second)

int	Seek (const int position)

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

bool	HasError (void) const

void	ClearError (void)

int	GetError (void) const

int	GetClusterSize (void) const

int	GetClusterCount (void) const

int	GetFilesize (void) const

Static Public Attributes
static const int	kNoError = libpropeller::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 = libpropeller::SDSafeSPI::kErrorCardNotReset

static const int	kError3v3NotSupported = libpropeller::SDSafeSPI::kError3v3NotSupported

static const int	kErrorOcrFailed = libpropeller::SDSafeSPI::kErrorOcrFailed

static const int	kErrorBlockNotLongAligned = libpropeller::SDSafeSPI::kErrorBlockNotLongAligned

static const int	kErrorAsmNoReadToken = -libpropeller::SDSafeSPI::kErrorAsmNoReadToken

static const int	kErrorAsmBlockNotWritten = -libpropeller::SDSafeSPI::kErrorAsmBlockNotWritten

static const int	kErrorSpiEngineNotRunning = libpropeller::SDSafeSPI::kErrorSpiEngineNotRunning

static const int	kErrorCardBusyTimeout = libpropeller::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);

Definition at line 65 of file sd.h.

Constructor & Destructor Documentation

◆ ~SD()

libpropeller::SD::~SD ( )

Stops the SPI driver cog.

Definition at line 101 of file sd.h.

Here is the call graph for this function:

Member Function Documentation

◆ ClearError()

void libpropeller::SD::ClearError ( void )

Resets the error flag to kNoError.

Definition at line 666 of file sd.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Close()

void libpropeller::SD::Close ( void )

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.

Definition at line 367 of file sd.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Get() [1/2]

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

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.

Definition at line 412 of file sd.h.

◆ Get() [2/2]

int libpropeller::SD::Get ( void )

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.

Definition at line 390 of file sd.h.

◆ GetClusterCount()

int libpropeller::SD::GetClusterCount ( void ) const

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.

Definition at line 696 of file sd.h.

◆ GetClusterSize()

int libpropeller::SD::GetClusterSize ( void ) const

Get the FAT cluster size.

Returns: the size of the cluster, in bytes.

Definition at line 686 of file sd.h.

◆ GetError()

int libpropeller::SD::GetError ( void ) const

Get the error code.

Returns: The error code.

Definition at line 675 of file sd.h.

◆ GetFilesize()

int libpropeller::SD::GetFilesize ( void ) const

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

Definition at line 704 of file sd.h.

◆ HasError()

bool libpropeller::SD::HasError ( void ) const

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

Returns: The error code.

Definition at line 660 of file sd.h.

Here is the call graph for this function:

◆ Mount() [1/2]

void libpropeller::SD::Mount ( const int basepin )

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

Definition at line 114 of file sd.h.

◆ Mount() [2/2]

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

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.

Definition at line 125 of file sd.h.

Here is the call graph for this function:

◆ NextFile()

bool libpropeller::SD::NextFile ( char * filename )

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.

Definition at line 526 of file sd.h.

◆ Open()

void libpropeller::SD::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.

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

Definition at line 232 of file sd.h.

Here is the call graph for this function:

◆ OpenRootDirectory()

void libpropeller::SD::OpenRootDirectory ( void )

Set up for a directory file listing.

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

Definition at line 507 of file sd.h.

Here is the call graph for this function:

◆ Put() [1/3]

int libpropeller::SD::Put ( const char * B )

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.

Definition at line 461 of file sd.h.

Here is the call graph for this function:

◆ Put() [2/3]

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

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.

Definition at line 473 of file sd.h.

◆ Put() [3/3]

int libpropeller::SD::Put ( const char C )

Write a single character to the file.

Parameters

C	The character to write.

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

Definition at line 444 of file sd.h.

Here is the caller graph for this function:

◆ Seek()

int libpropeller::SD::Seek ( const int position )

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.

Definition at line 593 of file sd.h.

◆ SetDate()

int libpropeller::SD::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.

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

Definition at line 648 of file sd.h.

Here is the caller graph for this function:

◆ Unmount()

void libpropeller::SD::Unmount ( void )

Closes any open files, and unmounts the SD card. Frees a cog.

Definition at line 208 of file sd.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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

libpropeller/libpropeller/sd/sd.h
libpropeller/libpropeller/sd/sd.cpp

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~SD()

Member Function Documentation

◆ ClearError()

◆ Close()

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetClusterCount()

◆ GetClusterSize()

◆ GetError()

◆ GetFilesize()

◆ HasError()

◆ Mount() [1/2]

◆ Mount() [2/2]

◆ NextFile()

◆ Open()

◆ OpenRootDirectory()

◆ Put() [1/3]

◆ Put() [2/3]

◆ Put() [3/3]

◆ Seek()

◆ SetDate()

◆ Unmount()