Microchip MDD File System Interface Library

MDDFS Interface Library Help
Contents | Index
Next
Microchip MDD File System Interface Library
Welcome to the Microchip Memory Disk Drive File System Interface Library!

Microchip's Memory Disk Drive File System(MDDFS) supports FAT12, FAT16 and FAT32 format for all 8, 16 and 32 bit PIC MCU's. MDDFS software is independent of the physical layer used and can be easily integrated to any of the phsical layers like USB, SD card, compact flash...etc...

MDDFS supports all file and directory operations(like read,write,remove,rename...etc...) for Long File Name(LFN) entries upto 255 characters. That means each file or directory name can be upto 255 characters. This feature is available using PIC24F & PIC32 microcontrollers. PIC18F doesn't support LFN feature due to less RAM size. Whereas the basic 8.3 format filename is supported by all PIC18F, PIC24F & PIC32 MCU's.The MDD File System Interface Library will provide an easy way to create and manipulate files on removable flash-based media devices.

USB Functionality

Note that the source code package and help file for this library do not include USB physical layer information. For more information about using the USB Host stack as a physical layer, please visit [image] Microchip's USB Development Page or the [image] AN1145: Using a USB Flash Drive with an Embedded Host page.

Updates

The latest version of the Microchip MDD File System Interface library is always available at [image] Microchip MDD File System page.

Getting Help

The MDDFS Interface Library is supported through Microchip's standard support channels. If you encounter difficulties, you may submit ticket requests at [image] http://support.microchip.com.

Thank You!

We appreciate your interest in the Microchip MDD File System Interface Library, and thank you for choosing Microchip products!

Microchip MDD File System Interface Library
Microchip MDD File System Interface 1.3.2 - [July 14, 2011]
Copyright © 2011 Microchip Technology, Inc. All rights reserved.


SW License Agreement

Contents | Index | Home
Previous | Next
SW License Agreement

MICROCHIP IS WILLING TO LICENSE THE ACCOMPANYING SOFTWARE AND DOCUMENTATION TO YOU ONLY ON THE CONDITION THAT YOU ACCEPT ALL OF THE FOLLOWING TERMS. TO ACCEPT THE TERMS OF THIS LICENSE, CLICK "I ACCEPT" AND PROCEED WITH THE DOWNLOAD OR INSTALL. IF YOU DO NOT ACCEPT THESE LICENSE TERMS, CLICK "I DO NOT ACCEPT," AND DO NOT DOWNLOAD OR INSTALL THIS SOFTWARE. BY DOWNLOADING AND INSTALLING THE SOFTWARE, LICENSEE AGREES TO BE BOUND BY THE TERMS OF THIS AGREEMENT.

NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT FOR ACCOMPANYING MICROCHIP SOFTWARE AND DOCUMENTATION

This Nonexclusive Software License Agreement ("Agreement") is a contract between you, your heirs, successors and assigns ("Licensee") and Microchip Technology Incorporated, a Delaware corporation, with a principal place of business at 2355 W. Chandler Blvd., Chandler, AZ 85224-6199, and its subsidiary, Microchip Technology (Barbados) II Incorporated (collectively, "Microchip") for the accompanying Microchip software including, but not limited to, Graphics Library Software, IrDA Stack Software, MCHPFSUSB Stack Software, Memory Disk Drive File System Software, mTouch(TM) Capacitive Library Software, Smart Card Library Software, TCP/IP Stack Software, MiWi(TM) DE Software, and/or any PC programs and any updates thereto (collectively, the "Software"), and accompanying documentation, including images and any other graphic resources provided by Microchip ("Documentation").

The Software and Documentation are licensed under this Agreement and not sold. U.S. copyright laws, international copyright treaties, and other intellectual property laws and treaties protect the Software and Documentation. Microchip reserves all rights not expressly granted to Licensee in this Agreement.

(1) Definitions. As used in this Agreement, the following capitalized terms will have the meanings defined below:

a. "Microchip Products" means Microchip microcontrollers and Microchip digital signal controllers.

b. "Licensee Products" means Licensee products that use or incorporate Microchip Products.

c. "Object Code" means the Software computer programming code that is in binary form (including related documentation, if any), and error corrections, improvements, modifications, and updates.

d. "Source Code" means the Software computer programming code that may be printed out or displayed in human readable form (including related programmer comments and documentation, if any), and error corrections, improvements, modifications, and updates.

e. "Third Party" means Licensee’s agents, representatives, consultants, clients, customers, or contract manufacturers.

f. "Third Party Products" means Third Party products that use or incorporate Microchip Products.

(2) Software License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to:

a. use the Software in connection with Licensee Products and/or Third Party Products;

b. if Source Code is provided, modify the Software, provided that no Open Source Components (defined in Section 5 below) are incorporated into such Software in such a way that would affect Microchip’s right to distribute the Software with the limitations set forth herein and provided that Licensee clearly notifies Third Parties regarding such modifications;

c. distribute the Software to Third Parties for use in Third Party Products, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept") and this Agreement accompanies such distribution;

d. sublicense to a Third Party to use the Software, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept");

e. with respect to the TCP/IP Stack Software, Licensee may port the ENC28J60.c, ENC28J60.h, ENCX24J600.c, and ENCX24J600.h driver source files to a non-Microchip Product used in conjunction with a Microchip ethernet controller;

f. with respect to the MiWi (TM) DE Software, Licensee may only exercise its rights when the Software is embedded on a Microchip Product and used with a Microchip radio frequency transceiver or UBEC UZ2400 radio frequency transceiver which are integrated into Licensee Products or Third Party Products.

For purposes of clarity, Licensee may NOT embed the Software on a non-Microchip Product, except as described in this Section.

(3) Documentation License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to use the Documentation in support of Licensee's authorized use of the Software

(4) Third Party Requirements. Licensee acknowledges that it is Licensee’s responsibility to comply with any third party license terms or requirements applicable to the use of such third party software, specifications, systems, or tools. Microchip is not responsible and will not be held responsible in any manner for Licensee’s failure to comply with such applicable terms or requirements.

(5) Open Source Components. Notwithstanding the license grant in Section 1 above, Licensee further acknowledges that certain components of the Software may be covered by so-called "open source" software licenses ("Open Source Components"). Open Source Components means any software licenses approved as open source licenses by the Open Source Initiative or any substantially similar licenses, including without limitation any license that, as a condition of distribution of the software licensed under such license, requires that the distributor make the software available in source code format. To the extent required by the licenses covering Open Source Components, the terms of such license will apply in lieu of the terms of this Agreement, and Microchip hereby represents and warrants that the licenses granted to such Open Source Components will be no less broad than the license granted in Section 1. To the extent the terms of the licenses applicable to Open Source Components prohibit any of the restrictions in this Agreement with respect to such Open Source Components, such restrictions will not apply to such Open Source Component.

(6) Licensee Obligations.

a. Licensee will ensure Third Party compliance with the terms of this Agreement, and will be liable for any breach of this Agreement committed by such Third Party.

b. Licensee will not: (i) engage in unauthorized use, modification, disclosure or distribution of Software or Documentation, or its derivatives; (ii) use all or any portion of the Software, Documentation, or its derivatives except in conjunction with Microchip Products or Third Party Products; or (iii) reverse engineer (by disassembly, decompilation or otherwise) Software or any portion thereof.

c. Licensee may not remove or alter any Microchip copyright or other proprietary rights notice posted in any portion of the Software or Documentation.

d. Licensee will defend, indemnify and hold Microchip and its subsidiaries harmless from and against any and all claims, costs, damages, expenses (including reasonable attorney's fees), liabilities, and losses, including without limitation product liability claims, directly or indirectly arising from or related to: (i) the use, modification, disclosure or distribution of the Software, Documentation, or any intellectual property rights related thereto; (ii) the use, sale and distribution of Licensee Products or Third Party Products; and (iii) breach of this Agreement. THIS SECTION 3(d) STATES THE SOLE AND EXCLUSIVE LIABILITY OF THE PARTIES FOR INTELLECTUAL PROPERTY INFRINGEMENT.

(7) Confidentiality. Licensee agrees that the Software (including but not limited to the Source Code, Object Code and library files) and its derivatives, Documentation and underlying inventions, algorithms, know-how and ideas relating to the Software and the Documentation are proprietary information belonging to Microchip and its licensors ("Proprietary Information"). Except as expressly and unambiguously allowed herein, Licensee will hold in confidence and not use or disclose any Proprietary Information and will similarly bind its employees and Third Party(ies) in writing. Proprietary Information will not include information that: (i) is in or enters the public domain without breach of this Agreement and through no fault of the receiving party; (ii) the receiving party was legally in possession of prior to receiving it; (iii) the receiving party can demonstrate was developed by the receiving party independently and without use of or reference to the disclosing party's Proprietary Information; or (iv) the receiving party receives from a third party without restriction on disclosure. If Licensee is required to disclose Proprietary Information by law, court order, or government agency, License will give Microchip prompt notice of such requirement in order to allow Microchip to object or limit such disclosure. Licensee agrees that the provisions of this Agreement regarding unauthorized use and nondisclosure of the Software, Documentation and related Proprietary Rights are necessary to protect the legitimate business interests of Microchip and its licensors and that monetary damage alone cannot adequately compensate Microchip or its licensors if such provisions are violated. Licensee, therefore, agrees that if Microchip alleges that Licensee or Third Party has breached or violated such provision then Microchip will have the right to petition for injunctive relief, without the requirement for the posting of a bond, in addition to all other remedies at law or in equity.

(8) Ownership of Proprietary Rights. Microchip and its licensors retain all right, title and interest in and to the Software and Documentation ("Proprietary Rights") including, but not limited to all patent, copyright, trade secret and other intellectual property rights in the Software, Documentation, and underlying technology and all copies and derivative works thereof (by whomever produced). Further, copies and derivative works will be considered works made for hire with ownership vesting in Microchip on creation. To the extent such modifications and derivatives do not qualify as a "work for hire," Licensee hereby irrevocably transfers, assigns and conveys the exclusive copyright thereof to Microchip, free and clear of any and all liens, claims or other encumbrances, to the fullest extent permitted by law. Licensee and Third Party use of such modifications and derivatives is limited to the license rights described in Sections this Agreement.

(9) Termination of Agreement. Without prejudice to any other rights, this Agreement terminates immediately, without notice by Microchip, upon a failure by Licensee or Third Party to comply with any provision of this Agreement. Upon termination, Licensee and Third Party will immediately stop using the Software, Documentation, and derivatives thereof, and immediately destroy all such copies.

(10) Warranty Disclaimers. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. MICROCHIP AND ITS LICENSORS ASSUME NO RESPONSIBILITY FOR THE ACCURACY, RELIABILITY OR APPLICATION OF THE SOFTWARE OR DOCUMENTATION. MICROCHIP AND ITS LICENSORS DO NOT WARRANT THAT THE SOFTWARE WILL MEET REQUIREMENTS OF LICENSEE OR THIRD PARTY, BE UNINTERRUPTED OR ERROR-FREE. MICROCHIP AND ITS LICENSORS HAVE NO OBLIGATION TO CORRECT ANY DEFECTS IN THE SOFTWARE. LICENSEE AND THIRD PARTY ASSUME THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION PROVIDED UNDER THIS AGREEMENT.

(11) Limited Liability. IN NO EVENT WILL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL OR EQUITABLE THEORY FOR ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. The aggregate and cumulative liability of Microchip and its licensors for damages hereunder will in no event exceed $1000 or the amount Licensee paid Microchip for the Software and Documentation, whichever is greater. Licensee acknowledges that the foregoing limitations are reasonable and an essential part of this Agreement.

LICENSEE ACKNOWLEDGES AND AGREES THAT IT IS SOLELY RESPONSIBLE FOR THE LICENSEE PRODUCTS AND THIRD PARTY PRODUCTS, INCLUDING DETERMINING WHETHER SUCH PRODUCTS INFRINGE A PATENT, COPYRIGHT OR OTHER PROPRIETARY RIGHT OF ANY THIRD PARTY. LICENSEE AGREES THAT MICROCHIP HAS NO OBLIGATION TO INDEMNIFY OR DEFEND LICENSEE IN THE EVENT THAT A THIRD PARTY MAKES A CLAIM REGARDING LICENSEE PRODUCTS OR THIRD PARTY PRODUCTS.

(12) General. THIS AGREEMENT WILL BE GOVERNED BY AND CONSTRUED UNDER THE LAWS OF THE STATE OF ARIZONA AND THE UNITED STATES WITHOUT REGARD TO CONFLICTS OF LAWS PROVISIONS. Licensee agrees that any disputes arising out of or related to this Agreement, Software or Documentation will be brought in the courts of the State of Arizona. The parties agree to waive their rights to a jury trial in actions relating to this Agreement. If either the Microchip or Licensee employs attorneys to enforce any rights arising out of or relating to this Agreement, the prevailing party will be entitled to recover its reasonable attorneys' fees, costs and other expenses. This Agreement will constitute the entire agreement between the parties with respect to the subject matter hereof. It will not be modified except by a written agreement signed by an authorized representative of the Microchip. Microchip’s authorized representatives will have the right to reasonably inspect Licensee's premises and to audit Licensee's records and inventory of Licensee Products in order to ensure Licensee's adherence to the terms of this Agreement. If any provision of this Agreement will be held by a court of competent jurisdiction to be illegal, invalid or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this Agreement will otherwise remain in full force and effect and enforceable. No waiver of any breach of any provision of this Agreement will constitute a waiver of any prior, concurrent or subsequent breach of the same or any other provisions hereof, and no waiver will be effective unless made in writing and signed by an authorized representative of the waiving party. Licensee agrees to comply with all export laws and restrictions and regulations of the Department of Commerce or other United States or foreign agency or authority. The indemnities, obligations of confidentiality, and limitations on liability described herein, and any right of action for breach of this Agreement prior to termination, will survive any termination of this Agreement. Neither this Agreement nor any rights, licenses or obligations hereunder, may be assigned by Licensee without the prior written approval of Microchip except pursuant to a merger, sale of all assets of Licensee or other corporate reorganization, provided that assignee agrees in writing to be bound by the Agreement. Any prohibited assignment will be null and void. Use, duplication or disclosure by the United States Government is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer-Restricted Rights clause of FAR 52.227-19 when applicable, or in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, and in similar clauses in the NASA FAR Supplement. Contractor/manufacturer is Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199.

If Licensee has any questions about this Agreement, please write to Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199 USA. ATTN: Marketing.

Copyright (c) 2011 Microchip Technology Inc. All rights reserved.

License Rev. No. 03-060111

SW License Agreement


Release Notes

Contents | Index | Home
Previous | Next
Release Notes

Microchip Memory Disk Drive File System Release Notes

Description

This library is intended to provide an interface to file systems compatible with ISO/IEC specification 9293 (commonly referred to as FAT12 and FAT16). The FAT32 file system is also supported, along with Long File Name(LFN) support for files and directories. This library includes four different physical interface files: one for SecureDigital card interface using the SPI module, one for CompactFlash card interface

using manual bit toggling, one for CompactFlash card interface using the Parallel Master Port module included on several PIC24/PIC32 microcontrollers, and one template interface file that can be modified by the user to create a custom interface layer to an unsupported device.. In addition, Microchip’s USB Host stack (available from www.microchip.com/usb can be used as a physical layer.

Version 1.3.2 Log

  1. Modified SD-SPI.c, MDD_SDSPI_AsyncWriteTasks() so pre-erase command only gets used for multi-block write scenarios. .

Compiler Version Used

This library was compiled using MPLAB C18 v.3.38, MPLAB C30 v.3.25, and

MPLAB C32 v1.11 C compliers.

Memory Size

Unoptimized memory usage for the file interface library using the SD-SPI physical layer is given in Table 1. 512 bytes of data memory are used for the data buffer, and an additional 512 are used for the file allocation table buffer. Additional data memory will be needed based on the number of files opened by the user at once. The default data

memory values provided include space for two files opened in static allocation mode. The

C18 data memory value includes a 512 byte stack. The first row of the table indicates the smallest amount of memory that the library will use (for read-only mode), and each subsequent row indicates the increase in memory caused by enabling other functionality. Optimized and unoptimized totals for program and data memory with all functions enabled are listed after the table. This data was compiled while allowing two file objects to be opened simultaneously.

Table 1: Memory Usage (Unoptimized)

Total memory usage*

  • C18 ( without LFN support ):

Unoptimized Program memory- 73702 bytes Unoptimized Data memory- 1976 bytes Optimized Program memory- 38834 bytes Optimized Data Memory- 1976 bytes

  • C30 ( with LFN support ):

Unoptimized Program memory- 60606 bytes Unoptimized Data memory- 5104 bytes Optimized Program memory- 32903 bytes Optimized Data memory- 5104 bytes

  • C32 ( with LFN support ):

Unoptimized Program memory- 80192 bytes Unoptimized Data memory- 6096 bytes Optimized Program memory- 41236 bytes Optimized Data memory- 6096 bytes

*Note: C18 total memory usage does not include FSfprintf functionality. Since FSfprintf requires integer promotion to be enabled, using it greatly increases the code size of all functions.

More Information

More detailed information about the operation of this library is available in Application

Note 1045, available from www.microchip.com.

Previous Versions Log

version 1.3.0

  1. Supported LFN entries for files and directories.
  2. Implemented new functions to improve the previous performance/flexibility issues in SD- SPI.c and .h files.
  3. Fixed SD Card Initialization Issues, especially with SDHC.

version 1.2.4

  1. Add a software mechanism for the card detection to be used when the connectors does not provide a card detect signal (e.g. MicroSD connectors).
  2. Optimize some code by collapsing duplicated code into a single for loop.
  3. Update to use the CSD register data to calculate the SD card capacity.
  4. Fixed compatibility problems in SD-SPI.c that was preventing it from working with some of the cards.
  5. Make modifications to allow dynamic sector size giving the possibility to use thumb drives with different sector sizes.
  6. Corrected a bug that prevented the last two clusters of a drive to be able to be written to.
  7. Add the GetDiskProperties function to allow the users to get the disk properties (size of disk, free space, etc)

version 1.2.3

  1. Added FSGetDiskProperties() function. This function gets the remaining disk space as well as other properties such as sector size, clusters per sector, partition format, etc.
  2. Fixed bug that prevented the last two clusters in a partition from being allocated.
  3. Added SDHC support for the MDD file system.
  4. Fixed the problem where on an append to a file that is smaller than a sector.
  5. Fixed TODO that limited internal flash to PSV page boundaries in on PIC24 and only PSVPAG = 1.
  6. Fixed an issue with the FSattrib function that was changing the wrong cached file object.

version 1.2.2

  1. Improved the SPI code operation and prescaler calculation.
  2. Cast the root directory size value determination to a double word for devices in which the root directory begins after 0xFFFF clusters.
  3. Changed the size of the index variable in the FSformat function to allow calculation in devices with larger FATs.
  4. Replaced several hard-coded values with references to MEDIA_SECTOR_SIZE.
  5. Changed the return mechanism of the MediaInitialize function to provide compatibility with the USB stack. This function will now return a pointer to a MEDIA_INFORMATION structure, which contains an error code and (for the USB stack) the size of a sector (in bytes) and the number of LUNs on the device. This structure’s definition is located in FSDefs.h.
  6. Added a new error code: CE_UNSUPPORTED_SECTOR_SIZE indicates that the sector size of the device is not supported by the file system.

version 1.2.1

  1. Fixed an issue with the calculation of the SPI prescaler value for 16-bit microcontrollers.
  2. Changed the ‘cwdclus’ type in the SearchRec structure to ‘unsigned long’
  3. Fixed a potential null-pointer reference in the Cache_File_Entry() function
  4. Improved PIC32 reliability.
  5. Changed PIC32 code to allow the user to select which SPI module to use. Selection is performed using #define macros in HardwareProfile.h.
  6. Changed PIC32 code to allow the user to define the desired SPI clock frequency. Selection is performed by setting #define SPI_FREQUENCY to the desired value in HardwareProfiles.h.
  7. Changed the return type of MDD_SDSPI_ShutdownMedia to match the USB Host ShutdownMedia function.
  8. Replaced instances of C18XX with 18CXX
  9. Added the packed attribute to several structures in FSDefs.h.

version 1.2.0

  1. Fixed a bug that prevented the library from correctly loading the boot sector on devices with no Master Boot Record.
  2. Added support for 8.3 format directory names (up to 8 name characters and 3 extension characters.) To create or access directories with extensions, use path strings with radix characters (e.g. FSmkdir (“EXAMPLE.DIR”)).
  3. Added checks to the FSmkdir function to prevent the user from creating files with too many radix characters (‘.’). Radixes at the beginning of the directory name will cause the FSmkdir function to fail.
  4. Added a check to the FSrmdir function to prevent the user from using it to delete non- directory files or the current working directory.
  5. Added the question mark (‘?’) partial string search operator to the FindFirst and FindNext functions. Now when calling FindFirst or FindNext, you can skip checks of individual characters by replacing them with question marks in the search string. For example, calling FindFirst (“F?L?.TX?, ATTR_ARCHIVE, &rec); would let you find the files “FILE.TXT,” “FOLD.TXT,” “FILM.TXM,” etc.
  6. Modified the FindFirst and FindNext functions to correctly output directory names with extensions.
  7. Modified the FSgetcwd function to correctly insert directory names with extensions in a path string.
  8. Merged the functions to validate file/directory name characters together.
  9. Added three new methods of opening files. To use these methods, just specify the new strings as the mode argument in the FSfopen function. The new modes are:
    • “r+”: File will be opened for reading or writing
    • “w+”: File will be opened for reading or writing. If the file exists, its length will be truncated to 0.
    • “a+”: File will be opened for reading or writing. If the file exists, the current location within the file will be set to the end of the file.
  10. Modified the FSfopen function to allow the user to open directories in the read mode.
  11. Modified the FSrename function. Now, to rename a directory, open the directory in read mode with FSfopen and pass the pointer to that open directory into FSrename.
  12. Added a new function. The FSattrib function will allow the user to change the attributes of files and directories.
  13. Modified the SD Data Logger project to include a new shell command; the ‘ATTRIB’ command will let the user change or display the attributes of a file.
    • Example 1: ATTRIB +R +S –H –A FILE.TXT This command will give the file FILE.TXT the read-only and system attributes, and remove the hidden and archive attributes, if they’re set.
    • Example 2: ATTRIB FILE.TXT This example will display the attributes of FILE.TXT.
  14. Added a new function. The FSferror function will provide information about why a previously called function failed.
  15. Revised most of the comment headers in the library.
  16. Generated a CHM help file for the library. This file can be found in the (default) directory “…\Microchip Solutions\Microchip\Help”
  17. Removed extraneous macros and definitions.
  18. Added a new Microchip standard header file (Compiler.h) to the library.
  19. Removed the architecture-type configuration from the sample HardwareProfile.h files. This will now be taken care of automatically within the source files.

version 1.1.2

  1. Fixed a bug that prevented the allocation of new clusters to the root directory in FAT32 implementations.
  2. Fixed a bug that prevented writing more than one cluster’s worth of file entries to the root directory in FAT16/FAT12 implementations.
  3. Fixed a bug that returned an incorrect date for directory entries located in the first directory entry after a cluster boundary of a FAT32 root directory.
  4. Fixed a bug with FSrename that would cause the function to improperly fail if the directory entries in the current working directory (or previous directory, when renaming the CWD) completely filled a cluster (and no data clusters were allocated to the directory after that).

version 1.1.1

  1. Fixed a bug with the PIC24 clock divider that was causing the interface to run more slowly than intended.
  2. Added support for PIC32 microcontrollers.

version 1.1.0

  1. Added support for FAT32. To enable this functionality, make sure the SUPPORT_FAT32 macro is uncommented in FSconfig.h.
  2. Added functions to provide support for the USB Mass Storage Host code.
  3. Moved pin and hardware definitions from physical interface files to HardwareProfiles.h.
  4. Created function pointers for functions that vary between interface files. These are located in FSconfig.h.
  5. Moved macros to select the correct physical layer to HardwareProfiles.h.
  6. Modified the SD-SPI physical layer to ensure that communication speed during startup falls between 100 kHz and 400 kHz
  7. Created a new example project: MDD File System-PIC24-SD Data Logger. This project contains code for a shell-style program based on the USB Thumb-drive shell demonstrated in Application Note 1145.
  8. Decreased the delay in the SD-SPI media initialization from 100 ms to 1 ms. i. Added the ability to change directories when writes are disabled.

version 1.01

  1. FindFirst and FindNext will now return the create time/data in the timestamp field of a SearchRec object when they return values for a directory.
  2. Corrects a bug in the FindEmptyCluster function when searching for files beyond the end of a storage device.
  3. Automatically aligns buffers for 16-bit architectures.
  4. For the SPI interface, prescaler divides will now be determined dynamically based on the system clock speed defined in FSconfig.h.
  5. The DiskMount, LoadMBR, LoadBootSector, and FSFormat functions, as well as the gDiskData, gFATBuffer, and gDataBuffer structures are now located in FSIO.c instead of in the interface files.
  6. The SectorRead function will now do a dummy read of the sector and discard the data if it is called with NULL as the data pointer.
  7. Replaced the device initialization code in the FSFormat function with calls to InitIO and MediaInitialize.
  8. The MediaDetect function is not de-bounced. In order to determine that a device is available, you must call MediaDetect, wait for an appropriate amount of time, and then call it again.
  9. The sample linker script in the MDD File System-PIC18-CF-DynMem-UserDefClock project has been modified. Previously, several databanks were merged together; this caused an issue accessing variables that spanned multiple data banks. C18 only allows users to access variables like these using pointers.
  10. Added a new user function. The FSrename function will allow the user to rename files and directories. A version that accepts a ROM filename is available for PIC18 (FSrenamepgm).
Release Notes


Getting Started

Contents | Index | Home
Previous | Next
Getting Started

This section will walk through the terminologies used in FAT file systems, initial configuration of the stack and compatible Microchip development hardware.

Topics
Name | Description
Terminology | Below are the terms which are frequently referred in the File Systems.
Directory Structure | Describes where to find files in the MDDFS Interface Library.
Configuring Hardware | Walks through hardware configuration for supported development platforms.
Software Configuration | Information about software configuration options for the library.
The SD Card Demo | Information about the default SD Card demo.
The SD Data Logger Demo | Information about the SD card file explorer demo.
Getting Started


Terminology

Contents | Index | Home
Previous | Up | Next
Terminology

Below are the terms which are frequently referred in the File Systems.

Topics
Name | Description
Boot sector | The boot sector is the first sector of a partition. It contains information about how the partition is organized.
Cluster | A cluster is a group of sectors in the data region of a FAT partition. The number of sectors per cluster can be any positive, power-of-two signed 8-bit value (1, 2, 4, 8, 16, 32, or 64) and is set when the partition is formatted.
Current Working Directory | All file I/O operations (except those that accept a path variable) take place within the current working directory. When FSInit completes successfully the CWD will be set the the root directory. It can be changed using the FSchdir or FSchdirpgm function.
Directory | A directory is a type of file that contains pointers to other files or directories.
FAT | The File Allocation Table. The FAT is an array-based linked list with one entry for each data cluster on the device. Each entry either points to the next cluster of a file or contains a special value. FAT12 has 12-bit entries, FAT16 has 16-bit entries, and FAT32 has 32-bit entries. FAT can also refer to the FAT file system itself.
Master Boot Record | The first cluster of a device. The master boot record contains pointers to different partitions on the device and information about how they're organized.
Root directory | The root directory is a directory that is the base of the directory tree. For FAT12 and FAT16 the root directory is located after the FAT; for FAT32 the root directory is make up of clusters (like a regular directory) and is located in the data region of the device.
Sector | A sector is a group of bytes in the FAT file system. Sectors are most commonly 512 bytes.
LFN | LFN refers to the Long File Name entries of the files and directories present in the memory. As per the LFN specifications, the file or directory name can be maximum of 255 characters.
Getting Started > Terminology


Boot sector

Contents | Index | Home
Previous | Up | Next
Boot sector

The boot sector is the first sector of a partition. It contains information about how the partition is organized.

Getting Started > Terminology > Boot sector


Cluster

Contents | Index | Home
Previous | Up | Next
Cluster

A cluster is a group of sectors in the data region of a FAT partition. The number of sectors per cluster can be any positive, power-of-two signed 8-bit value (1, 2, 4, 8, 16, 32, or 64) and is set when the partition is formatted.

Getting Started > Terminology > Cluster


Current Working Directory

Contents | Index | Home
Previous | Up | Next
Current Working Directory

All file I/O operations (except those that accept a path variable) take place within the current working directory. When FSInit completes successfully the CWD will be set the the root directory. It can be changed using the FSchdir or FSchdirpgm function.

Getting Started > Terminology > Current Working Directory


Directory

Contents | Index | Home
Previous | Up | Next
Directory

A directory is a type of file that contains pointers to other files or directories.

Getting Started > Terminology > Directory


FAT

Contents | Index | Home
Previous | Up | Next
FAT

The File Allocation Table. The FAT is an array-based linked list with one entry for each data cluster on the device. Each entry either points to the next cluster of a file or contains a special value. FAT12 has 12-bit entries, FAT16 has 16-bit entries, and FAT32 has 32-bit entries.

FAT can also refer to the FAT file system itself.

Getting Started > Terminology > FAT


Master Boot Record

Contents | Index | Home
Previous | Up | Next
Master Boot Record

The first cluster of a device. The master boot record contains pointers to different partitions on the device and information about how they're organized.

Getting Started > Terminology > Master Boot Record


Root directory

Contents | Index | Home
Previous | Up | Next
Root directory

The root directory is a directory that is the base of the directory tree. For FAT12 and FAT16 the root directory is located after the FAT; for FAT32 the root directory is make up of clusters (like a regular directory) and is located in the data region of the device.

Getting Started > Terminology > Root directory


Sector

Contents | Index | Home
Previous | Up | Next
Sector

A sector is a group of bytes in the FAT file system. Sectors are most commonly 512 bytes.

Getting Started > Terminology > Sector


LFN

Contents | Index | Home
Previous | Up | Next
LFN

LFN refers to the Long File Name entries of the files and directories present in the memory. As per the LFN specifications, the file or directory name can be maximum of 255 characters.

Getting Started > Terminology > LFN


Directory Structure

Contents | Index | Home
Previous | Up | Next
Directory Structure

The MDDFS Library comes with many files, documents, and project examples. Before getting started, take a moment to familiarize yourself with the directory structure so that you may find what you need quickly.

Directory Structure

By default, the MDDFS Library installs into C:\Microchip Solutions along with any other Microchip software stacks you may be using. Inside that folder, several subdirectories are created, as documented in the table below.

C:\Microchip Solutions | Root folder for all library files
\MDD File System-SD Card | Main demo application for file system interfacing with SD card.
\MDD File System-SD Card\PIC18F | Configuration files for the PIC18F project in the demo.
\MDD File System-SD Card\PIC24F | Configuration files for the PIC24F project in the demo.
\MDD File System-SD Card\PIC32 | Configuration files for the PIC32 project in the demo.
\MDD File System- SD Data Logger | Demo application that functions as a shell program using the UART module and an SD card.
\Microchip | Internal stack files. These files rarely need modification.
\Microchip\MDD File System | Source (*.c) files of the MDD File System Library
\Microchip\PIC18 salloc | Source (*.c) files for dynamic memory allocation for PIC18
\Microchip\MDD File System\Documentation | Readme files, schematics, and AN1045.
\Microchip\Help | The location of this help file.
\Microchip\Include |
\Microchip\Include\MDD File System | Header (*.h) files for the MDDFS Library
\Microchip\Include\PIC18 salloc | Header (*.h) files for dynamic memory allocation for PIC18
Getting Started > Directory Structure


Configuring Hardware

Contents | Index | Home
Previous | Up | Next
Configuring Hardware

The first step to use the stack is to make sure an appropriate development board is configured. To get started, select a platform from the topics presented below.

Topics
Name | Description
Explorer 16 with PICtail for SD and MMC | Information about how to configure the Explorer 16 board to use the demo projects.
HPC Explorer with PICtail for SD and MMC | Information about how to configure the HPC Explorer board to use the demo projects.
Getting Started > Configuring Hardware


Explorer 16 with PICtail for SD and MMC

Contents | Index | Home
Previous | Up | Next
Explorer 16 with PICtail for SD and MMC

Visit the Microchip web site to view the Explorer 16 [image] Product Page and [image] User's Guide, and the [image] PICtail Board for SD and MMC,

The Explorer 16 board can be expanded for SD card support using the PICtailTM Board for SD and MMC. The daughterboard should be inserted into the top-most socket of the J5 header. The orientation of the daughterboard should be such that the card socket faces towards the Processor Interface Module.

Check that:

  1. Switch S2 selects PIM.
  2. Jumper J7 selects PIC24.

The development board is now ready to use.

Project Setup

A few configuration settings are required to ensure that the MDDFS Interface Library will run on your hardware:

  1. Start with an appropriate MPLAB IDE project:
    • 16-bit parts: MDD File System-SD Card\MDDFS-SD-PIC24.mcp
    • 32-bit parts: MDD File System-SD Card\MDDFS-SD-PIC32.mcp
  2. Change the MPLAB IDE processor target selection to match the part installed on the Explorer 16 (e.x. PIC24FJ128GA010, PIC32MX360F256L).
Getting Started > Configuring Hardware > Explorer 16 with PICtail for SD and MMC


HPC Explorer with PICtail for SD and MMC

Contents | Index | Home
Previous | Up | Next
HPC Explorer with PICtail for SD and MMC

Visit the Microchip web site to view the HPC Explorer [image] Product Page and [image] User's Guide, and the [image] PICtail Board for SD and MMC,

The HPC Explorer board can be expanded for SD card support using the PICtailTM Board for SD and MMC. The daughterboard should be inserted into the PICtail connector.

The development board is now ready to use.

Project Setup

A few configuration settings are required to ensure that the MDDFS Interface Library will run on your hardware:

  1. Start with an appropriate MPLAB IDE project: MDD File System-SD Card\MDDFS-SD-PIC18.mcp
  2. Change the MPLAB IDE processor target selection to match the part installed on the HPC Explorer Board (e.x. PIC18F8722).
Troubleshooting

Because of the level translator on the PICtailTM board for SD and MMC, some versions of the HPC Explorer may experience communication errors between the microcontroller and SD card. This disruption is not limited to a specific range of clock frequencies. To improve the chances of a successful communication, some options are:

  1. Change the SPI module speed so the communication will proceed more slowly.
  2. Cut the traces that correspond to the SPI pins near the PICtail connector. Bridge the trace cuts with 100-400 Ohm terminating resistors. Note that this solution will cause damage to the HPC Explorer board.
Getting Started > Configuring Hardware > HPC Explorer with PICtail for SD and MMC


Software Configuration

Contents | Index | Home
Previous | Up | Next
Software Configuration

Once your hardware is configured, the next step is to configure the MDDFS Library firmware. Library configuration is stored as a set of configuration macros in FSconfig.h and HardwareProfiles.h in the demo application folders. To begin, open FSconfig.h in a text editor program like MPLAB.

FSconfig.h

This file contains options to configure the library firmware. The configuration macros include:

Macro/Option | Category | Indication
FS_MAX_FILES_OPEN | Definition | Describes the maximum number of files that can/will be opened at once.
SUPPORT_LFN | Definition | When enabled, the file system supports Long File Name entries for files and directories.
MEDIA_SECTOR_SIZE | Definition | Describes the size of a sector on the device. This will almost always equal 512.
ALLOW_FILESEARCH | Feature toggle | Comment this definition out to disable the file search functions (FindFirst and FindNext). This will reduce code size.
ALLOW_WRITES | Feature toggle | Comment this definition out to disable all write functionality. This will reduce code size.
ALLOW_FORMATS | Feature toggle | Comment this definition out to disable the format function. This will reduce code size.
ALLOW_DIRS | Feature toggle | Comment this definition out to disable all directory functionality. This will reduce code size.
ALLOW_PGMFUNCTIONS | Feature toggle | Comment this definition out to disable -pgm functions. The library requires -pgm functions to be disabled when not using PIC18. This will reduce code size.
ALLOW_FSFPRINTF | Feature toggle | Comment this definition out to disable the FSfprintf function. This will reduce code size.
SUPPORT_FAT32 | Feature toggle | Comment this definition out to disable FAT32 support. FAT12 and FAT16 will still be supported.
USEREALTIMECLOCK | Create/last modified timestamp generator | Uncomment this macro to generate timestamps automatically with the RTCC module. You must configure the RTCC for this method to work correctly. Only one timestamp generation method may be enabled at one time.
USERDEFINEDCLOCK | Create/last modified timestamp generator | Uncomment this macro to generate timestamps based on global variabled that are set manually by the user using the SetClockVars() function. Only one timestamp generation method may be enabled at one time.
INCREMENTTIMESTAMP | Create/last modified timestamp generator | Uncomment this macro to generate static timestamps. These timestamps will be incremented by 1 whenever the file is accessed. This should only be used in applications when create.modified times are not required. Only one timestamp generation method may be enabled at one time.
FS_DYNAMIC_MEM | Static/dynamic FSFILE object allocation. | Set the #if preprocessor definition to 1 to allocate FSFILE objects dynamically. You will be required to allocate a heap to do this. For PIC18, you will be required to include the salloc.c and salloc.h files in your project. If the #if statement is set to 0, FSFILE objects will be allocated in a static array, with the maximum number of FSFILE objects determined by the FS_MAX_FILES_OPEN macro.
HardwareProfiles.h

The HardwareProfiles.h header file reflects the state of the hardware. It contains the following macros:

Macro | Indication
GetSystemClock() | Returns the value of the system clock.
GetPeripheralClock() | Returns the value of the microcontroller's peripheral clock
GetInstructionClock() | Returns the value of the microcontroller's instruction clock
USE_SD_INTERFACE_WITH_SPI | Uncomment this definition to use the SD-SPI physical layer. Only one physical layer may be enabled at one time.
USE_CF_INTERFACE_WITH_PMP | Uncomment this definition to use the CF-PMP physical layer. Only one physical layer may be enabled at one time.
USE_MANUAL_CF_INTERFACE | Uncomment this definition to use the CF-Manual physical layer. Only one physical layer may be enabled at one time.
USE_USB_INTERFACE | Uncomment this definition to use the USB host physical layer. This physical layer is described in greater detail at [image] http://www.microchip.com/usb. Only one physical layer may be enabled at one time.
SD_CS, SD_CD, SD_WE | Used for the SD-SPI physical layer. Set these to the I/O port register locations for the chip select, card detect, and write protect signals (e.g. PORTBbits.RB3).
SD_CS_TRIS, SD_CD_TRIS, SD_WE_TRIS | Used for the SD-SPI physical layer. Set these to the I/O tris register locations that correspond to the pins used for each signal (e.g. TRISBbits.TRISB3).
SPICON1, SPISTAT, SPIBUF, SPISTAT_RBF, SPICON1bits, SPISTATbits, SPI_INTERRUPT_FLAG, SPIENABLE | Used for the SD-SPI physical layer. Set these to the SPI registers or bits that correspond to the module you're using (e.g. SSP1CON1, SSP1STAT, SSP1BUF, SSP1STATbits.BF, SSP1CON1bits, SSP1STATbits, PIR1bits.SSPIF).
SPICLOCK, SPIIN, SPIOUT, SPICLOCKLAT, SPIINLAT, SPIOUTLAT, SPICLOCKPORT, SPIINPORT, SPIOUTPORT | Used for the SD-SPI physical layer. Set these to the SPI tris/lat/port register bits for the module you're using.
CF_PMP_RST, CF_PMP_RDY, CF_PMP_CD1 | Used with the CF-PMP physical layer. Set these to the I/O port register locations for the reset, ready, and card detect signals for your card.
CF_PMP_RESETDIR, CF_PMP_READYDIR, CF_PMP_CD1DIR | Used with the CF-PMP physical layer. Set these to the I/O tris register that corresponds to the reset, ready, and card detect signals.
MDD_CFPMP_DATADIR | Used with the CF-PMP physical layer. Set this to the tris register that corresponds to the PMP data bus.
ADDBL, ADDDIR | Used with the CF-Manual physical layer. Set these to the lat and tris registers that correspond to the address bus (PIC18).
ADDR0, ADDR1, ADDR2, ADDR3 | Used with the CF-Manual physical layer. Set these to the 4 lat pins used for your address bus.
ADRTRIS0, ADRTRIS1, ADRTRIS2, ADRTRIS3 | Used with the CF-Manual physical layer. Set these to the corresponding tris bits for your data bus.
MDD_CFBT_DATABIN, MDD_CFBT_DATABOUT, MDD_CFBT_DATADIR | Used with the CF-Manual physical layer. Set these to the port, lat, and tris registers that correspond to your data bus.
CF_CE, CF_OE, CF_WE, CF_BT_RST, CF_BT_RDY, CF_BT_CD1 | Used with the CF-Manual physical layer. Set these to the I/O lat and port bits that correspond to the chip select, output enable strobe, write enable strobe, reset, ready, and card detect signals, respectively.
CF_CEDIR, CF_OEDIR, CF_WEDIR, CF_BT_RESETDIR, CF_BT_READYDIR, CF_BT_CD1DIR | Used with the CF-Manual physical layer. Set these to tris bits that correspond to the control signals for the card.
Getting Started > Software Configuration


The SD Card Demo

Contents | Index | Home
Previous | Up | Next
The SD Card Demo

SD Card demo application supports PIC18, PIC24, and PIC32 architectures. This project will give a basic demonstration of file I/O operations.This demo shows how to create a file, write into the file, close the file, read from the file, rename the file, delete a file, create a directory, change the current working directory, delete the directory and it's contents, search a file in the directory...etc...etc.. in the SD card memory.

The LFN support can be enabled by uncommenting the "SUPPORT_LFN" macro in 'FSconfig.h' file.

Getting Started > The SD Card Demo


The SD Data Logger Demo

Contents | Index | Home
Previous | Up | Next
The SD Data Logger Demo

The SD Data Logger project is based on the USB Data logger project found in [image] AN1145.

Additional Hardware Setup

This demonstration is set up to use the Explorer 16 board with a PIC24 or PIC32 part. It will require a serial connection from the D-sub (DB-9) connector on the Explorer 16 to a PC running a terminal program (e.g. HyperTerminal) with the following settings: 57600 BPS, 8 data bits, no parity, 1 stop bit, no flow control.

Using the Demo

Upon programming and running the demo code, a command prompt will appear on the PC's terminal screen. By typing "HELP" or "?" and pressing enter, the user can display a list of commands that can be used to access and modify files and directories on the card. Note that the terminal program is only transmitting and receiving information from the microcontroller; all functionality (including echoing characters) is handled by the microcontroller. The LFN support can be enabled by uncommenting the "SUPPORT_LFN" macro in 'FSconfig.h' file. Available shell commands in this demo include:

COMMAND | SYNTAX | EXAMPLE | FUNCTION
ATTRIB | ATTRIB <+|->R <+|->S <+|->H <+|->A <name> | ATTRIB +S +A -H FILE.TXT | Clears or sets read-only, system, hidden, or archive attributes from a file or directory.
CD | CD <name> | CD DIR1\DIR2 | Changes the directory to the path specified by <name>.
COPY | COPY <file1> <file2> | COPY ONE.TXT TWO.TXT | Copies <file1> to <file2>.The <file1> name should be either in 8.3 format or maximum of 255 characters(LFN) with no spaces in between the characters. Note : This feature is disabled if LFN support is enabled in the FSconfig.h file of PIC24F demo application.
COPY | COPY CON <file1> | COPY CON EXAMPLE.TXT | Copies data from the console into a file as the user types it.
DATE | DATE [yyyy-mm-dd] | DATE 2008-08-19 | Sets the date. If no date is specified, this command will display the currently set date.
DEL | DEL <file> | DEL FILE.TXT | Deletes a file.
DIR | DIR [file] | DIR EXAMPLE.* | Displays files or directories in the current working directory that match the specified naming criteria. If no argument is specified, all files in the current working directory will be displayed.
HELP/? | HELP | HELP | Displays a list of available commands.
LOG | LOG <POT|TMP> <file> | LOG TMP DATA.CSV | Logs data from the temperature sensor to potentiometer on the Explorer 16 to the specified file.
MD | MD <name> | MD ONE\TWO\THREE | Create one or more directories.
RD | RD <name> | RD ONE\TWO\THREE | Remove a directory.
REN | REN <file1> <file2> | REN ONE.TXT TWO.TXT | Renames <file1> to <file2>. Note : The <file1> name should be either in 8.3 format or maximum of 255 characters(LFN) with no spaces in between the characters.
TIME | TIME [hh:mm:ss] | TIME [10:52:03] | Set the time to the specified value. If no value is specified, the current time will be output.
TYPE | TYPE <file> | TYPE EXAMPLE.TXT | Display the contents of a file in ASCII text

Note : In this demo application, the file and directory names provided from the PC's terminal screen are restricted to 50 characters due to RAM constraints.

Getting Started > The SD Data Logger Demo


APIs

Contents | Index | Home
Previous | Next
APIs

The Microchip MDDFS Interface Library is implemented as an application layer (written by the user), a file manipulation layer, which actually performs operations on files, and one of several physical interface layers, including an SD card interface and two methods for interfacing with CF cards. The APIs for the file manipulation layer and each physical layer are described in this section.

Topics
Name | Description
File Manipulation Layer (FSIO) | The File Manipulation Layer contains functions for manipulating files or functions to access the device that are common across all physical layers.
SD-SPI Physical Layer | The SD-SPI physical layer offers the ability to interface to SD cards using the SPI protocol. SPI modules can be found on many Microchip microcontrollers.
CF Physical Layer | The CF physical layers offer two methods for interfacing with CF cards. The manual interface method will bit-bang the parallel interface protocol used by CF cards. The CF-PMP files will interface to the cards using the parallel master port on 16-bit PIC devices. At this time, 8-bit architecture PMP interface is not supported.
APIs


File Manipulation Layer (FSIO)

Contents | Index | Home
Previous | Up | Next
File Manipulation Layer (FSIO)

The File Manipulation Layer contains functions for manipulating files or functions to access the device that are common across all physical layers.

Topics
Name | Description
Public Members | The following functions, variables, structures, and macros are available for use by the user application.
Library Members | The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.
Internal Members | The following functions, variables, structures, and macros are designated as internal to the library.
APIs > File Manipulation Layer (FSIO)


Public Members

Contents | Index | Home
Previous | Up | Next
Public Members

The following functions, variables, structures, and macros are available for use by the user application.

Functions
Name | Description
FindFirst | Initial search function for the input Ascii fileName
FindFirstpgm | Find a file named with a ROM string on PIC18
wFindFirst | Initial search function for the input UTF16 fileName
FindNext | Sequential search function
FSfopen | Open a Ascii file
FSfopenpgm | Open a Ascii file named with a ROM string on PIC18
wFSfopen | Open a UTF16 file.
FSfclose | Update file information and free FSFILE objects
FSremove | Delete a Ascii file
FSremovepgm | Delete a file named with a ROM string on PIC18
wFSremove | Delete a UTF16 file
FSrename | Change the name of a file or directory
FSrenamepgm | Rename a file named with a ROM string on PIC18
wFSrename | Change the name of a file or directory to the UTF16 input fileName
FSmkdir | Create a directory as per the Ascii input path
FSmkdirpgm | Create a directory with a path in ROM on PIC18
wFSmkdir | Create a directory as per the UTF16 input path
FSchdir | Change the current working directory as per the path specified in Ascii format
FSchdirpgm | Changed the CWD with a path in ROM on PIC18
wFSchdir | Change the current working directory as per the path specified in UTF16 format
FSrmdir | Delete a directory as per the Ascii input path
FSrmdirpgm | Delete a directory with a path in ROM on PIC18
wFSrmdir | Delete a directory as per the UTF16 input path
FSgetcwd | Get the current working directory path in Ascii format
wFSgetcwd | Get the current working directory path in UTF16 format
FSattrib | Change the attributes of a file
FSCreateMBR | Creates a master boot record
FSerror | Return an error code for the last function call
FSfeof | Indicate whether the current file position is at the end
FSformat | Formats a device
FSfprintf | Function to write formatted strings to a file
FSfread | Read data from a file
FSfseek | Change the current position in a file
FSftell | Determine the current location in a file
FSfwrite | Write data to a file
FSInit | Function to initialize the device.
FSrewind | Set the current position in a file to the beginning
SetClockVars | Manually set timestamp variables
FSfprintf | This is function FSfprintf.
FSGetDiskProperties | Allows user to get the disk properties (size of disk, free space, etc)
Macros
Name | Description
ALLOW_DIRS | A macro to enable/disable directory operations.
ALLOW_FILESEARCH | A macro to enable/disable file search functions.
ALLOW_WRITES | A macro to enable/disable write functionality
APPEND | deprecated
ATTR_ARCHIVE | An archive attribute macro
ATTR_DIRECTORY | A directory attribute macro
ATTR_HIDDEN | A hidden attribute macro
ATTR_MASK | A macro for all attributes
ATTR_READ_ONLY | A read-only attribute macro
ATTR_SYSTEM | A system attribute macro
ATTR_VOLUME | A volume attribute macro
EOF | Indicates error conditions or end-of-file conditions
FALSE | False value
FS_DYNAMIC_MEM | A macro indicating that FSFILE objects will be allocated dynamically
SUPPORT_LFN | A macro indicating whether Long File Name is supported
FS_MAX_FILES_OPEN | A macro indicating the maximum number of concurrently open files
MAX_HEAP_SIZE | A macro used to define the heap size for PIC18
MDD_MediaDetect | Function pointer to the Media Detect Physical Layer function
MEDIA_SECTOR_SIZE | A macro defining the size of a sector
NEAR_MODEL | A macro used to enable nead-model RAM addressing
SEEK_CUR | Macro for the FSfseek SEEK_CUR base location.
SEEK_END | Macro for the FSfseek SEEK_END base location
SEEK_SET | Macro for the FSfseek SEEK_SET base location.
SUPPORT_FAT32 | A macro to enable/disable FAT32 support.
TRUE | True value
USE_SD_INTERFACE_WITH_SPI | Macro used to enable the SD-SPI physical layer (SD-SPI.c and .h)
USEREALTIMECLOCK | A macro to enable RTCC based timestamp generation
WRITE | deprecated
FILE_NAME_SIZE_8P3 | MAcro indicating the length of an 8.3 file name in a directory entry
MAX_FILE_NAME_LENGTH_LFN | Macro indicating the max length of a LFN file name
Structures
Name | Description
FSFILE | Contains file information and is used to indicate which file to access.
SearchRec | A structure used for searching for files on a device.
APIs > File Manipulation Layer (FSIO) > Public Members


FindFirst Function

Contents | Index | Home
Previous | Up | Next
FindFirst Function
C
int FindFirst(
    const char * fileName,
    unsigned int attr,
    SearchRec * rec
);
Description

The FindFirst function will search for a file based on parameters passed in by the user. This function will use the FILEfind function to parse through the current working directory searching for entries that match the specified parameters. If a file is found, its parameters are copied into the SearchRec structure, as are the initial parameters passed in by the user and the position of the file entry in the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation.

Preconditions

None

Parameters
Parameters
Description
fileName
The name to search for

  • Parital string search characters
  • * - Indicates the rest of the filename or extension can vary (e.g. FILE.*)
  • ? - Indicates that one character in a filename can vary (e.g. F?LE.T?T)

attr
The attributes that a found file may have

  • ATTR_READ_ONLY - File may be read only
  • ATTR_HIDDEN - File may be a hidden file
  • ATTR_SYSTEM - File may be a system file
  • ATTR_VOLUME - Entry may be a volume label
  • ATTR_DIRECTORY - File may be a directory
  • ATTR_ARCHIVE - File may have archive attribute
  • ATTR_MASK - All attributes

rec
pointer to a structure to put the file information in
Return Values
Return Values | Description
0 | File was found
-1 | No file matching the specified criteria was found
Side Effects

Search criteria from previous FindFirst call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent FindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed.

Remarks

Call FindFirst or FindFirstpgm before calling FindNext

APIs > File Manipulation Layer (FSIO) > Public Members > FindFirst Function


FindFirstpgm Function

Contents | Index | Home
Previous | Up | Next
FindFirstpgm Function
C
int FindFirstpgm(
    const rom char * fileName,
    unsigned int attr,
    SearchRec * rec
);
Description

The FindFirstpgm function will copy a PIC18 ROM fileName argument into a RAM array, and then pass that array to the FindFirst function.

Preconditions

None

Parameters
Parameters | Description
fileName | The name of the file to be found (ROM)
attr | The attributes of the file to be found
rec | Pointer to a search record to store the file info in
Return Values
Return Values | Description
0 | File was found
-1 | No file matching the given parameters was found
Side Effects

Search criteria from previous FindFirst call on passed SearchRec object will be lost. The FSerrno variable will be changed.

Remarks

Call FindFirstpgm or FindFirst before calling FindNext. This function is for use with PIC18 when passing arguments in ROM.

APIs > File Manipulation Layer (FSIO) > Public Members > FindFirstpgm Function


wFindFirst Function

Contents | Index | Home
Previous | Up | Next
wFindFirst Function
C
int wFindFirst(
    const unsigned short int * fileName,
    unsigned int attr,
    SearchRec * rec
);
Description

The wFindFirst function will search for a file based on parameters passed in by the user. This function will use the FILEfind function to parse through the current working directory searching for entries that match the specified parameters. If a file is found, its parameters are copied into the SearchRec structure, as are the initial parameters passed in by the user and the position of the file entry in the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation.

Preconditions

None

Parameters
Parameters
Description
fileName
The name to search for

  • Parital string search characters
  • * - Indicates the rest of the filename or extension can vary (e.g. FILE.*)
  • ? - Indicates that one character in a filename can vary (e.g. F?LE.T?T)

attr
The attributes that a found file may have

  • ATTR_READ_ONLY - File may be read only
  • ATTR_HIDDEN - File may be a hidden file
  • ATTR_SYSTEM - File may be a system file
  • ATTR_VOLUME - Entry may be a volume label
  • ATTR_DIRECTORY - File may be a directory
  • ATTR_ARCHIVE - File may have archive attribute
  • ATTR_MASK - All attributes

rec
pointer to a structure to put the file information in
Return Values
Return Values | Description
0 | File was found
-1 | No file matching the specified criteria was found
Side Effects

Search criteria from previous wFindFirst call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent wFindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed.

Remarks

Call FindFirst or FindFirstpgm before calling FindNext

APIs > File Manipulation Layer (FSIO) > Public Members > wFindFirst Function


FindNext Function

Contents | Index | Home
Previous | Up | Next
FindNext Function
C
int FindNext(
    SearchRec * rec
);
Description

The FindNext function performs the same function as the FindFirst funciton, except it does not copy any search parameters into the SearchRec structure (only info about found files) and it begins searching at the last directory entry offset at which a file was found, rather than at the beginning of the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation.

Preconditions

None

Parameters
Parameters | Description
rec | The structure to store the file information in
Return Values
Return Values | Description
0 | File was found
-1 | No additional files matching the specified criteria were found
Side Effects

Search criteria from previous FindNext call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent FindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed.

Remarks

Call FindFirst or FindFirstpgm before calling this function

APIs > File Manipulation Layer (FSIO) > Public Members > FindNext Function


FSfopen Function

Contents | Index | Home
Previous | Up | Next
FSfopen Function
C
FSFILE * FSfopen(
    const char * fileName,
    const char * mode
);
Description

This function will open a file or directory. First, RAM in the dynamic heap or static array will be allocated to a new FSFILE object. Then, the specified file name will be formatted to ensure that it's in 8.3 format or LFN format. Next, the FILEfind function will be used to search for the specified file name. If the name is found, one of three things will happen: if the file was opened in read mode, its file info will be loaded using the FILEopen function; if it was opened in write mode, it will be erased, and a new file will be constructed in its place; if it was opened in append mode, its file info will be loaded with FILEopen and the current location will be moved to the end of the file using the FSfseek function. If the file was not found by FILEfind, a new file will be created if the mode was specified as a write or append mode. In these cases, a pointer to the heap or static FSFILE object array will be returned. If the file was not found and the mode was specified as a read mode, the memory allocated to the file will be freed and the NULL pointer value will be returned.

Preconditions

For read modes, file exists; FSInit performed

Parameters
Parameters
Description
fileName
The name of the file to open
mode

  • WRITE - Create a new file or replace an existing file
  • READ - Read data from an existing file
  • APPEND - Append data to an existing file
  • WRITEPLUS - Create a new file or replace an existing file (reads also enabled)
  • READPLUS - Read data from an existing file (writes also enabled)
  • APPENDPLUS - Append data to an existing file (reads also enabled)

Return Values
Return Values | Description
FSFILE * | The pointer to the file object
NULL | The file could not be opened
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfopen Function


FSfopenpgm Function

Contents | Index | Home
Previous | Up | Next
FSfopenpgm Function
C
FSFILE * FSfopenpgm(
    const rom char * fileName,
    const rom char * mode
);
Description

The FSfopenpgm function will copy a PIC18 ROM fileName and mode argument into RAM arrays, and then pass those arrays to the FSfopen function.

Preconditions

For read modes, file exists; FSInit performed

Parameters
Parameters | Description
fileName | The name of the file to be opened (ROM)
mode | The mode the file will be opened in (ROM)
Return Values
Return Values | Description
FSFILE * | A pointer to the file object
NULL | File could not be opened
Side Effects

The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arguments in ROM.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfopenpgm Function


wFSfopen Function

Contents | Index | Home
Previous | Up | Next
wFSfopen Function
C
FSFILE * wFSfopen(
    const unsigned short int * fileName,
    const char * mode
);
Description

This function will open a file or directory. First, RAM in the dynamic heap or static array will be allocated to a new FSFILE object. Then, the specified file name will be formatted to ensure that it's in 8.3 format or LFN format. Next, the FILEfind function will be used to search for the specified file name. If the name is found, one of three things will happen: if the file was opened in read mode, its file info will be loaded using the FILEopen function; if it was opened in write mode, it will be erased, and a new file will be constructed in its place; if it was opened in append mode, its file info will be loaded with FILEopen and the current location will be moved to the end of the file using the FSfseek function. If the file was not found by FILEfind, a new file will be created if the mode was specified as a write or append mode. In these cases, a pointer to the heap or static FSFILE object array will be returned. If the file was not found and the mode was specified as a read mode, the memory allocated to the file will be freed and the NULL pointer value will be returned.

Preconditions

For read modes, file exists; FSInit performed

Parameters
Parameters
Description
fileName
The name of the file to open
mode

  • WRITE - Create a new file or replace an existing file
  • READ - Read data from an existing file
  • APPEND - Append data to an existing file
  • WRITEPLUS - Create a new file or replace an existing file (reads also enabled)
  • READPLUS - Read data from an existing file (writes also enabled)
  • APPENDPLUS - Append data to an existing file (reads also enabled)

Return Values
Return Values | Description
FSFILE * | The pointer to the file object
NULL | The file could not be opened
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > wFSfopen Function


FSfclose Function

Contents | Index | Home
Previous | Up | Next
FSfclose Function
C
int FSfclose(
    FSFILE * fo
);
Description

This function will update the directory entry for the file pointed to by 'fo' with the information contained in 'fo,' including the new file size and attributes. Timestamp information will also be loaded based on the method selected by the user and written to the entry as the last modified time and date. The file entry will then be written to the device. Finally, the memory used for the specified file object will be freed from the dynamic heap or the array of FSFILE objects.

Preconditions

File opened

Parameters
Parameters | Description
fo | Pointer to the file to close
Return Values
Return Values | Description
0 | File closed successfully
EOF | Error closing the file
Side Effects

The FSerrno variable will be changed.

Remarks

A function to flush data to the device without closing the file can be created by removing the portion of this function that frees the memory and the line that clears the write flag.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfclose Function


FSremove Function

Contents | Index | Home
Previous | Up | Next
FSremove Function
C
int FSremove(
    const char * fileName
);
Description

The FSremove function will attempt to find the specified file with the FILEfind function. If the file is found, it will be erased using the FILEerase function. The user can also provide ascii alias name of the ascii long file name as the input to this function to get it erased from the memory.

Preconditions

File not opened, file exists

Parameters
Parameters | Description
fileName | Name of the file to erase
Return Values
Return Values | Description
0 | File removed
EOF | File was not removed
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSremove Function


FSremovepgm Function

Contents | Index | Home
Previous | Up | Next
FSremovepgm Function
C
int FSremovepgm(
    const rom char * fileName
);
Description

The FSremovepgm function will copy a PIC18 ROM fileName argument into a RAM array, and then pass that array to the FSremove function.

Preconditions

File not opened; file exists

Parameters
Parameters | Description
fileName | The name of the file to be deleted (ROM)
Return Values
Return Values | Description
0 | File was removed successfully
-1 | File could not be removed
Side Effects

The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arguments in ROM.

APIs > File Manipulation Layer (FSIO) > Public Members > FSremovepgm Function


wFSremove Function

Contents | Index | Home
Previous | Up | Next
wFSremove Function
C
int wFSremove(
    const unsigned short int * fileName
);
Description

The wFSremove function will attempt to find the specified UTF16 file name with the FILEfind function. If the file is found, it will be erased using the FILEerase function.

Preconditions

File not opened, file exists

Parameters
Parameters | Description
fileName | Name of the file to erase
Return Values
Return Values | Description
0 | File removed
EOF | File was not removed
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > wFSremove Function


FSrename Function

Contents | Index | Home
Previous | Up | Next
FSrename Function
C
int FSrename(
    const char * fileName,
    FSFILE * fo
);
Description

The FSrename function will rename a file. First, it will search through the current working directory to ensure the specified new filename is not already in use. If it isn't, the new filename will be written to the file entry of the file pointed to by 'fo.'

Preconditions

File opened.

Parameters
Parameters | Description
fileName | The new name of the file
fo | The file to rename
Return Values
Return Values | Description
0 | File was renamed successfully
EOF | File was not renamed
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSrename Function


FSrenamepgm Function

Contents | Index | Home
Previous | Up | Next
FSrenamepgm Function
C
int FSrenamepgm(
    const rom char * fileName,
    FSFILE * fo
);
Description

The Fsrenamepgm function will copy the rom fileName specified by the user into a RAM array and pass that array into the FSrename function.

Preconditions

File opened.

Parameters
Parameters | Description
fileName | The new name of the file (in ROM)
fo | The file to rename
Return Values
Return Values | Description
0 | File renamed successfully
-1 | File could not be renamed
Side Effects

The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arguments in ROM.

APIs > File Manipulation Layer (FSIO) > Public Members > FSrenamepgm Function


wFSrename Function

Contents | Index | Home
Previous | Up | Next
wFSrename Function
C
int wFSrename(
    const unsigned short int * fileName,
    FSFILE * fo
);
Description

The wFSrename function will rename a file. First, it will search through the current working directory to ensure the specified new UTF16 filename is not already in use. If it isn't, the new filename will be written to the file entry of the file pointed to by 'fo.'

Preconditions

File opened.

Parameters
Parameters | Description
fileName | The new name of the file
fo | The file to rename
Return Values
Return Values | Description
0 | File was renamed successfully
EOF | File was not renamed
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > wFSrename Function


FSmkdir Function

Contents | Index | Home
Previous | Up | Next
FSmkdir Function
C
int FSmkdir(
    char * path
);
Description

The FSmkdir function passes a RAM pointer to the path to the mkdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of directories to create.
Return Values
Return Values | Description
0 | The specified directory was created successfully
EOF | The specified directory could not be created
Side Effects

Will create all non-existent directories in the path. The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSmkdir Function


FSmkdirpgm Function

Contents | Index | Home
Previous | Up | Next
FSmkdirpgm Function
C
int FSmkdirpgm(
    const rom char * path
);
Description

The FSmkdirpgm function passes a PIC18 ROM path pointer to the mkdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of directories to create (ROM)
Return Values
Return Values | Description
0 | The specified directory was created successfully
EOF | The specified directory could not be created
Side Effects

Will create all non-existent directories in the path. The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arugments in ROM

APIs > File Manipulation Layer (FSIO) > Public Members > FSmkdirpgm Function


wFSmkdir Function

Contents | Index | Home
Previous | Up | Next
wFSmkdir Function
C
int wFSmkdir(
    unsigned short int * path
);
Description

The wFSmkdir function passes a RAM pointer to the path to the mkdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of directories to create.
Return Values
Return Values | Description
0 | The specified directory was created successfully
EOF | The specified directory could not be created
Side Effects

Will create all non-existent directories in the path. The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > wFSmkdir Function


FSchdir Function

Contents | Index | Home
Previous | Up | Next
FSchdir Function
C
int FSchdir(
    char * path
);
Description

The FSchdir function passes a RAM pointer to the path to the chdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of the directory to change to.
Return Values
Return Values | Description
0 | The current working directory was changed successfully
EOF | The current working directory could not be changed
Side Effects

The current working directory may be changed. The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSchdir Function


FSchdirpgm Function

Contents | Index | Home
Previous | Up | Next
FSchdirpgm Function
C
int FSchdirpgm(
    const rom char * path
);
Description

The FSchdirpgm function passes a PIC18 ROM path pointer to the chdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of the directory to change to (ROM)
Return Values
Return Values | Description
0 | The current working directory was changed successfully
EOF | The current working directory could not be changed
Side Effects

The current working directory may be changed. The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arguments in ROM

APIs > File Manipulation Layer (FSIO) > Public Members > FSchdirpgm Function


wFSchdir Function

Contents | Index | Home
Previous | Up | Next
wFSchdir Function
C
int wFSchdir(
    unsigned short int * path
);
Description

The wFSchdir function passes a RAM pointer to the path to the chdirhelper function.

Preconditions

None

Parameters
Parameters | Description
path | The path of the directory to change to.
Return Values
Return Values | Description
0 | The current working directory was changed successfully
EOF | The current working directory could not be changed
Side Effects

The current working directory may be changed. The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > wFSchdir Function


FSrmdir Function

Contents | Index | Home
Previous | Up | Next
FSrmdir Function
C
int FSrmdir(
    char * path,
    unsigned char rmsubdirs
);
Description

The FSrmdir function passes a RAM pointer to the path to the rmdirhelper function.

Preconditions

None

Parameters
Parameters
Description
path
The path of the directory to remove
rmsubdirs

  • TRUE - All sub-dirs and files in the target dir will be removed
  • FALSE - FSrmdir will not remove non-empty directories

Return Values
Return Values | Description
0 | The specified directory was deleted successfully
EOF | The specified directory could not be deleted
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSrmdir Function


FSrmdirpgm Function

Contents | Index | Home
Previous | Up | Next
FSrmdirpgm Function
C
int FSrmdirpgm(
    const rom char * path,
    unsigned char rmsubdirs
);
Description

The FSrmdirpgm function passes a PIC18 ROM path pointer to the rmdirhelper function.

Preconditions

None.

Parameters
Parameters
Description
path
The path of the directory to remove (ROM)
rmsubdirs

  • TRUE - All sub-dirs and files in the target dir will be removed
  • FALSE - FSrmdir will not remove non-empty directories

Return Values
Return Values | Description
0 | The specified directory was deleted successfully
EOF | The specified directory could not be deleted
Side Effects

The FSerrno variable will be changed.

Remarks

This function is for use with PIC18 when passing arguments in ROM.

APIs > File Manipulation Layer (FSIO) > Public Members > FSrmdirpgm Function


wFSrmdir Function

Contents | Index | Home
Previous | Up | Next
wFSrmdir Function
C
int wFSrmdir(
    unsigned short int * path,
    unsigned char rmsubdirs
);
Description

The wFSrmdir function passes a RAM pointer to the path to the rmdirhelper function.

Preconditions

None

Parameters
Parameters
Description
path
The path of the directory to remove
rmsubdirs

  • TRUE - All sub-dirs and files in the target dir will be removed
  • FALSE - FSrmdir will not remove non-empty directories

Return Values
Return Values | Description
0 | The specified directory was deleted successfully
EOF | The specified directory could not be deleted
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > wFSrmdir Function


FSgetcwd Function

Contents | Index | Home
Previous | Up | Next
FSgetcwd Function
C
char * FSgetcwd(
    char * path,
    int numbchars
);
Description

The FSgetcwd function will get the name of the current working directory and return it to the user. The name will be copied into the buffer pointed to by 'path,' starting at the root directory and copying as many chars as possible before the end of the buffer. The buffer size is indicated by the 'numchars' argument. The first thing this function will do is load the name of the current working directory, if it isn't already present. This could occur if the user switched to the dotdot entry of a subdirectory immediately before calling this function. The function will then copy the current working directory name into the buffer backwards, and insert a backslash character. Next, the function will continuously switch to the previous directories and copy their names backwards into the buffer until it reaches the root. If the buffer overflows, it will be treated as a circular buffer, and data will be copied over existing characters, starting at the beginning. Once the root directory is reached, the text in the buffer will be swapped, so that the buffer contains as much of the current working directory name as possible, starting at the root.

Preconditions

None

Parameters
Parameters | Description
path | Pointer to the array to return the cwd name in
numchars | Number of chars in the path
Return Values
Return Values | Description
char * | The cwd name string pointer (path or defaultArray)
NULL | The current working directory name could not be loaded.
Side Effects

The FSerrno variable will be changed

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSgetcwd Function


wFSgetcwd Function

Contents | Index | Home
Previous | Up | Next
wFSgetcwd Function
C
char * wFSgetcwd(
    unsigned short int * path,
    int numbchars
);
Description

The FSgetcwd function will get the name of the current working directory and return it to the user. The name will be copied into the buffer pointed to by 'path,' starting at the root directory and copying as many chars as possible before the end of the buffer. The buffer size is indicated by the 'numchars' argument. The first thing this function will do is load the name of the current working directory, if it isn't already present. This could occur if the user switched to the dotdot entry of a subdirectory immediately before calling this function. The function will then copy the current working directory name into the buffer backwards, and insert a backslash character. Next, the function will continuously switch to the previous directories and copy their names backwards into the buffer until it reaches the root. If the buffer overflows, it will be treated as a circular buffer, and data will be copied over existing characters, starting at the beginning. Once the root directory is reached, the text in the buffer will be swapped, so that the buffer contains as much of the current working directory name as possible, starting at the root.

Preconditions

None

Parameters
Parameters | Description
path | Pointer to the array to return the cwd name in
numchars | Number of chars in the path
Return Values
Return Values | Description
char * | The cwd name string pointer (path or defaultArray)
NULL | The current working directory name could not be loaded.
Side Effects

The FSerrno variable will be changed

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > wFSgetcwd Function


FSattrib Function

Contents | Index | Home
Previous | Up | Next
FSattrib Function
C
int FSattrib(
    FSFILE * file,
    unsigned char attributes
);
Description

The FSattrib funciton will set the attributes of the specified file to the attributes passed in by the user. This function will load the file entry, replace the attributes with the ones specified, and write the attributes back. If the specified file is a directory, the directory attribute will be preserved.

Preconditions

File opened

Parameters
Parameters
Description
file
Pointer to file structure
attributes
The attributes to set for the file

  • Attribute - Value - Indications
  • ATTR_READ_ONLY - 0x01 - The read-only attribute
  • ATTR_HIDDEN - 0x02 - The hidden attribute
  • ATTR_SYSTEM - 0x04 - The system attribute
  • ATTR_ARCHIVE - 0x20 - The archive attribute

Return Values
Return Values | Description
0 | Attribute change was successful
-1 | Attribute change was unsuccessful
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSattrib Function


FSCreateMBR Function

Contents | Index | Home
Previous | Up | Next
FSCreateMBR Function
C
int FSCreateMBR(
    unsigned long firstSector,
    unsigned long numSectors
);
Description

This function can be used to create a master boot record for a device. Note that this function should not be used on a device that is already formatted with a master boot record (i.e. most SD cards, CF cards, USB keys). This function will fill the global data buffer with appropriate partition information for a FAT partition with a type determined by the number of sectors available to the partition. It will then write the MBR information to the first sector on the device. This function should be followed by a call to FSformat, which will create a boot sector, root dir, and FAT appropriate the the information contained in the new master boot record. Note that FSformat only supports FAT12 and FAT16 formatting at this time, and so cannot be used to format a device with more than 0x3FFD5F sectors.

Preconditions

The I/O pins for the device have been initialized by the InitIO function.

Parameters
Parameters | Description
firstSector | The first sector of the partition on the device (cannot be 0; that's the MBR)
numSectors | The number of sectors available in memory (including the MBR)
Return Values
Return Values | Description
0 | MBR was created successfully
EOF | MBR could not be created
Side Effects

None

Remarks

This function can damage the device being used, and should not be called unless the user is sure about the size of the device and the first sector value.

APIs > File Manipulation Layer (FSIO) > Public Members > FSCreateMBR Function


FSerror Function

Contents | Index | Home
Previous | Up | Next
FSerror Function
C
int FSerror();
Description

The FSerror function will return the FSerrno variable. This global variable will have been set to an error value during the last call of a library function.

Preconditions

The return value depends on the last function called.

Return Values
Return Values
Description
FSInit

  • CE_GOOD – No Error
  • CE_INIT_ERROR – The physical media could not be initialized
  • CE_BAD_SECTOR_READ – The MBR or the boot sector could not be read correctly
  • CE_BAD_PARITION – The MBR signature code was incorrect.
  • CE_NOT_FORMATTED – The boot sector signature code was incorrect or indicates an invalid number of bytes per sector.
  • CE_UNSUPPORTED_SECTOR_SIZE - The number of bytes per sector is unsupported
  • CE_CARDFAT32 – The physical media is FAT32 type (only an error when FAT32 support is disabled).
  • CE_UNSUPPORTED_FS – The device is formatted with an unsupported file system (not FAT12 or 16).

FSfopen

  • CE_GOOD – No Error
  • CE_NOT_INIT – The device has not been initialized.
  • CE_TOO_MANY_FILES_OPEN – The function could not allocate any additional file information to the array of FSFILE structures or the heap.
  • CE_INVALID_FILENAME – The file name argument was invalid.
  • CE_INVALID_ARGUMENT – The user attempted to open a directory in a write mode or specified an invalid mode argument.
  • CE_FILE_NOT_FOUND – The specified file (which was to be opened in read mode) does not exist on the device.
  • CE_BADCACHEREAD – A read from the device failed.
  • CE_ERASE_FAIL – The existing file could not be erased (when opening a file in WRITE mode).
  • CE_DIR_FULL – The directory is full.
  • CE_DISK_FULL– The data memory section is full.
  • CE_WRITE_ERROR – A write to the device failed.
  • CE_SEEK_ERROR – The current position in the file could not be set to the end (when the file was opened in APPEND mode).

FSfclose

  • CE_GOOD – No Error
  • CE_WRITE_ERROR – The existing data in the data buffer or the new file entry information could not be written to the device.
  • CE_BADCACHEREAD – The file entry information could not be cached

FSfread

  • CE_GOOD – No Error
  • CE_WRITEONLY – The file was opened in a write-only mode.
  • CE_WRITE_ERROR – The existing data in the data buffer could not be written to the device.
  • CE_BAD_SECTOR_READ – The data sector could not be read.
  • CE_EOF – The end of the file was reached.
  • CE_COULD_NOT_GET_CLUSTER – Additional clusters in the file could not be loaded.

FSfwrite

  • CE_GOOD – No Error
  • CE_READONLY – The file was opened in a read-only mode.
  • CE_WRITE_PROTECTED – The device write-protect check function indicated that the device has been write-protected.
  • CE_WRITE_ERROR – There was an error writing data to the device.
  • CE_BADCACHEREAD – The data sector to be modified could not be read from the device.
  • CE_DISK_FULL – All data clusters on the device are in use.

FSfseek

  • CE_GOOD – No Error
  • CE_WRITE_ERROR – The existing data in the data buffer could not be written to the device.
  • CE_INVALID_ARGUMENT – The specified offset exceeds the size of the file.
  • CE_BADCACHEREAD – The sector that contains the new current position could not be loaded.
  • CE_COULD_NOT_GET_CLUSTER – Additional clusters in the file could not be loaded/allocated.

FSftell

  • CE_GOOD – No Error

FSattrib

  • CE_GOOD – No Error
  • CE_INVALID_ARGUMENT – The attribute argument was invalid.
  • CE_BADCACHEREAD – The existing file entry information could not be loaded.
  • CE_WRITE_ERROR – The file entry information could not be written to the device.

FSrename

  • CE_GOOD – No Error
  • CE_FILENOTOPENED – A null file pointer was passed into the function.
  • CE_INVALID_FILENAME – The file name passed into the function was invalid.
  • CE_BADCACHEREAD – A read from the device failed.
  • CE_FILENAME_EXISTS – A file with the specified name already exists.
  • CE_WRITE_ERROR – The new file entry data could not be written to the device.

FSfeof

  • CE_GOOD – No Error

FSformat

  • CE_GOOD – No Error
  • CE_INIT_ERROR – The device could not be initialized.
  • CE_BADCACHEREAD – The master boot record or boot sector could not be loaded successfully.
  • CE_INVALID_ARGUMENT – The user selected to create their own boot sector on a device that has no master boot record, or the mode argument was invalid.
  • CE_WRITE_ERROR – The updated MBR/Boot sector could not be written to the device.
  • CE_BAD_PARTITION – The calculated number of sectors per clusters was invalid.
  • CE_NONSUPPORTED_SIZE – The card has too many sectors to be formatted as FAT12 or FAT16.

FSremove

  • CE_GOOD – No Error
  • CE_WRITE_PROTECTED – The device write-protect check function indicated that the device has been write-protected.
  • CE_INVALID_FILENAME – The specified filename was invalid.
  • CE_FILE_NOT_FOUND – The specified file could not be found.
  • CE_ERASE_FAIL – The file could not be erased.

FSchdir

  • CE_GOOD – No Error
  • CE_INVALID_ARGUMENT – The path string was mis-formed or the user tried to change to a non-directory file.
  • CE_BADCACHEREAD – A directory entry could not be cached.
  • CE_DIR_NOT_FOUND – Could not find a directory in the path.

FSgetcwd

  • CE_GOOD – No Error
  • CE_INVALID_ARGUMENT – The user passed a 0-length buffer into the function.
  • CE_BADCACHEREAD – A directory entry could not be cached.
  • CE_BAD_SECTOR_READ – The function could not determine a previous directory of the current working directory.

FSmkdir

  • CE_GOOD – No Error
  • CE_WRITE_PROTECTED – The device write-protect check function indicated that the device has been write-protected.
  • CE_INVALID_ARGUMENT – The path string was mis-formed.
  • CE_BADCACHEREAD – Could not successfully change to a recently created directory to store its dir entry information, or could not cache directory entry information.
  • CE_INVALID_FILENAME – One or more of the directory names has an invalid format.
  • CE_WRITE_ERROR – The existing data in the data buffer could not be written to the device or the dot/dotdot entries could not be written to a newly created directory.
  • CE_DIR_FULL – There are no available dir entries in the CWD.
  • CE_DISK_FULL – There are no available clusters in the data region of the device.

FSrmdir

  • CE_GOOD – No Error
  • CE_DIR_NOT_FOUND – The directory specified could not be found or the function could not change to a subdirectory within the directory to be deleted (when recursive delete is enabled).
  • CE_INVALID_ARGUMENT – The user tried to remove the CWD or root directory.
  • CE_BADCACHEREAD – A directory entry could not be cached.
  • CE_DIR_NOT_EMPTY – The directory to be deleted was not empty and recursive subdirectory removal was disabled.
  • CE_ERASE_FAIL – The directory or one of the directories or files within it could not be deleted.
  • CE_BAD_SECTOR_READ – The function could not determine a previous directory of the CWD.

SetClockVars

  • CE_GOOD – No Error
  • CE_INVALID_ARGUMENT – The time values passed into the function were invalid.

FindFirst

  • CE_GOOD – No Error
  • CE_INVALID_FILENAME – The specified filename was invalid.
  • CE_FILE_NOT_FOUND – No file matching the specified criteria was found.
  • CE_BADCACHEREAD – The file information for the file that was found could not be cached.

FindNext

  • CE_GOOD – No Error
  • CE_NOT_INIT – The SearchRec object was not initialized by a call to FindFirst.
  • CE_INVALID_ARGUMENT – The SearchRec object was initialized in a different directory from the CWD.
  • CE_INVALID_FILENAME – The filename is invalid.
  • CE_FILE_NOT_FOUND – No file matching the specified criteria was found.

FSfprintf

  • CE_GOOD – No Error
  • CE_WRITE_ERROR – Characters could not be written to the file.

Side Effects

None.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSerror Function


FSfeof Function

Contents | Index | Home
Previous | Up | Next
FSfeof Function
C
int FSfeof(
    FSFILE * stream
);
Description

The FSfeof function will indicate that the end-of- file has been reached for the specified file by comparing the absolute location in the file to the size of the file.

Preconditions

File is open in a read mode

Parameters
Parameters | Description
stream | Pointer to the target file
Return Values
Return Values | Description
Non-Zero | EOF reached
0 | Not at end of File
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfeof Function


FSformat Function

Contents | Index | Home
Previous | Up | Next
FSformat Function
C
int FSformat(
    char mode,
    long int serialNumber,
    char * volumeID
);
Description

The FSformat function can be used to create a new boot sector on a device, based on the information in the master boot record. This function will first initialize the I/O pins and the device, and then attempts to read the master boot record. If the MBR cannot be loaded successfully, the function will fail. Next, if the 'mode' argument is specified as '0' the existing boot sector information will be loaded. If the 'mode' argument is '1' an entirely new boot sector will be constructed using the disk values from the master boot record. Once the boot sector has been successfully loaded/created, the locations of the FAT and root will be loaded from it, and they will be completely erased. If the user has specified a volumeID parameter, a VOLUME attribute entry will be created in the root directory to name the device.

FAT12, FAT16 and FAT32 formatting are supported.

Based on the number of sectors, the format function automatically compute the smallest possible value for the cluster size in order to accommodate the physical size of the media. In this case, if a media with a big capacity is formatted, the format function may take a very long time to write all the FAT tables.

Therefore, the FORMAT_SECTORS_PER_CLUSTER macro may be used to specify the exact cluster size (in multiples of sector size). This macro can be defined in FSconfig.h

Preconditions

The device must possess a valid master boot record.

Parameters
Parameters
Description
mode

  • 0 - Just erase the FAT and root
  • 1 - Create a new boot sector

serialNumber
Serial number to write to the card
volumeID
Name of the card
Return Values
Return Values | Description
0 | Format was successful
EOF | Format was unsuccessful
Side Effects

The FSerrno variable will be changed.

Remarks

Only devices with a sector size of 512 bytes are supported by the format function

APIs > File Manipulation Layer (FSIO) > Public Members > FSformat Function


FSfprintf Function

Contents | Index | Home
Previous | Up | Next
FSfprintf Function
C
int FSfprintf(
    FSFILE * fptr,
    const rom char * fmt,
    ...
);
Description

Writes a specially formatted string to a file.

Preconditions

For PIC18, integer promotion must be enabled in the project build options menu. File opened in a write mode.

Parameters
Parameters | Description
fptr | A pointer to the file to write to.
fmt | A string of characters and format specifiers to write to the file
... | Additional arguments inserted in the string by format specifiers
Returns

The number of characters written to the file

Side Effects

The FSerrno variable will be changed.

Remarks

Consult AN1045 for a full description of how to use format specifiers.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfprintf Function


FSfread Function

Contents | Index | Home
Previous | Up | Next
FSfread Function
C
size_t FSfread(
    void * ptr,
    size_t size,
    size_t n,
    FSFILE * stream
);
Description

The FSfread function will read data from the specified file. First, the appropriate sector of the file is loaded. Then, data is read into the specified buffer until the specified number of bytes have been read. When a cluster boundary is reached, a new cluster will be loaded. The parameters 'size' and 'n' indicate how much data to read. 'Size' refers to the size of one object to read (in bytes), and 'n' will refer to the number of these objects to read. The value returned will be equal to 'n' unless an error occured or the user tried to read beyond the end of the file.

Preconditions

File is opened in a read mode

Parameters
Parameters | Description
ptr | Destination buffer for read bytes
size | Size of units in bytes
n | Number of units to be read
stream | File to be read from
Returns

size_t - number of units read

Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfread Function


FSfseek Function

Contents | Index | Home
Previous | Up | Next
FSfseek Function
C
int FSfseek(
    FSFILE * stream,
    long offset,
    int whence
);
Description

The FSfseek function will change the current position in the file to one specified by the user. First, an absolute offset is calculated using the offset and base location passed in by the user. Then, the position variables are updated, and the sector number that corresponds to the new location. That sector is then loaded. If the offset falls exactly on a cluster boundary, a new cluster will be allocated to the file and the position will be set to the first byte of that cluster.

Preconditions

File opened

Parameters
Parameters
Description
stream
Pointer to file structure
offset
Offset from base location
whence

  • SEEK_SET - Seek from start of file
  • SEEK_CUR - Seek from current location
  • SEEK_END - Seek from end of file (subtract offset)

Return Values
Return Values | Description
0 | Operation successful
-1 | Operation unsuccesful
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSfseek Function


FSftell Function

Contents | Index | Home
Previous | Up | Next
FSftell Function
C
long FSftell(
    FSFILE * fo
);
Description

The FSftell function will return the current position in the file pointed to by 'fo' by returning the 'seek' variable in the FSFILE object, which is used to keep track of the absolute location of the current position in the file.

Preconditions

File opened

Parameters
Parameters | Description
fo | Pointer to file structure
Returns

Current location in the file

Side Effects

The FSerrno variable will be changed

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSftell Function


FSfwrite Function

Contents | Index | Home
Previous | Up | Next
FSfwrite Function
C
size_t FSfwrite(
    const void * ptr,
    size_t size,
    size_t n,
    FSFILE * stream
);
Description

The FSfwrite function will write data to a file. First, the sector that corresponds to the current position in the file will be loaded (if it hasn't already been cached in the global data buffer). Data will then be written to the device from the specified buffer until the specified amount has been written. If the end of a cluster is reached, the next cluster will be loaded, unless the end-of-file flag for the specified file has been set. If it has, a new cluster will be allocated to the file. Finally, the new position and filesize will be stored in the FSFILE object. The parameters 'size' and 'n' indicate how much data to write. 'Size' refers to the size of one object to write (in bytes), and 'n' will refer to the number of these objects to write. The value returned will be equal to 'n' unless an error occured.

Preconditions

File opened in WRITE, APPEND, WRITE+, APPEND+, READ+ mode

Parameters
Parameters | Description
ptr | Pointer to source buffer
size | Size of units in bytes
n | Number of units to transfer
stream | Pointer to file structure
Returns

size_t - number of units written

Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfwrite Function


FSInit Function

Contents | Index | Home
Previous | Up | Next
FSInit Function
C
int FSInit();
Description

Initializes the static or dynamic memory slots for holding file structures. Initializes the device with the DISKmount function. Loads MBR and boot sector information. Initializes the current working directory to the root directory for the device if directory support is enabled.

Preconditions

The physical device should be connected to the microcontroller.

Return Values
Return Values | Description
TRUE | Initialization successful
FALSE | Initialization unsuccessful
Side Effects

The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Public Members > FSInit Function


FSrewind Function

Contents | Index | Home
Previous | Up | Next
FSrewind Function
C
void FSrewind(
    FSFILE * fo
);
Description

The FSrewind funciton will reset the position of the specified file to the beginning of the file. This functionality is faster than using FSfseek to reset the position in the file.

Preconditions

File opened.

Parameters
Parameters | Description
fo | Pointer to file structure
Side Effects

None.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Public Members > FSrewind Function


SetClockVars Function

Contents | Index | Home
Previous | Up | Next
SetClockVars Function
C
int SetClockVars(
    unsigned int year,
    unsigned char month,
    unsigned char day,
    unsigned char hour,
    unsigned char minute,
    unsigned char second
);
Description

Lets the user manually set the timing variables. The values passed in will be converted to the format used by the FAT timestamps.

Preconditions

USERDEFINEDCLOCK macro defined in FSconfig.h.

Parameters
Parameters | Description
year | The year (1980-2107)
month | The month (1-12)
day | The day of the month (1-31)
hour | The hour (0-23)
minute | The minute (0-59)
second | The second (0-59)
Side Effects

Modifies global timing variables

Remarks

Call this before creating a file or directory (set create time) and before closing a file (set last access time, last modified time)

APIs > File Manipulation Layer (FSIO) > Public Members > SetClockVars Function


FSfprintf Function

Contents | Index | Home
Previous | Up | Next
FSfprintf Function
C
int FSfprintf(
    FSFILE * fptr,
    const char * fmt,
    ...
);
Description

This is function FSfprintf.

APIs > File Manipulation Layer (FSIO) > Public Members > FSfprintf Function


FSGetDiskProperties Function

Contents | Index | Home
Previous | Up | Next
FSGetDiskProperties Function
C
void FSGetDiskProperties(
    FS_DISK_PROPERTIES* properties
);
Description

This function returns the information about the mounted drive. The results member of the properties object passed into the function is populated with the information about the drive.

Before starting a new request, the new_request member of the properties input parameter should be set to TRUE. This will initiate a new search request.

This function will return before the search is complete with partial results. All of the results except the free_clusters will be correct after the first call. The free_clusters will contain the number of free clusters found up until that point, thus the free_clusters result will continue to grow until the entire drive is searched. If an application only needs to know that a certain number of bytes is available and doesn't need to know the total free size, then this function can be called until the required free size is verified. To continue a search, pass a pointer to the same FS_DISK_PROPERTIES object that was passed in to create the search.

A new search request sould be made once this function has returned a value other than FS_GET_PROPERTIES_STILL_WORKING. Continuing a completed search can result in undefined behavior or results.

Typical Usage:

Copy Code
FS_DISK_PROPERTIES disk_properties;

disk_properties.new_request = TRUE;

do
{
    FSGetDiskProperties(&disk_properties);
} while (disk_properties.properties_status == FS_GET_PROPERTIES_STILL_WORKING);

results.disk_format - contains the format of the drive. Valid results are FAT12(1), FAT16(2), or FAT32(3).

results.sector_size - the sector size of the mounted drive. Valid values are 512, 1024, 2048, and 4096.

results.sectors_per_cluster - the number sectors per cluster.

results.total_clusters - the number of total clusters on the drive. This can be used to calculate the total disk size (total_clusters * sectors_per_cluster * sector_size = total size of drive in bytes)

results.free_clusters - the number of free (unallocated) clusters on the drive. This can be used to calculate the total free disk size (free_clusters * sectors_per_cluster * sector_size = total size of drive in bytes)

Preconditions

1) ALLOW_GET_DISK_PROPERTIES must be defined in FSconfig.h 2) a FS_DISK_PROPERTIES object must be created before the function is called 3) the new_request member of the FS_DISK_PROPERTIES object must be set before calling the function for the first time. This will start a new search. 4) this function should not be called while there is a file open. Close all files before calling this function.

Parameters
Parameters | Description
properties | a pointer to a FS_DISK_PROPERTIES object where the results should be stored.
Return Values
Return Values | Description
following possible values |
FS_GET_PROPERTIES_NO_ERRORS | operation completed without error. Results are in the properties object passed into the function.
FS_GET_PROPERTIES_DISK_NOT_MOUNTED | there is no mounted disk. Results in properties object is not valid
FS_GET_PROPERTIES_CLUSTER_FAILURE | there was a failure trying to read a cluster from the drive. The results in the properties object is a partial result up until the point of the failure.
FS_GET_PROPERTIES_STILL_WORKING | the search for free sectors is still in process. Continue calling this function with the same properties pointer until either the function completes or until the partial results meets the application needs. The properties object contains the partial results of the search and can be used by the application.
Side Effects

Can cause errors if called when files are open. Close all files before calling this function.

Calling this function without setting the new_request member on the first call can result in undefined behavior and results.

Calling this function after a result is returned other than FS_GET_PROPERTIES_STILL_WORKING can result in undefined behavior and results.

Remarks

PIC24F size estimates: Flash - 400 bytes (-Os setting)

PIC24F speed estimates: Search takes approximately 7 seconds per Gigabyte of drive space. Speed will vary based on the number of sectors per cluster and the sector size.

APIs > File Manipulation Layer (FSIO) > Public Members > FSGetDiskProperties Function


ALLOW_DIRS Macro

Contents | Index | Home
Previous | Up | Next
ALLOW_DIRS Macro
C
#define ALLOW_DIRS
Description

The ALLOW_DIRS definition can be commented out to disable all directory functionality. This will reduce code size. If directories are enabled, write operations must also be enabled by uncommenting ALLOW_WRITES in order to use the FSmkdir or FSrmdir functions.

APIs > File Manipulation Layer (FSIO) > Public Members > ALLOW_DIRS Macro


ALLOW_FILESEARCH Macro

Contents | Index | Home
Previous | Up | Next
ALLOW_FILESEARCH Macro
C
#define ALLOW_FILESEARCH
Description

The ALLOW_FILESEARCH definition can be commented out to disable file search functions in the library. This will prevent the use of the FindFirst and FindNext functions and reduce code size.

APIs > File Manipulation Layer (FSIO) > Public Members > ALLOW_FILESEARCH Macro


ALLOW_WRITES Macro

Contents | Index | Home
Previous | Up | Next
ALLOW_WRITES Macro
C
#define ALLOW_WRITES
Description

The ALLOW_WRITES definition can be commented out to disable all operations that write to the device. This will greatly reduce code size.

APIs > File Manipulation Layer (FSIO) > Public Members > ALLOW_WRITES Macro


APPEND Macro

Contents | Index | Home
Previous | Up | Next
APPEND Macro
C
#define APPEND "a"     //deprecated
Description

deprecated

APIs > File Manipulation Layer (FSIO) > Public Members > APPEND Macro


ATTR_ARCHIVE Macro

Contents | Index | Home
Previous | Up | Next
ATTR_ARCHIVE Macro
C
#define ATTR_ARCHIVE 0x20
Description

A macro for the archive attribute. This attribute will indicate to some archiving programs that the file with this attribute needs to be backed up. Most operating systems create files with the archive attribute set.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_ARCHIVE Macro


ATTR_DIRECTORY Macro

Contents | Index | Home
Previous | Up | Next
ATTR_DIRECTORY Macro
C
#define ATTR_DIRECTORY 0x10
Description

A macro for the directory attribute. If a directory entry has this attribute set, the file it points to is a directory- type file, and will contain directory entries that point to additional directories or files.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_DIRECTORY Macro


ATTR_HIDDEN Macro

Contents | Index | Home
Previous | Up | Next
ATTR_HIDDEN Macro
C
#define ATTR_HIDDEN 0x02
Description

A macro for the hidden attribute. A file with this attribute may be hidden from the user, depending on the implementation of the operating system.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_HIDDEN Macro


ATTR_MASK Macro

Contents | Index | Home
Previous | Up | Next
ATTR_MASK Macro
C
#define ATTR_MASK 0x3f
Description

A macro for all attributes. The search functions in this library require an argument that determines which attributes a file is allowed to have in order to be found. If ATTR_MASK is specified as this argument, any file may be found, regardless of its attributes.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_MASK Macro


ATTR_READ_ONLY Macro

Contents | Index | Home
Previous | Up | Next
ATTR_READ_ONLY Macro
C
#define ATTR_READ_ONLY 0x01
Description

A macro for the read-only attribute. A file with this attribute should not be written to. Note that this attribute will not actually prevent a write to the file; that functionality is operating-system dependant. The user should take care not to write to a read-only file.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_READ_ONLY Macro


ATTR_SYSTEM Macro

Contents | Index | Home
Previous | Up | Next
ATTR_SYSTEM Macro
C
#define ATTR_SYSTEM 0x04
Description

A macro for the system attribute. A file with this attribute is used by the operating system, and should not be modified. Note that this attribute will not actually prevent a write to the file.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_SYSTEM Macro


ATTR_VOLUME Macro

Contents | Index | Home
Previous | Up | Next
ATTR_VOLUME Macro
C
#define ATTR_VOLUME 0x08
Description

A macro for the volume attribute. If the first directory entry in the root directory has the volume attribute set, the device will use the name in that directory entry as the volume name.

APIs > File Manipulation Layer (FSIO) > Public Members > ATTR_VOLUME Macro


EOF Macro

Contents | Index | Home
Previous | Up | Next
EOF Macro
C
#define EOF ((int)-1)
Description

The EOF macro is used to indicate error conditions in some function calls. It is also used to indicate that the end-of-file has been reached.

APIs > File Manipulation Layer (FSIO) > Public Members > EOF Macro


FALSE Macro

Contents | Index | Home
Previous | Up | Next
FALSE Macro
C
#define FALSE 0
Description

This macro will indicate that a condition is false.

APIs > File Manipulation Layer (FSIO) > Public Members > FALSE Macro


FS_DYNAMIC_MEM Macro

Contents | Index | Home
Previous | Up | Next
FS_DYNAMIC_MEM Macro
C
#define FS_DYNAMIC_MEM
Description

The FS_DYNAMIC_MEM macro will cause FSFILE objects to be allocated from a dynamic heap. If it is undefined, the file objects will be allocated using a static array.

APIs > File Manipulation Layer (FSIO) > Public Members > FS_DYNAMIC_MEM Macro


SUPPORT_LFN Macro

Contents | Index | Home
Previous | Up | Next
SUPPORT_LFN Macro
C
#define SUPPORT_LFN
Description

If this macro is disabled then only 8.3 format file name is enabled. If this macro is enabled then long file names upto 256 characters are supported.

APIs > File Manipulation Layer (FSIO) > Public Members > SUPPORT_LFN Macro


FS_MAX_FILES_OPEN Macro

Contents | Index | Home
Previous | Up | Next
FS_MAX_FILES_OPEN Macro
C
#define FS_MAX_FILES_OPEN 3
Description

The FS_MAX_FILES_OPEN #define is only applicable when dynamic memory allocation is not used (FS_DYNAMIC_MEM is not defined). This macro defines the maximum number of open files at any given time. The amount of RAM used by FSFILE objects will be equal to the size of an FSFILE object multipled by this macro value. This value should be kept as small as possible as dictated by the application. This will reduce memory usage.

APIs > File Manipulation Layer (FSIO) > Public Members > FS_MAX_FILES_OPEN Macro


MAX_HEAP_SIZE Macro

Contents | Index | Home
Previous | Up | Next
MAX_HEAP_SIZE Macro
C
#define MAX_HEAP_SIZE 0x100
Description

When using dynamic FSFILE object allocation with PIC18, the MAX_HEAP_SIZE will allow the user to specify the size of the dynamic heap to use

APIs > File Manipulation Layer (FSIO) > Public Members > MAX_HEAP_SIZE Macro


MDD_MediaDetect Macro

Contents | Index | Home
Previous | Up | Next
MDD_MediaDetect Macro
C
#define MDD_MediaDetect USBHostMSDSCSIMediaDetect
Description

Function pointer to the Media Detect Physical Layer function

APIs > File Manipulation Layer (FSIO) > Public Members > MDD_MediaDetect Macro


MEDIA_SECTOR_SIZE Macro

Contents | Index | Home
Previous | Up | Next
MEDIA_SECTOR_SIZE Macro
C
#define MEDIA_SECTOR_SIZE 512
Description

The MEDIA_SECTOR_SIZE macro will define the size of a sector on the FAT file system. This value must equal 512 bytes, 1024 bytes, 2048 bytes, or 4096 bytes. The value of a sector will usually be 512 bytes.

APIs > File Manipulation Layer (FSIO) > Public Members > MEDIA_SECTOR_SIZE Macro


NEAR_MODEL Macro

Contents | Index | Home
Previous | Up | Next
NEAR_MODEL Macro
C
#define NEAR_MODEL
Description

By uncommenting the NEAR_MODEL macro, the user can enable near-model RAM addressing when using dynamic FSFILE object allocation with PIC18

APIs > File Manipulation Layer (FSIO) > Public Members > NEAR_MODEL Macro


SEEK_CUR Macro

Contents | Index | Home
Previous | Up | Next
SEEK_CUR Macro
C
#define SEEK_CUR 1
Description

Functions as an input for FSfseek that specifies that the position in the file will be changed relative to the current location of the file

APIs > File Manipulation Layer (FSIO) > Public Members > SEEK_CUR Macro


SEEK_END Macro

Contents | Index | Home
Previous | Up | Next
SEEK_END Macro
C
#define SEEK_END 2
Description

Functions as an input for FSfseek that specifies that the position in the file will be changed relative to the end of the file. For this macro, the offset value will be subtracted from the end location of the file by default.

APIs > File Manipulation Layer (FSIO) > Public Members > SEEK_END Macro


SEEK_SET Macro

Contents | Index | Home
Previous | Up | Next
SEEK_SET Macro
C
#define SEEK_SET 0
Description

Functions as an input for FSfseek that specifies that the position in the file will be changed relative to the beginning of the file.

APIs > File Manipulation Layer (FSIO) > Public Members > SEEK_SET Macro


SUPPORT_FAT32 Macro

Contents | Index | Home
Previous | Up | Next
SUPPORT_FAT32 Macro
C
#define SUPPORT_FAT32
Description

The SUPPORT_FAT32 definition can be commented out to disable support for FAT32 functionality. This will save a small amount of code space.

APIs > File Manipulation Layer (FSIO) > Public Members > SUPPORT_FAT32 Macro


TRUE Macro

Contents | Index | Home
Previous | Up | Next
TRUE Macro
C
#define TRUE !FALSE
Description

True value

APIs > File Manipulation Layer (FSIO) > Public Members > TRUE Macro


USE_SD_INTERFACE_WITH_SPI Macro

Contents | Index | Home
Previous | Up | Next
USE_SD_INTERFACE_WITH_SPI Macro
C
#define USE_SD_INTERFACE_WITH_SPI
Description

Macro used to enable the SD-SPI physical layer (SD-SPI.c and .h)

APIs > File Manipulation Layer (FSIO) > Public Members > USE_SD_INTERFACE_WITH_SPI Macro


USEREALTIMECLOCK Macro

Contents | Index | Home
Previous | Up | Next
USEREALTIMECLOCK Macro
C
#define USEREALTIMECLOCK
Description

The USEREALTIMECLOCK macro will configure the code to automatically generate timestamp information for files from the RTCC module. The user must enable and configure the RTCC module before creating or modifying files.

APIs > File Manipulation Layer (FSIO) > Public Members > USEREALTIMECLOCK Macro


WRITE Macro

Contents | Index | Home
Previous | Up | Next
WRITE Macro
C
#define WRITE "w"     //deprecated
Description

deprecated

APIs > File Manipulation Layer (FSIO) > Public Members > WRITE Macro


FSFILE Structure

Contents | Index | Home
Previous | Up | Next
FSFILE Structure
C
typedef struct {
  DISK * dsk;
  DWORD cluster;
  DWORD ccls;
  WORD sec;
  WORD pos;
  DWORD seek;
  DWORD size;
  FILEFLAGS flags;
  WORD time;
  WORD date;
  char name[FILE_NAME_SIZE_8P3];
  BOOL AsciiEncodingType;
  unsigned short int * utf16LFNptr;
  unsigned short int utf16LFNlength;
  WORD entry;
  WORD chk;
  WORD attributes;
  DWORD dirclus;
  DWORD dirccls;
} FSFILE;
Description

The FSFILE structure is used to hold file information for an open file as it's being modified or accessed. A pointer to an open file's FSFILE structure will be passeed to any library function that will modify that file.

Members
Members | Description
DISK * dsk; | Pointer to a DISK structure
DWORD cluster; | The first cluster of the file
DWORD ccls; | The current cluster of the file
WORD sec; | The current sector in the current cluster of the file
WORD pos; | The position in the current sector
DWORD seek; | The absolute position in the file
DWORD size; | The size of the file
FILEFLAGS flags; | A structure containing file flags
WORD time; | The file's last update time
WORD date; | The file's last update date
char name[FILE_NAME_SIZE_8P3]; | The short name of the file
BOOL AsciiEncodingType; | Ascii file name or Non-Ascii file name indicator
unsigned short int * utf16LFNptr; | Pointer to long file name in UTF16 format
unsigned short int utf16LFNlength; | LFN length in terms of words including the NULL word at the last.
WORD entry; | The position of the file's directory entry in it's directory
WORD chk; | File structure checksum
WORD attributes; | The file attributes
DWORD dirclus; | The base cluster of the file's directory
DWORD dirccls; | The current cluster of the file's directory
APIs > File Manipulation Layer (FSIO) > Public Members > FSFILE Structure


SearchRec Structure

Contents | Index | Home
Previous | Up | Next
SearchRec Structure
C
typedef struct {
  char filename[FILE_NAME_SIZE_8P3 + 2];
  unsigned char attributes;
  unsigned long filesize;
  unsigned long timestamp;
  BOOL AsciiEncodingType;
  unsigned short int * utf16LFNfound;
  unsigned short int utf16LFNfoundLength;
  unsigned int entry;
  char searchname[FILE_NAME_SIZE_8P3 + 2];
  unsigned char searchattr;
  unsigned long cwdclus;
  unsigned char initialized;
} SearchRec;
Description

The SearchRec structure is used when searching for file on a device. It contains parameters that will be loaded with file information when a file is found. It also contains the parameters that the user searched for, allowing further searches to be perfomed in the same directory for additional files that meet the specified criteria.

Members
Members | Description
char filename[FILE_NAME_SIZE_8P3 + 2]; | The name of the file that has been found
unsigned char attributes; | The attributes of the file that has been found
unsigned long filesize; | The size of the file that has been found
unsigned long timestamp; | The last modified time of the file that has been found (create time for directories)
BOOL AsciiEncodingType; | Ascii file name or Non-Ascii file name indicator
unsigned short int * utf16LFNfound; | Pointer to long file name found in UTF16 format
unsigned short int utf16LFNfoundLength; | LFN Found length in terms of words including the NULL word at the last.
unsigned int entry; | The directory entry of the last file found that matches the specified attributes. (Internal use only)
char searchname[FILE_NAME_SIZE_8P3 + 2]; | The 8.3 format name specified when the user began the search. (Internal use only)
unsigned char searchattr; | The attributes specified when the user began the search. (Internal use only)
unsigned long cwdclus; | The directory that this search was performed in. (Internal use only)
unsigned char initialized; | Check to determine if the structure was initialized by FindFirst (Internal use only)
APIs > File Manipulation Layer (FSIO) > Public Members > SearchRec Structure


FILE_NAME_SIZE_8P3 Macro

Contents | Index | Home
Previous | Up | Next
FILE_NAME_SIZE_8P3 Macro
C
#define FILE_NAME_SIZE_8P3 11
Description

The FILE_NAME_SIZE_8P3 macro indicates the number of characters that an 8.3 file name will take up when packed in a directory entry. This value includes 8 characters for the name and 3 for the extension. Note that the radix is not stored in the directory entry.

APIs > File Manipulation Layer (FSIO) > Public Members > FILE_NAME_SIZE_8P3 Macro


MAX_FILE_NAME_LENGTH_LFN Macro

Contents | Index | Home
Previous | Up | Next
MAX_FILE_NAME_LENGTH_LFN Macro
C
#define MAX_FILE_NAME_LENGTH_LFN 256
Description

The MAX_FILE_NAME_LENGTH_LFN macro indicates the maximum number of characters in an LFN file name.

APIs > File Manipulation Layer (FSIO) > Public Members > MAX_FILE_NAME_LENGTH_LFN Macro


Library Members

Contents | Index | Home
Previous | Up | Next
Library Members

The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.

Enumerations
Name | Description
CETYPE | An enumeration used for various error codes.
_CETYPE | An enumeration used for various error codes.
MEDIA_ERRORS | This is type MEDIA_ERRORS.
SEARCH_TYPE | Indicates how to search for file entries in the FILEfind function
Functions
Name | Description
ReadByte | Read a byte from a buffer
ReadDWord | Read a 32-bit double word from a buffer
ReadWord | Read a 16-bit word from a buffer
Macros
Name | Description
ATTR_LONG_NAME | A macro for the attributes for a long-file name entry
BSI_BOOTSIG | A macro for the boot sector boot signature offset
BSI_BPS | A macro for the boot sector bytes per sector value offset
BSI_FAT32_BOOTSIG | A macro for the FAT32 boot sector boot signature offset
BSI_FAT32_FSTYPE | A macro for the FAT32 boot sector file system type string offset
BSI_FATCOUNT | A macro for the boot sector FAT count value offset
BSI_FATSZ32 | A macro for the boot sector 32-bit sector per FAT value offset
BSI_FSTYPE | A macro for the boot sector file system type string offset
BSI_RESRVSEC | A macro for the boot sector reserved sector count value offset
BSI_ROOTCLUS | A macro for the boot sector start cluster of root directory value offset
BSI_ROOTDIRENTS | A macro for the boot sector root directory entry count value offset
BSI_SPC | A macro for the boot sector sector per cluster value offset
BSI_SPF | A macro for the boot sector sectors per FAT value offset
BSI_TOTSEC16 | A macro for the boot sector 16-bit total sector count value offset
BSI_TOTSEC32 | A macro for the boot sector 32-bit total sector count value offset
CE_EOF | Error that indicates that the end of the file has been reached
CE_FAT_EOF | Error that indicates an attempt to read FAT entries beyond the end of the file
CLUSTER_EMPTY | A macro to indicate an empty FAT entry
CLUSTER_FAIL_FAT16 | A macro to indicate the failure of the ReadFAT function
CLUSTER_FAIL_FAT32 | A macro to indicate the failure of the ReadFAT function
DIR_DEL | A macro for a deleted dir entry marker.
DIR_EMPTY | A macro for the last dir entry marker.
DIR_EXTENSION | A macro used to indicate the length of an 8.3 file extension
DIR_NAMECOMP | A macro used to indicate the length of an 8.3 file name and extension
DIR_NAMESIZE | A macro used to indicate the length of an 8.3 file name
END_CLUSTER_FAT12 | A macro to indicate the last allocatable cluster for FAT12
END_CLUSTER_FAT16 | A macro to indicate the last allocatable cluster for FAT16
END_CLUSTER_FAT32 | A macro to indicate the last allocatable cluster for FAT32
FAT_GOOD_SIGN_0 | A macro for the first boot sector/MBR signature byte
FAT_GOOD_SIGN_1 | A macro for the second boot sector/MBR signature byte
FAT12 | A macro indicating the device is formatted with FAT12
FAT16 | A macro indicating the device is formatted with FAT16
FAT32 | A macro indicating the device is formatted with FAT32
FILE_NAME_SIZE | This is macro FILE_NAME_SIZE.
FO_MBR | A macro indicating the offset for the master boot record
FOUND | A macro indicating a dir entry was found
GetInstructionClock | Instruction clock frequency
GetPeripheralClock | Peripheral clock frequency
GetSystemClock | System clock frequency (Hz)
INPUT | A macro used to set TRIS register bits to input
LAST_CLUSTER_FAT12 | A macro to indicate the last cluster value for FAT12
LAST_CLUSTER_FAT16 | A macro to indicate the last cluster value for FAT16
LAST_CLUSTER_FAT32 | A macro to indicate the last cluster value for FAT32
MASK_MAX_FILE_ENTRY_LIMIT_BITS | A mask that indicates the limit of directory entries in a sector
MDD_InitIO | Function pointer to the I/O Initialization Physical Layer function
MDD_MediaInitialize | Function pointer to the Media Initialize Physical Layer function
MDD_ReadCapacity | Function pointer to the Read Capacity Physical Layer function
MDD_ReadSectorSize | Function pointer to the Read Sector Size Physical Layer Function
MDD_SectorRead | Function pointer to the Sector Read Physical Layer function
MDD_SectorWrite | Function pointer to the Sector Write Physical Layer function
MDD_ShutdownMedia | Function pointer to the Media Shutdown Physical Layer function
MDD_WriteProtectState | Function pointer to the Write Protect Check Physical Layer function
NO_MORE | A macro indicating that no more files were found
NOT_FOUND | A macro indicating no dir entry was found
NUMBER_OF_BYTES_IN_DIR_ENTRY | A macro indicating the number of bytes in a directory entry.
OUTPUT | A macro used to set TRIS register bits to output
RAMread | A macro to read a byte from RAM
RAMreadD | A macro to read a 32-bit word from RAM
RAMreadW | A macro to read a 16-bit word from RAM
RAMwrite | A macro to write a byte to RAM
TOTAL_FILE_SIZE | This is macro TOTAL_FILE_SIZE.
VALUE_BASED_ON_ENTRIES_PER_CLUSTER | Value used for shift operations to calculate the sector offset in a directory
VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT | A value that will indicate that a dotdot directory entry points to the root.
Structures
Name | Description
FILEFLAGS | This is type FILEFLAGS.
MEDIA_INFORMATION | This is type MEDIA_INFORMATION.
Types
Name | Description
BootSec | A pointer to a _BootSec structure
PT_MBR | A pointer to a _PT_MBR structure
SALLOC | The segment header data type
SWORD | A 24-bit data type
APIs > File Manipulation Layer (FSIO) > Library Members


ReadByte Function

Contents | Index | Home
Previous | Up | Next
ReadByte Function
C
BYTE ReadByte(
    BYTE* pBuffer,
    WORD index
);
Description

Reads a byte from a buffer

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
pBuffer | pointer to a buffer to read from
index | index in the buffer to read to
Returns

BYTE - the byte read

Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Library Members > ReadByte Function


ReadDWord Function

Contents | Index | Home
Previous | Up | Next
ReadDWord Function
C
DWORD ReadDWord(
    BYTE* pBuffer,
    WORD index
);
Description

Reads a 32-bit double word from a buffer

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
pBuffer | pointer to a buffer to read from
index | index in the buffer to read to
Returns

DWORD - the double word read

Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Library Members > ReadDWord Function


ReadWord Function

Contents | Index | Home
Previous | Up | Next
ReadWord Function
C
WORD ReadWord(
    BYTE* pBuffer,
    WORD index
);
Description

Reads a 16-bit word from a buffer

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
pBuffer | pointer to a buffer to read from
index | index in the buffer to read to
Returns

WORD - the word read

Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Library Members > ReadWord Function


ATTR_LONG_NAME Macro

Contents | Index | Home
Previous | Up | Next
ATTR_LONG_NAME Macro
C
#define ATTR_LONG_NAME 0x0f
Description

A macro for the long-name attributes. If a directory entry is used in a long-file name implementation, it will have all four lower bits set. This indicates that any software that does not support long file names should ignore that entry.

APIs > File Manipulation Layer (FSIO) > Library Members > ATTR_LONG_NAME Macro


BSI_BOOTSIG Macro

Contents | Index | Home
Previous | Up | Next
BSI_BOOTSIG Macro
C
#define BSI_BOOTSIG 38
Description

A macro for the boot sector boot signature offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_BOOTSIG Macro


BSI_BPS Macro

Contents | Index | Home
Previous | Up | Next
BSI_BPS Macro
C
#define BSI_BPS 11
Description

A macro for the boot sector bytes per sector value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_BPS Macro


BSI_FAT32_BOOTSIG Macro

Contents | Index | Home
Previous | Up | Next
BSI_FAT32_BOOTSIG Macro
C
#define BSI_FAT32_BOOTSIG 66
Description

A macro for the FAT32 boot sector boot signature offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_FAT32_BOOTSIG Macro


BSI_FAT32_FSTYPE Macro

Contents | Index | Home
Previous | Up | Next
BSI_FAT32_FSTYPE Macro
C
#define BSI_FAT32_FSTYPE 82
Description

A macro for the FAT32 boot sector file system type string offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_FAT32_FSTYPE Macro


BSI_FATCOUNT Macro

Contents | Index | Home
Previous | Up | Next
BSI_FATCOUNT Macro
C
#define BSI_FATCOUNT 16
Description

A macro for the boot sector FAT count value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_FATCOUNT Macro


BSI_FATSZ32 Macro

Contents | Index | Home
Previous | Up | Next
BSI_FATSZ32 Macro
C
#define BSI_FATSZ32 36
Description

A macro for the boot sector 32-bit sector per FAT value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_FATSZ32 Macro


BSI_FSTYPE Macro

Contents | Index | Home
Previous | Up | Next
BSI_FSTYPE Macro
C
#define BSI_FSTYPE 54
Description

A macro for the boot sector file system type string offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_FSTYPE Macro


BSI_RESRVSEC Macro

Contents | Index | Home
Previous | Up | Next
BSI_RESRVSEC Macro
C
#define BSI_RESRVSEC 14
Description

A macro for the boot sector reserved sector count value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_RESRVSEC Macro


BSI_ROOTCLUS Macro

Contents | Index | Home
Previous | Up | Next
BSI_ROOTCLUS Macro
C
#define BSI_ROOTCLUS 44
Description

A macro for the boot sector start cluster of root directory value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_ROOTCLUS Macro


BSI_ROOTDIRENTS Macro

Contents | Index | Home
Previous | Up | Next
BSI_ROOTDIRENTS Macro
C
#define BSI_ROOTDIRENTS 17
Description

A macro for the boot sector root directory entry count value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_ROOTDIRENTS Macro


BSI_SPC Macro

Contents | Index | Home
Previous | Up | Next
BSI_SPC Macro
C
#define BSI_SPC 13
Description

A macro for the boot sector sector per cluster value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_SPC Macro


BSI_SPF Macro

Contents | Index | Home
Previous | Up | Next
BSI_SPF Macro
C
#define BSI_SPF 22
Description

A macro for the boot sector sectors per FAT value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_SPF Macro


BSI_TOTSEC16 Macro

Contents | Index | Home
Previous | Up | Next
BSI_TOTSEC16 Macro
C
#define BSI_TOTSEC16 19
Description

A macro for the boot sector 16-bit total sector count value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_TOTSEC16 Macro


BSI_TOTSEC32 Macro

Contents | Index | Home
Previous | Up | Next
BSI_TOTSEC32 Macro
C
#define BSI_TOTSEC32 32
Description

A macro for the boot sector 32-bit total sector count value offset

APIs > File Manipulation Layer (FSIO) > Library Members > BSI_TOTSEC32 Macro


CE_EOF Macro

Contents | Index | Home
Previous | Up | Next
CE_EOF Macro
C
#define CE_EOF 61   // Error that indicates that the end of the file has been reached
Description

Error that indicates that the end of the file has been reached

APIs > File Manipulation Layer (FSIO) > Library Members > CE_EOF Macro


CE_FAT_EOF Macro

Contents | Index | Home
Previous | Up | Next
CE_FAT_EOF Macro
C
#define CE_FAT_EOF 60   // Error that indicates an attempt to read FAT entries beyond the end of the file
Description

Error that indicates an attempt to read FAT entries beyond the end of the file

APIs > File Manipulation Layer (FSIO) > Library Members > CE_FAT_EOF Macro


CLUSTER_EMPTY Macro

Contents | Index | Home
Previous | Up | Next
CLUSTER_EMPTY Macro
C
#define CLUSTER_EMPTY 0x0000
Description

The CLUSTER_EMPTY value is used to indicate that a FAT entry and it's corresponding cluster are available.

APIs > File Manipulation Layer (FSIO) > Library Members > CLUSTER_EMPTY Macro


CLUSTER_FAIL_FAT16 Macro

Contents | Index | Home
Previous | Up | Next
CLUSTER_FAIL_FAT16 Macro
C
#define CLUSTER_FAIL_FAT16 0xFFFF
Description

The CLUSTER_FAIL_FAT16 macro is used by the ReadFAT function to indicate that an error occured reading a FAT12 or FAT16 file allocation table. Note that since '0xFFF8' is used for the last cluster return value in the FAT16 implementation the end-of-file value '0xFFFF' can be used to indicate an error condition.

APIs > File Manipulation Layer (FSIO) > Library Members > CLUSTER_FAIL_FAT16 Macro


CLUSTER_FAIL_FAT32 Macro

Contents | Index | Home
Previous | Up | Next
CLUSTER_FAIL_FAT32 Macro
C
#define CLUSTER_FAIL_FAT32 0x0FFFFFFF
Description

The CLUSTER_FAIL_FAT32 macro is used by the ReadFAT function to indicate that an error occured reading a FAT32 file allocation able.

APIs > File Manipulation Layer (FSIO) > Library Members > CLUSTER_FAIL_FAT32 Macro


DIR_DEL Macro

Contents | Index | Home
Previous | Up | Next
DIR_DEL Macro
C
#define DIR_DEL 0xE5
Description

The DIR_DEL macro is used to mark a directory entry as deleted. When a file is deleted, this value will replace the first character in the file name, and will indicate that the file the entry points to was deleted.

APIs > File Manipulation Layer (FSIO) > Library Members > DIR_DEL Macro


DIR_EMPTY Macro

Contents | Index | Home
Previous | Up | Next
DIR_EMPTY Macro
C
#define DIR_EMPTY 0
Description

The DIR_EMPTY macro is used to indicate the last entry in a directory. Since entries in use cannot start with a 0 and deleted entries start with the DIR_DEL character, a 0 will mark the end of the in-use or previously used group of entries in a directory

APIs > File Manipulation Layer (FSIO) > Library Members > DIR_EMPTY Macro


DIR_EXTENSION Macro

Contents | Index | Home
Previous | Up | Next
DIR_EXTENSION Macro
C
#define DIR_EXTENSION 3
Description

The DIR_EXTENSION macro is used when validating the extension portion of 8.3 filenames

APIs > File Manipulation Layer (FSIO) > Library Members > DIR_EXTENSION Macro


DIR_NAMECOMP Macro

Contents | Index | Home
Previous | Up | Next
DIR_NAMECOMP Macro
C
#define DIR_NAMECOMP (DIR_NAMESIZE+DIR_EXTENSION)
Description

The DIR_NAMECOMP macro is used when validating 8.3 filenames

APIs > File Manipulation Layer (FSIO) > Library Members > DIR_NAMECOMP Macro


DIR_NAMESIZE Macro

Contents | Index | Home
Previous | Up | Next
DIR_NAMESIZE Macro
C
#define DIR_NAMESIZE 8
Description

The DIR_NAMESIZE macro is used when validing the name portion of 8.3 filenames

APIs > File Manipulation Layer (FSIO) > Library Members > DIR_NAMESIZE Macro


END_CLUSTER_FAT12 Macro

Contents | Index | Home
Previous | Up | Next
END_CLUSTER_FAT12 Macro
C
#define END_CLUSTER_FAT12 0xFF7
Description

The END_CLUSTER_FAT12 value is used as a comparison in FAT12 to determine that the firmware has reached the end of the range of allowed allocatable clusters.

APIs > File Manipulation Layer (FSIO) > Library Members > END_CLUSTER_FAT12 Macro


END_CLUSTER_FAT16 Macro

Contents | Index | Home
Previous | Up | Next
END_CLUSTER_FAT16 Macro
C
#define END_CLUSTER_FAT16 0xFFF7
Description

The END_CLUSTER_FAT16 value is used as a comparison in FAT16 to determine that the firmware has reached the end of the range of allowed allocatable clusters.

APIs > File Manipulation Layer (FSIO) > Library Members > END_CLUSTER_FAT16 Macro


END_CLUSTER_FAT32 Macro

Contents | Index | Home
Previous | Up | Next
END_CLUSTER_FAT32 Macro
C
#define END_CLUSTER_FAT32 0x0FFFFFF7
Description

The END_CLUSTER_FAT32 value is used as a comparison in FAT32 to determine that the firmware has reached the end of the range of allowed allocatable clusters.

APIs > File Manipulation Layer (FSIO) > Library Members > END_CLUSTER_FAT32 Macro


FAT_GOOD_SIGN_0 Macro

Contents | Index | Home
Previous | Up | Next
FAT_GOOD_SIGN_0 Macro
C
#define FAT_GOOD_SIGN_0 0x55
Description

The FAT_GOOD_SIGN_0 macro is used to determine that the first byte of the MBR or boot sector signature code is correct

APIs > File Manipulation Layer (FSIO) > Library Members > FAT_GOOD_SIGN_0 Macro


FAT_GOOD_SIGN_1 Macro

Contents | Index | Home
Previous | Up | Next
FAT_GOOD_SIGN_1 Macro
C
#define FAT_GOOD_SIGN_1 0xAA
Description

The FAT_GOOD_SIGN_1 macro is used to determine that the second byte of the MBR or boot sector signature code is correct

APIs > File Manipulation Layer (FSIO) > Library Members > FAT_GOOD_SIGN_1 Macro


FAT12 Macro

Contents | Index | Home
Previous | Up | Next
FAT12 Macro
C
#define FAT12 1
Description

The FAT12 macro is used to indicate that the file system on the device being accessed is a FAT12 file system.

APIs > File Manipulation Layer (FSIO) > Library Members > FAT12 Macro


FAT16 Macro

Contents | Index | Home
Previous | Up | Next
FAT16 Macro
C
#define FAT16 2
Description

The FAT16 macro is used to indicate that the file system on the device being accessed is a FAT16 file system.

APIs > File Manipulation Layer (FSIO) > Library Members > FAT16 Macro


FAT32 Macro

Contents | Index | Home
Previous | Up | Next
FAT32 Macro
C
#define FAT32 3
Description

The FAT32 macro is used to indicate that the file system on the device being accessed is a FAT32 file system.

APIs > File Manipulation Layer (FSIO) > Library Members > FAT32 Macro


FILE_NAME_SIZE Macro

Contents | Index | Home
Previous | Up | Next
FILE_NAME_SIZE Macro
C
#define FILE_NAME_SIZE FILE_NAME_SIZE_8P3
Description

This is macro FILE_NAME_SIZE.

APIs > File Manipulation Layer (FSIO) > Library Members > FILE_NAME_SIZE Macro


FO_MBR Macro

Contents | Index | Home
Previous | Up | Next
FO_MBR Macro
C
#define FO_MBR 0L
Description

FO_MBR is a macro that indicates the addresss of the master boot record on the device. When the device is initialized this sector will be read

APIs > File Manipulation Layer (FSIO) > Library Members > FO_MBR Macro


FOUND Macro

Contents | Index | Home
Previous | Up | Next
FOUND Macro
C
#define FOUND 0
Description

The FOUND macro indicates that a directory entry was found in the specified position

APIs > File Manipulation Layer (FSIO) > Library Members > FOUND Macro


GetInstructionClock Macro

Contents | Index | Home
Previous | Up | Next
GetInstructionClock Macro
C
#define GetInstructionClock (GetSystemClock())
Description

Instruction clock frequency

APIs > File Manipulation Layer (FSIO) > Library Members > GetInstructionClock Macro


GetPeripheralClock Macro

Contents | Index | Home
Previous | Up | Next
GetPeripheralClock Macro
C
#define GetPeripheralClock (GetSystemClock()/2)
Description

Peripheral clock frequency

APIs > File Manipulation Layer (FSIO) > Library Members > GetPeripheralClock Macro


GetSystemClock Macro

Contents | Index | Home
Previous | Up | Next
GetSystemClock Macro
C
#define GetSystemClock (80000000ul)
Description

System clock frequency (Hz)

APIs > File Manipulation Layer (FSIO) > Library Members > GetSystemClock Macro


INPUT Macro

Contents | Index | Home
Previous | Up | Next
INPUT Macro
C
#define INPUT 1
Description

A macro used to set TRIS register bits to input

APIs > File Manipulation Layer (FSIO) > Library Members > INPUT Macro


LAST_CLUSTER_FAT12 Macro

Contents | Index | Home
Previous | Up | Next
LAST_CLUSTER_FAT12 Macro
C
#define LAST_CLUSTER_FAT12 0xff8
Description

The LAST_CLUSTER_FAT12 macro is used when reading the FAT to indicate that the next FAT12 entry for a file contains the end-of-file value.

APIs > File Manipulation Layer (FSIO) > Library Members > LAST_CLUSTER_FAT12 Macro


LAST_CLUSTER_FAT16 Macro

Contents | Index | Home
Previous | Up | Next
LAST_CLUSTER_FAT16 Macro
C
#define LAST_CLUSTER_FAT16 0xfff8
Description

The LAST_CLUSTER_FAT16 macro is used when reading the FAT to indicate that the next FAT16 entry for a file contains the end-of-file value.

APIs > File Manipulation Layer (FSIO) > Library Members > LAST_CLUSTER_FAT16 Macro


LAST_CLUSTER_FAT32 Macro

Contents | Index | Home
Previous | Up | Next
LAST_CLUSTER_FAT32 Macro
C
#define LAST_CLUSTER_FAT32 0x0FFFFFF8
Description

The LAST_CLUSTER_FAT32 macro is used when reading the FAT to indicate that the next FAT32 entry for a file contains the end-of-file value.

APIs > File Manipulation Layer (FSIO) > Library Members > LAST_CLUSTER_FAT32 Macro


MASK_MAX_FILE_ENTRY_LIMIT_BITS Macro

Contents | Index | Home
Previous | Up | Next
MASK_MAX_FILE_ENTRY_LIMIT_BITS Macro
C
#define MASK_MAX_FILE_ENTRY_LIMIT_BITS 0x0f
Description

The MASK_MAX_FILE_ENTRY_LIMIT_BITS is used to indicate to the Cache_File_Entry function that a new sector needs to be loaded.

APIs > File Manipulation Layer (FSIO) > Library Members > MASK_MAX_FILE_ENTRY_LIMIT_BITS Macro


MDD_InitIO Macro

Contents | Index | Home
Previous | Up | Next
MDD_InitIO Macro
C
#define MDD_InitIO ;
Description

Function pointer to the I/O Initialization Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_InitIO Macro


MDD_MediaInitialize Macro

Contents | Index | Home
Previous | Up | Next
MDD_MediaInitialize Macro
C
#define MDD_MediaInitialize USBHostMSDSCSIMediaInitialize
Description

Function pointer to the Media Initialize Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_MediaInitialize Macro


MDD_ReadCapacity Macro

Contents | Index | Home
Previous | Up | Next
MDD_ReadCapacity Macro
C
#define MDD_ReadCapacity MDD_SDSPI_ReadCapacity
Description

Function pointer to the Read Capacity Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_ReadCapacity Macro


MDD_ReadSectorSize Macro

Contents | Index | Home
Previous | Up | Next
MDD_ReadSectorSize Macro
C
#define MDD_ReadSectorSize MDD_SDSPI_ReadSectorSize
Description

Function pointer to the Read Sector Size Physical Layer Function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_ReadSectorSize Macro


MDD_SectorRead Macro

Contents | Index | Home
Previous | Up | Next
MDD_SectorRead Macro
C
#define MDD_SectorRead USBHostMSDSCSISectorRead
Description

Function pointer to the Sector Read Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_SectorRead Macro


MDD_SectorWrite Macro

Contents | Index | Home
Previous | Up | Next
MDD_SectorWrite Macro
C
#define MDD_SectorWrite USBHostMSDSCSISectorWrite
Description

Function pointer to the Sector Write Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_SectorWrite Macro


MDD_ShutdownMedia Macro

Contents | Index | Home
Previous | Up | Next
MDD_ShutdownMedia Macro
C
#define MDD_ShutdownMedia USBHostMSDSCSIMediaReset
Description

Function pointer to the Media Shutdown Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_ShutdownMedia Macro


MDD_WriteProtectState Macro

Contents | Index | Home
Previous | Up | Next
MDD_WriteProtectState Macro
C
#define MDD_WriteProtectState USBHostMSDSCSIWriteProtectState
Description

Function pointer to the Write Protect Check Physical Layer function

APIs > File Manipulation Layer (FSIO) > Library Members > MDD_WriteProtectState Macro


NO_MORE Macro

Contents | Index | Home
Previous | Up | Next
NO_MORE Macro
C
#define NO_MORE 2
Description

The NO_MORE macro indicates that there are no more directory entries to search for

APIs > File Manipulation Layer (FSIO) > Library Members > NO_MORE Macro


NOT_FOUND Macro

Contents | Index | Home
Previous | Up | Next
NOT_FOUND Macro
C
#define NOT_FOUND 1
Description

The NOT_FOUND macro indicates that the specified directory entry to load was deleted

APIs > File Manipulation Layer (FSIO) > Library Members > NOT_FOUND Macro


NUMBER_OF_BYTES_IN_DIR_ENTRY Macro

Contents | Index | Home
Previous | Up | Next
NUMBER_OF_BYTES_IN_DIR_ENTRY Macro
C
#define NUMBER_OF_BYTES_IN_DIR_ENTRY 32
Description

The NUMBER_OF_BYTES_IN_DIR_ENTRY macro represents the number of bytes in one directory entry. It is used to calculate the number of sectors in the root directory based on information in the boot sector.

APIs > File Manipulation Layer (FSIO) > Library Members > NUMBER_OF_BYTES_IN_DIR_ENTRY Macro


OUTPUT Macro

Contents | Index | Home
Previous | Up | Next
OUTPUT Macro
C
#define OUTPUT 0
Description

A macro used to set TRIS register bits to output

APIs > File Manipulation Layer (FSIO) > Library Members > OUTPUT Macro


RAMread Macro

Contents | Index | Home
Previous | Up | Next
RAMread Macro
C
#define RAMread( a, f) *(a+f)
Description

The RAMread macro is used to read a byte of data from a RAM array

APIs > File Manipulation Layer (FSIO) > Library Members > RAMread Macro


RAMreadD Macro

Contents | Index | Home
Previous | Up | Next
RAMreadD Macro
C
#define RAMreadD( a, f) *(DWORD *)(a+f)
Description

The RAMreadD macro is used to read four bytes of data from a RAM array

APIs > File Manipulation Layer (FSIO) > Library Members > RAMreadD Macro


RAMreadW Macro

Contents | Index | Home
Previous | Up | Next
RAMreadW Macro
C
#define RAMreadW( a, f) *(WORD *)(a+f)
Description

The RAMreadW macro is used to read two bytes of data from a RAM array

APIs > File Manipulation Layer (FSIO) > Library Members > RAMreadW Macro


RAMwrite Macro

Contents | Index | Home
Previous | Up | Next
RAMwrite Macro
C
#define RAMwrite( a, f, d) *(a+f) = d
Description

The RAMwrite macro is used to write a byte of data to a RAM array

APIs > File Manipulation Layer (FSIO) > Library Members > RAMwrite Macro


TOTAL_FILE_SIZE Macro

Contents | Index | Home
Previous | Up | Next
TOTAL_FILE_SIZE Macro
C
#define TOTAL_FILE_SIZE TOTAL_FILE_SIZE_8P3
Description

This is macro TOTAL_FILE_SIZE.

APIs > File Manipulation Layer (FSIO) > Library Members > TOTAL_FILE_SIZE Macro


VALUE_BASED_ON_ENTRIES_PER_CLUSTER Macro

Contents | Index | Home
Previous | Up | Next
VALUE_BASED_ON_ENTRIES_PER_CLUSTER Macro
C
#define VALUE_BASED_ON_ENTRIES_PER_CLUSTER 4
Description

The VALUE_BASED_ON_ENTRIES_PER_CLUSTER macro is used to calculate sector offsets for directories. The position of the entry is shifted by 4 bits (divided by 16, since there are 16 entries in a sector) to calculate how many sectors a specified entry is offset from the beginning of the directory.

APIs > File Manipulation Layer (FSIO) > Library Members > VALUE_BASED_ON_ENTRIES_PER_CLUSTER Macro


VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT Macro

Contents | Index | Home
Previous | Up | Next
VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT Macro
C
#define VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT 0
Description

The VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT macro is used as an absolute address when writing information to a dotdot entry in a newly created directory. If a dotdot entry points to the root directory, it's cluster value must be set to 0, regardless of the actual cluster number of the root directory.

APIs > File Manipulation Layer (FSIO) > Library Members > VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT Macro


BootSec Type

Contents | Index | Home
Previous | Up | Next
BootSec Type
C
typedef _BootSec * BootSec;
Description

The BootSec pointer points to a _BootSec structure.

APIs > File Manipulation Layer (FSIO) > Library Members > BootSec Type


CETYPE Enumeration

Contents | Index | Home
Previous | Up | Next
CETYPE Enumeration
C
typedef enum _CETYPE {
  CE_GOOD = 0,
  CE_ERASE_FAIL,
  CE_NOT_PRESENT,
  CE_NOT_FORMATTED,
  CE_BAD_PARTITION,
  CE_UNSUPPORTED_FS,
  CE_INIT_ERROR,
  CE_NOT_INIT,
  CE_BAD_SECTOR_READ,
  CE_WRITE_ERROR,
  CE_INVALID_CLUSTER,
  CE_FILE_NOT_FOUND,
  CE_DIR_NOT_FOUND,
  CE_BAD_FILE,
  CE_DONE,
  CE_COULD_NOT_GET_CLUSTER,
  CE_FILENAME_2_LONG,
  CE_FILENAME_EXISTS,
  CE_INVALID_FILENAME,
  CE_DELETE_DIR,
  CE_DIR_FULL,
  CE_DISK_FULL,
  CE_DIR_NOT_EMPTY,
  CE_NONSUPPORTED_SIZE,
  CE_WRITE_PROTECTED,
  CE_FILENOTOPENED,
  CE_SEEK_ERROR,
  CE_BADCACHEREAD,
  CE_CARDFAT32,
  CE_READONLY,
  CE_WRITEONLY,
  CE_INVALID_ARGUMENT,
  CE_TOO_MANY_FILES_OPEN,
  CE_UNSUPPORTED_SECTOR_SIZE
} CETYPE;
Description

The CETYPE enumeration is used to indicate different error conditions during device operation.

Members
Members | Description
CE_GOOD = 0 | No error
CE_ERASE_FAIL | An erase failed
CE_NOT_PRESENT | No device was present
CE_NOT_FORMATTED | The disk is of an unsupported format
CE_BAD_PARTITION | The boot record is bad
CE_UNSUPPORTED_FS | The file system type is unsupported
CE_INIT_ERROR | An initialization error has occured
CE_NOT_INIT | An operation was performed on an uninitialized device
CE_BAD_SECTOR_READ | A bad read of a sector occured
CE_WRITE_ERROR | Could not write to a sector
CE_INVALID_CLUSTER | Invalid cluster value > maxcls
CE_FILE_NOT_FOUND | Could not find the file on the device
CE_DIR_NOT_FOUND | Could not find the directory
CE_BAD_FILE | File is corrupted
CE_DONE | No more files in this directory
CE_COULD_NOT_GET_CLUSTER | Could not load/allocate next cluster in file
CE_FILENAME_2_LONG | A specified file name is too long to use
CE_FILENAME_EXISTS | A specified filename already exists on the device
CE_INVALID_FILENAME | Invalid file name
CE_DELETE_DIR | The user tried to delete a directory with FSremove
CE_DIR_FULL | All root dir entry are taken
CE_DISK_FULL | All clusters in partition are taken
CE_DIR_NOT_EMPTY | This directory is not empty yet, remove files before deleting
CE_NONSUPPORTED_SIZE | The disk is too big to format as FAT16
CE_WRITE_PROTECTED | Card is write protected
CE_FILENOTOPENED | File not opened for the write
CE_SEEK_ERROR | File location could not be changed successfully
CE_BADCACHEREAD | Bad cache read
CE_CARDFAT32 | FAT 32 - card not supported
CE_READONLY | The file is read-only
CE_WRITEONLY | The file is write-only
CE_INVALID_ARGUMENT | Invalid argument
CE_TOO_MANY_FILES_OPEN | Too many files are already open
CE_UNSUPPORTED_SECTOR_SIZE | Unsupported sector size
APIs > File Manipulation Layer (FSIO) > Library Members > CETYPE Enumeration


FILEFLAGS Structure

Contents | Index | Home
Previous | Up | Next
FILEFLAGS Structure
C
typedef struct {
  unsigned write : 1;
  unsigned read : 1;
  unsigned FileWriteEOF : 1;
} FILEFLAGS;
Description

This is type FILEFLAGS.

Members
Members | Description
unsigned write : 1; | Indicates a file was opened in a mode that allows writes
unsigned read : 1; | Indicates a file was opened in a mode that allows reads
unsigned FileWriteEOF : 1; | Indicates the current position in a file is at the end of the file
APIs > File Manipulation Layer (FSIO) > Library Members > FILEFLAGS Structure


MEDIA_ERRORS Enumeration

Contents | Index | Home
Previous | Up | Next
MEDIA_ERRORS Enumeration
C
typedef enum {
  MEDIA_NO_ERROR,
  MEDIA_DEVICE_NOT_PRESENT,
  MEDIA_CANNOT_INITIALIZE
} MEDIA_ERRORS;
Description

This is type MEDIA_ERRORS.

Members
Members | Description
MEDIA_NO_ERROR | No errors
MEDIA_DEVICE_NOT_PRESENT | The requested device is not present
MEDIA_CANNOT_INITIALIZE | Cannot initialize media
APIs > File Manipulation Layer (FSIO) > Library Members > MEDIA_ERRORS Enumeration


MEDIA_INFORMATION Structure

Contents | Index | Home
Previous | Up | Next
MEDIA_INFORMATION Structure
C
typedef struct {
  BYTE errorCode;
  union {
    BYTE value;
    struct {
      BYTE sectorSize : 1;
      BYTE maxLUN : 1;
    } bits;
  } validityFlags;
  WORD sectorSize;
  BYTE maxLUN;
} MEDIA_INFORMATION;
Description

This is type MEDIA_INFORMATION.

APIs > File Manipulation Layer (FSIO) > Library Members > MEDIA_INFORMATION Structure


PT_MBR Type

Contents | Index | Home
Previous | Up | Next
PT_MBR Type
C
typedef _PT_MBR * PT_MBR;
Description

The PT_MBR pointer points to a _PT_MBR structure.

APIs > File Manipulation Layer (FSIO) > Library Members > PT_MBR Type


SALLOC Type

Contents | Index | Home
Previous | Up | Next
SALLOC Type
C
typedef union _SALLOC SALLOC;
Description

The SALLOC union allows the PIC18 dynamic memory allocation algorithm to perform bitwise accesses on segment headers.

APIs > File Manipulation Layer (FSIO) > Library Members > SALLOC Type


SEARCH_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
SEARCH_TYPE Enumeration
C
typedef enum {
  LOOK_FOR_EMPTY_ENTRY = 0,
  LOOK_FOR_MATCHING_ENTRY
} SEARCH_TYPE;
Description

The values in the SEARCH_TYPE enumeration are used internally by the library to indicate how the FILEfind function how to perform a search. The 'LOOK_FOR_EMPTY_ENTRY' value indicates that FILEfind should search for an empty file entry. The 'LOOK_FOR_MATCHING_ENTRY' value indicates that FILEfind should search for an entry that matches the FSFILE object that was passed into the FILEfind function.

APIs > File Manipulation Layer (FSIO) > Library Members > SEARCH_TYPE Enumeration


Internal Members

Contents | Index | Home
Previous | Up | Next
Internal Members

The following functions, variables, structures, and macros are designated as internal to the library.

Functions
Name | Description
_SRAMmerge | This function tries to merge adjacent segments that have not been allocated. The largest possible segment is merged if possible.
Cache_File_Entry | Load a file entry
CacheTime | Automatically store timestamp information from the RTCC
chdirhelper | Helper function for FSchdir
Cluster2Sector | Convert a cluster number to the corresponding sector
CreateDIR | FSmkdir helper function to create a directory
CreateFirstCluster | Create the first cluster for a file
DISKmount | Initialies the device and loads MBR and boot sector information
EraseCluster | Erase a cluster
FAT_erase_cluster_chain | Erase a chain of clusters
FATfindEmptyCluster | Find the next available cluster on the device
FILEallocate_new_cluster | This function will find an empty cluster on the device using the FATfindEmptyCluster function. It will then mark it as the last cluster in the file in the FAT chain, and link the current last cluster of the passed file to the new cluster. If the new cluster is a directory cluster, it will be erased (so there are no extraneous directory entries). If it's allocated to a non-directory file, it doesn't need to be erased; extraneous data in the cluster will be unviewable because of the file size parameter.
FILECreateHeadCluster | Create the first cluster of a file
FILEerase | Erase a file
FILEfind | Finds a file on the device
FILEget_next_cluster | Step through a chain of clusters
FileObjectCopy | Copy a file object
FILEopen | Loads file information from the device
eraseDir | FSrmdir helper function to erase dirs
Fill_File_Object | Fill a file object with specified dir entry data
FindEmptyEntries | Find an empty dir entry
flushData | Flush unwritten data to a file
FSputc | FSfprintf helper function to write a char
FSvfprintf | Helper function for FSfprintf
GetFullClusterNumber | Gets the cluster number from a directory entry
GetPreviousEntry | Get the file entry info for the parent dir of the specified dir
IncrementTimeStamp | Automatically set the timestamp to "don't care" data
LoadBootSector | Load the boot sector and extract the necessary information
LoadDirAttrib | Load file information from a directory entry and cache the entry
LoadMBR | Loads the MBR and extracts necessary information
mkdirhelper | Helper function for FSmkdir
ReadFAT | Read the next entry from the FAT
rmdirhelper | Helper function for FSrmdir
SRAMInitHeap | This function initializes the dynamic heap. It inserts segment headers to maximize segment space.
str_put_n_chars | FSfprintf helper function to write a char multiple times
Write_File_Entry | Write dir entry info into a specified entry
writeDotEntries | Create dot and dotdot entries in a non-root directory
Macros
Name | Description
_FLAG_MINUS | FSfprintf minus flag indicator
_FLAG_OCTO | FSfprintf octothorpe (hash mark) flag indicator
_FLAG_PLUS | FSfprintf plus flag indicator
_FLAG_SIGNED | FSfprintf signed flag indicator
_FLAG_SPACE | FSfprintf space flag indicator
_FLAG_ZERO | FSfprintf zero flag indicator
_FMT_BYTE | FSfprintf 8-bit argument size flag
_FMT_LONG | FSfprintf 32-bit argument size flag
_FMT_LONGLONG | FSfprintf 64-bit argument size flag
_FMT_SHRTLONG | FSfprintf 24-bit argument size flag
_FMT_UNSPECIFIED | FSfprintf unspecified argument size flag
_MAX_HEAP_SIZE | A macro used to determine the heap initialization size.
_MAX_SEGMENT_SIZE | A macro used to determine the maximum size of a dynamic memory segment.
DIRECTORY | Value indicating that the CreateFileEntry function will be creating a directory
DIRENTRIES_PER_SECTOR | The number of directory entries in a sector
NEAR | A macro used to specify the near-model action
Structures
Name | Description
_DIRENTRY | Directory entry structure
Types
Name | Description
DIRENTRY | A pointer to a directory entry structure
FILEOBJ | Pointer to an FSFILE object
Variables
Name | Description
_uDynamicHeap | The PIC18 dynamic memory heap
cwd | Global current working directory
cwdptr | Pointer to the current working directory
defaultArray | This string is used by FSgetcwd to return the cwd name if the path passed into the function is NULL
dirCleared | Global variable used by the "recursive" FSrmdir function to indicate that all subdirectories and files have been deleted from the target directory.
FatRootDirClusterValue | Global variable containing the cluster number of the root dir (0 for FAT12/16)
FSerrno | Global error variable. Set to one of many error codes after each function call.
gBufferOwner | Global variable indicating which file is using the data buffer
gBufferZeroed | Global variable indicating that the data buffer contains all zeros
gDataBuffer | The global data sector buffer
gDiskData | Global structure containing device information.
gFATBuffer | The global FAT sector buffer
gFileArray | Array that contains file information (static allocation)
gFileSlotOpen | Array that indicates which elements of gFileArray are available for use
gFileTemp | Global variable used for file operations.
gLastDataSectorRead | Global variable indicating which data sector was read last
gLastFATSectorRead | Global variable indicating which FAT sector was read last
gNeedDataWrite | Global variable indicating that there is information that needs to be written to the data section
gNeedFATWrite | Global variable indicating that there is information that needs to be written to the FAT
gTimeAccDate | Global time variable (for timestamps) used to indicate last access date
gTimeCrtDate | Global time variable (for timestamps) used to indicate create date
gTimeCrtMS | Global time variable (for timestamps) used to indicate create time (milliseconds)
gTimeCrtTime | Global time variable (for timestamps) used to indicate create time
gTimeWrtDate | Global time variable (for timestamps) used to indicate last update date
gTimeWrtTime | Global time variable (for timestamps) used to indicate last update time
nextClusterIsLast | Global variable indicating that the entries in a directory align with a cluster boundary
recache | Global variable used by the "recursive" FSrmdir function to indicate that additional cache reads are needed.
s_digits | FSfprintf table of conversion digits
tempArray | This array is used to prevent a stack frame error
TempClusterCalc | Global variable used to store the calculated value of the cluster of a specified sector.
tempCWDobj | Global variable used to preserve the current working directory information.
APIs > File Manipulation Layer (FSIO) > Internal Members


_SRAMmerge Function

Contents | Index | Home
Previous | Up | Next
_SRAMmerge Function
C
NEAR unsigned char _SRAMmerge(
    SALLOC * NEAR pSegA
);
Description

This function tries to merge adjacent segments that have not been allocated. The largest possible segment is merged if possible.

Parameters
Parameters | Description
SALLOC * NEAR pSegA | pointer to the first segment.
Returns

usnigned char - returns the length of the merged segment or zero if failed to merge.

APIs > File Manipulation Layer (FSIO) > Internal Members > _SRAMmerge Function


Cache_File_Entry Function

Contents | Index | Home
Previous | Up | Next
Cache_File_Entry Function
C
DIRENTRY Cache_File_Entry(
    FILEOBJ fo,
    WORD * curEntry,
    BYTE ForceRead
);
Description

Load the sector containing the file entry pointed to by 'curEntry' from the directory pointed to by the variables in 'fo.'

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | File information
curEntry | Offset of the directory entry to load.
ForceRead | Forces loading of a new sector of the directory.
Returns

DIRENTRY - Pointer to the directory entry that was loaded.

Side Effects

Any unwritten data in the data buffer will be written to the device.

Remarks

Any modification of this function is extremely likely to break something.

APIs > File Manipulation Layer (FSIO) > Internal Members > Cache_File_Entry Function


CacheTime Function

Contents | Index | Home
Previous | Up | Next
CacheTime Function
C
void CacheTime();
Description

This function will automatically load information from an RTCC module and use it to update the global timing variables. These can then be used to update file timestamps.

Preconditions

RTCC module enabled. Should not be called by the user.

Side Effects

Modifies global timing variables

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > CacheTime Function


chdirhelper Function

Contents | Index | Home
Previous | Up | Next
chdirhelper Function
C
int chdirhelper(
    BYTE mode,
    char * ramptr,
    const rom char * romptr
);
Description

This helper function is used by the FSchdir function. If the path argument is specified in ROM for PIC18 this function will be able to parse it correctly. The function will loop through a switch statement to process the tokens in the path string. Dot or dotdot entries are handled in the first case statement. A backslash character is handled in the second case statement (note that this case statement will only be used if backslash is the first character in the path; backslash token delimiters will automatically be skipped after each token in the path is processed). The third case statement will handle actual directory name strings.

Preconditions

None

Parameters
Parameters | Description
mode | Indicates which path pointer to use
ramptr | Pointer to the path specified in RAM
romptr | Pointer to the path specified in ROM
Return Values
Return Values | Description
0 | Directory was changed successfully.
EOF | Directory could not be changed.
Side Effects

The current working directory will be changed. The FSerrno variable will be changed. Any unwritten data in the data buffer will be written to the device.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > chdirhelper Function


Cluster2Sector Function

Contents | Index | Home
Previous | Up | Next
Cluster2Sector Function
C
DWORD Cluster2Sector(
    DISK * disk,
    DWORD cluster
);
Description

The Cluster2Sector function will calculate the sector number that corresponds to the first sector of the cluster whose value was passed into the function.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
disk | Disk structure
cluster | Cluster to be converted
Returns

sector - Sector that corresponds to given cluster

Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > Cluster2Sector Function


CreateDIR Function

Contents | Index | Home
Previous | Up | Next
CreateDIR Function
C
int CreateDIR(
    char * path
);
Description

The CreateDIR function is a helper function for the mkdirhelper function. The CreateDIR function will create a new file entry for a directory and assign a cluster to it. It will erase the cluster and write a dot and dotdot entry to it.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
path | The name of the dir to create
Return Values
Return Values | Description
TRUE | Directory was created successfully
FALSE | Directory could not be created.
Side Effects

Any unwritten data in the data buffer or the FAT buffer will be written to the device.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > CreateDIR Function


CreateFirstCluster Function

Contents | Index | Home
Previous | Up | Next
CreateFirstCluster Function
C
CETYPE CreateFirstCluster(
    FILEOBJ fo
);
Description

This function will find an unused cluster, link it to a file's directory entry, and write the entry back to the device.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | The file that contains the first cluster
Return Values
Return Values | Description
CE_GOOD | First cluster created successfully
CE_WRITE_ERROR | Cluster creation failed
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > CreateFirstCluster Function


DISKmount Function

Contents | Index | Home
Previous | Up | Next
DISKmount Function
C
BYTE DISKmount(
    DISK * dsk
);
Description

This function will use the function pointed to by the MDD_MediaInitialize function pointer to initialize the device (if any initialization is required). It then attempts to load the master boot record with the LoadMBR function and the boot sector with the LoadBootSector function. These two functions will be used to initialize a global DISK structure that will be used when accessing file information in the future.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
dsk | The disk structure to be initialized.
Return Values
Return Values | Description
CE_GOOD | Disk mounted
CE_INIT_ERROR | Initialization error has occured
CE_UNSUPPORTED_SECTOR_SIZE | Media sector size bigger than MEDIA_SECTOR_SIZE as defined in FSconfig.h.
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > DISKmount Function


EraseCluster Function

Contents | Index | Home
Previous | Up | Next
EraseCluster Function
C
BYTE EraseCluster(
    DISK * disk,
    DWORD cluster
);
Description

The EraseCluster function will write a 0 value into every byte of the specified cluster.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
dsk | Disk structure
cluster | Cluster to be erased
Return Values
Return Values | Description
CE_GOOD | File closed successfully
CE_WRITE_ERROR | Could not write to the sector
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > EraseCluster Function


FAT_erase_cluster_chain Function

Contents | Index | Home
Previous | Up | Next
FAT_erase_cluster_chain Function
C
BYTE FAT_erase_cluster_chain(
    DWORD cluster,
    DISK * dsk
);
Description

This function will parse through a cluster chain starting with the cluster pointed to by 'cluster' and mark all of the FAT entries as empty until the end of the chain has been reached or an error occurs.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
cluster | The cluster number
dsk | The disk structure
Return Values
Return Values | Description
TRUE | Operation successful
FALSE | Operation failed
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > FAT_erase_cluster_chain Function


FATfindEmptyCluster Function

Contents | Index | Home
Previous | Up | Next
FATfindEmptyCluster Function
C
DWORD FATfindEmptyCluster(
    FILEOBJ fo
);
Description

This function will search through the FAT to find the next available cluster on the device.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
Return Values
Return Values | Description
DWORD | Address of empty cluster
0 | Could not find empty cluster
Side Effects

None

Remarks

Should not be called by user

APIs > File Manipulation Layer (FSIO) > Internal Members > FATfindEmptyCluster Function


FILEallocate_new_cluster Function

Contents | Index | Home
Previous | Up | Next
FILEallocate_new_cluster Function
C
BYTE FILEallocate_new_cluster(
    FILEOBJ fo,
    BYTE mode
);
Description

This function will find an empty cluster on the device using the FATfindEmptyCluster function. It will then mark it as the last cluster in the file in the FAT chain, and link the current last cluster of the passed file to the new cluster. If the new cluster is a directory cluster, it will be erased (so there are no extraneous directory entries). If it's allocated to a non-directory file, it doesn't need to be erased; extraneous data in the cluster will be unviewable because of the file size parameter.

Preconditions

Should not be called by the user.

Parameters
Parameters
Description
fo
Pointer to file structure
mode

  • 0 - Allocate a cluster to a file
  • 1 - Allocate a cluster to a directory

Return Values
Return Values | Description
CE_GOOD | Cluster allocated
CE_DISK_FULL | No clusters available
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEallocate_new_cluster Function


FILECreateHeadCluster Function

Contents | Index | Home
Previous | Up | Next
FILECreateHeadCluster Function
C
CETYPE FILECreateHeadCluster(
    FILEOBJ fo,
    DWORD * cluster
);
Description

The FILECreateHeadCluster function will create the first cluster of a file. First, it will find an empty cluster with the FATfindEmptyCluster function and mark it as the last cluster in the file. It will then erase the cluster using the EraseCluster function.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
cluster | Cluster location
Return Values
Return Values | Description
CE_GOOD | File closed successfully
CE_WRITE_ERROR | Could not write to the sector
CE_DISK_FULL | All clusters in partition are taken
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > FILECreateHeadCluster Function


FILEerase Function

Contents | Index | Home
Previous | Up | Next
FILEerase Function
C
CETYPE FILEerase(
    FILEOBJ fo,
    WORD * fHandle,
    BYTE EraseClusters
);
Description

This function will cache the sector of directory entries in the directory pointed to by the dirclus value in the FSFILE object 'fo' that contains the entry that corresponds to the fHandle offset. It will then mark that entry as deleted. If the EraseClusters argument is TRUE, the chain of clusters for that file will be marked as unused in the FAT by the FAT_erase_cluster_chain function.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
fHandle | Location of file information
EraseClusters | If set to TRUE, delete the corresponding cluster of file
Return Values
Return Values | Description
CE_GOOD | File erased successfully
CE_FILE_NOT_FOUND | Could not find the file on the card
CE_ERASE_FAIL | Internal Card erase failed
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEerase Function


FILEfind Function

Contents | Index | Home
Previous | Up | Next
FILEfind Function
C
CETYPE FILEfind(
    FILEOBJ foDest,
    FILEOBJ foCompareTo,
    BYTE cmd,
    BYTE mode
);
Description

The FILEfind function will sequentially cache directory entries within the current working directory into the foDest FSFILE object. If the cmd parameter is specified as LOOK_FOR_EMPTY_ENTRY the search will continue until an empty directory entry is found. If the cmd parameter is specified as LOOK_FOR_MATCHING_ENTRY these entries will be compared to the foCompareTo object until a match is found or there are no more entries in the current working directory. If the mode is specified a '0' the attributes of the FSFILE entries are irrelevant. If the mode is specified as '1' the attributes of the foDest entry must match the attributes specified in the foCompareTo file and partial string search characters may bypass portions of the comparison.

Preconditions

This function should not be called by the user.

Parameters
Parameters
Description
foDest
FSFILE object containing information of the file found
foCompareTo
FSFILE object containing the name/attr of the file to be found
cmd

  • LOOK_FOR_EMPTY_ENTRY: Search for empty entry.
  • LOOK_FOR_MATCHING_ENTRY: Search for matching entry.

mode

  • 0: Match file exactly with default attributes.
  • 1: Match file to user-specified attributes.

Return Values
Return Values | Description
CE_GOOD | File found.
CE_FILE_NOT_FOUND | File not found.
Side Effects

None.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEfind Function


FILEget_next_cluster Function

Contents | Index | Home
Previous | Up | Next
FILEget_next_cluster Function
C
BYTE FILEget_next_cluster(
    FILEOBJ fo,
    DWORD n
);
Description

This function will load 'n' proximate clusters for a file from the FAT on the device. It will stop checking for clusters if the ReadFAT function returns an error, if it reaches the last cluster in a file, or if the device tries to read beyond the last cluster used by the device.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | The file to get the next cluster of
n | Number of links in the FAT cluster chain to jump through
Return Values
Return Values | Description
CE_GOOD | Operation successful
CE_BAD_SECTOR_READ | A bad read occured of a sector
CE_INVALID_CLUSTER | Invalid cluster value > maxcls
CE_FAT_EOF | Fat attempt to read beyond EOF
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEget_next_cluster Function


FileObjectCopy Function

Contents | Index | Home
Previous | Up | Next
FileObjectCopy Function
C
void FileObjectCopy(
    FILEOBJ foDest,
    FILEOBJ foSource
);
Description

The FileObjectCopy function will make an exacy copy of a specified FSFILE object.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
foDest | The destination
foSource | the source
Returns

None

Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > FileObjectCopy Function


FILEopen Function

Contents | Index | Home
Previous | Up | Next
FILEopen Function
C
CETYPE FILEopen(
    FILEOBJ fo,
    WORD * fHandle,
    char type
);
Description

This function will cache a directory entry in the directory specified by the dirclus parameter of hte FSFILE object 'fo.' The offset of the entry in the directory is specified by fHandle. Once the directory entry has been loaded, the first sector of the file can be loaded using the cluster value specified in the directory entry. The type argument will specify the mode the files will be opened in. This will allow this function to set the correct read/write flags for the file.

Preconditions

This function should not be called by the user.

Parameters
Parameters
Description
fo
File to be opened
fHandle
Location of file
type

  • WRITE - Create a new file or replace an existing file
  • READ - Read data from an existing file
  • APPEND - Append data to an existing file

Return Values
Return Values | Description
CE_GOOD | FILEopen successful
CE_NOT_INIT | Device is not yet initialized
CE_FILE_NOT_FOUND | Could not find the file on the device
CE_BAD_SECTOR_READ | A bad read of a sector occured
Side Effects

None

Remarks

If the mode the file is being opened in is a plus mode (e.g. READ+) the flags will be modified further in the FSfopen function.

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEopen Function


Fill_File_Object Function

Contents | Index | Home
Previous | Up | Next
Fill_File_Object Function
C
BYTE Fill_File_Object(
    FILEOBJ fo,
    WORD * fHandle
);
Description

This function will cache the sector of directory entries in the directory pointed to by the dirclus value in the FSFILE object 'fo' that contains the entry that corresponds to the fHandle offset. It will then copy the file information for that entry into the 'fo' FSFILE object.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
fHandle | Passed member's location
Return Values
Return Values | Description
FOUND | Operation successful
NOT_FOUND | Operation failed
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > Fill_File_Object Function


FindEmptyEntries Function

Contents | Index | Home
Previous | Up | Next
FindEmptyEntries Function
C
BYTE FindEmptyEntries(
    FILEOBJ fo,
    WORD * fHandle
);
Description

This function will cache directory entries, starting with the one pointed to by the fHandle argument. It will then search through the entries until an unused one is found. If the end of the cluster chain for the directory is reached, a new cluster will be allocated to the directory (unless it's a FAT12 or FAT16 root) and the first entry of the new cluster will be used.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
fHandle | Start of entries
Return Values
Return Values | Description
TRUE | One found
FALSE | None found
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > FindEmptyEntries Function


flushData Function

Contents | Index | Home
Previous | Up | Next
flushData Function
C
BYTE flushData();
Description

The flushData function is called when it is necessary to read new data into the global data buffer and the gNeedDataWrite variable indicates that there is data in the buffer that hasn't been written to the device. The flushData function will write the data from the buffer into the current cluster of the FSFILE object that is stored in the gBufferOwner global variable.

Preconditions

File opened in a write mode, data needs to be written

Return Values
Return Values | Description
CE_GOOD | Data was updated successfully
CE_WRITE_ERROR | Data could not be updated
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > flushData Function


FSputc Function

Contents | Index | Home
Previous | Up | Next
FSputc Function
C
int FSputc(
    char c,
    FSFILE * file
);
Description

This is a helper function for FSfprintf. It will write one character to a file.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
c | The character to write to the file.
file | The file to write to.
Return Values
Return Values | Description
0 | The character was written successfully
EOF | The character was not written to the file.
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > FSputc Function


FSvfprintf Function

Contents | Index | Home
Previous | Up | Next
FSvfprintf Function
C
int FSvfprintf(
    auto FSFILE * handle,
    auto const rom char * formatString,
    auto va_list ap
);
Description

This helper function will access the elements passed to FSfprintf

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
handle | A pointer to the file to write to.
formatString | A string of characters and format specifiers to write to the file
ap | A structure pointing to the arguments on the stack
Returns

The number of characters written to the file

Side Effects

The FSerrno variable will be changed.

Remarks

Consult AN1045 for a full description of how to use format specifiers.

APIs > File Manipulation Layer (FSIO) > Internal Members > FSvfprintf Function


GetFullClusterNumber Function

Contents | Index | Home
Previous | Up | Next
GetFullClusterNumber Function
C
DWORD GetFullClusterNumber(
    DIRENTRY entry
);
Description

This function will load both the high and low 16-bit first cluster values of a file from a directory entry and copy them into a 32-bit cluster number variable, which will be returned.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
entry | The cached directory entry to get the cluster number from
Returns

The cluster value from the passed directory entry

Side Effects

None.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > GetFullClusterNumber Function


GetPreviousEntry Function

Contents | Index | Home
Previous | Up | Next
GetPreviousEntry Function
C
BYTE GetPreviousEntry(
    FSFILE * fo
);
Description

The GetPreviousEntry function is used by the FSgetcwd function to load the previous (parent) directory. This function will load the parent directory and then search through the file entries in that directory for one that matches the cluster number of the original directory. When the matching entry is found, the name of the original directory is copied into the 'fo' FSFILE object.

Preconditions

Should not be called by the user.

Parameters
Parameters | Description
fo | The file to get the previous entry of
Return Values
Return Values | Description
0 | The previous entry was successfully retrieved
-1 | The previous entry could not be retrieved
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > GetPreviousEntry Function


IncrementTimeStamp Function

Contents | Index | Home
Previous | Up | Next
IncrementTimeStamp Function
C
void IncrementTimeStamp(
    DIRENTRY dir
);
Description

This function will increment the timestamp variable in the 'dir' directory entry. This is used for the don't-care timing method.

Preconditions

Should not be called by the user.

Parameters
Parameters | Description
dir | Pointer to directory structure
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > IncrementTimeStamp Function


LoadBootSector Function

Contents | Index | Home
Previous | Up | Next
LoadBootSector Function
C
BYTE LoadBootSector(
    DISK * dsk
);
Description

LoadBootSector will use the function pointed to by the MDD_SectorWrite function pointer to load the boot sector, whose location was obtained by a previous call of LoadMBR. If the boot sector is loaded successfully, partition information will be calcualted from it and copied into the DISK structure pointed to by 'dsk.'

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
dsk | The disk containing the boot sector
Return Values
Return Values | Description
CE_GOOD | Boot sector loaded
CE_BAD_SECTOR_READ | A bad read occured of a sector
CE_NOT_FORMATTED | The disk is of an unsupported format
CE_CARDFAT32 | FAT 32 device not supported
CE_UNSUPPORTED_SECTOR_SIZE | The sector size is not supported
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > LoadBootSector Function


LoadDirAttrib Function

Contents | Index | Home
Previous | Up | Next
LoadDirAttrib Function
C
DIRENTRY LoadDirAttrib(
    FILEOBJ fo,
    WORD * fHandle
);
Description

This function will cache the sector of directory entries in the directory pointed to by the dirclus value in the FSFILE object 'fo' that contains the entry that corresponds to the fHandle offset. It will then return a pointer to the directory entry in the global data buffer.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | Pointer to file structure
fHandle | Information location
Return Values
Return Values | Description
DIRENTRY | Pointer to the directory entry
NULL | Directory entry could not be loaded
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > LoadDirAttrib Function


LoadMBR Function

Contents | Index | Home
Previous | Up | Next
LoadMBR Function
C
BYTE LoadMBR(
    DISK * dsk
);
Description

The LoadMBR function will use the function pointed to by the MDD_SectorRead function pointer to read the 0 sector from the device. If a valid boot signature is obtained, this function will compare fields in that cached sector to the values that would be present if that sector was a boot sector. If all of those values match, it will be assumed that the device does not have a master boot record and the 0 sector is actually the boot sector. Otherwise, data about the partition and the actual location of the boot sector will be loaded from the MBR into the DISK structure pointed to by 'dsk.'

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
dsk | The disk containing the master boot record to be loaded
Return Values
Return Values | Description
CE_GOOD | MBR loaded successfully
CE_BAD_SECTOR_READ | A bad read occured of a sector
CE_BAD_PARTITION | The boot record is bad
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > LoadMBR Function


mkdirhelper Function

Contents | Index | Home
Previous | Up | Next
mkdirhelper Function
C
int mkdirhelper(
    BYTE mode,
    char * ramptr,
    const rom char * romptr
);
Description

This helper function is used by the FSchdir function. If the path argument is specified in ROM for PIC18 this function will be able to parse it correctly. This function will first scan through the path to ensure that any DIR names don't exceed 11 characters. It will then backup the current working directory and begin changing directories through the path until it reaches a directory than can't be changed to. It will then create the specified directory and change directories to the new directory. The function will continue creating and changing to directories until the end of the path is reached. The function will then restore the original current working directory.

Preconditions

None

Parameters
Parameters | Description
mode | Indicates which path pointer to use
ramptr | Pointer to the path specified in RAM
romptr | Pointer to the path specified in ROM
Return Values
Return Values | Description
0 | Directory was created
-1 | Directory could not be created
Side Effects

Will create all non-existant directories in the path. The FSerrno variable will be changed.

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > mkdirhelper Function


ReadFAT Function

Contents | Index | Home
Previous | Up | Next
ReadFAT Function
C
DWORD ReadFAT(
    DISK * dsk,
    DWORD ccls
);
Description

The ReadFAT function will read the FAT and determine the next cluster value after the cluster specified by 'ccls.' Note that the FAT sector that is read is stored in the global FAT cache buffer.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
dsk | The disk structure
ccls | The current cluster
Returns

DWORD - The next cluster in a file chain

Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > ReadFAT Function


rmdirhelper Function

Contents | Index | Home
Previous | Up | Next
rmdirhelper Function
C
int rmdirhelper(
    BYTE mode,
    char * ramptr,
    const rom char * romptr,
    unsigned char rmsubdirs
);
Description

This helper function is used by the FSmkdir function. If the path argument is specified in ROM for PIC18 this function will be able to parse it correctly. This function will first change to the specified directory. If the rmsubdirs argument is FALSE the function will search through the directory to ensure that it is empty and then remove it. If the rmsubdirs argument is TRUE the function will also search through the directory for subdirectories or files. When the function finds a file, the file will be erased. When the function finds a subdirectory, it will switch to the subdirectory and begin removing all of the files in that subdirectory. Once the subdirectory is empty, the function will switch back to the original directory. return to the original position in that directory, and continue removing files. Once the specified directory is empty, the function will change to the parent directory, search through it for the directory to remove, and then erase that directory.

Preconditions

This function should not be called by the user.

Parameters
Parameters
Description
path
The path of the dir to delete
rmsubdirs

  • TRUE - Remove all sub-directories and files in the directory
  • FALSE - Non-empty directories can not be removed

Return Values
Return Values | Description
0 | The specified directory was successfully removed.
EOF | The specified directory could not be removed.
Side Effects

The FSerrno variable will be changed.

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > rmdirhelper Function


SRAMInitHeap Function

Contents | Index | Home
Previous | Up | Next
SRAMInitHeap Function
C
void SRAMInitHeap();
Description

This function initializes the dynamic heap. It inserts segment headers to maximize segment space.

Returns

void

Remarks

This function must be called at least one time. And it could be called more times to reset the heap.

APIs > File Manipulation Layer (FSIO) > Internal Members > SRAMInitHeap Function


str_put_n_chars Function

Contents | Index | Home
Previous | Up | Next
str_put_n_chars Function
C
unsigned char str_put_n_chars(
    FSFILE * handle,
    unsigned char n,
    char c
);
Description

This funciton is used by the FSfprintf function to write multiple instances of a single character to a file (for example, when padding a format specifier with leading spacez or zeros).

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
handle | The file to write to.
n | The number of times to write that character to a file.
c | The character to write to the file.
Return Values
Return Values | Description
0 | The characters were written successfully
EOF | The characters were not written to the file.
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > str_put_n_chars Function


Write_File_Entry Function

Contents | Index | Home
Previous | Up | Next
Write_File_Entry Function
C
BYTE Write_File_Entry(
    FILEOBJ fo,
    WORD * curEntry
);
Description

This function will calculate the sector of the directory (whose base sector is pointed to by the dirccls value in the FSFILE object 'fo') that contains a directory entry whose offset is indicated by the curEntry parameter. It will then write the data in the global data buffer (which should already contain the entries for that sector) to the device.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
fo | File structure
curEntry | Write destination
Return Values
Return Values | Description
TRUE | Operation successful
FALSE | Operation failed
Side Effects

None

Remarks

None

APIs > File Manipulation Layer (FSIO) > Internal Members > Write_File_Entry Function


writeDotEntries Function

Contents | Index | Home
Previous | Up | Next
writeDotEntries Function
C
BYTE writeDotEntries(
    DISK * dsk,
    DWORD dotAddress,
    DWORD dotdotAddress
);
Description

The writeDotEntries function will create and write dot and dotdot entries to a newly created directory.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
disk | The global disk structure
dotAddress | The cluster the current dir is in
dotdotAddress | The cluster the previous directory was in
Return Values
Return Values | Description
TRUE | The dot and dotdot entries were created
FALSE | The dot and dotdot entries could not be created in the new directory
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > writeDotEntries Function


_FLAG_MINUS Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_MINUS Macro
C
#define _FLAG_MINUS 0x1             // FSfprintf minus flag indicator
Description

FSfprintf minus flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_MINUS Macro


_FLAG_OCTO Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_OCTO Macro
C
#define _FLAG_OCTO 0x8             // FSfprintf octothorpe (hash mark) flag indicator
Description

FSfprintf octothorpe (hash mark) flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_OCTO Macro


_FLAG_PLUS Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_PLUS Macro
C
#define _FLAG_PLUS 0x2             // FSfprintf plus flag indicator
Description

FSfprintf plus flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_PLUS Macro


_FLAG_SIGNED Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_SIGNED Macro
C
#define _FLAG_SIGNED 0x80           // FSfprintf signed flag indicator
Description

FSfprintf signed flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_SIGNED Macro


_FLAG_SPACE Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_SPACE Macro
C
#define _FLAG_SPACE 0x4             // FSfprintf space flag indicator
Description

FSfprintf space flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_SPACE Macro


_FLAG_ZERO Macro

Contents | Index | Home
Previous | Up | Next
_FLAG_ZERO Macro
C
#define _FLAG_ZERO 0x10            // FSfprintf zero flag indicator
Description

FSfprintf zero flag indicator

APIs > File Manipulation Layer (FSIO) > Internal Members > _FLAG_ZERO Macro


_FMT_BYTE Macro

Contents | Index | Home
Previous | Up | Next
_FMT_BYTE Macro
C
#define _FMT_BYTE 3             // FSfprintf 8-bit argument size flag
Description

FSfprintf 8-bit argument size flag

APIs > File Manipulation Layer (FSIO) > Internal Members > _FMT_BYTE Macro


_FMT_LONG Macro

Contents | Index | Home
Previous | Up | Next
_FMT_LONG Macro
C
#define _FMT_LONG 2             // FSfprintf 32-bit argument size flag
Description

FSfprintf 32-bit argument size flag

APIs > File Manipulation Layer (FSIO) > Internal Members > _FMT_LONG Macro


_FMT_LONGLONG Macro

Contents | Index | Home
Previous | Up | Next
_FMT_LONGLONG Macro
C
#define _FMT_LONGLONG 1         // FSfprintf 64-bit argument size flag
Description

FSfprintf 64-bit argument size flag

APIs > File Manipulation Layer (FSIO) > Internal Members > _FMT_LONGLONG Macro


_FMT_SHRTLONG Macro

Contents | Index | Home
Previous | Up | Next
_FMT_SHRTLONG Macro
C
#define _FMT_SHRTLONG 2         // FSfprintf 24-bit argument size flag
Description

FSfprintf 24-bit argument size flag

APIs > File Manipulation Layer (FSIO) > Internal Members > _FMT_SHRTLONG Macro


_FMT_UNSPECIFIED Macro

Contents | Index | Home
Previous | Up | Next
_FMT_UNSPECIFIED Macro
C
#define _FMT_UNSPECIFIED 0      // FSfprintf unspecified argument size flag
Description

FSfprintf unspecified argument size flag

APIs > File Manipulation Layer (FSIO) > Internal Members > _FMT_UNSPECIFIED Macro


_MAX_HEAP_SIZE Macro

Contents | Index | Home
Previous | Up | Next
_MAX_HEAP_SIZE Macro
C
#define _MAX_HEAP_SIZE MAX_HEAP_SIZE-1
Description

A macro used to determine the heap initialization size.

APIs > File Manipulation Layer (FSIO) > Internal Members > _MAX_HEAP_SIZE Macro


_MAX_SEGMENT_SIZE Macro

Contents | Index | Home
Previous | Up | Next
_MAX_SEGMENT_SIZE Macro
C
#define _MAX_SEGMENT_SIZE 0x7F
Description

A macro used to determine the maximum size of a dynamic memory segment.

APIs > File Manipulation Layer (FSIO) > Internal Members > _MAX_SEGMENT_SIZE Macro


DIRECTORY Macro

Contents | Index | Home
Previous | Up | Next
DIRECTORY Macro
C
#define DIRECTORY 0x12          // Value indicating that the CreateFileEntry function will be creating a directory
Description

Value indicating that the CreateFileEntry function will be creating a directory

APIs > File Manipulation Layer (FSIO) > Internal Members > DIRECTORY Macro


DIRENTRIES_PER_SECTOR Macro

Contents | Index | Home
Previous | Up | Next
DIRENTRIES_PER_SECTOR Macro
C
#define DIRENTRIES_PER_SECTOR (MEDIA_SECTOR_SIZE / 32)        // The number of directory entries in a sector
Description

The number of directory entries in a sector

APIs > File Manipulation Layer (FSIO) > Internal Members > DIRENTRIES_PER_SECTOR Macro


NEAR Macro

Contents | Index | Home
Previous | Up | Next
NEAR Macro
C
#define NEAR
Description

Functions can be declared using the NEAR macro. If the NEAR_MODEL macro is uncommented, the NEAR macro will be ignored.

APIs > File Manipulation Layer (FSIO) > Internal Members > NEAR Macro


_DIRENTRY Structure

Contents | Index | Home
Previous | Up | Next
_DIRENTRY Structure
C
typedef struct {
  char DIR_Name[DIR_NAMESIZE];
  char DIR_Extension[DIR_EXTENSION];
  BYTE DIR_Attr;
  BYTE DIR_NTRes;
  BYTE DIR_CrtTimeTenth;
  WORD DIR_CrtTime;
  WORD DIR_CrtDate;
  WORD DIR_LstAccDate;
  WORD DIR_FstClusHI;
  WORD DIR_WrtTime;
  WORD DIR_WrtDate;
  WORD DIR_FstClusLO;
  DWORD DIR_FileSize;
} _DIRENTRY;
Description

Directory entry structure

Members
Members | Description
char DIR_Name[DIR_NAMESIZE]; | File name
char DIR_Extension[DIR_EXTENSION]; | File extension
BYTE DIR_Attr; | File attributes
BYTE DIR_NTRes; | Reserved byte
BYTE DIR_CrtTimeTenth; | Create time (millisecond field)
WORD DIR_CrtTime; | Create time (second, minute, hour field)
WORD DIR_CrtDate; | Create date
WORD DIR_LstAccDate; | Last access date
WORD DIR_FstClusHI; | High word of the entry's first cluster number
WORD DIR_WrtTime; | Last update time
WORD DIR_WrtDate; | Last update date
WORD DIR_FstClusLO; | Low word of the entry's first cluster number
DWORD DIR_FileSize; | The 32-bit file size
APIs > File Manipulation Layer (FSIO) > Internal Members > _DIRENTRY Structure


DIRENTRY Type

Contents | Index | Home
Previous | Up | Next
DIRENTRY Type
C
typedef _DIRENTRY * DIRENTRY;
Description

A pointer to a directory entry structure

APIs > File Manipulation Layer (FSIO) > Internal Members > DIRENTRY Type


FILEOBJ Type

Contents | Index | Home
Previous | Up | Next
FILEOBJ Type
C
typedef FSFILE * FILEOBJ;
Description

Pointer to an FSFILE object

APIs > File Manipulation Layer (FSIO) > Internal Members > FILEOBJ Type


_uDynamicHeap Variable

Contents | Index | Home
Previous | Up | Next
_uDynamicHeap Variable
C
unsigned char _uDynamicHeap[MAX_HEAP_SIZE];
Description

The _uDynamicHeap array is used as a heap for PIC18 dynamic memory allocation.

APIs > File Manipulation Layer (FSIO) > Internal Members > _uDynamicHeap Variable


cwd Variable

Contents | Index | Home
Previous | Up | Next
cwd Variable
C
FSFILE cwd;
Description

Global current working directory

APIs > File Manipulation Layer (FSIO) > Internal Members > cwd Variable


cwdptr Variable

Contents | Index | Home
Previous | Up | Next
cwdptr Variable
C
FSFILE * cwdptr = &cwd;
Description

Pointer to the current working directory

APIs > File Manipulation Layer (FSIO) > Internal Members > cwdptr Variable


defaultArray Variable

Contents | Index | Home
Previous | Up | Next
defaultArray Variable
C
char defaultArray[10];
Description

This string is used by FSgetcwd to return the cwd name if the path passed into the function is NULL

APIs > File Manipulation Layer (FSIO) > Internal Members > defaultArray Variable


dirCleared Variable

Contents | Index | Home
Previous | Up | Next
dirCleared Variable
C
BYTE dirCleared;
Description

Global variable used by the "recursive" FSrmdir function to indicate that all subdirectories and files have been deleted from the target directory.

APIs > File Manipulation Layer (FSIO) > Internal Members > dirCleared Variable


FatRootDirClusterValue Variable

Contents | Index | Home
Previous | Up | Next
FatRootDirClusterValue Variable
C
DWORD FatRootDirClusterValue;
Description

Global variable containing the cluster number of the root dir (0 for FAT12/16)

APIs > File Manipulation Layer (FSIO) > Internal Members > FatRootDirClusterValue Variable


FSerrno Variable

Contents | Index | Home
Previous | Up | Next
FSerrno Variable
C
BYTE FSerrno;
Description

Global error variable. Set to one of many error codes after each function call.

APIs > File Manipulation Layer (FSIO) > Internal Members > FSerrno Variable


gBufferOwner Variable

Contents | Index | Home
Previous | Up | Next
gBufferOwner Variable
C
FSFILE * gBufferOwner = NULL;
Description

Global variable indicating which file is using the data buffer

APIs > File Manipulation Layer (FSIO) > Internal Members > gBufferOwner Variable


gBufferZeroed Variable

Contents | Index | Home
Previous | Up | Next
gBufferZeroed Variable
C
BYTE gBufferZeroed = FALSE;
Description

Global variable indicating that the data buffer contains all zeros

APIs > File Manipulation Layer (FSIO) > Internal Members > gBufferZeroed Variable


gDataBuffer Variable

Contents | Index | Home
Previous | Up | Next
gDataBuffer Variable
C
BYTE gDataBuffer[MEDIA_SECTOR_SIZE];
Description

The global data sector buffer

APIs > File Manipulation Layer (FSIO) > Internal Members > gDataBuffer Variable


gDiskData Variable

Contents | Index | Home
Previous | Up | Next
gDiskData Variable
C
DISK gDiskData;
Description

Global structure containing device information.

APIs > File Manipulation Layer (FSIO) > Internal Members > gDiskData Variable


gFATBuffer Variable

Contents | Index | Home
Previous | Up | Next
gFATBuffer Variable
C
BYTE gFATBuffer[MEDIA_SECTOR_SIZE];
Description

The global FAT sector buffer

APIs > File Manipulation Layer (FSIO) > Internal Members > gFATBuffer Variable


gFileArray Variable

Contents | Index | Home
Previous | Up | Next
gFileArray Variable
C
FSFILE gFileArray[FS_MAX_FILES_OPEN];
Description

Array that contains file information (static allocation)

APIs > File Manipulation Layer (FSIO) > Internal Members > gFileArray Variable


gFileSlotOpen Variable

Contents | Index | Home
Previous | Up | Next
gFileSlotOpen Variable
C
BYTE gFileSlotOpen[FS_MAX_FILES_OPEN];
Description

Array that indicates which elements of gFileArray are available for use

APIs > File Manipulation Layer (FSIO) > Internal Members > gFileSlotOpen Variable


gFileTemp Variable

Contents | Index | Home
Previous | Up | Next
gFileTemp Variable
C
FSFILE gFileTemp;
Description

Global variable used for file operations.

APIs > File Manipulation Layer (FSIO) > Internal Members > gFileTemp Variable


gLastDataSectorRead Variable

Contents | Index | Home
Previous | Up | Next
gLastDataSectorRead Variable
C
DWORD gLastDataSectorRead = 0xFFFFFFFF;
Description

Global variable indicating which data sector was read last

APIs > File Manipulation Layer (FSIO) > Internal Members > gLastDataSectorRead Variable


gLastFATSectorRead Variable

Contents | Index | Home
Previous | Up | Next
gLastFATSectorRead Variable
C
DWORD gLastFATSectorRead = 0xFFFFFFFF;
Description

Global variable indicating which FAT sector was read last

APIs > File Manipulation Layer (FSIO) > Internal Members > gLastFATSectorRead Variable


gNeedDataWrite Variable

Contents | Index | Home
Previous | Up | Next
gNeedDataWrite Variable
C
BYTE gNeedDataWrite = FALSE;
Description

Global variable indicating that there is information that needs to be written to the data section

APIs > File Manipulation Layer (FSIO) > Internal Members > gNeedDataWrite Variable


gNeedFATWrite Variable

Contents | Index | Home
Previous | Up | Next
gNeedFATWrite Variable
C
BYTE gNeedFATWrite = FALSE;
Description

Global variable indicating that there is information that needs to be written to the FAT

APIs > File Manipulation Layer (FSIO) > Internal Members > gNeedFATWrite Variable


gTimeAccDate Variable

Contents | Index | Home
Previous | Up | Next
gTimeAccDate Variable
C
WORD gTimeAccDate;
Description

Global time variable (for timestamps) used to indicate last access date

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeAccDate Variable


gTimeCrtDate Variable

Contents | Index | Home
Previous | Up | Next
gTimeCrtDate Variable
C
WORD gTimeCrtDate;
Description

Global time variable (for timestamps) used to indicate create date

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeCrtDate Variable


gTimeCrtMS Variable

Contents | Index | Home
Previous | Up | Next
gTimeCrtMS Variable
C
BYTE gTimeCrtMS;
Description

Global time variable (for timestamps) used to indicate create time (milliseconds)

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeCrtMS Variable


gTimeCrtTime Variable

Contents | Index | Home
Previous | Up | Next
gTimeCrtTime Variable
C
WORD gTimeCrtTime;
Description

Global time variable (for timestamps) used to indicate create time

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeCrtTime Variable


gTimeWrtDate Variable

Contents | Index | Home
Previous | Up | Next
gTimeWrtDate Variable
C
WORD gTimeWrtDate;
Description

Global time variable (for timestamps) used to indicate last update date

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeWrtDate Variable


gTimeWrtTime Variable

Contents | Index | Home
Previous | Up | Next
gTimeWrtTime Variable
C
WORD gTimeWrtTime;
Description

Global time variable (for timestamps) used to indicate last update time

APIs > File Manipulation Layer (FSIO) > Internal Members > gTimeWrtTime Variable


nextClusterIsLast Variable

Contents | Index | Home
Previous | Up | Next
nextClusterIsLast Variable
C
BYTE nextClusterIsLast = FALSE;
Description

Global variable indicating that the entries in a directory align with a cluster boundary

APIs > File Manipulation Layer (FSIO) > Internal Members > nextClusterIsLast Variable


recache Variable

Contents | Index | Home
Previous | Up | Next
recache Variable
C
BYTE recache = FALSE;
Description

Global variable used by the "recursive" FSrmdir function to indicate that additional cache reads are needed.

APIs > File Manipulation Layer (FSIO) > Internal Members > recache Variable


s_digits Variable

Contents | Index | Home
Previous | Up | Next
s_digits Variable
C
const char s_digits[] = "0123456789abcdef";
Description

FSfprintf table of conversion digits

APIs > File Manipulation Layer (FSIO) > Internal Members > s_digits Variable


tempArray Variable

Contents | Index | Home
Previous | Up | Next
tempArray Variable
C
char tempArray[13] = "           ";
Description

This array is used to prevent a stack frame error

APIs > File Manipulation Layer (FSIO) > Internal Members > tempArray Variable


TempClusterCalc Variable

Contents | Index | Home
Previous | Up | Next
TempClusterCalc Variable
C
DWORD TempClusterCalc;
Description

Global variable used to store the calculated value of the cluster of a specified sector.

APIs > File Manipulation Layer (FSIO) > Internal Members > TempClusterCalc Variable


tempCWDobj Variable

Contents | Index | Home
Previous | Up | Next
tempCWDobj Variable
C
FSFILE tempCWDobj;
Description

Global variable used to preserve the current working directory information.

APIs > File Manipulation Layer (FSIO) > Internal Members > tempCWDobj Variable


SD-SPI Physical Layer

Contents | Index | Home
Previous | Up | Next
SD-SPI Physical Layer

The SD-SPI physical layer offers the ability to interface to SD cards using the SPI protocol. SPI modules can be found on many Microchip microcontrollers.

Topics
Name | Description
Public Members | The following functions, variables, structures, and macros are available for use by the user application.
Library Members | The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.
Internal Members | The following functions, variables, structures, and macros are designated as internal to the library.
APIs > SD-SPI Physical Layer


Public Members

Contents | Index | Home
Previous | Up | Next
Public Members

The following functions, variables, structures, and macros are available for use by the user application.

Functions
Name | Description
MDD_SDSPI_AsyncReadTasks | Speed optimized, non-blocking, state machine based read function that reads data packets from the media, and copies them to a user specified RAM buffer. Pre-Conditions: The ASYNC_IO structure must be initialized correctly, prior to calling this function for the first time. Certain parameters, such as the user data buffer pointer (pBuffer) in the ASYNC_IO struct are allowed to be changed by the application firmware, in between each call to MDD_SDSPI_AsyncReadTasks(). Additionally, the media and microcontroller SPI module should have already been initalized before using this function. This function is mutually exclusive with the MDD_SDSPI_AsyncWriteTasks() function. Only one operation (either... more
MDD_SDSPI_AsyncWriteTasks | Speed optimized, non-blocking, state machine based write function that writes data from the user specified buffer, onto the media, at the specified address block address. Pre-Conditions: The ASYNC_IO structure must be initialized correctly, prior to calling this function for the first time. Certain parameters, such as the user data buffer pointer (pBuffer) in the ASYNC_IO struct are allowed to be changed by the application firmware, in between each call to MDD_SDSPI_AsyncWriteTasks(). Additionally, the media and microcontroller SPI module should have already been initalized before using this function. This function is mutually exclusive with the MDD_SDSPI_AsyncReadTasks() function. Only one operation... more
Macros
Name | Description
MDD_USE_SPI_1 | Define macro used to select SPI module 1 when using PIC32 parts.
SD_CD | SD-SPI Card Detect Input bit
SD_CD_TRIS | SD-SPI Card Detect TRIS bit
SD_CS | SD-SPI Chip Select Output bit
SD_CS_TRIS | SD-SPI Chip Select TRIS bit
SD_WE | SD-SPI Write Protect Check Input bit
SD_WE_TRIS | SD-SPI Write Protect Check TRIS bit
SPI_FREQUENCY | Define macro used to select SPI frequency when using PIC32 parts.
SPI_INTERRUPT_FLAG | The interrupt flag for the SPI module
SPIBRG | The definition for the SPI baud rate generator register (PIC32)
SPIBUF | The SPI Buffer
SPICLOCK | The TRIS bit for the SCK pin
SPICLOCKPORT | The port for the SCK pin
SPICLOCKLAT | The output latch for the SCK pin
SPICON1 | The main SPI control register
SPICON1bits | The bitwise define for the SPI control register (i.e. _____bits)
SPIENABLE | The enable bit for the SPI module
SPIIN | The TRIS bit for the SDI pin
SPIINPORT | The port for the SDI pin
SPIINLAT | The output latch for the SDI pin
SPIOUT | The TRIS bit for the SDO pin
SPIOUTPORT | The port for the SDO pin
SPIOUTLAT | The output latch for the SDO pin
SPISTAT | The SPI status register
SPISTAT_RBF | The receive buffer full bit in the SPI status register
SPISTATbits | The bitwise define for the SPI status register (i.e. _____bits)
ASYNC_READ_ABORT | This is macro ASYNC_READ_ABORT.
ASYNC_READ_BUSY | This is macro ASYNC_READ_BUSY.
ASYNC_READ_COMPLETE | MDD_SDSPI_AsyncReadTasks() state machine variable values. These are used internally to SD-SPI.c.
ASYNC_READ_ERROR | This is macro ASYNC_READ_ERROR.
ASYNC_READ_NEW_PACKET_READY | This is macro ASYNC_READ_NEW_PACKET_READY.
ASYNC_READ_QUEUED | Initialize to this to start a read sequence
ASYNC_READ_WAIT_START_TOKEN | This is macro ASYNC_READ_WAIT_START_TOKEN.
ASYNC_STOP_TOKEN_SENT_WAIT_BUSY | This is macro ASYNC_STOP_TOKEN_SENT_WAIT_BUSY.
ASYNC_WRITE_ABORT | This is macro ASYNC_WRITE_ABORT.
ASYNC_WRITE_BUSY | This is macro ASYNC_WRITE_BUSY.
ASYNC_WRITE_COMPLETE | MDD_SDSPI_AsyncWriteTasks() state machine variable values. These are used internally to SD-SPI.c.
ASYNC_WRITE_ERROR | This is macro ASYNC_WRITE_ERROR.
ASYNC_WRITE_MEDIA_BUSY | This is macro ASYNC_WRITE_MEDIA_BUSY.
ASYNC_WRITE_QUEUED | Initialize to this to start a write sequence
ASYNC_WRITE_SEND_PACKET | This is macro ASYNC_WRITE_SEND_PACKET.
ASYNC_WRITE_TRANSMIT_PACKET | This is macro ASYNC_WRITE_TRANSMIT_PACKET.
cmdSD_SEND_OP_COND | This macro defines the command code to intitialize an SD card and provide the CSD register value.
cmdSEND_IF_COND | This macro defined the command code to check for sector addressing
cmdSET_WR_BLK_ERASE_COUNT | This macro defines the command code to tell the media how many blocks to pre-erase (for faster multi-block writes to follow)
DATA_START_MULTI_BLOCK_TOKEN | This macro represents an SD card start multi-block data token (used for multi-block writes)
DATA_STOP_TRAN_TOKEN | This macro represents an SD card stop transmission token. This is used when finishing a multi block write sequence.
Topics
Name | Description
MDD_USE_SPI_2 | Define macro used to select SPI module 2 when using PIC32 parts.
APIs > SD-SPI Physical Layer > Public Members


MDD_SDSPI_AsyncReadTasks Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_AsyncReadTasks Function
C
BYTE MDD_SDSPI_AsyncReadTasks(
    ASYNC_IO*
);
Description

Speed optimized, non-blocking, state machine based read function that reads data packets from the media, and copies them to a user specified RAM buffer. This function uses the multi-block read command (and stop transmission command) to perform fast reads of data. The total amount of data that will be returned on any given call to MDD_SDSPI_AsyncReadTasks() will be the info->numBytes parameter. However, if the function is called repeatedly, with info->bytesRemaining set to a large number, this function can successfully fetch data sizes >> than the block size (theoretically anything up to ~4GB, since bytesRemaining is a 32-bit DWORD). The application firmware should continue calling MDD_SDSPI_AsyncReadTasks(), until the ASYNC_READ_COMPLETE value is returned (or ASYNC_READ_ERROR), even if it has already received all of the data expected. This is necessary, so the state machine can issue the CMD12 (STOP_TRANMISSION) to terminate the multi-block read operation, once the total expected number of bytes have been read. This puts the media back into the default state ready for a new command.

During normal/successful operations, calls to MDD_SDSPI_AsyncReadTasks() would typically return:

  1. ASYNC_READ_BUSY - repeatedly up to several milliseconds, then
  2. ASYNC_READ_NEW_PACKET_READY - repeatedly, until 512 bytes [media read block size] is received, then
  3. Back to ASYNC_READ_BUSY (for awhile, may be short), then
  4. Back to ASYNC_READ_NEW_PACKET_READY (repeatedly, until the next 512 byte boundary, then back to #3, etc.
  5. After all data is received successfully, then the function will return ASYNC_READ_COMPLETE, for all subsequent calls (until a new read operation is started, by re-initializing the ASYNC_IO structure, and re-calling the function).
Parameters
Parameters | Description
ASYNC_IO* info | A pointer to a ASYNC_IO structure. The structure contains information about how to complete
the read operation (ex | number of total bytes to read, where to copy them once read, maximum number of bytes to return for each call to MDD_SDSPI_AsyncReadTasks(), etc.).
Return Values
Return Values | Description
BYTE | Returns a status byte indicating the current state of the read
operation. The possible return values are |
ASYNC_READ_BUSY | Returned when the state machine is busy waiting for a data start token from the media. The media has a random access time, which can often be quite long (<= ~3ms typ, with maximum of 100ms). No data has been copied yet in this case, and the application should keep calling MDD_SDSPI_AsyncReadTasks() until either an error/timeout occurs, or ASYNC_READ_NEW_PACKET_READY is returned.
ASYNC_READ_NEW_PACKET_READY | Returned after a single packet, of the specified size (in info->numBytes), is ready to be read from the media and copied to the user specified data buffer. Often, after receiving this return value, the application firmware would want to update the info->pReceiveBuffer pointer before calling MDD_SDSPI_AsyncReadTasks() again. This way, the application can begin fetching the next packet worth of data, while still using/consuming the previous packet of data.
ASYNC_READ_COMPLETE | Returned when all data bytes in the read operation have been read and returned successfully, and the media is now ready for the next operation.
ASYNC_READ_ERROR | Returned when some failure occurs. This could be either due to a media timeout, or due to some other unknown type of error. In this case, the MDD_SDSPI_AsyncReadTasks() handler will terminate the read attempt and will try to put the media back in a default state, ready for a new command. The application firmware may then retry the read attempt (if desired) by re-initializing the ASYNC_IO structure and setting the bStateVariable = ASYNC_READ_QUEUED.
Side Effects

Uses the SPI bus and the media. The media and SPI bus should not be used by any other function until the read operation has either completed successfully, or returned with the ASYNC_READ_ERROR condition.

Remarks

This function will monopolize the SPI module during the operation. Do not use the SPI module for any other purpose, while a fetch operation is in progress. Additionally, the ASYNC_IO structure must not be modified in a different context, while the MDD_SDSPI_AsyncReadTasks() function is executing. In between calls to MDD_SDSPI_AsyncReadTasks(), certain parameters, namely the info->numBytes and info->pReceiveBuffer are allowed to change however.

The bytesRemaining value must always be an exact integer multiple of numBytes for the function to operate correctly. Additionally, it is recommended, although not essential, for the bytesRemaining to be an integer multiple of the media read block size.

When starting a read operation, the info->stateVariable must be initalized to ASYNC_READ_QUEUED. All other fields in the info structure should also be initialized correctly.

The info->wNumBytes must always be less than or equal to the media block size, (which is 512 bytes). Additionally, info->wNumBytes must always be an exact integer factor of the media block size (unless info->dwBytesRemaining is less than the media block size). Example values that are allowed for info->wNumBytes are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512.

APIs > SD-SPI Physical Layer > Public Members > MDD_SDSPI_AsyncReadTasks Function


MDD_SDSPI_AsyncWriteTasks Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_AsyncWriteTasks Function
C
BYTE MDD_SDSPI_AsyncWriteTasks(
    ASYNC_IO*
);
Description

Speed optimized, non-blocking, state machine based read function that writes data packets to the media, from a user specified RAM buffer. This function uses either the single block or multi-block write command to perform fast writes of the data. The total amount of data that will be written on any given call to MDD_SDSPI_AsyncWriteTasks() will be the info->numBytes parameter. However, if the function is called repeatedly, with info->dwBytesRemaining set to a large number, this function can successfully write data sizes >> than the block size (theoretically anything up to ~4GB, since dwBytesRemaining is a 32-bit DWORD). The application firmware should continue calling MDD_SDSPI_AsyncWriteTasks(), until the ASYNC_WRITE_COMPLETE value is returned (or ASYNC_WRITE_ERROR), even if it has already sent all of the data expected. This is necessary, so the state machine can finish the write process and terminate the multi-block write operation, once the total expected number of bytes have been written. This puts the media back into the default state ready for a new command.

During normal/successful operations, calls to MDD_SDSPI_AsyncWriteTasks() would typically return:

  1. ASYNC_WRITE_SEND_PACKET - repeatedly, until 512 bytes [media read block size] is received, then
  2. ASYNC_WRITE_BUSY (for awhile, could be a long time, many milliseconds), then
  3. Back to ASYNC_WRITE_SEND_PACKET (repeatedly, until the next 512 byte boundary, then back to #2, etc.
  4. After all data is copied successfully, then the function will return ASYNC_WRITE_COMPLETE, for all subsequent calls (until a new write operation is started, by re-initializing the ASYNC_IO structure, and re-calling the function).
Parameters
Parameters | Description
ASYNC_IO* info | A pointer to a ASYNC_IO structure. The structure contains information about how to complete
the write operation (ex | number of total bytes to write, where to obtain the bytes from, number of bytes to write for each call to MDD_SDSPI_AsyncWriteTasks(), etc.).
Return Values
Return Values | Description
BYTE | Returns a status byte indicating the current state of the write
operation. The possible return values are |
ASYNC_WRITE_BUSY | Returned when the state machine is busy waiting for the media to become ready to accept new data. The media has write time, which can often be quite long (a few ms typ, with maximum of 250ms). The application should keep calling MDD_SDSPI_AsyncWriteTasks() until either an error/timeout occurs, ASYNC_WRITE_SEND_PACKET is returned, or ASYNC_WRITE_COMPLETE is returned.
ASYNC_WRITE_SEND_PACKET | Returned when the MDD_SDSPI_AsyncWriteTasks() handler is ready to consume data and send it to the media. After ASYNC_WRITE_SEND_PACKET is returned, the application should make certain that the info->wNumBytes and pBuffer parameters are correct, prior to calling MDD_SDSPI_AsyncWriteTasks() again. After the function returns, the application is then free to write new data into the pBuffer RAM location.
ASYNC_WRITE_COMPLETE | Returned when all data bytes in the write operation have been written to the media successfully, and the media is now ready for the next operation.
ASYNC_WRITE_ERROR | Returned when some failure occurs. This could be either due to a media timeout, or due to some other unknown type of error. In this case, the MDD_SDSPI_AsyncWriteTasks() handler will terminate the write attempt and will try to put the media back in a default state, ready for a new command. The application firmware may then retry the write attempt (if desired) by re-initializing the ASYNC_IO structure and setting the bStateVariable = ASYNC_WRITE_QUEUED.
Side Effects

Uses the SPI bus and the media. The media and SPI bus should not be used by any other function until the read operation has either completed successfully, or returned with the ASYNC_WRITE_ERROR condition.

Remarks

When starting a read operation, the info->stateVariable must be initalized to ASYNC_WRITE_QUEUED. All other fields in the info structure should also be initialized correctly.

This function will monopolize the SPI module during the operation. Do not use the SPI module for any other purpose, while a write operation is in progress. Additionally, the ASYNC_IO structure must not be modified in a different context, while the MDD_SDSPI_AsyncReadTasks() function is actively executing. In between calls to MDD_SDSPI_AsyncWriteTasks(), certain parameters, namely the info->wNumBytes and info->pBuffer are allowed to change however.

The dwBytesRemaining value must always be an exact integer multiple of wNumBytes for the function to operate correctly. Additionally, it is required that the wNumBytes parameter, must always be less than or equal to the media block size, (which is 512 bytes). Additionally, info->wNumBytes must always be an exact integer factor of the media block size. Example values that are allowed for info->wNumBytes are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512.

APIs > SD-SPI Physical Layer > Public Members > MDD_SDSPI_AsyncWriteTasks Function


MDD_USE_SPI_1 Macro

Contents | Index | Home
Previous | Up | Next
MDD_USE_SPI_1 Macro
C
#define MDD_USE_SPI_1
Description

Define macro used to select SPI module 1 when using PIC32 parts.

APIs > SD-SPI Physical Layer > Public Members > MDD_USE_SPI_1 Macro


MDD_USE_SPI_2

Contents | Index | Home
Previous | Up | Next
MDD_USE_SPI_2

Define macro used to select SPI module 2 when using PIC32 parts.

APIs > SD-SPI Physical Layer > Public Members > MDD_USE_SPI_2


SD_CD Macro

Contents | Index | Home
Previous | Up | Next
SD_CD Macro
C
#define SD_CD PORTGbits.RG0
Description

SD-SPI Card Detect Input bit

APIs > SD-SPI Physical Layer > Public Members > SD_CD Macro


SD_CD_TRIS Macro

Contents | Index | Home
Previous | Up | Next
SD_CD_TRIS Macro
C
#define SD_CD_TRIS TRISGbits.TRISG0
Description

SD-SPI Card Detect TRIS bit

APIs > SD-SPI Physical Layer > Public Members > SD_CD_TRIS Macro


SD_CS Macro

Contents | Index | Home
Previous | Up | Next
SD_CS Macro
C
#define SD_CS LATBbits.LATB9
Description

SD-SPI Chip Select Output bit

APIs > SD-SPI Physical Layer > Public Members > SD_CS Macro


SD_CS_TRIS Macro

Contents | Index | Home
Previous | Up | Next
SD_CS_TRIS Macro
C
#define SD_CS_TRIS TRISBbits.TRISB9
Description

SD-SPI Chip Select TRIS bit

APIs > SD-SPI Physical Layer > Public Members > SD_CS_TRIS Macro


SD_WE Macro

Contents | Index | Home
Previous | Up | Next
SD_WE Macro
C
#define SD_WE PORTGbits.RG1
Description

SD-SPI Write Protect Check Input bit

APIs > SD-SPI Physical Layer > Public Members > SD_WE Macro


SD_WE_TRIS Macro

Contents | Index | Home
Previous | Up | Next
SD_WE_TRIS Macro
C
#define SD_WE_TRIS TRISGbits.TRISG1
Description

SD-SPI Write Protect Check TRIS bit

APIs > SD-SPI Physical Layer > Public Members > SD_WE_TRIS Macro


SPI_FREQUENCY Macro

Contents | Index | Home
Previous | Up | Next
SPI_FREQUENCY Macro
C
#define SPI_FREQUENCY (20000000)
Description

Define macro used to select SPI frequency when using PIC32 parts.

APIs > SD-SPI Physical Layer > Public Members > SPI_FREQUENCY Macro


SPI_INTERRUPT_FLAG Macro

Contents | Index | Home
Previous | Up | Next
SPI_INTERRUPT_FLAG Macro
C
#define SPI_INTERRUPT_FLAG PIR1bits.SSPIF
Description

The interrupt flag for the SPI module

APIs > SD-SPI Physical Layer > Public Members > SPI_INTERRUPT_FLAG Macro


SPIBRG Macro

Contents | Index | Home
Previous | Up | Next
SPIBRG Macro
C
#define SPIBRG SPI2BRG
Description

The definition for the SPI baud rate generator register (PIC32)

APIs > SD-SPI Physical Layer > Public Members > SPIBRG Macro


SPIBUF Macro

Contents | Index | Home
Previous | Up | Next
SPIBUF Macro
C
#define SPIBUF SPI2BUF
Description

The SPI Buffer

APIs > SD-SPI Physical Layer > Public Members > SPIBUF Macro


SPICLOCK Macro

Contents | Index | Home
Previous | Up | Next
SPICLOCK Macro
C
#define SPICLOCK TRISGbits.TRISG6
Description

The TRIS bit for the SCK pin

APIs > SD-SPI Physical Layer > Public Members > SPICLOCK Macro


SPICLOCKPORT Macro

Contents | Index | Home
Previous | Up | Next
SPICLOCKPORT Macro
C
#define SPICLOCKPORT PORTCbits.RC3
Description

The port for the SCK pin

APIs > SD-SPI Physical Layer > Public Members > SPICLOCKPORT Macro


SPICLOCKLAT Macro

Contents | Index | Home
Previous | Up | Next
SPICLOCKLAT Macro
C
#define SPICLOCKLAT LATCbits.LATC3
Description

The output latch for the SCK pin

APIs > SD-SPI Physical Layer > Public Members > SPICLOCKLAT Macro


SPICON1 Macro

Contents | Index | Home
Previous | Up | Next
SPICON1 Macro
C
#define SPICON1 SPI2CON
Description

The main SPI control register

APIs > SD-SPI Physical Layer > Public Members > SPICON1 Macro


SPICON1bits Macro

Contents | Index | Home
Previous | Up | Next
SPICON1bits Macro
C
#define SPICON1bits SPI2CONbits
Description

The bitwise define for the SPI control register (i.e. _____bits)

APIs > SD-SPI Physical Layer > Public Members > SPICON1bits Macro


SPIENABLE Macro

Contents | Index | Home
Previous | Up | Next
SPIENABLE Macro
C
#define SPIENABLE SPI2CONbits.ON
Description

The enable bit for the SPI module

APIs > SD-SPI Physical Layer > Public Members > SPIENABLE Macro


SPIIN Macro

Contents | Index | Home
Previous | Up | Next
SPIIN Macro
C
#define SPIIN TRISGbits.TRISG7
Description

The TRIS bit for the SDI pin

APIs > SD-SPI Physical Layer > Public Members > SPIIN Macro


SPIINPORT Macro

Contents | Index | Home
Previous | Up | Next
SPIINPORT Macro
C
#define SPIINPORT PORTCbits.RC4
Description

The port for the SDI pin

APIs > SD-SPI Physical Layer > Public Members > SPIINPORT Macro


SPIINLAT Macro

Contents | Index | Home
Previous | Up | Next
SPIINLAT Macro
C
#define SPIINLAT LATCbits.LATC4
Description

The output latch for the SDI pin

APIs > SD-SPI Physical Layer > Public Members > SPIINLAT Macro


SPIOUT Macro

Contents | Index | Home
Previous | Up | Next
SPIOUT Macro
C
#define SPIOUT TRISGbits.TRISG8
Description

The TRIS bit for the SDO pin

APIs > SD-SPI Physical Layer > Public Members > SPIOUT Macro


SPIOUTPORT Macro

Contents | Index | Home
Previous | Up | Next
SPIOUTPORT Macro
C
#define SPIOUTPORT PORTCbits.RC5
Description

The port for the SDO pin

APIs > SD-SPI Physical Layer > Public Members > SPIOUTPORT Macro


SPIOUTLAT Macro

Contents | Index | Home
Previous | Up | Next
SPIOUTLAT Macro
C
#define SPIOUTLAT LATCbits.LATC5
Description

The output latch for the SDO pin

APIs > SD-SPI Physical Layer > Public Members > SPIOUTLAT Macro


SPISTAT Macro

Contents | Index | Home
Previous | Up | Next
SPISTAT Macro
C
#define SPISTAT SPI2STAT
Description

The SPI status register

APIs > SD-SPI Physical Layer > Public Members > SPISTAT Macro


SPISTAT_RBF Macro

Contents | Index | Home
Previous | Up | Next
SPISTAT_RBF Macro
C
#define SPISTAT_RBF SPI2STATbits.SPIRBF
Description

The receive buffer full bit in the SPI status register

APIs > SD-SPI Physical Layer > Public Members > SPISTAT_RBF Macro


SPISTATbits Macro

Contents | Index | Home
Previous | Up | Next
SPISTATbits Macro
C
#define SPISTATbits SPI2STATbits
Description

The bitwise define for the SPI status register (i.e. _____bits)

APIs > SD-SPI Physical Layer > Public Members > SPISTATbits Macro


ASYNC_READ_ABORT Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_ABORT Macro
C
#define ASYNC_READ_ABORT 0xFE
Description

This is macro ASYNC_READ_ABORT.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_ABORT Macro


ASYNC_READ_BUSY Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_BUSY Macro
C
#define ASYNC_READ_BUSY 0x01
Description

This is macro ASYNC_READ_BUSY.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_BUSY Macro


ASYNC_READ_COMPLETE Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_COMPLETE Macro
C
#define ASYNC_READ_COMPLETE 0x00
Description

MDD_SDSPI_AsyncReadTasks() state machine variable values. These are used internally to SD-SPI.c.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_COMPLETE Macro


ASYNC_READ_ERROR Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_ERROR Macro
C
#define ASYNC_READ_ERROR 0xFF
Description

This is macro ASYNC_READ_ERROR.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_ERROR Macro


ASYNC_READ_NEW_PACKET_READY Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_NEW_PACKET_READY Macro
C
#define ASYNC_READ_NEW_PACKET_READY 0x02
Description

This is macro ASYNC_READ_NEW_PACKET_READY.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_NEW_PACKET_READY Macro


ASYNC_READ_QUEUED Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_QUEUED Macro
C
#define ASYNC_READ_QUEUED 0x01    //Initialize to this to start a read sequence
Description

Initialize to this to start a read sequence

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_QUEUED Macro


ASYNC_READ_WAIT_START_TOKEN Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_READ_WAIT_START_TOKEN Macro
C
#define ASYNC_READ_WAIT_START_TOKEN 0x03
Description

This is macro ASYNC_READ_WAIT_START_TOKEN.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_READ_WAIT_START_TOKEN Macro


ASYNC_STOP_TOKEN_SENT_WAIT_BUSY Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_STOP_TOKEN_SENT_WAIT_BUSY Macro
C
#define ASYNC_STOP_TOKEN_SENT_WAIT_BUSY 0x04
Description

This is macro ASYNC_STOP_TOKEN_SENT_WAIT_BUSY.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_STOP_TOKEN_SENT_WAIT_BUSY Macro


ASYNC_WRITE_ABORT Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_ABORT Macro
C
#define ASYNC_WRITE_ABORT 0xFE
Description

This is macro ASYNC_WRITE_ABORT.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_ABORT Macro


ASYNC_WRITE_BUSY Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_BUSY Macro
C
#define ASYNC_WRITE_BUSY 0x03
Description

This is macro ASYNC_WRITE_BUSY.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_BUSY Macro


ASYNC_WRITE_COMPLETE Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_COMPLETE Macro
C
#define ASYNC_WRITE_COMPLETE 0x00
Description

MDD_SDSPI_AsyncWriteTasks() state machine variable values. These are used internally to SD-SPI.c.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_COMPLETE Macro


ASYNC_WRITE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_ERROR Macro
C
#define ASYNC_WRITE_ERROR 0xFF
Description

This is macro ASYNC_WRITE_ERROR.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_ERROR Macro


ASYNC_WRITE_MEDIA_BUSY Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_MEDIA_BUSY Macro
C
#define ASYNC_WRITE_MEDIA_BUSY 0x03
Description

This is macro ASYNC_WRITE_MEDIA_BUSY.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_MEDIA_BUSY Macro


ASYNC_WRITE_QUEUED Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_QUEUED Macro
C
#define ASYNC_WRITE_QUEUED 0x01    //Initialize to this to start a write sequence
Description

Initialize to this to start a write sequence

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_QUEUED Macro


ASYNC_WRITE_SEND_PACKET Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_SEND_PACKET Macro
C
#define ASYNC_WRITE_SEND_PACKET 0x02
Description

This is macro ASYNC_WRITE_SEND_PACKET.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_SEND_PACKET Macro


ASYNC_WRITE_TRANSMIT_PACKET Macro

Contents | Index | Home
Previous | Up | Next
ASYNC_WRITE_TRANSMIT_PACKET Macro
C
#define ASYNC_WRITE_TRANSMIT_PACKET 0x02
Description

This is macro ASYNC_WRITE_TRANSMIT_PACKET.

APIs > SD-SPI Physical Layer > Public Members > ASYNC_WRITE_TRANSMIT_PACKET Macro


cmdSD_SEND_OP_COND Macro

Contents | Index | Home
Previous | Up | Next
cmdSD_SEND_OP_COND Macro
C
#define cmdSD_SEND_OP_COND 41
Description

This macro defines the command code to intitialize an SD card and provide the CSD register value.

Remarks

this is an "application specific" command (specific to SD cards) and must be preceded by cmdAPP_CMD.

APIs > SD-SPI Physical Layer > Public Members > cmdSD_SEND_OP_COND Macro


cmdSEND_IF_COND Macro

Contents | Index | Home
Previous | Up | Next
cmdSEND_IF_COND Macro
C
#define cmdSEND_IF_COND 8
Description

This macro defined the command code to check for sector addressing

APIs > SD-SPI Physical Layer > Public Members > cmdSEND_IF_COND Macro


cmdSET_WR_BLK_ERASE_COUNT Macro

Contents | Index | Home
Previous | Up | Next
cmdSET_WR_BLK_ERASE_COUNT Macro
C
#define cmdSET_WR_BLK_ERASE_COUNT 23
Description

This macro defines the command code to tell the media how many blocks to pre-erase (for faster multi-block writes to follow)

Remarks

This is an "application specific" command. This tells the media how many blocks to pre-erase for the subsequent WRITE_MULTI_BLOCK

APIs > SD-SPI Physical Layer > Public Members > cmdSET_WR_BLK_ERASE_COUNT Macro


DATA_START_MULTI_BLOCK_TOKEN Macro

Contents | Index | Home
Previous | Up | Next
DATA_START_MULTI_BLOCK_TOKEN Macro
C
#define DATA_START_MULTI_BLOCK_TOKEN 0xFC
Description

This macro represents an SD card start multi-block data token (used for multi-block writes)

APIs > SD-SPI Physical Layer > Public Members > DATA_START_MULTI_BLOCK_TOKEN Macro


DATA_STOP_TRAN_TOKEN Macro

Contents | Index | Home
Previous | Up | Next
DATA_STOP_TRAN_TOKEN Macro
C
#define DATA_STOP_TRAN_TOKEN 0xFD
Description

This macro represents an SD card stop transmission token. This is used when finishing a multi block write sequence.

APIs > SD-SPI Physical Layer > Public Members > DATA_STOP_TRAN_TOKEN Macro


Library Members

Contents | Index | Home
Previous | Up | Next
Library Members

The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.

Enumerations
Name | Description
RESP | Enumeration of different SD response types
sdmmc_cmd | An enumeration of SD commands
Functions
Name | Description
MDD_SDSPI_InitIO | Initializes the I/O lines connected to the card
MDD_SDSPI_MediaDetect | Determines whether an SD card is present
MDD_SDSPI_MediaInitialize | Initializes the SD card.
MDD_SDSPI_ReadCapacity | Determines the current capacity of the SD card
MDD_SDSPI_ReadMedia | Reads a byte of data from the SD card.
MDD_SDSPI_ReadSectorSize | Determines the current sector size on the SD card
MDD_SDSPI_SectorWrite | Writes a sector of data to an SD card.
MDD_SDSPI_SectorRead | Reads a sector of data from an SD card.
MDD_SDSPI_ShutdownMedia | Disables the SD card
MDD_SDSPI_WriteProtectState | Indicates whether the card is write-protected.
Macros
Name | Description
cmdAPP_CMD | This macro defines the command code to begin application specific command inputs
cmdCRC_ON_OFF | This macro defines the command code to disable CRC checking
cmdERASE | This macro defines the command code to erase all previously selected blocks
cmdGO_IDLE_STATE | This macro defines the command code to reset the SD card
cmdREAD_MULTI_BLOCK | This macro defines the command code to read multiple blocks from the card
cmdREAD_OCR | This macro defines the command code to get the OCR register information from the card
cmdREAD_SINGLE_BLOCK | This macro defines the command code to read one block from the card
cmdSEND_CID | This macro defines the command code to get the Card Information
cmdSEND_CSD | This macro defines the command code to get the Card Specific Data
cmdSEND_OP_COND | This macro defines the command code to initialize the SD card
cmdSEND_STATUS | This macro defines the command code to get the card status information
cmdSET_BLOCKLEN | This macro defines the command code to set the block length of the card
cmdSTOP_TRANSMISSION | This macro defines the command code to stop transmission during a multi-block read
cmdTAG_SECTOR_END | This macro defines the command code to set the address of the end of an erase operation
cmdTAG_SECTOR_START | This macro defines the command code to set the address of the start of an erase operation
cmdWRITE_MULTI_BLOCK | This macro defines the command code to write multiple blocks to the card
cmdWRITE_SINGLE_BLOCK | This macro defines the command code to write one block to the card
DATA_ACCEPTED | This macro represents an SD card data accepted token
DATA_START_TOKEN | This macro represents an SD card start single data block token (used for single block writes)
DELAY_OVERHEAD | An approximation of the number of cycles per delay loop of overhead
DELAY_PRESCALER | A delay prescaler
MASTER_ENABLE_ON | This macro indicates the SPI enable bit for 16-bit PICs
MILLISECDELAY | An approximate calculation of how many times to loop to delay 1 ms in the Delayms function
MMC_BAD_RESPONSE | This macro represents a bad SD card response byte
MMC_FLOATING_BUS | This macro represents a floating SPI bus condition
MOREDATA | This macro indicates that the SD card expects to transmit or receive more data
mReadCRC | A macro to send clock cycles to dummy-read the CRC
mSend8ClkCycles | A macro to send 8 clock cycles for SD timing requirements
mSendCRC | A macro to send clock cycles to dummy-write the CRC
NODATA | This macro indicates that the SD card does not expect to transmit or receive more data
PRI_PRESCAL_1_1 | This macro is used to initialize a 16-bit PIC SPI module primary prescaler
SEC_PRESCAL_1_1 | This macro is used to initialize a 16-bit PIC SPI module secondary prescaler
SYNC_MODE_FAST | This macro is used to initialize a 16-bit PIC SPI module
SYNC_MODE_MED | This macro is used to initialize a PIC18 SPI module with a 16x prescale divider
SYNC_MODE_SLOW | This macro is used to initialize a 16-bit PIC SPI module
Structures
Name | Description
typMMC_CMD | SD card command data structure
Types
Name | Description
ASYNC_IO | Definition for a structure used when calling either MDD_SDSPI_AsyncReadTasks() function, or the MDD_SDSPI_AsyncWriteTasks() function.
Unions
Name | Description
CID | A description of the card information register
CMD_PACKET | An SD command packet
CSD | A description of the card specific data register
RESPONSE_1 | The format of an R1 type response
RESPONSE_2 | The format of an R2 type response
MMC_RESPONSE | A union of responses from an SD card
Variables
Name | Description
mediaInformation | Global Variables
APIs > SD-SPI Physical Layer > Library Members


MDD_SDSPI_InitIO Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_InitIO Function
C
void MDD_SDSPI_InitIO();
Description

The MDD_SDSPI_InitIO function initializes the I/O pins connected to the SD card.

Preconditions

MDD_MediaInitialize() is complete. The MDD_InitIO function pointer is pointing to this function.

Returns

None

Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_InitIO Function


MDD_SDSPI_MediaDetect Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_MediaDetect Function
C
BYTE MDD_SDSPI_MediaDetect();
Description

The MDD_SDSPI_MediaDetect function determine if an SD card is connected to the microcontroller. If the MEDIA_SOFT_DETECT is not defined, the detection is done by polling the SD card detect pin. The MicroSD connector does not have a card detect pin, and therefore a software mechanism must be used. To do this, the SEND_STATUS command is sent to the card. If the card is not answering with 0x00, the card is either not present, not configured, or in an error state. If this is the case, we try to reconfigure the card. If the configuration fails, we consider the card not present (it still may be present, but malfunctioning). In order to use the software card detect mechanism, the MEDIA_SOFT_DETECT macro must be defined.

Preconditions

The MDD_MediaDetect function pointer must be configured to point to this function in FSconfig.h

Return Values
Return Values | Description
TRUE | Card detected
FALSE | No card detected
Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_MediaDetect Function


MDD_SDSPI_MediaInitialize Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_MediaInitialize Function
C
MEDIA_INFORMATION * MDD_SDSPI_MediaInitialize();
Description

This function will send initialization commands to and SD card.

Preconditions

The MDD_MediaInitialize function pointer must be pointing to this function.

Return Values
Return Values
Description
errorCode member may contain the following values

  • MEDIA_NO_ERROR - The media initialized successfully
  • MEDIA_CANNOT_INITIALIZE - Cannot initialize the media.

Side Effects

None.

Remarks

Psuedo code flow for the media initialization process is as follows:

-----------------------------------------------------------------------------------------

SD Card SPI Initialization Sequence (for physical layer v1.x or v2.0 device) is as follows:

-----------------------------------------------------------------------------------------
  1. Power up tasks a. Initialize microcontroller SPI module to no more than 400kbps rate so as to support MMC devices. b. Add delay for SD card power up, prior to sending it any commands. It wants the longer of: 1ms, the Vdd ramp time (time from 2.7V to Vdd stable), and 74+ clock pulses.
  2. Send CMD0 (GO_IDLE_STATE) with CS = 0. This puts the media in SPI mode and software resets the SD/MMC card.
  3. Send CMD8 (SEND_IF_COND). This requests what voltage the card wants to run at.

    Some cards will not support this command. a. If illegal command response is received, this implies either a v1.x physical spec device, or not an SD card (ex: MMC). b. If normal response is received, then it must be a v2.0 or later SD memory card.

If v1.x device:

---------------
  3. Send CMD1 repeatedly, until initialization complete (indicated by R1 response byte/idle bit == 0)
  4. Basic initialization is complete. May now switch to higher SPI frequencies.
  5. Send CMD9 to read the CSD structure. This will tell us the total flash size and other info which will be useful later.
  6. Parse CSD structure bits (based on v1.x structure format) and extract useful information about the media.
  7. The card is now ready to perform application data transfers.

If v2.0+ device:

---------------
  3. Verify the voltage range is feasible. If not, unusable card, should notify user that the card is incompatible with this host.
  4. Send CMD58 (Read OCR).
  5. Send CMD55, then ACMD41 (SD_SEND_OP_COND, with HCS = 1). a. Loop CMD55/ACMD41 until R1 response byte == 0x00 (indicating the card is no longer busy/no longer in idle state).
  6. Send CMD58 (Get CCS). a. If CCS = 1 --> SDHC card. b. If CCS = 0 --> Standard capacity SD card (which is v2.0+).
  7. Basic initialization is complete. May now switch to higher SPI frequencies.
  8. Send CMD9 to read the CSD structure. This will tell us the total flash size and other info which will be useful later.
  9. Parse CSD structure bits (based on v2.0 structure format) and extract useful information about the media.
  10. The card is now ready to perform application data transfers.
APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_MediaInitialize Function


MDD_SDSPI_ReadCapacity Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_ReadCapacity Function
C
DWORD MDD_SDSPI_ReadCapacity();
Description

The MDD_SDSPI_ReadCapacity function is used by the USB mass storage class to return the total number of sectors on the card.

Preconditions

MDD_MediaInitialize() is complete

Returns

The capacity of the device

Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_ReadCapacity Function


MDD_SDSPI_ReadMedia Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_ReadMedia Function
C
BYTE MDD_SDSPI_ReadMedia();
Description

The MDD_SDSPI_ReadMedia function will read one byte from the SPI port.

Preconditions

None.

Returns

The byte read.

Side Effects

None.

Remarks

This function replaces ReadSPI, since some implementations of that function will initialize SSPBUF/SPIBUF to 0x00 when reading. The card expects 0xFF.

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_ReadMedia Function


MDD_SDSPI_ReadSectorSize Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_ReadSectorSize Function
C
WORD MDD_SDSPI_ReadSectorSize();
Description

The MDD_SDSPI_ReadSectorSize function is used by the USB mass storage class to return the card's sector size to the PC on request.

Preconditions

MDD_MediaInitialize() is complete

Returns

The size of the sectors for the physical media

Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_ReadSectorSize Function


MDD_SDSPI_SectorWrite Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_SectorWrite Function
C
BYTE MDD_SDSPI_SectorWrite(
    DWORD sector_addr,
    BYTE* buffer,
    BYTE allowWriteToZero
);
Description

The MDD_SDSPI_SectorWrite function writes one sector of data (512 bytes) of data from the location pointed to by 'buffer' to the specified sector of the SD card.

Preconditions

The MDD_SectorWrite function pointer must be pointing to this function.

Parameters
Parameters
Description
sector_addr
The address of the sector on the card.
buffer
The buffer with the data to write.
allowWriteToZero

  • TRUE - Writes to the 0 sector (MBR) are allowed
  • FALSE - Any write to the 0 sector will fail.

Return Values
Return Values | Description
TRUE | The sector was written successfully.
FALSE | The sector could not be written.
Side Effects

None.

Remarks

The card expects the address field in the command packet to be a byte address. The sector_addr value is ocnverted to a byte address by shifting it left nine times (multiplying by 512).

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_SectorWrite Function


MDD_SDSPI_SectorRead Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_SectorRead Function
C
BYTE MDD_SDSPI_SectorRead(
    DWORD sector_addr,
    BYTE* buffer
);
Description

The MDD_SDSPI_SectorRead function reads a sector of data bytes (512 bytes) of data from the SD card starting at the sector address and stores them in the location pointed to by 'buffer.'

Preconditions

The MDD_SectorRead function pointer must be pointing towards this function.

Parameters
Parameters | Description
sector_addr | The address of the sector on the card.
buffer | The buffer where the retrieved data will be stored. If buffer is NULL, do not store the data anywhere.
Return Values
Return Values | Description
TRUE | The sector was read successfully
FALSE | The sector could not be read
Side Effects

None

Remarks

The card expects the address field in the command packet to be a byte address. The sector_addr value is converted to a byte address by shifting it left nine times (multiplying by 512).

This function performs a synchronous read operation. In other words, this function is a blocking function, and will not return until either the data has fully been read, or, a timeout or other error occurred.

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_SectorRead Function


MDD_SDSPI_ShutdownMedia Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_ShutdownMedia Function
C
BYTE MDD_SDSPI_ShutdownMedia();
Description

This function will disable the SPI port and deselect the SD card.

Preconditions

The MDD_ShutdownMedia function pointer is pointing towards this function.

Returns

None

Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_ShutdownMedia Function


cmdAPP_CMD Macro

Contents | Index | Home
Previous | Up | Next
cmdAPP_CMD Macro
C
#define cmdAPP_CMD 55
Description

This macro defines the command code to begin application specific command inputs

APIs > SD-SPI Physical Layer > Library Members > cmdAPP_CMD Macro


cmdCRC_ON_OFF Macro

Contents | Index | Home
Previous | Up | Next
cmdCRC_ON_OFF Macro
C
#define cmdCRC_ON_OFF 59
Description

This macro defines the command code to disable CRC checking

APIs > SD-SPI Physical Layer > Library Members > cmdCRC_ON_OFF Macro


cmdERASE Macro

Contents | Index | Home
Previous | Up | Next
cmdERASE Macro
C
#define cmdERASE 38
Description

This macro defines the command code to erase all previously selected blocks

APIs > SD-SPI Physical Layer > Library Members > cmdERASE Macro


cmdGO_IDLE_STATE Macro

Contents | Index | Home
Previous | Up | Next
cmdGO_IDLE_STATE Macro
C
#define cmdGO_IDLE_STATE 0
Description

This macro defines the command code to reset the SD card

APIs > SD-SPI Physical Layer > Library Members > cmdGO_IDLE_STATE Macro


cmdREAD_MULTI_BLOCK Macro

Contents | Index | Home
Previous | Up | Next
cmdREAD_MULTI_BLOCK Macro
C
#define cmdREAD_MULTI_BLOCK 18
Description

This macro defines the command code to read multiple blocks from the card

APIs > SD-SPI Physical Layer > Library Members > cmdREAD_MULTI_BLOCK Macro


cmdREAD_OCR Macro

Contents | Index | Home
Previous | Up | Next
cmdREAD_OCR Macro
C
#define cmdREAD_OCR 58
Description

This macro defines the command code to get the OCR register information from the card

APIs > SD-SPI Physical Layer > Library Members > cmdREAD_OCR Macro


cmdREAD_SINGLE_BLOCK Macro

Contents | Index | Home
Previous | Up | Next
cmdREAD_SINGLE_BLOCK Macro
C
#define cmdREAD_SINGLE_BLOCK 17
Description

This macro defines the command code to read one block from the card

APIs > SD-SPI Physical Layer > Library Members > cmdREAD_SINGLE_BLOCK Macro


cmdSEND_CID Macro

Contents | Index | Home
Previous | Up | Next
cmdSEND_CID Macro
C
#define cmdSEND_CID 10
Description

This macro defines the command code to get the Card Information

APIs > SD-SPI Physical Layer > Library Members > cmdSEND_CID Macro


cmdSEND_CSD Macro

Contents | Index | Home
Previous | Up | Next
cmdSEND_CSD Macro
C
#define cmdSEND_CSD 9
Description

This macro defines the command code to get the Card Specific Data

APIs > SD-SPI Physical Layer > Library Members > cmdSEND_CSD Macro


cmdSEND_OP_COND Macro

Contents | Index | Home
Previous | Up | Next
cmdSEND_OP_COND Macro
C
#define cmdSEND_OP_COND 1
Description

This macro defines the command code to initialize the SD card

APIs > SD-SPI Physical Layer > Library Members > cmdSEND_OP_COND Macro


cmdSEND_STATUS Macro

Contents | Index | Home
Previous | Up | Next
cmdSEND_STATUS Macro
C
#define cmdSEND_STATUS 13
Description

This macro defines the command code to get the card status information

APIs > SD-SPI Physical Layer > Library Members > cmdSEND_STATUS Macro


cmdSET_BLOCKLEN Macro

Contents | Index | Home
Previous | Up | Next
cmdSET_BLOCKLEN Macro
C
#define cmdSET_BLOCKLEN 16
Description

This macro defines the command code to set the block length of the card

APIs > SD-SPI Physical Layer > Library Members > cmdSET_BLOCKLEN Macro


cmdSTOP_TRANSMISSION Macro

Contents | Index | Home
Previous | Up | Next
cmdSTOP_TRANSMISSION Macro
C
#define cmdSTOP_TRANSMISSION 12
Description

This macro defines the command code to stop transmission during a multi-block read

APIs > SD-SPI Physical Layer > Library Members > cmdSTOP_TRANSMISSION Macro


cmdTAG_SECTOR_END Macro

Contents | Index | Home
Previous | Up | Next
cmdTAG_SECTOR_END Macro
C
#define cmdTAG_SECTOR_END 33
Description

This macro defines the command code to set the address of the end of an erase operation

APIs > SD-SPI Physical Layer > Library Members > cmdTAG_SECTOR_END Macro


cmdTAG_SECTOR_START Macro

Contents | Index | Home
Previous | Up | Next
cmdTAG_SECTOR_START Macro
C
#define cmdTAG_SECTOR_START 32
Description

This macro defines the command code to set the address of the start of an erase operation

APIs > SD-SPI Physical Layer > Library Members > cmdTAG_SECTOR_START Macro


cmdWRITE_MULTI_BLOCK Macro

Contents | Index | Home
Previous | Up | Next
cmdWRITE_MULTI_BLOCK Macro
C
#define cmdWRITE_MULTI_BLOCK 25
Description

This macro defines the command code to write multiple blocks to the card

APIs > SD-SPI Physical Layer > Library Members > cmdWRITE_MULTI_BLOCK Macro


cmdWRITE_SINGLE_BLOCK Macro

Contents | Index | Home
Previous | Up | Next
cmdWRITE_SINGLE_BLOCK Macro
C
#define cmdWRITE_SINGLE_BLOCK 24
Description

This macro defines the command code to write one block to the card

APIs > SD-SPI Physical Layer > Library Members > cmdWRITE_SINGLE_BLOCK Macro


DATA_ACCEPTED Macro

Contents | Index | Home
Previous | Up | Next
DATA_ACCEPTED Macro
C
#define DATA_ACCEPTED 0x05
Description

This macro represents an SD card data accepted token

APIs > SD-SPI Physical Layer > Library Members > DATA_ACCEPTED Macro


DATA_START_TOKEN Macro

Contents | Index | Home
Previous | Up | Next
DATA_START_TOKEN Macro
C
#define DATA_START_TOKEN 0xFE
Description

This macro represents an SD card start single data block token (used for single block writes)

APIs > SD-SPI Physical Layer > Library Members > DATA_START_TOKEN Macro


DELAY_OVERHEAD Macro

Contents | Index | Home
Previous | Up | Next
DELAY_OVERHEAD Macro
C
#define DELAY_OVERHEAD (BYTE)      5
Description

An approximation of the number of cycles per delay loop of overhead

APIs > SD-SPI Physical Layer > Library Members > DELAY_OVERHEAD Macro


DELAY_PRESCALER Macro

Contents | Index | Home
Previous | Up | Next
DELAY_PRESCALER Macro
C
#define DELAY_PRESCALER (BYTE)      8
Description

A delay prescaler

APIs > SD-SPI Physical Layer > Library Members > DELAY_PRESCALER Macro


MASTER_ENABLE_ON Macro

Contents | Index | Home
Previous | Up | Next
MASTER_ENABLE_ON Macro
C
#define MASTER_ENABLE_ON 0x0020
Description

This macro indicates the SPI enable bit for 16-bit PICs

APIs > SD-SPI Physical Layer > Library Members > MASTER_ENABLE_ON Macro


MILLISECDELAY Macro

Contents | Index | Home
Previous | Up | Next
MILLISECDELAY Macro
C
#define MILLISECDELAY (WORD)      ((GetInstructionClock()/DELAY_PRESCALER/(WORD)1000) - DELAY_OVERHEAD)
Description

An approximate calculation of how many times to loop to delay 1 ms in the Delayms function

APIs > SD-SPI Physical Layer > Library Members > MILLISECDELAY Macro


MMC_BAD_RESPONSE Macro

Contents | Index | Home
Previous | Up | Next
MMC_BAD_RESPONSE Macro
C
#define MMC_BAD_RESPONSE MMC_FLOATING_BUS
Description

This macro represents a bad SD card response byte

APIs > SD-SPI Physical Layer > Library Members > MMC_BAD_RESPONSE Macro


MMC_FLOATING_BUS Macro

Contents | Index | Home
Previous | Up | Next
MMC_FLOATING_BUS Macro
C
#define MMC_FLOATING_BUS 0xFF
Description

This macro represents a floating SPI bus condition

APIs > SD-SPI Physical Layer > Library Members > MMC_FLOATING_BUS Macro


MOREDATA Macro

Contents | Index | Home
Previous | Up | Next
MOREDATA Macro
C
#define MOREDATA !0
Description

This macro indicates that the SD card expects to transmit or receive more data

APIs > SD-SPI Physical Layer > Library Members > MOREDATA Macro


mReadCRC Macro

Contents | Index | Home
Previous | Up | Next
mReadCRC Macro
C
#define mReadCRC WriteSPIM(0xFF);WriteSPIM(0xFF);
Description

A macro to send clock cycles to dummy-read the CRC

APIs > SD-SPI Physical Layer > Library Members > mReadCRC Macro


mSend8ClkCycles Macro

Contents | Index | Home
Previous | Up | Next
mSend8ClkCycles Macro
C
#define mSend8ClkCycles WriteSPIM(0xFF);
Description

A macro to send 8 clock cycles for SD timing requirements

APIs > SD-SPI Physical Layer > Library Members > mSend8ClkCycles Macro


mSendCRC Macro

Contents | Index | Home
Previous | Up | Next
mSendCRC Macro
C
#define mSendCRC WriteSPIM(0xFF);WriteSPIM(0xFF);
Description

A macro to send clock cycles to dummy-write the CRC

APIs > SD-SPI Physical Layer > Library Members > mSendCRC Macro


NODATA Macro

Contents | Index | Home
Previous | Up | Next
NODATA Macro
C
#define NODATA 0
Description

This macro indicates that the SD card does not expect to transmit or receive more data

APIs > SD-SPI Physical Layer > Library Members > NODATA Macro


PRI_PRESCAL_1_1 Macro

Contents | Index | Home
Previous | Up | Next
PRI_PRESCAL_1_1 Macro
C
#define PRI_PRESCAL_1_1 0x0003
Description

This macro is used to initialize a 16-bit PIC SPI module primary prescaler

APIs > SD-SPI Physical Layer > Library Members > PRI_PRESCAL_1_1 Macro


SEC_PRESCAL_1_1 Macro

Contents | Index | Home
Previous | Up | Next
SEC_PRESCAL_1_1 Macro
C
#define SEC_PRESCAL_1_1 0x001c
Description

This macro is used to initialize a 16-bit PIC SPI module secondary prescaler

APIs > SD-SPI Physical Layer > Library Members > SEC_PRESCAL_1_1 Macro


SYNC_MODE_FAST Macro

Contents | Index | Home
Previous | Up | Next
SYNC_MODE_FAST Macro
C
#define SYNC_MODE_FAST 0x3E
Description

This macro is used to initialize a 16-bit PIC SPI module

APIs > SD-SPI Physical Layer > Library Members > SYNC_MODE_FAST Macro


SYNC_MODE_MED Macro

Contents | Index | Home
Previous | Up | Next
SYNC_MODE_MED Macro
C
#define SYNC_MODE_MED 0x01
Description

This macro is used to initialize a PIC18 SPI module with a 16x prescale divider

APIs > SD-SPI Physical Layer > Library Members > SYNC_MODE_MED Macro


SYNC_MODE_SLOW Macro

Contents | Index | Home
Previous | Up | Next
SYNC_MODE_SLOW Macro
C
#define SYNC_MODE_SLOW 0x3C
Description

This macro is used to initialize a 16-bit PIC SPI module

APIs > SD-SPI Physical Layer > Library Members > SYNC_MODE_SLOW Macro


CID Union

Contents | Index | Home
Previous | Up | Next
CID Union
C
typedef union {
  struct {
    DWORD _u320;
    DWORD _u321;
    DWORD _u322;
    DWORD _u323;
  }
  struct {
    BYTE _byte[16];
  }
  struct {
    unsigned NOT_USED : 1;
    unsigned CRC : 7;
    unsigned MDT : 8;
    DWORD PSN;
    unsigned PRV : 8;
    char PNM[6];
    WORD OID;
    unsigned MID : 8;
  }
} CID;
Description

This union represents different ways to access information in a packet with SD card CID register informaiton. For more information on the CID register, consult an SD card user's manual.

APIs > SD-SPI Physical Layer > Library Members > CID Union


CMD_PACKET Union

Contents | Index | Home
Previous | Up | Next
CMD_PACKET Union
C
typedef union {
  struct {
    BYTE field[7];
  }
  struct {
    BYTE crc;
    BYTE c30filler;
    BYTE c32filler[3];
    BYTE addr0;
    BYTE addr1;
    BYTE addr2;
    BYTE addr3;
    BYTE cmd;
  }
  struct {
    BYTE END_BIT : 1;
    BYTE CRC7 : 7;
    DWORD address;
    BYTE CMD_INDEX : 6;
    BYTE TRANSMIT_BIT : 1;
    BYTE START_BIT : 1;
  }
} CMD_PACKET;
Description

This union represents different ways to access an SD card command packet

Members
Members | Description
BYTE field[7]; | BYTE array
BYTE crc; | The CRC byte
BYTE c30filler; | Filler space (since bitwise declarations can't cross a WORD boundary)
BYTE c32filler[3]; | Filler space (since bitwise declarations can't cross a DWORD boundary)
BYTE addr0; | Address byte 0
BYTE addr1; | Address byte 1
BYTE addr2; | Address byte 2
BYTE addr3; | Address byte 3
BYTE cmd; | Command code byte
BYTE END_BIT : 1; | Packet end bit
BYTE CRC7 : 7; | CRC value
DWORD address; | Address
BYTE CMD_INDEX : 6; | Command code
BYTE TRANSMIT_BIT : 1; | Transmit bit
BYTE START_BIT : 1; | Packet start bit
APIs > SD-SPI Physical Layer > Library Members > CMD_PACKET Union


CSD Union

Contents | Index | Home
Previous | Up | Next
CSD Union
C
typedef union {
  struct {
    DWORD _u320;
    DWORD _u321;
    DWORD _u322;
    DWORD _u323;
  }
  struct {
    BYTE _byte[16];
  }
  struct {
    unsigned NOT_USED : 1;
    unsigned CRC : 7;
    unsigned ECC : 2;
    unsigned FILE_FORMAT : 2;
    unsigned TMP_WRITE_PROTECT : 1;
    unsigned PERM_WRITE_PROTECT : 1;
    unsigned COPY : 1;
    unsigned FILE_FORMAT_GRP : 1;
    unsigned RESERVED_1 : 5;
    unsigned WRITE_BL_PARTIAL : 1;
    unsigned WRITE_BL_LEN_L : 2;
    unsigned WRITE_BL_LEN_H : 2;
    unsigned R2W_FACTOR : 3;
    unsigned DEFAULT_ECC : 2;
    unsigned WP_GRP_ENABLE : 1;
    unsigned WP_GRP_SIZE : 5;
    unsigned ERASE_GRP_SIZE_L : 3;
    unsigned ERASE_GRP_SIZE_H : 2;
    unsigned SECTOR_SIZE : 5;
    unsigned C_SIZE_MULT_L : 1;
    unsigned C_SIZE_MULT_H : 2;
    unsigned VDD_W_CURR_MAX : 3;
    unsigned VDD_W_CUR_MIN : 3;
    unsigned VDD_R_CURR_MAX : 3;
    unsigned VDD_R_CURR_MIN : 3;
    unsigned C_SIZE_L : 2;
    unsigned C_SIZE_H : 8;
    unsigned C_SIZE_U : 2;
    unsigned RESERVED_2 : 2;
    unsigned DSR_IMP : 1;
    unsigned READ_BLK_MISALIGN : 1;
    unsigned WRITE_BLK_MISALIGN : 1;
    unsigned READ_BL_PARTIAL : 1;
    unsigned READ_BL_LEN : 4;
    unsigned CCC_L : 4;
    unsigned CCC_H : 8;
    unsigned TRAN_SPEED : 8;
    unsigned NSAC : 8;
    unsigned TAAC : 8;
    unsigned RESERVED_3 : 2;
    unsigned SPEC_VERS : 4;
    unsigned CSD_STRUCTURE : 2;
  }
} CSD;
Description

This union represents different ways to access information in a packet with SD card CSD informaiton. For more information on the CSD register, consult an SD card user's manual.

APIs > SD-SPI Physical Layer > Library Members > CSD Union


RESPONSE_1 Union

Contents | Index | Home
Previous | Up | Next
RESPONSE_1 Union
C
typedef union {
  BYTE _byte;
  struct {
    unsigned IN_IDLE_STATE : 1;
    unsigned ERASE_RESET : 1;
    unsigned ILLEGAL_CMD : 1;
    unsigned CRC_ERR : 1;
    unsigned ERASE_SEQ_ERR : 1;
    unsigned ADDRESS_ERR : 1;
    unsigned PARAM_ERR : 1;
    unsigned B7 : 1;
  }
} RESPONSE_1;
Description

This union represents different ways to access an SD card R1 type response packet.

Members
Members | Description
BYTE _byte; | Byte-wise access This structure allows bitwise access of the response
unsigned IN_IDLE_STATE : 1; | Card is in idle state
unsigned ERASE_RESET : 1; | Erase reset flag
unsigned ILLEGAL_CMD : 1; | Illegal command flag
unsigned CRC_ERR : 1; | CRC error flag
unsigned ERASE_SEQ_ERR : 1; | Erase sequence error flag
unsigned ADDRESS_ERR : 1; | Address error flag
unsigned PARAM_ERR : 1; | Parameter flag
unsigned B7 : 1; | Unused bit 7
APIs > SD-SPI Physical Layer > Library Members > RESPONSE_1 Union


RESPONSE_2 Union

Contents | Index | Home
Previous | Up | Next
RESPONSE_2 Union
C
typedef union {
  WORD _word;
  struct {
    BYTE _byte0;
    BYTE _byte1;
  }
  struct {
    unsigned IN_IDLE_STATE : 1;
    unsigned ERASE_RESET : 1;
    unsigned ILLEGAL_CMD : 1;
    unsigned CRC_ERR : 1;
    unsigned ERASE_SEQ_ERR : 1;
    unsigned ADDRESS_ERR : 1;
    unsigned PARAM_ERR : 1;
    unsigned B7 : 1;
    unsigned CARD_IS_LOCKED : 1;
    unsigned WP_ERASE_SKIP_LK_FAIL : 1;
    unsigned ERROR : 1;
    unsigned CC_ERROR : 1;
    unsigned CARD_ECC_FAIL : 1;
    unsigned WP_VIOLATION : 1;
    unsigned ERASE_PARAM : 1;
    unsigned OUTRANGE_CSD_OVERWRITE : 1;
  }
} RESPONSE_2;
Description

This union represents different ways to access an SD card R2 type response packet

APIs > SD-SPI Physical Layer > Library Members > RESPONSE_2 Union


MMC_RESPONSE Union

Contents | Index | Home
Previous | Up | Next
MMC_RESPONSE Union
C
typedef union {
  RESPONSE_1 r1;
  RESPONSE_2 r2;
  RESPONSE_7 r7;
} MMC_RESPONSE;
Description

The MMC_RESPONSE union represents any of the possible responses that an SD card can return after being issued a command.

APIs > SD-SPI Physical Layer > Library Members > MMC_RESPONSE Union


RESP Enumeration

Contents | Index | Home
Previous | Up | Next
RESP Enumeration
C
typedef enum {
  R1,
  R1b,
  R2,
  R3,
  R7
} RESP;
Description

Enumeration of different SD response types

Members
Members | Description
R1 | R1 type response
R1b | R1b type response
R2 | R2 type response
R3 | R3 type response
R7 | R7 type response
APIs > SD-SPI Physical Layer > Library Members > RESP Enumeration


sdmmc_cmd Enumeration

Contents | Index | Home
Previous | Up | Next
sdmmc_cmd Enumeration
C
typedef enum {
  GO_IDLE_STATE,
  SEND_OP_COND,
  SEND_IF_COND,
  SEND_CSD,
  SEND_CID,
  STOP_TRANSMISSION,
  SEND_STATUS,
  SET_BLOCKLEN,
  READ_SINGLE_BLOCK,
  READ_MULTI_BLOCK,
  WRITE_SINGLE_BLOCK,
  WRITE_MULTI_BLOCK,
  TAG_SECTOR_START,
  TAG_SECTOR_END,
  ERASE,
  APP_CMD,
  READ_OCR,
  CRC_ON_OFF,
  SD_SEND_OP_COND,
  SET_WR_BLK_ERASE_COUNT
} sdmmc_cmd;
Description

This enumeration corresponds to the position of each command in the sdmmc_cmdtable array These macros indicate to the SendMMCCmd function which element of the sdmmc_cmdtable array to retrieve command code information from.

APIs > SD-SPI Physical Layer > Library Members > sdmmc_cmd Enumeration


typMMC_CMD Structure

Contents | Index | Home
Previous | Up | Next
typMMC_CMD Structure
C
typedef struct {
  BYTE CmdCode;
  BYTE CRC;
  RESP responsetype;
  BYTE moredataexpected;
} typMMC_CMD;
Description

The typMMC_CMD structure is used to create a command table of information needed for each relevant SD command

Members
Members | Description
BYTE CmdCode; | The command code
BYTE CRC; | The CRC value for that command
RESP responsetype; | The response type
BYTE moredataexpected; | Set to MOREDATA or NODATA, depending on whether more data is expected or not
APIs > SD-SPI Physical Layer > Library Members > typMMC_CMD Structure


mediaInformation Variable

Contents | Index | Home
Previous | Up | Next
mediaInformation Variable
C
MEDIA_INFORMATION mediaInformation;
Description

Global Variables

APIs > SD-SPI Physical Layer > Library Members > mediaInformation Variable


ASYNC_IO Type

Contents | Index | Home
Previous | Up | Next
ASYNC_IO Type
C
typedef struct ASYNC_IO@1 ASYNC_IO;
Description

Definition for a structure used when calling either MDD_SDSPI_AsyncReadTasks() function, or the MDD_SDSPI_AsyncWriteTasks() function.

APIs > SD-SPI Physical Layer > Library Members > ASYNC_IO Type


Internal Members

Contents | Index | Home
Previous | Up | Next
Internal Members

The following functions, variables, structures, and macros are designated as internal to the library.

Functions
Name | Description
Delayms | Delay.
CloseSPIM | Disables the SPI module.
OpenSPIM | This is function OpenSPIM.
ReadMediaManual | Reads a byte of data from the SD card.
SendMMCCmd | Sends a command packet to the SD card.
SendMMCCmdManual | Sends a command packet to the SD card with bit-bang SPI.
WriteSPIM | Writes data to the SD card.
WriteSPIManual | Write a character to the SD card with bit-bang SPI.
Macros
Name | Description
MANUAL_SPI_CLOCK_VALUE | Delay value for the manual SPI clock
Variables
Name | Description
sdmmc_cmdtable | Table of SD card commands and parameters
MDD_SDSPI_finalLBA | Used for the mass-storage library to determine capacity
APIs > SD-SPI Physical Layer > Internal Members


Delayms Function

Contents | Index | Home
Previous | Up | Next
Delayms Function
C
void Delayms(
    BYTE milliseconds
);
Description

The Delayms function will delay a specified number of milliseconds. Used for SPI timing.

Preconditions

None.

Parameters
Parameters | Description
BYTE milliseconds | Number of ms to delay
Returns

None.

Side Effects

None.

Remarks

Depending on compiler revisions, this function may not delay for the exact time specified. This shouldn't create a significant problem.

APIs > SD-SPI Physical Layer > Internal Members > Delayms Function


CloseSPIM Function

Contents | Index | Home
Previous | Up | Next
CloseSPIM Function
C
void CloseSPIM();
Description

Disables the SPI module.

Preconditions

None.

Returns

None.

Side Effects

None.

Remarks

None.

APIs > SD-SPI Physical Layer > Internal Members > CloseSPIM Function


OpenSPIM Function

Contents | Index | Home
Previous | Up | Next
OpenSPIM Function
C
void OpenSPIM(
    unsigned int sync_mode
);
Description

This is function OpenSPIM.

APIs > SD-SPI Physical Layer > Internal Members > OpenSPIM Function


ReadMediaManual Function

Contents | Index | Home
Previous | Up | Next
ReadMediaManual Function
C
BYTE ReadMediaManual();
Description

The MDD_SDSPI_ReadMedia function will read one byte from the SPI port.

Preconditions

None.

Returns

The byte read.

Side Effects

None.

Remarks

This function replaces ReadSPI, since some implementations of that function will initialize SSPBUF/SPIBUF to 0x00 when reading. The card expects 0xFF. This function is for use on a PIC18 when the clock speed is so high that the maximum SPI clock prescaler cannot reduce the SPI clock below the maximum SD card initialization speed.

APIs > SD-SPI Physical Layer > Internal Members > ReadMediaManual Function


SendMMCCmd Function

Contents | Index | Home
Previous | Up | Next
SendMMCCmd Function
C
MMC_RESPONSE SendMMCCmd(
    BYTE cmd,
    DWORD address
);
Description

SendMMCCmd prepares a command packet and sends it out over the SPI interface. Response data of type 'R1' (as indicated by the SD/MMC product manual is returned.

Preconditions

None.

Return Values
Return Values
Description
MMC_RESPONSE
The response from the card

  • Bit 0 - Idle state
  • Bit 1 - Erase Reset
  • Bit 2 - Illegal Command
  • Bit 3 - Command CRC Error
  • Bit 4 - Erase Sequence Error
  • Bit 5 - Address Error
  • Bit 6 - Parameter Error
  • Bit 7 - Unused. Always 0.

Side Effects

None.

Remarks

None.

APIs > SD-SPI Physical Layer > Internal Members > SendMMCCmd Function


SendMMCCmdManual Function

Contents | Index | Home
Previous | Up | Next
SendMMCCmdManual Function
C
MMC_RESPONSE SendMMCCmdManual(
    BYTE cmd,
    DWORD address
);
Description

SendMMCCmd prepares a command packet and sends it out over the SPI interface. Response data of type 'R1' (as indicated by the SD/MMC product manual is returned. This function is intended to be used when the clock speed of a PIC18 device is so high that the maximum SPI divider can't reduce the clock below the maximum SD card initialization sequence speed.

Preconditions

None.

Return Values
Return Values
Description
Assuming an "R1" type of response, each bit will be set depending upon status
MMC_RESPONSE - The response from the card

  • Bit 0 - Idle state
  • Bit 1 - Erase Reset
  • Bit 2 - Illegal Command
  • Bit 3 - Command CRC Error
  • Bit 4 - Erase Sequence Error
  • Bit 5 - Address Error
  • Bit 6 - Parameter Error
  • Bit 7 - Unused. Always 0.

Other response types (ex
R3/R7) have up to 5 bytes of response. The first byte is always the same as the R1 response. The contents of the other bytes depends on the command.
Side Effects

None.

Remarks

None.

APIs > SD-SPI Physical Layer > Internal Members > SendMMCCmdManual Function


WriteSPIM Function

Contents | Index | Home
Previous | Up | Next
WriteSPIM Function
C
unsigned char WriteSPIM(
    unsigned char data_out
);
Description

The WriteSPIM function will write a byte of data from the microcontroller to the SD card.

Preconditions

None.

Parameters
Parameters | Description
data_out | The data to write.
Returns

0.

Side Effects

None.

Remarks

None.

APIs > SD-SPI Physical Layer > Internal Members > WriteSPIM Function


WriteSPIManual Function

Contents | Index | Home
Previous | Up | Next
WriteSPIManual Function
C
unsigned char WriteSPIManual(
    unsigned char data_out
);
Description

Writes a character to the SD card.

Preconditions

Make sure the SDI pin is pre-configured as a digital pin, if it is multiplexed with analog functionality.

Parameters
Parameters | Description
data_out | Data to send.
Returns

0.

Side Effects

None.

Remarks

The WriteSPIManual function is for use on a PIC18 when the clock speed is so high that the maximum SPI clock divider cannot reduce the SPI clock speed below the maximum SD card initialization speed.

APIs > SD-SPI Physical Layer > Internal Members > WriteSPIManual Function


MANUAL_SPI_CLOCK_VALUE Macro

Contents | Index | Home
Previous | Up | Next
MANUAL_SPI_CLOCK_VALUE Macro
C
#define MANUAL_SPI_CLOCK_VALUE 1
Description

Delay value for the manual SPI clock

APIs > SD-SPI Physical Layer > Internal Members > MANUAL_SPI_CLOCK_VALUE Macro


sdmmc_cmdtable Variable

Contents | Index | Home
Previous | Up | Next
sdmmc_cmdtable Variable
C
const rom typMMC_CMD sdmmc_cmdtable[] = const typMMC_CMD sdmmc_cmdtable[] = { {cmdGO_IDLE_STATE, 0x95, R1, NODATA}, {cmdSEND_OP_COND, 0xF9, R1, NODATA}, {cmdSEND_IF_COND, 0x87, R7, NODATA}, {cmdSEND_CSD, 0xAF, R1, MOREDATA}, {cmdSEND_CID, 0x1B, R1, MOREDATA}, {cmdSTOP_TRANSMISSION, 0xC3, R1b, NODATA}, {cmdSEND_STATUS, 0xAF, R2, NODATA}, {cmdSET_BLOCKLEN, 0xFF, R1, NODATA}, {cmdREAD_SINGLE_BLOCK, 0xFF, R1, MOREDATA}, {cmdREAD_MULTI_BLOCK, 0xFF, R1, MOREDATA}, {cmdWRITE_SINGLE_BLOCK, 0xFF, R1, MOREDATA}, {cmdWRITE_MULTI_BLOCK, 0xFF, R1, MOREDATA}, {cmdTAG_SECTOR_START, 0xFF, R1, NODATA}, {cmdTAG_SECTOR_END, 0xFF, R1, NODATA}, {cmdERASE, 0xDF, R1b, NODATA}, {cmdAPP_CMD, 0x73, R1, NODATA}, {cmdREAD_OCR, 0x25, R7, NODATA}, {cmdCRC_ON_OFF, 0x25, R1, NODATA}, {cmdSD_SEND_OP_COND, 0xFF, R7, NODATA}, {cmdSET_WR_BLK_ERASE_COUNT, 0xFF, R1, NODATA} };
Description

The sdmmc_cmdtable contains an array of SD card commands, the corresponding CRC code, the response type that the card will return, and a parameter indicating whether to expect additional data from the card.

APIs > SD-SPI Physical Layer > Internal Members > sdmmc_cmdtable Variable


MDD_SDSPI_finalLBA Variable

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_finalLBA Variable
C
DWORD MDD_SDSPI_finalLBA;
Description

Used for the mass-storage library to determine capacity

APIs > SD-SPI Physical Layer > Internal Members > MDD_SDSPI_finalLBA Variable


CF Physical Layer

Contents | Index | Home
Previous | Up | Next
CF Physical Layer

The CF physical layers offer two methods for interfacing with CF cards. The manual interface method will bit-bang the parallel interface protocol used by CF cards. The CF-PMP files will interface to the cards using the parallel master port on 16-bit PIC devices. At this time, 8-bit architecture PMP interface is not supported.

Topics
Name | Description
Public Members | The following functions, variables, structures, and macros are available for use by the user application.
Library Members | The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.
APIs > CF Physical Layer


Public Members

Contents | Index | Home
Previous | Up | Next
Public Members

The following functions, variables, structures, and macros are available for use by the user application.

Functions
Name | Description
MDD_CFBT_MediaDetect | Determines if a card is inserted
MDD_CFPMP_MediaDetect | Determines if a card is inserted
Macros
Name | Description
MDD_CFBT_DATABIN | The Manual CF data bus port register
MDD_CFBT_DATABOUT | The Manual CF data bus output latch register
MDD_CFBT_DATADIR | The Manual CF data bus TRIS register
MDD_CFPMP_DATADIR | Defines the PMP data bus direction register
MDD_CFread | Function pointer to the CompactFlash Read Physical Layer function
MDD_CFwait | Function pointer to the CompactFlash Wait Physical Layer function
MDD_CFwrite | Function pointer to the CompactFlash Write Physical Layer function
ADDBL | The CF address bus output latch register (for PIC18)
ADDDIR | The CF address bus TRIS register (for PIC18)
ADDR0 | The CF address bus bit 0 output latch definition (for PIC24/30/33/32)
ADDR1 | The CF address bus bit 1 output latch definition (for PIC24/30/33/32)
ADDR2 | The CF address bus bit 2 output latch definition (for PIC24/30/33/32)
ADDR3 | The CF address bus bit 3 output latch definition (for PIC24/30/33/32)
ADRTRIS0 | The CF address bus bit 0 TRIS definition (for PIC24/30/33/32)
ADRTRIS1 | The CF address bus bit 1 TRIS definition (for PIC24/30/33/32)
ADRTRIS2 | The CF address bus bit 2 TRIS definition (for PIC24/30/33/32)
ADRTRIS3 | The CF address bus bit 3 TRIS definition (for PIC24/30/33/32)
CF_BT_CD1 | The CF card detect signal port bit
CF_BT_CD1DIR | The CF card detect signal TRIS bit
CF_BT_RDY | The CF card ready signal port bit
CF_BT_READYDIR | The CF card ready signal TRIS bit
CF_BT_RESETDIR | The CF card reset signal TRIS bit
CF_BT_RST | The CF card reset signal latch bit
CF_CE | The CF card chip select output latch bit
CF_CEDIR | The CF card chip select TRIS bit
CF_OE | The CF card output enable strobe latch bit
CF_OEDIR | The CF card output enable strobe TRIS bit
CF_PMP_CD1 | The input port for the CF card detect signal
CF_PMP_CD1DIR | The TRIS bit for the CF card detect signal
CF_PMP_RDY | The input port for the CF Ready signal
CF_PMP_READYDIR | The TRIS bit for the CF Ready signal
CF_PMP_RESETDIR | The TRIS bit for the CF Reset signal
CF_PMP_RST | The output latch for the CF Reset signal
CF_WE | The CF card write enable strobe latch bit
CF_WEDIR | The CF card write enable strobe TRIS bit
APIs > CF Physical Layer > Public Members


MDD_CFBT_DATABIN Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_DATABIN Macro
C
#define MDD_CFBT_DATABIN PORTE
Description

The Manual CF data bus port register

APIs > CF Physical Layer > Public Members > MDD_CFBT_DATABIN Macro


MDD_CFBT_DATABOUT Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_DATABOUT Macro
C
#define MDD_CFBT_DATABOUT PORTE
Description

The Manual CF data bus output latch register

APIs > CF Physical Layer > Public Members > MDD_CFBT_DATABOUT Macro


MDD_CFBT_DATADIR Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_DATADIR Macro
C
#define MDD_CFBT_DATADIR TRISE
Description

The Manual CF data bus TRIS register

APIs > CF Physical Layer > Public Members > MDD_CFBT_DATADIR Macro


MDD_CFBT_MediaDetect Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_MediaDetect Function
C
BYTE MDD_CFBT_MediaDetect();
Description

Determines if a card is inserted

Preconditions

None

Returns

TRUE - Card present FALSE - Card absent

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Public Members > MDD_CFBT_MediaDetect Function


MDD_CFPMP_DATADIR Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_DATADIR Macro
C
#define MDD_CFPMP_DATADIR TRISE
Description

Defines the PMP data bus direction register

APIs > CF Physical Layer > Public Members > MDD_CFPMP_DATADIR Macro


MDD_CFPMP_MediaDetect Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_MediaDetect Function
C
BYTE MDD_CFPMP_MediaDetect();
Description

Determines if a card is inserted

Preconditions

None

Returns

TRUE - Card present FALSE - Card absent

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Public Members > MDD_CFPMP_MediaDetect Function


MDD_CFread Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFread Macro
C
#define MDD_CFread MDD_CFBT_CFread
Description

Function pointer to the CompactFlash Read Physical Layer function

APIs > CF Physical Layer > Public Members > MDD_CFread Macro


MDD_CFwait Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFwait Macro
C
#define MDD_CFwait MDD_CFBT_CFwait
Description

Function pointer to the CompactFlash Wait Physical Layer function

APIs > CF Physical Layer > Public Members > MDD_CFwait Macro


MDD_CFwrite Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFwrite Macro
C
#define MDD_CFwrite MDD_CFBT_CFwrite
Description

Function pointer to the CompactFlash Write Physical Layer function

APIs > CF Physical Layer > Public Members > MDD_CFwrite Macro


ADDBL Macro

Contents | Index | Home
Previous | Up | Next
ADDBL Macro
C
#define ADDBL LATA
Description

The CF address bus output latch register (for PIC18)

APIs > CF Physical Layer > Public Members > ADDBL Macro


ADDDIR Macro

Contents | Index | Home
Previous | Up | Next
ADDDIR Macro
C
#define ADDDIR TRISA
Description

The CF address bus TRIS register (for PIC18)

APIs > CF Physical Layer > Public Members > ADDDIR Macro


ADDR0 Macro

Contents | Index | Home
Previous | Up | Next
ADDR0 Macro
C
#define ADDR0 LATBbits.LATB15
Description

The CF address bus bit 0 output latch definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADDR0 Macro


ADDR1 Macro

Contents | Index | Home
Previous | Up | Next
ADDR1 Macro
C
#define ADDR1 LATBbits.LATB14
Description

The CF address bus bit 1 output latch definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADDR1 Macro


ADDR2 Macro

Contents | Index | Home
Previous | Up | Next
ADDR2 Macro
C
#define ADDR2 LATGbits.LATG9
Description

The CF address bus bit 2 output latch definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADDR2 Macro


ADDR3 Macro

Contents | Index | Home
Previous | Up | Next
ADDR3 Macro
C
#define ADDR3 LATGbits.LATG8
Description

The CF address bus bit 3 output latch definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADDR3 Macro


ADRTRIS0 Macro

Contents | Index | Home
Previous | Up | Next
ADRTRIS0 Macro
C
#define ADRTRIS0 TRISBbits.TRISB15
Description

The CF address bus bit 0 TRIS definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADRTRIS0 Macro


ADRTRIS1 Macro

Contents | Index | Home
Previous | Up | Next
ADRTRIS1 Macro
C
#define ADRTRIS1 TRISBbits.TRISB14
Description

The CF address bus bit 1 TRIS definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADRTRIS1 Macro


ADRTRIS2 Macro

Contents | Index | Home
Previous | Up | Next
ADRTRIS2 Macro
C
#define ADRTRIS2 TRISGbits.TRISG9
Description

The CF address bus bit 2 TRIS definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADRTRIS2 Macro


ADRTRIS3 Macro

Contents | Index | Home
Previous | Up | Next
ADRTRIS3 Macro
C
#define ADRTRIS3 TRISGbits.TRISG8
Description

The CF address bus bit 3 TRIS definition (for PIC24/30/33/32)

APIs > CF Physical Layer > Public Members > ADRTRIS3 Macro


CF_BT_CD1 Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_CD1 Macro
C
#define CF_BT_CD1 PORTCbits.RC4
Description

The CF card detect signal port bit

APIs > CF Physical Layer > Public Members > CF_BT_CD1 Macro


CF_BT_CD1DIR Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_CD1DIR Macro
C
#define CF_BT_CD1DIR TRISCbits.TRISC4
Description

The CF card detect signal TRIS bit

APIs > CF Physical Layer > Public Members > CF_BT_CD1DIR Macro


CF_BT_RDY Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_RDY Macro
C
#define CF_BT_RDY PORTDbits.RD12
Description

The CF card ready signal port bit

APIs > CF Physical Layer > Public Members > CF_BT_RDY Macro


CF_BT_READYDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_READYDIR Macro
C
#define CF_BT_READYDIR TRISDbits.TRISD12
Description

The CF card ready signal TRIS bit

APIs > CF Physical Layer > Public Members > CF_BT_READYDIR Macro


CF_BT_RESETDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_RESETDIR Macro
C
#define CF_BT_RESETDIR TRISDbits.TRISD0
Description

The CF card reset signal TRIS bit

APIs > CF Physical Layer > Public Members > CF_BT_RESETDIR Macro


CF_BT_RST Macro

Contents | Index | Home
Previous | Up | Next
CF_BT_RST Macro
C
#define CF_BT_RST PORTDbits.RD0
Description

The CF card reset signal latch bit

APIs > CF Physical Layer > Public Members > CF_BT_RST Macro


CF_CE Macro

Contents | Index | Home
Previous | Up | Next
CF_CE Macro
C
#define CF_CE PORTDbits.RD11
Description

The CF card chip select output latch bit

APIs > CF Physical Layer > Public Members > CF_CE Macro


CF_CEDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_CEDIR Macro
C
#define CF_CEDIR TRISDbits.TRISD11
Description

The CF card chip select TRIS bit

APIs > CF Physical Layer > Public Members > CF_CEDIR Macro


CF_OE Macro

Contents | Index | Home
Previous | Up | Next
CF_OE Macro
C
#define CF_OE PORTDbits.RD5
Description

The CF card output enable strobe latch bit

APIs > CF Physical Layer > Public Members > CF_OE Macro


CF_OEDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_OEDIR Macro
C
#define CF_OEDIR TRISDbits.TRISD5
Description

The CF card output enable strobe TRIS bit

APIs > CF Physical Layer > Public Members > CF_OEDIR Macro


CF_PMP_CD1 Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_CD1 Macro
C
#define CF_PMP_CD1 PORTCbits.RC4
Description

The input port for the CF card detect signal

APIs > CF Physical Layer > Public Members > CF_PMP_CD1 Macro


CF_PMP_CD1DIR Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_CD1DIR Macro
C
#define CF_PMP_CD1DIR TRISCbits.TRISC4
Description

The TRIS bit for the CF card detect signal

APIs > CF Physical Layer > Public Members > CF_PMP_CD1DIR Macro


CF_PMP_RDY Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_RDY Macro
C
#define CF_PMP_RDY PORTDbits.RD12
Description

The input port for the CF Ready signal

APIs > CF Physical Layer > Public Members > CF_PMP_RDY Macro


CF_PMP_READYDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_READYDIR Macro
C
#define CF_PMP_READYDIR TRISDbits.TRISD12
Description

The TRIS bit for the CF Ready signal

APIs > CF Physical Layer > Public Members > CF_PMP_READYDIR Macro


CF_PMP_RESETDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_RESETDIR Macro
C
#define CF_PMP_RESETDIR TRISDbits.TRISD0
Description

The TRIS bit for the CF Reset signal

APIs > CF Physical Layer > Public Members > CF_PMP_RESETDIR Macro


CF_PMP_RST Macro

Contents | Index | Home
Previous | Up | Next
CF_PMP_RST Macro
C
#define CF_PMP_RST LATDbits.LATD0
Description

The output latch for the CF Reset signal

APIs > CF Physical Layer > Public Members > CF_PMP_RST Macro


CF_WE Macro

Contents | Index | Home
Previous | Up | Next
CF_WE Macro
C
#define CF_WE PORTDbits.RD4
Description

The CF card write enable strobe latch bit

APIs > CF Physical Layer > Public Members > CF_WE Macro


CF_WEDIR Macro

Contents | Index | Home
Previous | Up | Next
CF_WEDIR Macro
C
#define CF_WEDIR TRISDbits.TRISD4
Description

The CF card write enable strobe TRIS bit

APIs > CF Physical Layer > Public Members > CF_WEDIR Macro


Library Members

Contents | Index | Home
Previous | Up | Next
Library Members

The following functions, variables, structures, and macros are public, but are intended only to be accessed by the library itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
MDD_CFBT_CFread | Reads a byte from the CF card
MDD_CFBT_CFwait | Wait until the card is ready
MDD_CFBT_CFwrite | Writes a byte to the CF card
MDD_CFBT_InitIO | None
MDD_CFBT_MediaInitialize | Return a MEDIA_INFORMATION structure to FSIO.c
MDD_CFBT_SectorRead | SectorRead reads 512 bytes of data from the card starting at the sector address specified by sector_addr and stores them in the location pointed to by 'buffer'.
MDD_CFBT_SectorWrite | SectorWrite sends 512 bytes of data from the location pointed to by 'buffer' to the card starting at the sector address specified by sector_addr.
MDD_CFBT_WriteProtectState | Added for compatibility- no write protect feature
MDD_CFPMP_CFread | Reads a byte from the CF card
MDD_CFPMP_CFwait | Wait until the card and PMP are ready
MDD_CFPMP_CFwrite | Writes a byte to the CF card
MDD_CFPMP_InitIO | None
MDD_CFPMP_MediaInitialize | Return a MEDIA_INFORMATION structure to FSIO.c
MDD_CFPMP_SectorRead | SectorRead reads 512 bytes of data from the card starting at the sector address specified by sector_addr and stores them in the location pointed to by 'buffer'.
MDD_CFPMP_SectorWrite | SectorWrite sends 512 bytes of data from the location pointed to by 'buffer' to the card starting at the sector address specified by sector_addr.
MDD_CFPMP_WriteProtectState | Added for compatibility- no write protect feature
Macros
Name | Description
MDD_CFBT_DATABinput | A macro to set the CF data bus TRIS register to inputs
MDD_CFBT_DATABoutput | A macro to set the CF data bus TRIS register to outputs
MDD_CFPMP_DATABinput | A macro to set the CF data bus TRIS register to inputs
MDD_CFPMP_DATABoutput | A macro to set the CF data bus TRIS register to outputs
R_CMD | A macro for the command register offset for CF cards
R_COUNT | A macro for the count register offset for CF cards
R_CYHI | A macro for the cylinder-high register offset for CF cards
R_CYLO | A macro for the cylinder-low register offset for CF cards
R_DATA | A macro for the data register offset for CF cards
R_DRIVE | A macro for the drive register offset for CF cards
R_ERROR | A macro for the error register offset for CF cards
R_SECT | A macro for the sector register offset for CF cards
R_STATUS | A macro for the status offset for CF cards
C_DRIVE_DIAG | A macro for the CF drive diagnostic command
C_DRIVE_IDENT | A macro for the CF drive identify command
C_SECTOR_READ | A macro for the CF read comment
C_SECTOR_WRITE | A macro for the CF write command
S_ERROR | A macro indicating that the CF status register reports an error condition
S_READY | A macro indicating that the CF status register reports a ready condition
APIs > CF Physical Layer > Library Members


MDD_CFBT_CFread Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_CFread Function
C
BYTE MDD_CFBT_CFread(
    BYTE add
);
Description

Reads a byte from the CF card

Preconditions

None

Parameters
Parameters | Description
BYTE add | address to read from
Returns

BYTE - the byte read

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_CFread Function


MDD_CFBT_CFwait Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_CFwait Function
C
void MDD_CFBT_CFwait();
Description

Wait until the card is ready

Preconditions

None

Returns

None

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_CFwait Function


MDD_CFBT_CFwrite Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_CFwrite Function
C
void MDD_CFBT_CFwrite(
    BYTE add,
    BYTE d
);
Description

Writes a byte to the CF card

Preconditions

None

Parameters
Parameters | Description
BYTE add | the address to write to
BYTE d | the byte to write
Returns

None

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_CFwrite Function


MDD_CFBT_DATABinput Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_DATABinput Macro
C
#define MDD_CFBT_DATABinput MDD_CFBT_DATADIR = 0xff;
Description

A macro to set the CF data bus TRIS register to inputs

APIs > CF Physical Layer > Library Members > MDD_CFBT_DATABinput Macro


MDD_CFBT_DATABoutput Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_DATABoutput Macro
C
#define MDD_CFBT_DATABoutput MDD_CFBT_DATADIR = 0;
Description

A macro to set the CF data bus TRIS register to outputs

APIs > CF Physical Layer > Library Members > MDD_CFBT_DATABoutput Macro


MDD_CFBT_InitIO Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_InitIO Function
C
void MDD_CFBT_InitIO();
Description

None

Preconditions

None

Returns

void

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_InitIO Function


MDD_CFBT_MediaInitialize Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_MediaInitialize Function
C
MEDIA_INFORMATION * MDD_CFBT_MediaInitialize();
Description

Return a MEDIA_INFORMATION structure to FSIO.c

Preconditions

None

Returns

MEDIA_NO_ERROR - The media initialized successfully

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_MediaInitialize Function


MDD_CFBT_SectorRead Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_SectorRead Function
C
BYTE MDD_CFBT_SectorRead(
    DWORD lda,
    BYTE * buf
);
Description

SectorRead reads 512 bytes of data from the card starting at the sector address specified by sector_addr and stores them in the location pointed to by 'buffer'.

Preconditions

None

Parameters
Parameters | Description
sector_addr | Sector address, each sector contains 512-byte
buffer | Buffer where data will be stored, see 'ram_acs.h' for 'block' definition. 'Block' is dependent on whether internal or external memory is used
Returns

TRUE - Sector read FALSE - Sector could not be read

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_SectorRead Function


MDD_CFBT_SectorWrite Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_SectorWrite Function
C
BYTE MDD_CFBT_SectorWrite(
    DWORD lda,
    BYTE * buf,
    BYTE allowWriteToZero
);
Description

SectorWrite sends 512 bytes of data from the location pointed to by 'buffer' to the card starting at the sector address specified by sector_addr.

Preconditions

None

Parameters
Parameters | Description
sector_addr | Sector address, each sector contains 512 bytes
buffer | Buffer where data will be read from
allowWriteToZero | allows write to the MBR sector
Returns

TRUE - Sector written FALSE - Sector could not be written

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_SectorWrite Function


MDD_CFBT_WriteProtectState Function

Contents | Index | Home
Previous | Up | Next
MDD_CFBT_WriteProtectState Function
C
BYTE MDD_CFBT_WriteProtectState();
Description

Added for compatibility- no write protect feature

Preconditions

None

Returns

0

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFBT_WriteProtectState Function


MDD_CFPMP_CFread Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_CFread Function
C
BYTE MDD_CFPMP_CFread(
    BYTE add
);
Description

Reads a byte from the CF card

Preconditions

None

Parameters
Parameters | Description
BYTE add | address to read from
Returns

BYTE - the byte read

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_CFread Function


MDD_CFPMP_CFwait Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_CFwait Function
C
void MDD_CFPMP_CFwait();
Description

Wait until the card and PMP are ready

Preconditions

None

Returns

None

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_CFwait Function


MDD_CFPMP_CFwrite Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_CFwrite Function
C
void MDD_CFPMP_CFwrite(
    BYTE add,
    BYTE d
);
Description

Writes a byte to the CF card

Preconditions

None

Parameters
Parameters | Description
BYTE add | the address to write to
BYTE d | the byte to write
Returns

None

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_CFwrite Function


MDD_CFPMP_DATABinput Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_DATABinput Macro
C
#define MDD_CFPMP_DATABinput MDD_CFPMP_DATADIR = 0xff;
Description

A macro to set the CF data bus TRIS register to inputs

APIs > CF Physical Layer > Library Members > MDD_CFPMP_DATABinput Macro


MDD_CFPMP_DATABoutput Macro

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_DATABoutput Macro
C
#define MDD_CFPMP_DATABoutput MDD_CFPMP_DATADIR = 0;
Description

A macro to set the CF data bus TRIS register to outputs

APIs > CF Physical Layer > Library Members > MDD_CFPMP_DATABoutput Macro


MDD_CFPMP_MediaInitialize Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_MediaInitialize Function
C
MEDIA_INFORMATION * MDD_CFPMP_MediaInitialize();
Description

Return a MEDIA_INFORMATION structure to FSIO.c

Preconditions

None

Returns

MEDIA_NO_ERROR - The media initialized successfully

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_MediaInitialize Function


MDD_CFPMP_SectorRead Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_SectorRead Function
C
BYTE MDD_CFPMP_SectorRead(
    DWORD lda,
    BYTE * buf
);
Description

SectorRead reads 512 bytes of data from the card starting at the sector address specified by sector_addr and stores them in the location pointed to by 'buffer'.

Preconditions

None

Parameters
Parameters | Description
sector_addr | Sector address, each sector contains 512-byte
buffer | Buffer where data will be stored
Returns

TRUE - Sector read FALSE - Sector could not be read

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_SectorRead Function


MDD_CFPMP_SectorWrite Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_SectorWrite Function
C
BYTE MDD_CFPMP_SectorWrite(
    DWORD lda,
    BYTE * buf,
    BYTE allowWriteToZero
);
Description

SectorWrite sends 512 bytes of data from the location pointed to by 'buffer' to the card starting at the sector address specified by sector_addr.

Preconditions

None

Parameters
Parameters | Description
sector_addr | Sector address, each sector contains 512 bytes
buffer | Buffer where data will be read from
allowWriteToZero | allows write to the MBR sector
Returns

TRUE - Sector written FALSE - Sector could not be written

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_SectorWrite Function


MDD_CFPMP_WriteProtectState Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_WriteProtectState Function
C
BYTE MDD_CFPMP_WriteProtectState();
Description

Added for compatibility- no write protect feature

Preconditions

None

Returns

0

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_WriteProtectState Function


R_CMD Macro

Contents | Index | Home
Previous | Up | Next
R_CMD Macro
C
#define R_CMD 7
Description

A macro for the command register offset for CF cards

APIs > CF Physical Layer > Library Members > R_CMD Macro


R_COUNT Macro

Contents | Index | Home
Previous | Up | Next
R_COUNT Macro
C
#define R_COUNT 2
Description

A macro for the count register offset for CF cards

APIs > CF Physical Layer > Library Members > R_COUNT Macro


R_CYHI Macro

Contents | Index | Home
Previous | Up | Next
R_CYHI Macro
C
#define R_CYHI 5
Description

A macro for the cylinder-high register offset for CF cards

APIs > CF Physical Layer > Library Members > R_CYHI Macro


R_CYLO Macro

Contents | Index | Home
Previous | Up | Next
R_CYLO Macro
C
#define R_CYLO 4
Description

A macro for the cylinder-low register offset for CF cards

APIs > CF Physical Layer > Library Members > R_CYLO Macro


R_DATA Macro

Contents | Index | Home
Previous | Up | Next
R_DATA Macro
C
#define R_DATA 0
Description

A macro for the data register offset for CF cards

APIs > CF Physical Layer > Library Members > R_DATA Macro


R_DRIVE Macro

Contents | Index | Home
Previous | Up | Next
R_DRIVE Macro
C
#define R_DRIVE 6
Description

A macro for the drive register offset for CF cards

APIs > CF Physical Layer > Library Members > R_DRIVE Macro


R_ERROR Macro

Contents | Index | Home
Previous | Up | Next
R_ERROR Macro
C
#define R_ERROR 1
Description

A macro for the error register offset for CF cards

APIs > CF Physical Layer > Library Members > R_ERROR Macro


R_SECT Macro

Contents | Index | Home
Previous | Up | Next
R_SECT Macro
C
#define R_SECT 3
Description

A macro for the sector register offset for CF cards

APIs > CF Physical Layer > Library Members > R_SECT Macro


R_STATUS Macro

Contents | Index | Home
Previous | Up | Next
R_STATUS Macro
C
#define R_STATUS 7
Description

A macro for the status offset for CF cards

APIs > CF Physical Layer > Library Members > R_STATUS Macro


C_DRIVE_DIAG Macro

Contents | Index | Home
Previous | Up | Next
C_DRIVE_DIAG Macro
C
#define C_DRIVE_DIAG 0x90
Description

A macro for the CF drive diagnostic command

APIs > CF Physical Layer > Library Members > C_DRIVE_DIAG Macro


C_DRIVE_IDENT Macro

Contents | Index | Home
Previous | Up | Next
C_DRIVE_IDENT Macro
C
#define C_DRIVE_IDENT 0xEC
Description

A macro for the CF drive identify command

APIs > CF Physical Layer > Library Members > C_DRIVE_IDENT Macro


C_SECTOR_READ Macro

Contents | Index | Home
Previous | Up | Next
C_SECTOR_READ Macro
C
#define C_SECTOR_READ 0x20
Description

A macro for the CF read comment

APIs > CF Physical Layer > Library Members > C_SECTOR_READ Macro


C_SECTOR_WRITE Macro

Contents | Index | Home
Previous | Up | Next
C_SECTOR_WRITE Macro
C
#define C_SECTOR_WRITE 0x30
Description

A macro for the CF write command

APIs > CF Physical Layer > Library Members > C_SECTOR_WRITE Macro


S_ERROR Macro

Contents | Index | Home
Previous | Up | Next
S_ERROR Macro
C
#define S_ERROR 0x51
Description

A macro indicating that the CF status register reports an error condition

APIs > CF Physical Layer > Library Members > S_ERROR Macro


S_READY Macro

Contents | Index | Home
Previous | Up
S_READY Macro
C
#define S_READY 0x58
Description

A macro indicating that the CF status register reports a ready condition

APIs > CF Physical Layer > Library Members > S_READY Macro


Contents

Contents | Index | Home
Contents
Microchip MDD File System Interface Library
SW License Agreement
Release Notes
Getting Started
Terminology
Boot sector
Cluster
Current Working Directory
Directory
FAT
Master Boot Record
Root directory
Sector
LFN
Directory Structure
Configuring Hardware
Explorer 16 with PICtail for SD and MMC
HPC Explorer with PICtail for SD and MMC
Software Configuration
The SD Card Demo
The SD Data Logger Demo
APIs
File Manipulation Layer (FSIO)
Public Members
FindFirst Function
FindFirstpgm Function
wFindFirst Function
FindNext Function
FSfopen Function
FSfopenpgm Function
wFSfopen Function
FSfclose Function
FSremove Function
FSremovepgm Function
wFSremove Function
FSrename Function
FSrenamepgm Function
wFSrename Function
FSmkdir Function
FSmkdirpgm Function
wFSmkdir Function
FSchdir Function
FSchdirpgm Function
wFSchdir Function
FSrmdir Function
FSrmdirpgm Function
wFSrmdir Function
FSgetcwd Function
wFSgetcwd Function
FSattrib Function
FSCreateMBR Function
FSerror Function
FSfeof Function
FSformat Function
FSfprintf Function
FSfread Function
FSfseek Function
FSftell Function
FSfwrite Function
FSInit Function
FSrewind Function
SetClockVars Function
FSfprintf Function
FSGetDiskProperties Function
ALLOW_DIRS Macro
ALLOW_FILESEARCH Macro
ALLOW_WRITES Macro
APPEND Macro
ATTR_ARCHIVE Macro
ATTR_DIRECTORY Macro
ATTR_HIDDEN Macro
ATTR_MASK Macro
ATTR_READ_ONLY Macro
ATTR_SYSTEM Macro
ATTR_VOLUME Macro
EOF Macro
FALSE Macro
FS_DYNAMIC_MEM Macro
SUPPORT_LFN Macro
FS_MAX_FILES_OPEN Macro
MAX_HEAP_SIZE Macro
MDD_MediaDetect Macro
MEDIA_SECTOR_SIZE Macro
NEAR_MODEL Macro
SEEK_CUR Macro
SEEK_END Macro
SEEK_SET Macro
SUPPORT_FAT32 Macro
TRUE Macro
USE_SD_INTERFACE_WITH_SPI Macro
USEREALTIMECLOCK Macro
WRITE Macro
FSFILE Structure
SearchRec Structure
FILE_NAME_SIZE_8P3 Macro
MAX_FILE_NAME_LENGTH_LFN Macro
Library Members
ReadByte Function
ReadDWord Function
ReadWord Function
ATTR_LONG_NAME Macro
BSI_BOOTSIG Macro
BSI_BPS Macro
BSI_FAT32_BOOTSIG Macro
BSI_FAT32_FSTYPE Macro
BSI_FATCOUNT Macro
BSI_FATSZ32 Macro
BSI_FSTYPE Macro
BSI_RESRVSEC Macro
BSI_ROOTCLUS Macro
BSI_ROOTDIRENTS Macro
BSI_SPC Macro
BSI_SPF Macro
BSI_TOTSEC16 Macro
BSI_TOTSEC32 Macro
CE_EOF Macro
CE_FAT_EOF Macro
CLUSTER_EMPTY Macro
CLUSTER_FAIL_FAT16 Macro
CLUSTER_FAIL_FAT32 Macro
DIR_DEL Macro
DIR_EMPTY Macro
DIR_EXTENSION Macro
DIR_NAMECOMP Macro
DIR_NAMESIZE Macro
END_CLUSTER_FAT12 Macro
END_CLUSTER_FAT16 Macro
END_CLUSTER_FAT32 Macro
FAT_GOOD_SIGN_0 Macro
FAT_GOOD_SIGN_1 Macro
FAT12 Macro
FAT16 Macro
FAT32 Macro
FILE_NAME_SIZE Macro
FO_MBR Macro
FOUND Macro
GetInstructionClock Macro
GetPeripheralClock Macro
GetSystemClock Macro
INPUT Macro
LAST_CLUSTER_FAT12 Macro
LAST_CLUSTER_FAT16 Macro
LAST_CLUSTER_FAT32 Macro
MASK_MAX_FILE_ENTRY_LIMIT_BITS Macro
MDD_InitIO Macro
MDD_MediaInitialize Macro
MDD_ReadCapacity Macro
MDD_ReadSectorSize Macro
MDD_SectorRead Macro
MDD_SectorWrite Macro
MDD_ShutdownMedia Macro
MDD_WriteProtectState Macro
NO_MORE Macro
NOT_FOUND Macro
NUMBER_OF_BYTES_IN_DIR_ENTRY Macro
OUTPUT Macro
RAMread Macro
RAMreadD Macro
RAMreadW Macro
RAMwrite Macro
TOTAL_FILE_SIZE Macro
VALUE_BASED_ON_ENTRIES_PER_CLUSTER Macro
VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT Macro
BootSec Type
CETYPE Enumeration
FILEFLAGS Structure
MEDIA_ERRORS Enumeration
MEDIA_INFORMATION Structure
PT_MBR Type
SALLOC Type
SEARCH_TYPE Enumeration
Internal Members
_SRAMmerge Function
Cache_File_Entry Function
CacheTime Function
chdirhelper Function
Cluster2Sector Function
CreateDIR Function
CreateFirstCluster Function
DISKmount Function
EraseCluster Function
FAT_erase_cluster_chain Function
FATfindEmptyCluster Function
FILEallocate_new_cluster Function
FILECreateHeadCluster Function
FILEerase Function
FILEfind Function
FILEget_next_cluster Function
FileObjectCopy Function
FILEopen Function
Fill_File_Object Function
FindEmptyEntries Function
flushData Function
FSputc Function
FSvfprintf Function
GetFullClusterNumber Function
GetPreviousEntry Function
IncrementTimeStamp Function
LoadBootSector Function
LoadDirAttrib Function
LoadMBR Function
mkdirhelper Function
ReadFAT Function
rmdirhelper Function
SRAMInitHeap Function
str_put_n_chars Function
Write_File_Entry Function
writeDotEntries Function
WriteFAT Function
_FLAG_MINUS Macro
_FLAG_OCTO Macro
_FLAG_PLUS Macro
_FLAG_SIGNED Macro
_FLAG_SPACE Macro
_FLAG_ZERO Macro
_FMT_BYTE Macro
_FMT_LONG Macro
_FMT_LONGLONG Macro
_FMT_SHRTLONG Macro
_FMT_UNSPECIFIED Macro
_MAX_HEAP_SIZE Macro
_MAX_SEGMENT_SIZE Macro
DIRECTORY Macro
DIRENTRIES_PER_SECTOR Macro
NEAR Macro
_DIRENTRY Structure
DIRENTRY Type
FILEOBJ Type
_uDynamicHeap Variable
cwd Variable
cwdptr Variable
defaultArray Variable
dirCleared Variable
FatRootDirClusterValue Variable
FSerrno Variable
gBufferOwner Variable
gBufferZeroed Variable
gDataBuffer Variable
gDiskData Variable
gFATBuffer Variable
gFileArray Variable
gFileSlotOpen Variable
gFileTemp Variable
gLastDataSectorRead Variable
gLastFATSectorRead Variable
gNeedDataWrite Variable
gNeedFATWrite Variable
gTimeAccDate Variable
gTimeCrtDate Variable
gTimeCrtMS Variable
gTimeCrtTime Variable
gTimeWrtDate Variable
gTimeWrtTime Variable
nextClusterIsLast Variable
recache Variable
s_digits Variable
tempArray Variable
TempClusterCalc Variable
tempCWDobj Variable
SD-SPI Physical Layer
Public Members
MDD_SDSPI_AsyncReadTasks Function
MDD_SDSPI_AsyncWriteTasks Function
MDD_USE_SPI_1 Macro
MDD_USE_SPI_2
SD_CD Macro
SD_CD_TRIS Macro
SD_CS Macro
SD_CS_TRIS Macro
SD_WE Macro
SD_WE_TRIS Macro
SPI_FREQUENCY Macro
SPI_INTERRUPT_FLAG Macro
SPIBRG Macro
SPIBUF Macro
SPICLOCK Macro
SPICLOCKPORT Macro
SPICLOCKLAT Macro
SPICON1 Macro
SPICON1bits Macro
SPIENABLE Macro
SPIIN Macro
SPIINPORT Macro
SPIINLAT Macro
SPIOUT Macro
SPIOUTPORT Macro
SPIOUTLAT Macro
SPISTAT Macro
SPISTAT_RBF Macro
SPISTATbits Macro
ASYNC_READ_ABORT Macro
ASYNC_READ_BUSY Macro
ASYNC_READ_COMPLETE Macro
ASYNC_READ_ERROR Macro
ASYNC_READ_NEW_PACKET_READY Macro
ASYNC_READ_QUEUED Macro
ASYNC_READ_WAIT_START_TOKEN Macro
ASYNC_STOP_TOKEN_SENT_WAIT_BUSY Macro
ASYNC_WRITE_ABORT Macro
ASYNC_WRITE_BUSY Macro
ASYNC_WRITE_COMPLETE Macro
ASYNC_WRITE_ERROR Macro
ASYNC_WRITE_MEDIA_BUSY Macro
ASYNC_WRITE_QUEUED Macro
ASYNC_WRITE_SEND_PACKET Macro
ASYNC_WRITE_TRANSMIT_PACKET Macro
cmdSD_SEND_OP_COND Macro
cmdSEND_IF_COND Macro
cmdSET_WR_BLK_ERASE_COUNT Macro
DATA_START_MULTI_BLOCK_TOKEN Macro
DATA_STOP_TRAN_TOKEN Macro
Library Members
MDD_SDSPI_InitIO Function
MDD_SDSPI_MediaDetect Function
MDD_SDSPI_MediaInitialize Function
MDD_SDSPI_ReadCapacity Function
MDD_SDSPI_ReadMedia Function
MDD_SDSPI_ReadSectorSize Function
MDD_SDSPI_SectorWrite Function
MDD_SDSPI_SectorRead Function
MDD_SDSPI_ShutdownMedia Function
cmdAPP_CMD Macro
cmdCRC_ON_OFF Macro
cmdERASE Macro
cmdGO_IDLE_STATE Macro
cmdREAD_MULTI_BLOCK Macro
cmdREAD_OCR Macro
cmdREAD_SINGLE_BLOCK Macro
cmdSEND_CID Macro
cmdSEND_CSD Macro
cmdSEND_OP_COND Macro
cmdSEND_STATUS Macro
cmdSET_BLOCKLEN Macro
cmdSTOP_TRANSMISSION Macro
cmdTAG_SECTOR_END Macro
cmdTAG_SECTOR_START Macro
cmdWRITE_MULTI_BLOCK Macro
cmdWRITE_SINGLE_BLOCK Macro
DATA_ACCEPTED Macro
DATA_START_TOKEN Macro
DELAY_OVERHEAD Macro
DELAY_PRESCALER Macro
MASTER_ENABLE_ON Macro
MILLISECDELAY Macro
MMC_BAD_RESPONSE Macro
MMC_FLOATING_BUS Macro
MOREDATA Macro
mReadCRC Macro
mSend8ClkCycles Macro
mSendCRC Macro
NODATA Macro
PRI_PRESCAL_1_1 Macro
SEC_PRESCAL_1_1 Macro
SYNC_MODE_FAST Macro
SYNC_MODE_MED Macro
SYNC_MODE_SLOW Macro
CID Union
CMD_PACKET Union
CSD Union
RESPONSE_1 Union
RESPONSE_2 Union
MMC_RESPONSE Union
RESP Enumeration
sdmmc_cmd Enumeration
typMMC_CMD Structure
mediaInformation Variable
ASYNC_IO Type
Internal Members
Delayms Function
CloseSPIM Function
OpenSPIM Function
ReadMediaManual Function
SendMMCCmd Function
SendMMCCmdManual Function
WriteSPIM Function
WriteSPIManual Function
MANUAL_SPI_CLOCK_VALUE Macro
sdmmc_cmdtable Variable
MDD_SDSPI_finalLBA Variable
CF Physical Layer
Public Members
MDD_CFBT_DATABIN Macro
MDD_CFBT_DATABOUT Macro
MDD_CFBT_DATADIR Macro
MDD_CFBT_MediaDetect Function
MDD_CFPMP_DATADIR Macro
MDD_CFPMP_MediaDetect Function
MDD_CFread Macro
MDD_CFwait Macro
MDD_CFwrite Macro
ADDBL Macro
ADDDIR Macro
ADDR0 Macro
ADDR1 Macro
ADDR2 Macro
ADDR3 Macro
ADRTRIS0 Macro
ADRTRIS1 Macro
ADRTRIS2 Macro
ADRTRIS3 Macro
CF_BT_CD1 Macro
CF_BT_CD1DIR Macro
CF_BT_RDY Macro
CF_BT_READYDIR Macro
CF_BT_RESETDIR Macro
CF_BT_RST Macro
CF_CE Macro
CF_CEDIR Macro
CF_OE Macro
CF_OEDIR Macro
CF_PMP_CD1 Macro
CF_PMP_CD1DIR Macro
CF_PMP_RDY Macro
CF_PMP_READYDIR Macro
CF_PMP_RESETDIR Macro
CF_PMP_RST Macro
CF_WE Macro
CF_WEDIR Macro
Library Members
MDD_CFBT_CFread Function
MDD_CFBT_CFwait Function
MDD_CFBT_CFwrite Function
MDD_CFBT_DATABinput Macro
MDD_CFBT_DATABoutput Macro
MDD_CFBT_InitIO Function
MDD_CFBT_MediaInitialize Function
MDD_CFBT_SectorRead Function
MDD_CFBT_SectorWrite Function
MDD_CFBT_WriteProtectState Function
MDD_CFPMP_CFread Function
MDD_CFPMP_CFwait Function
MDD_CFPMP_CFwrite Function
MDD_CFPMP_DATABinput Macro
MDD_CFPMP_DATABoutput Macro
MDD_CFPMP_MediaInitialize Function
MDD_CFPMP_SectorRead Function
MDD_CFPMP_SectorWrite Function
MDD_CFPMP_WriteProtectState Function
R_CMD Macro
R_COUNT Macro
R_CYHI Macro
R_CYLO Macro
R_DATA Macro
R_DRIVE Macro
R_ERROR Macro
R_SECT Macro
R_STATUS Macro
C_DRIVE_DIAG Macro
C_DRIVE_IDENT Macro
C_SECTOR_READ Macro
C_SECTOR_WRITE Macro
S_ERROR Macro
S_READY Macro


eraseDir Function

Contents | Index | Home
Previous | Up | Next
eraseDir Function
C
int eraseDir(
    char * path
);
Description

The eraseDir function is a helper function for the rmdirhelper function. The eraseDir function will search for the directory that matches the specified path name and then erase it with the FILEerase function.

Preconditions

This function should not be called by the user.

Parameters
Parameters | Description
path | The name of the directory to delete
Return Values
Return Values | Description
0 | Dir was deleted successfully
-1 | Dir could not be deleted.
Side Effects

None

Remarks

None.

APIs > File Manipulation Layer (FSIO) > Internal Members > eraseDir Function


Index

Contents | Index | Home
Index
_ | A | B | C | D | E | F | G | H | I | L | M | N | O | P | R | S | T | U | V | W
_
_CETYPE enumeration
_DIRENTRY structure
_FLAG_MINUS macro
_FLAG_OCTO macro
_FLAG_PLUS macro
_FLAG_SIGNED macro
_FLAG_SPACE macro
_FLAG_ZERO macro
_FMT_BYTE macro
_FMT_LONG macro
_FMT_LONGLONG macro
_FMT_SHRTLONG macro
_FMT_UNSPECIFIED macro
_MAX_HEAP_SIZE macro
_MAX_SEGMENT_SIZE macro
_SRAMmerge function
_uDynamicHeap variable
A
ADDBL macro
ADDDIR macro
ADDR0 macro
ADDR1 macro
ADDR2 macro
ADDR3 macro
ADRTRIS0 macro
ADRTRIS1 macro
ADRTRIS2 macro
ADRTRIS3 macro
ALLOW_DIRS macro
ALLOW_FILESEARCH macro
ALLOW_WRITES macro
APIs
APPEND macro
ASYNC_IO type
ASYNC_READ_ABORT macro
ASYNC_READ_BUSY macro
ASYNC_READ_COMPLETE macro
ASYNC_READ_ERROR macro
ASYNC_READ_NEW_PACKET_READY macro
ASYNC_READ_QUEUED macro
ASYNC_READ_WAIT_START_TOKEN macro
ASYNC_STOP_TOKEN_SENT_WAIT_BUSY macro
ASYNC_WRITE_ABORT macro
ASYNC_WRITE_BUSY macro
ASYNC_WRITE_COMPLETE macro
ASYNC_WRITE_ERROR macro
ASYNC_WRITE_MEDIA_BUSY macro
ASYNC_WRITE_QUEUED macro
ASYNC_WRITE_SEND_PACKET macro
ASYNC_WRITE_TRANSMIT_PACKET macro
ATTR_ARCHIVE macro
ATTR_DIRECTORY macro
ATTR_HIDDEN macro
ATTR_LONG_NAME macro
ATTR_MASK macro
ATTR_READ_ONLY macro
ATTR_SYSTEM macro
ATTR_VOLUME macro
B
Boot sector
BootSec type
BSI_BOOTSIG macro
BSI_BPS macro
BSI_FAT32_BOOTSIG macro
BSI_FAT32_FSTYPE macro
BSI_FATCOUNT macro
BSI_FATSZ32 macro
BSI_FSTYPE macro
BSI_RESRVSEC macro
BSI_ROOTCLUS macro
BSI_ROOTDIRENTS macro
BSI_SPC macro
BSI_SPF macro
BSI_TOTSEC16 macro
BSI_TOTSEC32 macro
C
C_DRIVE_DIAG macro
C_DRIVE_IDENT macro
C_SECTOR_READ macro
C_SECTOR_WRITE macro
Cache_File_Entry function
CacheTime function
CE_BAD_FILE enumeration member
CE_BAD_PARTITION enumeration member
CE_BAD_SECTOR_READ enumeration member
CE_BADCACHEREAD enumeration member
CE_CARDFAT32 enumeration member
CE_COULD_NOT_GET_CLUSTER enumeration member
CE_DELETE_DIR enumeration member
CE_DIR_FULL enumeration member
CE_DIR_NOT_EMPTY enumeration member
CE_DIR_NOT_FOUND enumeration member
CE_DISK_FULL enumeration member
CE_DONE enumeration member
CE_EOF macro
CE_ERASE_FAIL enumeration member
CE_FAT_EOF macro
CE_FILE_NOT_FOUND enumeration member
CE_FILENAME_2_LONG enumeration member
CE_FILENAME_EXISTS enumeration member
CE_FILENOTOPENED enumeration member
CE_GOOD enumeration member
CE_INIT_ERROR enumeration member
CE_INVALID_ARGUMENT enumeration member
CE_INVALID_CLUSTER enumeration member
CE_INVALID_FILENAME enumeration member
CE_NONSUPPORTED_SIZE enumeration member
CE_NOT_FORMATTED enumeration member
CE_NOT_INIT enumeration member
CE_NOT_PRESENT enumeration member
CE_READONLY enumeration member
CE_SEEK_ERROR enumeration member
CE_TOO_MANY_FILES_OPEN enumeration member
CE_UNSUPPORTED_FS enumeration member
CE_UNSUPPORTED_SECTOR_SIZE enumeration member
CE_WRITE_ERROR enumeration member
CE_WRITE_PROTECTED enumeration member
CE_WRITEONLY enumeration member
CETYPE enumeration
CF Physical Layer
CF_BT_CD1 macro
CF_BT_CD1DIR macro
CF_BT_RDY macro
CF_BT_READYDIR macro
CF_BT_RESETDIR macro
CF_BT_RST macro
CF_CE macro
CF_CEDIR macro
CF_OE macro
CF_OEDIR macro
CF_PMP_CD1 macro
CF_PMP_CD1DIR macro
CF_PMP_RDY macro
CF_PMP_READYDIR macro
CF_PMP_RESETDIR macro
CF_PMP_RST macro
CF_WE macro
CF_WEDIR macro
chdirhelper function
CID union
CloseSPIM function
Cluster
CLUSTER_EMPTY macro
CLUSTER_FAIL_FAT16 macro
CLUSTER_FAIL_FAT32 macro
Cluster2Sector function
CMD_PACKET union
cmdAPP_CMD macro
cmdCRC_ON_OFF macro
cmdERASE macro
cmdGO_IDLE_STATE macro
cmdREAD_MULTI_BLOCK macro
cmdREAD_OCR macro
cmdREAD_SINGLE_BLOCK macro
cmdSD_SEND_OP_COND macro
cmdSEND_CID macro
cmdSEND_CSD macro
cmdSEND_IF_COND macro
cmdSEND_OP_COND macro
cmdSEND_STATUS macro
cmdSET_BLOCKLEN macro
cmdSET_WR_BLK_ERASE_COUNT macro
cmdSTOP_TRANSMISSION macro
cmdTAG_SECTOR_END macro
cmdTAG_SECTOR_START macro
cmdWRITE_MULTI_BLOCK macro
cmdWRITE_SINGLE_BLOCK macro
Configuring Hardware
CreateDIR function
CreateFirstCluster function
CSD union
Current Working Directory
cwd variable
cwdptr variable
D
DATA_ACCEPTED macro
DATA_START_MULTI_BLOCK_TOKEN macro
DATA_START_TOKEN macro
DATA_STOP_TRAN_TOKEN macro
defaultArray variable
DELAY_OVERHEAD macro
DELAY_PRESCALER macro
Delayms function
DIR_DEL macro
DIR_EMPTY macro
DIR_EXTENSION macro
DIR_NAMECOMP macro
DIR_NAMESIZE macro
dirCleared variable
Directory
DIRECTORY macro
Directory Structure
DIRENTRIES_PER_SECTOR macro
DIRENTRY type
DISKmount function
E
END_CLUSTER_FAT12 macro
END_CLUSTER_FAT16 macro
END_CLUSTER_FAT32 macro
EOF macro
EraseCluster function
eraseDir function
Explorer 16 with PICtail for SD and MMC
F
FALSE macro
FAT
FAT_erase_cluster_chain function
FAT_GOOD_SIGN_0 macro
FAT_GOOD_SIGN_1 macro
FAT12 macro
FAT16 macro
FAT32 macro
FATfindEmptyCluster function
FatRootDirClusterValue variable
File Manipulation Layer (FSIO)
FILE_NAME_SIZE macro
FILE_NAME_SIZE_8P3 macro
FILEallocate_new_cluster function
FILECreateHeadCluster function
FILEerase function
FILEfind function
FILEFLAGS structure
FILEget_next_cluster function
FILEOBJ type
FileObjectCopy function
FILEopen function
Fill_File_Object function
FindEmptyEntries function
FindFirst function
FindFirstpgm function
FindNext function
flushData function
FO_MBR macro
FOUND macro
FS_DYNAMIC_MEM macro
FS_MAX_FILES_OPEN macro
FSattrib function
FSchdir function
FSchdirpgm function
FSCreateMBR function
FSerrno variable
FSerror function
FSfclose function
FSfeof function
FSFILE structure
FSfopen function
FSfopenpgm function
FSformat function
FSfprintf function
FSfread function
FSfseek function
FSftell function
FSfwrite function
FSgetcwd function
FSGetDiskProperties function
FSInit function
FSmkdir function
FSmkdirpgm function
FSputc function
FSremove function
FSremovepgm function
FSrename function
FSrenamepgm function
FSrewind function
FSrmdir function
FSrmdirpgm function
FSvfprintf function
G
gBufferOwner variable
gBufferZeroed variable
gDataBuffer variable
gDiskData variable
GetFullClusterNumber function
GetInstructionClock macro
GetPeripheralClock macro
GetPreviousEntry function
GetSystemClock macro
Getting Started
gFATBuffer variable
gFileArray variable
gFileSlotOpen variable
gFileTemp variable
gLastDataSectorRead variable
gLastFATSectorRead variable
gNeedDataWrite variable
gNeedFATWrite variable
gTimeAccDate variable
gTimeCrtDate variable
gTimeCrtMS variable
gTimeCrtTime variable
gTimeWrtDate variable
gTimeWrtTime variable
H
HPC Explorer with PICtail for SD and MMC
I
IncrementTimeStamp function
INPUT macro
Internal Members
L
LAST_CLUSTER_FAT12 macro
LAST_CLUSTER_FAT16 macro
LAST_CLUSTER_FAT32 macro
LFN
Library Members
LoadBootSector function
LoadDirAttrib function
LoadMBR function
M
MANUAL_SPI_CLOCK_VALUE macro
MASK_MAX_FILE_ENTRY_LIMIT_BITS macro
Master Boot Record
MASTER_ENABLE_ON macro
MAX_FILE_NAME_LENGTH_LFN macro
MAX_HEAP_SIZE macro
MDD_CFBT_CFread function
MDD_CFBT_CFwait function
MDD_CFBT_CFwrite function
MDD_CFBT_DATABIN macro
MDD_CFBT_DATABinput macro
MDD_CFBT_DATABOUT macro
MDD_CFBT_DATABoutput macro
MDD_CFBT_DATADIR macro
MDD_CFBT_InitIO function
MDD_CFBT_MediaDetect function
MDD_CFBT_MediaInitialize function
MDD_CFBT_SectorRead function
MDD_CFBT_SectorWrite function
MDD_CFBT_WriteProtectState function
MDD_CFPMP_CFread function
MDD_CFPMP_CFwait function
MDD_CFPMP_CFwrite function
MDD_CFPMP_DATABinput macro
MDD_CFPMP_DATABoutput macro
MDD_CFPMP_DATADIR macro
MDD_CFPMP_InitIO function
MDD_CFPMP_MediaDetect function
MDD_CFPMP_MediaInitialize function
MDD_CFPMP_SectorRead function
MDD_CFPMP_SectorWrite function
MDD_CFPMP_WriteProtectState function
MDD_CFread macro
MDD_CFwait macro
MDD_CFwrite macro
MDD_InitIO macro
MDD_MediaDetect macro
MDD_MediaInitialize macro
MDD_ReadCapacity macro
MDD_ReadSectorSize macro
MDD_SDSPI_AsyncReadTasks function
MDD_SDSPI_AsyncWriteTasks function
MDD_SDSPI_finalLBA variable
MDD_SDSPI_InitIO function
MDD_SDSPI_MediaDetect function
MDD_SDSPI_MediaInitialize function
MDD_SDSPI_ReadCapacity function
MDD_SDSPI_ReadMedia function
MDD_SDSPI_ReadSectorSize function
MDD_SDSPI_SectorRead function
MDD_SDSPI_SectorWrite function
MDD_SDSPI_ShutdownMedia function
MDD_SDSPI_WriteProtectState function
MDD_SectorRead macro
MDD_SectorWrite macro
MDD_ShutdownMedia macro
MDD_USE_SPI_1 macro
MDD_USE_SPI_2
MDD_WriteProtectState macro
MEDIA_ERRORS enumeration
MEDIA_INFORMATION structure
MEDIA_SECTOR_SIZE macro
mediaInformation variable
Microchip MDD File System Interface Library
MILLISECDELAY macro
mkdirhelper function
MMC_BAD_RESPONSE macro
MMC_FLOATING_BUS macro
MMC_RESPONSE union
MOREDATA macro
mReadCRC macro
mSend8ClkCycles macro
mSendCRC macro
N
NEAR macro
NEAR_MODEL macro
nextClusterIsLast variable
NO_MORE macro
NODATA macro
NOT_FOUND macro
NUMBER_OF_BYTES_IN_DIR_ENTRY macro
O
OpenSPIM function
OUTPUT macro
P
PRI_PRESCAL_1_1 macro
PT_MBR type
Public Members
R
R_CMD macro
R_COUNT macro
R_CYHI macro
R_CYLO macro
R_DATA macro
R_DRIVE macro
R_ERROR macro
R_SECT macro
R_STATUS macro
RAMread macro
RAMreadD macro
RAMreadW macro
RAMwrite macro
ReadByte function
ReadDWord function
ReadFAT function
ReadMediaManual function
ReadWord function
recache variable
Release Notes
RESP enumeration
RESPONSE_1 union
RESPONSE_2 union
rmdirhelper function
Root directory
S
s_digits variable
S_ERROR macro
S_READY macro
SALLOC type
SD_CD macro
SD_CD_TRIS macro
SD_CS macro
SD_CS_TRIS macro
SD_WE macro
SD_WE_TRIS macro
sdmmc_cmd enumeration
sdmmc_cmdtable variable
SD-SPI Physical Layer
SEARCH_TYPE enumeration
SearchRec structure
SEC_PRESCAL_1_1 macro
Sector
SEEK_CUR macro
SEEK_END macro
SEEK_SET macro
SendMMCCmd function
SendMMCCmdManual function
SetClockVars function
Software Configuration
SPI_FREQUENCY macro
SPI_INTERRUPT_FLAG macro
SPIBRG macro
SPIBUF macro
SPICLOCK macro
SPICLOCKLAT macro
SPICLOCKPORT macro
SPICON1 macro
SPICON1bits macro
SPIENABLE macro
SPIIN macro
SPIINLAT macro
SPIINPORT macro
SPIOUT macro
SPIOUTLAT macro
SPIOUTPORT macro
SPISTAT macro
SPISTAT_RBF macro
SPISTATbits macro
SRAMInitHeap function
str_put_n_chars function
SUPPORT_FAT32 macro
SUPPORT_LFN macro
SW License Agreement
SWORD type
SYNC_MODE_FAST macro
SYNC_MODE_MED macro
SYNC_MODE_SLOW macro
T
tempArray variable
TempClusterCalc variable
tempCWDobj variable
Terminology
The SD Card Demo
The SD Data Logger Demo
TOTAL_FILE_SIZE macro
TRUE macro
typMMC_CMD structure
U
USE_SD_INTERFACE_WITH_SPI macro
USEREALTIMECLOCK macro
V
VALUE_BASED_ON_ENTRIES_PER_CLUSTER macro
VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT macro
W
wFindFirst function
wFSchdir function
wFSfopen function
wFSgetcwd function
wFSmkdir function
wFSremove function
wFSrename function
wFSrmdir function
WRITE macro
Write_File_Entry function
writeDotEntries function
WriteSPIM function
WriteSPIManual function


Microchip MDD File System Interface Library

Contents | Index
Next
Microchip MDD File System Interface Library
Welcome to the Microchip Memory Disk Drive File System Interface Library!

Microchip's Memory Disk Drive File System(MDDFS) supports FAT12, FAT16 and FAT32 format for all 8, 16 and 32 bit PIC MCU's. MDDFS software is independent of the physical layer used and can be easily integrated to any of the phsical layers like USB, SD card, compact flash...etc...

MDDFS supports all file and directory operations(like read,write,remove,rename...etc...) for Long File Name(LFN) entries upto 255 characters. That means each file or directory name can be upto 255 characters. This feature is available using PIC24F & PIC32 microcontrollers. PIC18F doesn't support LFN feature due to less RAM size. Whereas the basic 8.3 format filename is supported by all PIC18F, PIC24F & PIC32 MCU's.The MDD File System Interface Library will provide an easy way to create and manipulate files on removable flash-based media devices.

USB Functionality

Note that the source code package and help file for this library do not include USB physical layer information. For more information about using the USB Host stack as a physical layer, please visit [image] Microchip's USB Development Page or the [image] AN1145: Using a USB Flash Drive with an Embedded Host page.

Updates

The latest version of the Microchip MDD File System Interface library is always available at [image] Microchip MDD File System page.

Getting Help

The MDDFS Interface Library is supported through Microchip's standard support channels. If you encounter difficulties, you may submit ticket requests at [image] http://support.microchip.com.

Thank You!

We appreciate your interest in the Microchip MDD File System Interface Library, and thank you for choosing Microchip products!

Microchip MDD File System Interface Library


MDD_CFPMP_InitIO Function

Contents | Index | Home
Previous | Up | Next
MDD_CFPMP_InitIO Function
C
void MDD_CFPMP_InitIO();
Description

None

Preconditions

None

Returns

TRUE - Card initialized FALSE - Card not initialized

Side Effects

None

Remarks

None

APIs > CF Physical Layer > Library Members > MDD_CFPMP_InitIO Function


MDD_SDSPI_WriteProtectState Function

Contents | Index | Home
Previous | Up | Next
MDD_SDSPI_WriteProtectState Function
C
BYTE MDD_SDSPI_WriteProtectState();
Description

The MDD_SDSPI_WriteProtectState function will determine if the SD card is write protected by checking the electrical signal that corresponds to the physical write-protect switch.

Preconditions

The MDD_WriteProtectState function pointer must be pointing to this function.

Return Values
Return Values | Description
TRUE | The card is write-protected
FALSE | The card is not write-protected
Side Effects

None.

Remarks

None

APIs > SD-SPI Physical Layer > Library Members > MDD_SDSPI_WriteProtectState Function


SWORD Type

Contents | Index | Home
Previous | Up | Next
SWORD Type
C
typedef unsigned short long SWORD;
Description

The SWORD macro is used to defined a 24-bit data type. For 16+ bit architectures, this must be represented as an array of three bytes.

APIs > File Manipulation Layer (FSIO) > Library Members > SWORD Type