Multi Media Card Library

The Multi Media Card (MMC) is a Flash memory card standard. MMC cards are currently available in sizes up to and including 32 GB and are used in cellular phones, digital audio players, digital cameras and PDA’s.
mikroBasic PRO for FT90x provides a library for accessing data on Multi Media Card via SPI communication. This library also supports SD (Secure Digital) and high capacity SDHC (Secure Digital High Capacity) memory cards .

Secure Digital Card

Secure Digital (SD) is a Flash memory card standard, based on the older Multi Media Card (MMC) format.
SD cards are currently available in sizes of up to and including 2 GB, and are used in digital cameras, digital camcorders, handheld computers, media players, mobile phones, GPS receivers, video games and PDAs.

Secure Digital High Capacity Card

SDHC (Secure Digital High Capacity, SD 2.0) is an extension of the SD standard which increases card's storage capacity up to 32 GB by using sector addressing instead of byte addressing in the previous SD standard.
SDHC cards share the same physical and electrical form factor as older (SD 1.x) cards, allowing SDHC-devices to support both newer SDHC cards and older SD-cards. The current standard limits the maximum capacity of an SDHC card to 32 GB.

Important :

Routines for file handling can be used only with FAT16 file system.
Library functions create and read files from the root directory only.
Library functions populate both FAT1 and FAT2 tables when writing to files, but the file data is being read from the FAT1 table only; i.e. there is no recovery if the FAT1 table gets corrupted.
If MMC/SD card has Master Boot Record (MBR), the library will work with the first available primary (logical) partition that has non-zero size. If MMC/SD card has Volume Boot Record (i.e. there is only one logical partition and no MBRs), the library works with entire card as a single partition. For more information on MBR, physical and logical drives, primary/secondary partitions and partition tables, please consult other resources, e.g. Wikipedia and similar.
Before write operation, make sure you don’t overwrite boot or FAT sector as it could make your card on PC or digital camera unreadable. Drive mapping tools, such as Winhex, can be of a great assistance.
Library uses SPI module for communication. The user must initialize the appropriate SPI module before using the MMC Library.
For MCUs with multiple SPI modules it is possible to initialize all of them and then switch by using the SPIM_Set_Active() function. See the SPI Library functions.

Tip : Once the MMC/SD card is initialized, SPI module can be reinitialized at higher a speed. See the Mmc_Init and Mmc_Fat_Init routines.

Library Dependency Tree

External dependencies of MMC Library

The following variable must be defined in all projects using MMC library:	Description :	Example :
`dim Mmc_Chip_Select as sbit sfr external`	Chip select pin.	`dim Mmc_Chip_Select as sbit at GPIO_PIN33_bit`

Routines for file handling:

Mmc_Fat_Init
Mmc_Fat_QuickFormat
Mmc_Fat_Assign
Mmc_Fat_Reset
Mmc_Fat_Read
Mmc_Fat_Rewrite
Mmc_Fat_Append
Mmc_Fat_Delete
Mmc_Fat_Write
Mmc_Fat_Set_File_Date
Mmc_Fat_Get_File_Date
Mmc_Fat_Get_File_Date_Modified
Mmc_Fat_Get_File_Size
Mmc_Get_File_Write_Sector
Mmc_Fat_Get_Swap_File
Mmc_Fat_Tell
Mmc_Fat_Seek
Mmc_Fat_Rename
Mmc_Fat_MakeDir
Mmc_Fat_RenameDir
Mmc_Fat_RemoveDir
Mmc_Fat_ChangeDir
Mmc_Fat_Exists
Mmc_Fat_Dir
Mmc_Fat_ReadDir
Mmc_Fat_Activate
Mmc_Fat_ReadN
Mmc_Fat_Open
Mmc_Fat_Close
Mmc_Fat_EOF

Mmc_Init

