Statistics
| Branch: | Revision:

root / arduino-1.0 / libraries / SD / utility / SdFatmainpage.h @ 58d82c77

History | View | Annotate | Download (8.01 KB)

1
/* Arduino SdFat Library
2
 * Copyright (C) 2009 by William Greiman
3
 *  
4
 * This file is part of the Arduino SdFat Library
5
 *  
6
 * This Library is free software: you can redistribute it and/or modify 
7
 * it under the terms of the GNU General Public License as published by 
8
 * the Free Software Foundation, either version 3 of the License, or
9
 * (at your option) any later version.
10
 * 
11
 * This Library is distributed in the hope that it will be useful,
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 * GNU General Public License for more details.
15
 *
16
 * You should have received a copy of the GNU General Public License
17
 * along with the Arduino SdFat Library.  If not, see
18
 * <http://www.gnu.org/licenses/>.
19
 */
20

    
21
/**
22
\mainpage Arduino SdFat Library
23
<CENTER>Copyright &copy; 2009 by William Greiman
24
</CENTER>
25

26
\section Intro Introduction
27
The Arduino SdFat Library is a minimal implementation of FAT16 and FAT32
28
file systems on SD flash memory cards.  Standard SD and high capacity
29
SDHC cards are supported.
30

31
The SdFat only supports short 8.3 names.
32

33
The main classes in SdFat are Sd2Card, SdVolume, and SdFile.
34

35
The Sd2Card class supports access to standard SD cards and SDHC cards.  Most
36
applications will only need to call the Sd2Card::init() member function.
37

38
The SdVolume class supports FAT16 and FAT32 partitions.  Most applications
39
will only need to call the SdVolume::init() member function.
40

41
The SdFile class provides file access functions such as open(), read(),
42
remove(), write(), close() and sync(). This class supports access to the root
43
directory and subdirectories.
44

45
A number of example are provided in the SdFat/examples folder.  These were
46
developed to test SdFat and illustrate its use.
47

48
SdFat was developed for high speed data recording.  SdFat was used to implement
49
an audio record/play class, WaveRP, for the Adafruit Wave Shield.  This
50
application uses special Sd2Card calls to write to contiguous files in raw mode.
51
These functions reduce write latency so that audio can be recorded with the
52
small amount of RAM in the Arduino.
53

54
\section SDcard SD\SDHC Cards
55

56
Arduinos access SD cards using the cards SPI protocol.  PCs, Macs, and
57
most consumer devices use the 4-bit parallel SD protocol.  A card that
58
functions well on A PC or Mac may not work well on the Arduino.
59

60
Most cards have good SPI read performance but cards vary widely in SPI
61
write performance.  Write performance is limited by how efficiently the
62
card manages internal erase/remapping operations.  The Arduino cannot
63
optimize writes to reduce erase operations because of its limit RAM.
64

65
SanDisk cards generally have good write performance.  They seem to have
66
more internal RAM buffering than other cards and therefore can limit
67
the number of flash erase operations that the Arduino forces due to its
68
limited RAM.
69

70
\section Hardware Hardware Configuration
71

72
SdFat was developed using an
73
<A HREF = "http://www.adafruit.com/"> Adafruit Industries</A> 
74
<A HREF = "http://www.ladyada.net/make/waveshield/"> Wave Shield</A>.
75

76
The hardware interface to the SD card should not use a resistor based level
77
shifter.  SdFat sets the SPI bus frequency to 8 MHz which results in signal
78
rise times that are too slow for the edge detectors in many newer SD card
79
controllers when resistor voltage dividers are used.
80

81
The 5 to 3.3 V level shifter for 5 V Arduinos should be IC based like the
82
74HC4050N based circuit shown in the file SdLevel.png.  The Adafruit Wave Shield
83
uses a 74AHC125N.  Gravitech sells SD and MicroSD Card Adapters based on the
84
74LCX245.
85

86
If you are using a resistor based level shifter and are having problems try
87
setting the SPI bus frequency to 4 MHz.  This can be done by using 
88
card.init(SPI_HALF_SPEED) to initialize the SD card.
89

90
\section comment Bugs and Comments
91

92
If you wish to report bugs or have comments, send email to fat16lib@sbcglobal.net.
93

94
\section SdFatClass SdFat Usage
95

96
SdFat uses a slightly restricted form of short names.
97
Only printable ASCII characters are supported. No characters with code point
98
values greater than 127 are allowed.  Space is not allowed even though space
99
was allowed in the API of early versions of DOS.
100

101
Short names are limited to 8 characters followed by an optional period (.)
102
and extension of up to 3 characters.  The characters may be any combination
103
of letters and digits.  The following special characters are also allowed:
104

105
$ % ' - _ @ ~ ` ! ( ) { } ^ # &
106

107
Short names are always converted to upper case and their original case
108
value is lost.
109

110
\note
111
  The Arduino Print class uses character
112
at a time writes so it was necessary to use a \link SdFile::sync() sync() \endlink
113
function to control when data is written to the SD card.
114

115
\par
116
An application which writes to a file using \link Print::print() print()\endlink,
117
\link Print::println() println() \endlink
118
or \link SdFile::write write() \endlink must call \link SdFile::sync() sync() \endlink
119
at the appropriate time to force data and directory information to be written
120
to the SD Card.  Data and directory information are also written to the SD card
121
when \link SdFile::close() close() \endlink is called.
122

123
\par
124
Applications must use care calling \link SdFile::sync() sync() \endlink
125
since 2048 bytes of I/O is required to update file and
126
directory information.  This includes writing the current data block, reading
127
the block that contains the directory entry for update, writing the directory
128
block back and reading back the current data block.
129

130
It is possible to open a file with two or more instances of SdFile.  A file may
131
be corrupted if data is written to the file by more than one instance of SdFile.
132

133
\section HowTo How to format SD Cards as FAT Volumes
134

135
You should use a freshly formatted SD card for best performance.  FAT
136
file systems become slower if many files have been created and deleted.
137
This is because the directory entry for a deleted file is marked as deleted,
138
but is not deleted.  When a new file is created, these entries must be scanned
139
before creating the file, a flaw in the FAT design.  Also files can become
140
fragmented which causes reads and writes to be slower.
141

142
Microsoft operating systems support removable media formatted with a
143
Master Boot Record, MBR, or formatted as a super floppy with a FAT Boot Sector
144
in block zero.
145

146
Microsoft operating systems expect MBR formatted removable media
147
to have only one partition. The first partition should be used.
148

149
Microsoft operating systems do not support partitioning SD flash cards.
150
If you erase an SD card with a program like KillDisk, Most versions of
151
Windows will format the card as a super floppy.
152

153
The best way to restore an SD card's format is to use SDFormatter
154
which can be downloaded from:
155

156
http://www.sdcard.org/consumers/formatter/
157

158
SDFormatter aligns flash erase boundaries with file
159
system structures which reduces write latency and file system overhead.
160

161
SDFormatter does not have an option for FAT type so it may format
162
small cards as FAT12.
163

164
After the MBR is restored by SDFormatter you may need to reformat small
165
cards that have been formatted FAT12 to force the volume type to be FAT16.
166

167
If you reformat the SD card with an OS utility, choose a cluster size that
168
will result in:
169

170
4084 < CountOfClusters && CountOfClusters < 65525
171

172
The volume will then be FAT16.
173

174
If you are formatting an SD card on OS X or Linux, be sure to use the first
175
partition. Format this partition with a cluster count in above range.
176

177
\section  References References
178

179
Adafruit Industries:
180

181
http://www.adafruit.com/
182

183
http://www.ladyada.net/make/waveshield/
184

185
The Arduino site:
186

187
http://www.arduino.cc/
188

189
For more information about FAT file systems see:
190

191
http://www.microsoft.com/whdc/system/platform/firmware/fatgen.mspx
192

193
For information about using SD cards as SPI devices see:
194

195
http://www.sdcard.org/developers/tech/sdcard/pls/Simplified_Physical_Layer_Spec.pdf
196

197
The ATmega328 datasheet:
198

199
http://www.atmel.com/dyn/resources/prod_documents/doc8161.pdf
200
 
201

202
 */