KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
sd.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  dc/sd.h
4  Copyright (C) 2012 Lawrence Sebald
5 */
6 
7 #ifndef __DC_SD_H
8 #define __DC_SD_H
9 
10 #include <sys/cdefs.h>
11 __BEGIN_DECLS
12 
13 #include <arch/types.h>
14 #include <kos/blockdev.h>
15 
16 /** \file dc/sd.h
17  \brief Block-level access to an SD card attached to the SCIF port.
18 
19  This file contains the interface to working with the SD card reader that was
20  designed by jj1odm. The SD card reader itself connects to the SCIF port and
21  uses it basically as a simple SPI bus.
22 
23  For reference, all I/O through this code should be done in the order of SD
24  card blocks (which are 512 bytes a piece). Also, this should adequately
25  support SD and SDHC cards (and possibly SDXC, but I don't have any of them
26  to try out).
27 
28  This code doesn't directly implement any filesystems on top of the SD card,
29  but rather provides you with direct block-level access. This probably will
30  not be useful to most people in its current form (without a filesystem), but
31  this will provide you with all of the building blocks you should need to
32  actually make it work for you.
33 
34  Due to the patent-encumbered nature of certain parts of the FAT32
35  filesystem, that filesystem will likely never be supported in KOS proper
36  (unless, of course, people are still using KOS after those patents expire).
37  I'm not going to encourage anyone to violate Microsoft's patents on FAT32
38  and I'm not going to be the enabler for anyone to do so either. So, if you
39  want FAT32, you're on your own.
40 
41  \author Lawrence Sebald
42  \see dc/scif.h
43 */
44 
45 /** \brief Calculate a SD/MMC-style CRC over a block of data.
46 
47  This function calculates a 7-bit CRC over a given block of data. The
48  polynomial of this CRC is x^7 + x^3 + 1. The CRC is shifted into the upper
49  7 bits of the return value, so bit 0 should always be 0.
50 
51  \param data The block of data to calculate the CRC over.
52  \param size The number of bytes in the block of data.
53  \param crc The starting value of the calculation. If you're
54  passing in a full block, this will probably be 0.
55  \return The calculated CRC.
56 */
57 uint8 sd_crc7(const uint8 *data, int size, uint8 crc);
58 
59 /** \brief Initialize the SD card for use.
60 
61  This function initializes the SD card for first use. This includes all steps
62  of the basic initialization sequence for SPI mode, as documented in the SD
63  card spec and at http://elm-chan.org/docs/mmc/mmc_e.html . This also will
64  call scif_sd_init() for you, so you don't have to worry about that ahead of
65  time.
66 
67  \retval 0 On success.
68  \retval -1 On failure. This could indicate any number of
69  problems, but probably means that no SD card was
70  detected.
71 */
72 int sd_init(void);
73 
74 /** \brief Shut down SD card support.
75 
76  This function shuts down SD card support, and cleans up anything that the
77  sd_init() function set up.
78 
79  \retval 0 On success.
80  \retval -1 On failure. The only currently defined error is if
81  the card was never initialized to start with.
82 */
83 int sd_shutdown(void);
84 
85 /** \brief Read one or more blocks from the SD card.
86 
87  This function reads the specified number of blocks from the SD card from the
88  beginning block specified into the buffer passed in. It is your
89  responsibility to allocate the buffer properly for the number of bytes that
90  is to be read (512 * the number of blocks requested).
91 
92  \param block The starting block number to read from.
93  \param count The number of 512 byte blocks of data to read.
94  \param buf The buffer to read into.
95  \retval 0 On success.
96  \retval -1 On error, errno will be set as appropriate.
97 
98  \par Error Conditions:
99  \em EIO - an I/O error occurred in reading data \n
100  \em ENXIO - SD card support was not initialized
101 */
102 int sd_read_blocks(uint32 block, size_t count, uint8 *buf);
103 
104 /** \brief Write one or more blocks to the SD card.
105 
106  This function writes the specified number of blocks to the SD card at the
107  beginning block specified from the buffer passed in. Each block is 512 bytes
108  in length, and you must write at least one block at a time. You cannot write
109  partial blocks.
110 
111  If this function returns an error, you have quite possibly corrupted
112  something on the card or have a damaged card in general (unless errno is
113  ENXIO).
114 
115  \param block The starting block number to write to.
116  \param count The number of 512 byte blocks of data to write.
117  \param buf The buffer to write from.
118  \retval 0 On success.
119  \retval -1 On error, errno will be set as appropriate.
120 
121  \par Error Conditions:
122  \em EIO - an I/O error occurred in reading data \n
123  \em ENXIO - SD card support was not initialized
124 */
125 int sd_write_blocks(uint32 block, size_t count, const uint8 *buf);
126 
127 /** \brief Retrieve the size of the SD card.
128 
129  This function reads the size of the SD card from the card's CSD register.
130  This is the raw size of the card, not its formatted capacity. To get the
131  number of blocks from this, divide by 512.
132 
133  \return On succes, the raw size of the SD card in bytes. On
134  error, (uint64)-1.
135 
136  \par Error Conditions:
137  \em EIO - an I/O error occurred in reading data \n
138  \em ENXIO - SD card support was not initialized
139 */
140 uint64 sd_get_size(void);
141 
142 /** \brief Get a block device for a given partition on the SD card.
143 
144  This function creates a block device descriptor for the given partition on
145  the attached SD card. This block device is used to interface with various
146  filesystems on the device.
147 
148  \param partition The partition number (0-3) to use.
149  \param rv Used to return the block device. Must be non-NULL.
150  \param partition_type Used to return the partition type. Must be non-NULL.
151  \retval 0 On success.
152  \retval -1 On error, errno will be set as appropriate.
153 
154  \par Error Conditions:
155  \em ENXIO - SD card support was not initialized \n
156  \em EIO - an I/O error occurred in reading data \n
157  \em EINVAL - invalid partition number was given \n
158  \em EFAULT - rv or partition_type was NULL \n
159  \em ENOENT - no MBR found \n
160  \em ENOENT - no partition at the specified position \n
161  \em ENOMEM - out of memory
162 
163  \note This interface currently only supports MBR-formatted SD cards. There
164  is currently no support for GPT partition tables.
165 */
166 int sd_blockdev_for_partition(int partition, kos_blockdev_t *rv,
167  uint8 *partition_type);
168 
169 __END_DECLS
170 #endif /* !__DC_SD_H */
Generated by   doxygen 1.8.1.1