Prototype	sub function Mmc_Init() as word
Description	Initializes MMC through hardware SPI or SD host interface. Mmc_Init needs to be called before using other functions of this library.
Parameters	None.
Returns	`0` - if MMC/SD card was detected and successfully initialized `1` - otherwise
Requires	External dependencies of the library from the top of the page must be defined before using this function. The appropriate hardware SPI or SD Host module must be previously initialized. See the SPIM1_Init, SPIM1_Init_Advanced, SDHost_Init and Mmc_Set_Interface routines.
Example	' MMC Chip Select connection dim Mmc_Chip_Select as sbit at GPIO_PIN33_bit ... ' initialize a MMC card mmc_error = Mmc_Init() if (mmc_error = 0) then ... end if
Notes	None.

Mmc_Read_Sector

Prototype	sub function Mmc_Read_Sector(dim sector as longword, dim byref dbuff as byte[512]) as word
Description	The function reads one sector (512 bytes) from MMC card.
Parameters	`sector:` MMC/SD card sector to be read. `dbuff:` buffer of minimum 512 bytes in length for data storage.
Returns	`0` - if reading was successful `1` - if an error occurred
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	' read sector 510 of the MMC/SD card dim error as word sectorNo as longword dataBuffer as byte[512] ... sectorNo = 510 error = Mmc_Read_Sector(sectorNo, dataBuffer)
Notes	None.

Mmc_Write_Sector

Prototype	sub function Mmc_Write_Sector(dim sector as longword, dim byref data as byte[512]) as word
Description	The function writes 512 bytes of data to one MMC card sector.
Parameters	`sector:` MMC/SD card sector to be written to. `dbuff:` data to be written (buffer of minimum 512 bytes in length).
Returns	`0` - if writing was successful `1` - if there was an error in sending write command `2` - if there was an error in writing (data rejected)
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	' write to sector 510 of the MMC/SD card dim error as word sectorNo as longword dataBuffer as byte[512] ... sectorNo = 510 error = Mmc_Write_Sector(sectorNo, dataBuffer)
Notes	None.

Mmc_Read_Cid

Prototype	sub function Mmc_Read_Cid(dim byref data_cid as byte[16]) as byte
Description	The function reads 16-byte CID register.
Parameters	`data_cid:` buffer of minimum 16 bytes in length for storing CID register content.
Returns	`0` - if CID register was read successfully `1` - if there was an error while reading
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	dim error as word dataBuffer as byte[512] ... error = Mmc_Read_Cid(dataBuffer)
Notes	None.

Mmc_Read_Csd

Prototype	sub function Mmc_Read_Csd(dim byref data_csd as byte[16]) as word
Description	The function reads 16-byte CSD register.
Parameters	`data_csd:` buffer of minimum 16 bytes in length for storing CSD register content.
Returns	`0` - if CSD register was read successfully `1` - if there was an error while reading
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	dim error as word dataBuffer as byte[512] ... error = Mmc_Read_Csd(dataBuffer)
Notes	None.

Mmc_Multi_Read_Start

Prototype	sub function Mmc_Multi_Read_Start(dim sector as longword) as word
Description	The function starts multi read mode, sectors are sequentially read starting from the sector given in the function argument.
Parameters	`sector:` starting sector number.
Returns	`0` - if multi read start was successful. `1` - ir error occured.
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	dim error as word dim sector as longword ... error = Mmc_Multi_Read_Start(sector)
Notes	None.

Mmc_Multi_Read_Sector

Prototype	sub procedure Mmc_Multi_Read_Sector(dim byref dbuff as byte[512])
Description	The procedure reads sectors in multi read mode and places them in the buffer given as the function argument. Next function call reads the subsequent sector. Buffer size should be 512B.
Parameters	`dbuff:` buffer for holding the sector data.
Returns	Nothing.
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	dim dataBuffer as byte[512] ... Mmc_Multi_Read_Sector(dataBuffer)
Notes	None.

Mmc_Multi_Read_Stop

Prototype	sub function Mmc_Multi_Read_Stop() as word
Description	The function stops multi read mode sequence.
Parameters	None.
Returns	`0` - if stop was successful. `1` - ir error was detected.
Requires	MMC/SD card must be initialized. See Mmc_Init.
Example	error = Mmc_Multi_Read_Stop()
Notes	None.

Mmc_Set_Interface

Prototype

sub procedure Mmc_Set_Interface(dim setInterface as byte)

Description

The function sets used MMC interface - SPI or SD I/O.

Parameters

setInterface: parameter used to sed desired interface. Valid values :

Value	Description
_MMC_INTERFACE_SPI	MMC SPI Interface.
_MMC_INTERFACE_SDHOST	MMC SD Host Interface.

Returns

Nothing.

Requires

This routine must be called before the Mmc_Init routine.
External dependencies of the library from the top of the page must be defined before using this function.

Example

' Set SDHost interface
Mmc_Set_Interface(_MMC_INTERFACE_SDHOST)

Notes

By default, the SPI interface is set in the library.

Mmc_Fat_Init

Prototype	sub function Mmc_Fat_Init() as word
Description	Initializes MMC/SD card, reads MMC/SD FAT16 boot sector and extracts necessary data needed by the library.
Parameters	None.
Returns	`0` - if MMC/SD card was detected and successfully initialized `1` - if FAT16 boot sector was not found `255` - if MMC/SD card was not detected
Requires	External dependencies of the library from the top of the page must be defined before using this function. The appropriate hardware SPI module must be previously initialized. See the SPIM1_Init, SPIM1_Init_Advanced routines.
Example	' MMC Chip Select connection dim Mmc_Chip_Select as sbit at GPIO_PIN33_bit ... ' Initialize SPI module SPIM1_Init_Advanced(_SPI_MASTER_CLK_RATIO_64, _SPI_CFG_POLARITY_IDLE_LOW or _SPI_CFG_PHASE_CAPTURE_FALLING, _SPI_SS_LINE_NONE) ' use fat16 quick format instead of init routine if a formatting is needed if (Mmc_Fat_Init() = 0) then ... end if
Notes	MMC/SD card has to be formatted to FAT16 file system.

Mmc_Fat_QuickFormat

Prototype	sub function Mmc_Fat_QuickFormat(dim byref mmc_fat_label as string[11]) as word
Description	Formats to FAT16 and initializes MMC/SD card.
Parameters	`mmc_fat_label:` volume label (11 characters in length). If less than 11 characters are provided, the label will be padded with spaces. If null string is passed volume will not be labeled
Returns	`0` - if MMC/SD card was detected, successfully formated and initialized `1` - if FAT16 format was unseccessful `255` - if MMC/SD card was not detected
Requires	The appropriate hardware SPI module must be previously initialized. See the SPIM1_Init, SPIM1_Init_Advanced routines.
Example	' MMC Chip Select connection dim Mmc_Chip_Select as sbit at GPIO_PIN33_bit ... ' Initialize SPI module SPIM1_Init_Advanced(_SPI_MASTER_CLK_RATIO_64, _SPI_CFG_POLARITY_IDLE_LOW or _SPI_CFG_PHASE_CAPTURE_FALLING, _SPI_SS_LINE_NONE) ' use fat16 quick format instead of init routine if a formatting is needed if (Mmc_Fat_QuickFormat() = 0) then ... end if
Notes	This routine can be used instead or in conjunction with Mmc_Fat_Init routine. If MMC/SD card already contains a valid boot sector, it will remain unchanged (except volume label field) and only FAT and ROOT tables will be erased. Also, the new volume label will be set.

Mmc_Fat_Assign

Prototype

sub function Mmc_Fat_Assign(dim byref filename as char[11], dim file_cre_attr as byte) as word

Description

Assigns file for file operations (read, write, delete...). All subsequent file operations will be applied on an assigned file.

Parameters

filename: name of the file that should be assigned for file operations. File name should be in DOS 8.3 (file_name.extension) format. The file name and extension will be automatically padded with spaces by the library if they have less than length required (i.e. "mikro.tx" -> "mikro .tx "), so the user does not have to take care of that. The file name and extension are case insensitive. The library will convert them to proper case automatically, so the user does not have to take care of that.
file_cre_attr: file creation and attributes flags. Each bit corresponds to the appropriate file attribute:

Bit Mask Description

0 0x01 Read Only

1 0x02 Hidden

2 0x04 System

3 0x08 Volume Label

4 0x10 Subdirectory

5 0x20 Archive

6 0x40 Device (internal use only, never found on disk)

7 0x80 File creation flag. If file does not exist and this flag is set, a new file with specified name will be created.

Returns

2 - if there are no more free file handlers, currently opened file is closed in order to free space.
1 - if file already exists or file does not exist but a new file is created.
0 - if file does not exist and no new file is created.

Requires

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

Example

' create file with archive attribut if it does not already exist
Mmc_Fat_Assign("MIKRO007.TXT",0xA0)

Notes

Long File Names (LFN) are not supported.

Mmc_Fat_Reset

Prototype	sub procedure Mmc_Fat_Reset(dim byref size as longword)
Description	Procedure resets the file pointer (moves it to the start of the file) of the assigned file, so that the file can be read.
Parameters	`size:` buffer to store file size to. After file has been opened for reading, its size is returned through this parameter.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim size as longword ... Mmc_Fat_Reset(size)
Notes	None.

Mmc_Fat_Read

Prototype	sub procedure Mmc_Fat_Read(dim byref bdata as byte)
Description	Reads a byte from the currently assigned file opened for reading. Upon function execution file pointers will be set to the next character in the file.
Parameters	`bdata:` buffer to store read byte to. Upon this function execution read byte is returned through this parameter.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign. The file must be opened for reading. See Mmc_Fat_Reset.
Example	dim character as byte ... Mmc_Fat_Read(character)
Notes	None.

Mmc_Fat_Rewrite

Prototype	sub procedure Mmc_Fat_Rewrite()
Description	Opens the currently assigned file for writing. If the file is not empty its content will be erased.
Parameters	None.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	' open file for writing Mmc_Fat_Rewrite()
Notes	None.

Mmc_Fat_Append

Prototype	sub procedure Mmc_Fat_Append()
Description	Opens the currently assigned file for appending. Upon this function execution file pointers will be positioned after the last byte in the file, so any subsequent file write operation will start from there.
Parameters	None.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	' open file for appending Mmc_Fat_Append()
Notes	None.

Mmc_Fat_Delete

Prototype	sub procedure Mmc_Fat_Delete()
Description	Deletes currently assigned file from MMC/SD card.
Parameters	None.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	' delete current file Mmc_Fat_Delete()
Notes	None.

Mmc_Fat_Write

Prototype	sub procedure Mmc_Fat_Write(dim byref fdata as byte[512], dim data_len as word)
Description	Writes requested number of bytes to the currently assigned file opened for writing.
Parameters	`fdata:` data to be written. `data_len:` number of bytes to be written.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign. The file must be opened for writing. See Mmc_Fat_Rewrite or Mmc_Fat_Append.
Example	dim file_contents as byte[42] ... Mmc_Fat_Write(file_contents, 42) ' write data to the assigned file
Notes	None.

Mmc_Fat_Set_File_Date

Prototype	sub procedure Mmc_Fat_Set_File_Date(dim year as word, dim month as byte, dim day as byte, dim hours as byte, dim mins as byte, dim seconds as byte)
Description	Sets the date/time stamp. Any subsequent file write operation will write this stamp to the currently assigned file's time/date attributes.
Parameters	`year:` year attribute. Valid values: 1980-2107 `month:` month attribute. Valid values: 1-12 `day:` day attribute. Valid values: 1-31 `hours:` hours attribute. Valid values: 0-23 `mins:` minutes attribute. Valid values: 0-59 `seconds:` seconds attribute. Valid values: 0-59
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign. The file must be opened for writing. See Mmc_Fat_Rewrite or Mmc_Fat_Append.
Example	Mmc_Fat_Set_File_Date(2005,9,30,17,41,0)
Notes	None.

Mmc_Fat_Get_File_Date

Prototype	sub procedure Mmc_Fat_Get_File_Date(dim byref year as word, dim byref month as byte, dim byref day as byte, dim byref hours as byte, dim byref mins as byte)
Description	Reads time/date attributes of the currently assigned file.
Parameters	`year:` buffer to store year attribute to. Upon function execution year attribute is returned through this parameter. `month:` buffer to store month attribute to. Upon function execution month attribute is returned through this parameter. `day:` buffer to store day attribute to. Upon function execution day attribute is returned through this parameter. `hours:` buffer to store hours attribute to. Upon function execution hours attribute is returned through this parameter. `mins:` buffer to store minutes attribute to. Upon function execution minutes attribute is returned through this parameter.
Returns	Nothing.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim year as word month, day, hours, mins as byte ... Mmc_Fat_Get_File_Date(year, month, day, hours, mins)
Notes	None.

Mmc_Fat_Get_File_Date_Modified

Prototype	sub procedure Mmc_Fat_Get_File_Date_Modified(dim byref year as word, dim byref month as byte, dim byref day as byte, dim byref hours as byte, dim byref mins as byte)
Description	Retrieves the last modification date/time for the currently selected file. Seconds are not being retrieved since they are written in 2-sec increments.
Parameters	`year:` buffer to store year attribute to. Upon function execution year attribute is returned through this parameter. `month:` buffer to store month attribute to. Upon function execution month attribute is returned through this parameter. `day:` buffer to store day attribute to. Upon function execution day attribute is returned through this parameter. `hours:` buffer to store hours attribute to. Upon function execution hours attribute is returned through this parameter. `mins:` buffer to store minutes attribute to. Upon function execution minutes attribute is returned through this parameter.
Returns	Nothing.
Requires	The file must be assigned, see Mmc_Fat_Assign.
Example	dim year as word month, day, hours, mins as byte ... Mmc_Fat_Get_File_Date_Modified(year, month, day, hours, mins)

Mmc_Fat_Get_File_Size

Prototype	sub function Mmc_Fat_Get_File_Size() as longword
Description	This function reads size of the currently assigned file in bytes.
Parameters	None.
Returns	This function returns size of active file (in bytes).
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim my_file_size as longword ... my_file_size = Mmc_Fat_Get_File_Size()
Notes	None.

Mmc_Get_File_Write_Sector

Prototype	sub function Mmc_Get_File_Write_Sector() as longword
Description	This function returns the current file write sector.
Parameters	None.
Returns	This function returns the current file write sector.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim sector as longword ... sector = Mmc_Get_File_Write_Sector()
Notes	None.

Mmc_Fat_Get_Swap_File

Prototype

sub function Mmc_Fat_Get_Swap_File(dim sectors_cnt as longword, dim byref filename as string[11], dim file_attr as byte) as longword

Description

This function is used to create a swap file of predefined name and size on the MMC/SD media. If a file with specified name already exists on the media, search for consecutive sectors will ignore sectors occupied by this file. Therefore, it is recommended to erase such file if it already exists before calling this function. If it is not erased and there is still enough space for a new swap file, this function will delete it after allocating new memory space for a new swap file.

The purpose of the swap file is to make reading and writing to MMC/SD media as fast as possible, by using the Mmc_Read_Sector() and Mmc_Write_Sector() functions directly, without potentially damaging the FAT system. The swap file can be considered as a "window" on the media where the user can freely write/read data. It's main purpose in this library is to be used for fast data acquisition; when the time-critical acquisition has finished, the data can be re-written into a "normal" file, and formatted in the most suitable way.

Parameters

sectors_cnt: number of consecutive sectors that user wants the swap file to have.
filename: name of the file that should be assigned for file operations. File name should be in DOS 8.3 (file_name.extension) format. The file name and extension will be automatically padded with spaces by the library if they have less than length required (i.e. "mikro.tx" -> "mikro .tx "), so the user does no have to take care of that. The file name and extension are case insensitive. The library will convert them to proper case automatically, so the user does not have to take care of that.
Also, in order to keep backward compatibility with the first version of this library, file names can be entered as UPPERCASE string of 11 bytes in length with no dot character between file name and extension (i.e. "MIKROELETXT" -> MIKROELE.TXT). In this case last 3 characters of the string are considered to be file extension.
file_attr: file creation and attributes flags. Each bit corresponds to the appropriate file attribute:

Returns

Number of the start sector for the newly created swap file, if there was enough free space on the MMC/SD card to create file of required size.
0 - otherwise.

Requires

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

Example

'-------------- Try to create a swap file with archive atribute, whose size will be at least 1000 sectors.
'               If it succeeds, it sends No. of start sector over UART
dim size as longword
...
size = Mmc_Fat_Get_Swap_File(1000, "mikroE.txt", 0x20)
if (size <> 0) then
  UART1_Write(0xAA)
  UART1_Write(Lo(size))
  UART1_Write(Hi(size))
  UART1_Write(Higher(size))
  UART1_Write(Highest(size))
  UART1_Write(0xAA)
end if

Notes

Long File Names (LFN) are not supported.

Mmc_Fat_Tell

Prototype	sub function Mmc_Fat_Tell() as longword
Description	This routine is used to retrieve the cursor position within an opened file.
Parameters	None.
Returns	Returns the cursor position in currently assigned file.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim position as longword position = Mmc_Fat_Tell()
Notes	None.

Mmc_Fat_Seek

Prototype	sub function Mmc_Fat_Seek(dim position as longword) as longword
Description	This routine is used to set the cursor position within an opened file and returns the cursor's new position within an opened file.
Parameters	`position:` desired position on which we want to place the cursor.
Returns	Returns the cursor's new position in currently assigned file.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	dim position as longword position = Mmc_Fat_Seek(1000)
Notes	If the desired cursor position exceeds file size, the cursor will be placed at the end of the file.

Mmc_Fat_Rename

Prototype	sub function Mmc_Fat_Rename(dim newname as ^char) as char
Description	This function renames the currently assigned file.
Parameters	`newname:` new file name.
Returns	`1` - if there are no assigned files `2` - if the new name in invalied `3` - if the file with the new name already exists `4` - if an error occurred during renaming `0` - if renaming was successful
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init. The file must be previously assigned. See Mmc_Fat_Assign.
Example	if (0 = Mmc_Fat_Rename("NEWNAME.TXT")) then ' if rename operation was successful... ... end if
Notes	None.

Mmc_Fat_MakeDir

Prototype	sub function Mmc_Fat_MakeDir(dim name as ^char, dim attrib as char) as char
Description	This sub function creates a new directory.
Parameters	`name:` directory name. `attrib:` directory attribute.
Returns	`0` - directory creation was successful `255` - if an error occurred
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	if (0 = Mmc_Fat_MakeDir('DIR_A')) then ' create DIR_A directory ... end if
Notes	None.

Mmc_Fat_RenameDir

Prototype	sub function Mmc_Fat_RenameDir(dim oldname as ^char, dim newname as ^char) as char
Description	This sub function renames a directory.
Parameters	`oldname:` old directory name. `newname:` new directory name.
Returns	`1` - if directory name is invalid `2` - if there is no directry with the old name `3` - if an entry with the new name already exits `4` - if an error occurred during renaming `0` - if renaming was successful
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	if (0 = Mmc_Fat_RenameDir("DIR_A", "DIR_B")) then ' if rename operation was successful... ... end if
Notes	None.

Mmc_Fat_RemoveDir

Prototype	sub function Mmc_Fat_RemoveDir(dim name as ^char) as char
Description	This function removes directory entry from current directory.
Parameters	`name:` directory name.
Returns	`1` - if directory name is invalid `2` - if directory name is non-existant `3` - if directory is not empty `4` - if an error occurred while writing `0` - if operation was successful
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	if (0 = Mmc_Fat_RemoveDir("DIR_A")) then ' if removing operation was successful... ... end if
Notes	Recursive removing is not supported, i.e. the directory must be empty before it can be removed.

Mmc_Fat_ChangeDir

Prototype	sub function Mmc_Fat_ChangeDir(dim name as ^char) as char
Description	This sub function changes the current directory to `name`.
Parameters	`name:` directory name.
Returns	`0` - if operation was successful `1` - if there is no entry with given directory name `2` - if an entry with the given name is not a directory
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	' enter DIR_A directory if (0 = Mmc_Fat_ChangeDir("DIR_A")) then ... end if ' go to parent directory if (0 = Mmc_Fat_ChangeDir("..")) then ... end if ' go to root directory if (0 = Mmc_Fat_ChangeDir("\")) then ... end if
Notes	Special directory names like "`.`" and "`..`" are also supported.

Mmc_Fat_Exists

Prototype	sub function Mmc_Fat_Exists(dim name as ^char) as char
Description	This sub function returns information on file/directory existence.
Parameters	`name:` file/directory name.
Returns	`0` - if file/directory doesn't exist `1` - if file/directory exists
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	status = Mmc_Fat_Exists("X_FILES.TXT") ' if process was successful... if (0 = status) then ... end if ' if an error occurred... if (255 = status) then ... end if
Notes	None.

Mmc_Fat_Dir

Prototype	sub function Mmc_Fat_Dir(dim print as ^TProcedure) as byte
Description	This routine displays contents of the current directory via user-defined medium (i.e. UART module, a file on FAT16 file system). The function displays character by character.
Parameters	`print:` sub function pointer to a routine which will display contents of the current directory.
Returns	`1` - if file nema is invalid `2` - if file already exists `3` - if error occured while writing `0` - if operation was successful
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	typedef TProcedure as sub procedure(dim ch as char) ' Displaying routine procedure PrintChar(dim ch as char) UART1_Write(ch) end sub ... Mmc_Fat_Dir(@PrintChar)
Notes	None.

Mmc_Fat_ReadDir

Prototype	sub function Mmc_Fat_ReadDir(dim byref d as F16_DIR) as short
Description	This function gets next directory entry from current directory.
Parameters	`d:` directory entry (valid if return value equals 1), consisted of the following fields : Copy Code To Clipboard structure F16_DIR dim name as char[13-1] ' directory name dim attrib as byte ' directory attribute dim ctime as byte[6] ' create time and date dim mtime as byte[6] ' modification time and date dim size as longword ' directory size dim first as word ' directory start cluster dim sect as longword ' directory entry sector dim entry as word ' derectory entry number in the entry sector end structure
Returns	`< 0` - if an error occurred `0` - if no more entries `1` - if a valid entry is returned
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example	if (1 = Mmc_Fat_ReadDir("DIR_A")) then ... end if
Notes	None.

Mmc_Fat_Activate

Prototype	sub function Mmc_Fat_Activate(dim fileHandle as short) as byte
Description	This function selects active file of currently opened files.
Parameters	`fileHandle:` file handle of the file which need to be activated.
Returns	`0` - if activation was successful `1` - if file handle is out of scope `2` - if file handle is empty
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example
Notes	Use Mmc_Fat_Open function to get file handles.

Mmc_Fat_ReadN

Prototype	sub function Mmc_Fat_ReadN(dim fdata as ^byte, dim n as word) as word
Description	This function reads multiple bytes.
Parameters	`fdata:` data buffer. `n:` number of bytes to read.
Returns	Number of read bytes.
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example
Notes	None.

Mmc_Fat_Open

Prototype

sub function Mmc_Fat_Open(dim byref name as char[12], dim mode, attrib as byte) as short

Description

This function opens a file for manipulation.

Parameters

name: file name.
mode: file handling mode, FILE_WRITE, FILE_READ or FILE_APPEND.
attrib: file creation and attributes flags. Each bit corresponds to the appropriate file attribute :

Returns

< 0 - if an error occurred
file handle for opened file otherwise

Requires

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

Example

Notes

None.

Mmc_Fat_Close

Prototype	sub function Mmc_Fat_Close() as byte
Description	This function closes currently opened file.
Parameters	None.
Returns	`0` - if closing was successful `1` - if there are no assigned files
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example
Notes	None.

Mmc_Fat_EOF

Prototype	sub function Mmc_Fat_EOF() as short
Description	This function check if the end of file is reached.
Parameters	None.
Returns	`-1` - if an error occurred `0` - if end of file was not reached `1` - if end of file was reached
Requires	MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.
Example
Notes	None.

Want more examples and libraries?
Find them on