KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
sd.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 dc/sd.h
4 Copyright (C) 2012 Lawrence Sebald
5 Copyright (C) 2025 Ruslan Rostovtsev
6*/
7
8/** \file dc/sd.h
9 \brief Block-level access to an SD card attached to the SCI or SCIF port.
10 \ingroup vfs_sd
11
12 This file contains the interface to working with SD card readers.
13 The original SD card reader designed by jj1odm connects to the SCIF port,
14 while the SCI port implementation was developed by SWAT (Ruslan Rostovtsev).
15 The SCIF implementation uses bit-banging technique to emulate SPI protocol,
16 while the SCI implementation utilizes the synchronous mode of this interface,
17 which is very similar to SPI.
18
19 For reference, all I/O through this code should be done in the order of SD
20 card blocks (which are 512 bytes a piece). Also, this should adequately
21 support SD and SDHC cards (and possibly SDXC, but I don't have any of them
22 to try out).
23
24 This code doesn't directly implement any filesystems on top of the SD card,
25 but rather provides you with direct block-level access. This probably will
26 not be useful to most people in its current form (without a filesystem), but
27 this will provide you with all of the building blocks you should need to
28 actually make it work for you.
29
30 Due to the patent-encumbered nature of certain parts of the FAT32
31 filesystem, that filesystem will likely never be supported in KOS proper
32 (unless, of course, people are still using KOS after those patents expire).
33 I'm not going to encourage anyone to violate Microsoft's patents on FAT32
34 and I'm not going to be the enabler for anyone to do so either. So, if you
35 want FAT32, you're on your own.
36
37 \author Lawrence Sebald
38 \see dc/scif.h
39*/
40
41#ifndef __DC_SD_H
42#define __DC_SD_H
43
44#include <sys/cdefs.h>
45__BEGIN_DECLS
46
47#include <arch/types.h>
48#include <kos/blockdev.h>
49#include <stdbool.h>
50
51/** \defgroup vfs_sd SD Card
52 \brief VFS driver for accessing SD cards over the SCIF or SCI port
53 \ingroup vfs
54
55 @{
56*/
57
58/** \brief SD card interface type */
59typedef enum {
60 SD_IF_SCIF = 0, /**< Use SCIF interface */
61 SD_IF_SCI = 1 /**< Use SCI interface */
63
64/** \brief SD card initialization parameters */
65typedef struct {
66 sd_interface_t interface; /**< Interface to use (SCIF or SCI) */
67 bool check_crc; /**< Enable CRC checking (true) or disable (false) */
69
70/** \brief Calculate a SD/MMC-style CRC over a block of data.
71
72 This function calculates a 7-bit CRC over a given block of data. The
73 polynomial of this CRC is x^7 + x^3 + 1. The CRC is shifted into the upper
74 7 bits of the return value, so bit 0 should always be 0.
75
76 \param data The block of data to calculate the CRC over.
77 \param size The number of bytes in the block of data.
78 \param crc The starting value of the calculation. If you're
79 passing in a full block, this will probably be 0.
80 \return The calculated CRC.
81*/
82uint8 sd_crc7(const uint8 *data, int size, uint8 crc);
83
84/** \brief Initialize the SD card with extended parameters.
85
86 This function initializes the SD card with specified parameters. This includes
87 all steps of the basic initialization sequence for SPI mode, as documented in
88 the SD card spec and at http://elm-chan.org/docs/mmc/mmc_e.html.
89
90 \param params Pointer to initialization parameters.
91 \retval 0 On success.
92 \retval -1 On failure. This could indicate any number of
93 problems, but probably means that no SD card was
94 detected.
95*/
96int sd_init_ex(const sd_init_params_t *params);
97
98/** \brief Initialize the SD card for use.
99
100 This function initializes the SD card for first use using default parameters
101 (SCIF interface and CRC checking enabled).
102
103 \retval 0 On success.
104 \retval -1 On failure. This could indicate any number of
105 problems, but probably means that no SD card was
106 detected.
107*/
108int sd_init(void);
109
110/** \brief Shut down SD card support.
111
112 This function shuts down SD card support, and cleans up anything that the
113 sd_init() function set up.
114
115 \retval 0 On success.
116 \retval -1 On failure. The only currently defined error is if
117 the card was never initialized to start with.
118*/
119int sd_shutdown(void);
120
121/** \brief Read one or more blocks from the SD card.
122
123 This function reads the specified number of blocks from the SD card from the
124 beginning block specified into the buffer passed in. It is your
125 responsibility to allocate the buffer properly for the number of bytes that
126 is to be read (512 * the number of blocks requested).
127
128 \param block The starting block number to read from.
129 \param count The number of 512 byte blocks of data to read.
130 \param buf The buffer to read into.
131 \retval 0 On success.
132 \retval -1 On error, errno will be set as appropriate.
133
134 \par Error Conditions:
135 \em EIO - an I/O error occurred in reading data \n
136 \em ENXIO - SD card support was not initialized
137*/
138int sd_read_blocks(uint32 block, size_t count, uint8 *buf);
139
140/** \brief Write one or more blocks to the SD card.
141
142 This function writes the specified number of blocks to the SD card at the
143 beginning block specified from the buffer passed in. Each block is 512 bytes
144 in length, and you must write at least one block at a time. You cannot write
145 partial blocks.
146
147 If this function returns an error, you have quite possibly corrupted
148 something on the card or have a damaged card in general (unless errno is
149 ENXIO).
150
151 \param block The starting block number to write to.
152 \param count The number of 512 byte blocks of data to write.
153 \param buf The buffer to write from.
154 \retval 0 On success.
155 \retval -1 On error, errno will be set as appropriate.
156
157 \par Error Conditions:
158 \em EIO - an I/O error occurred in reading data \n
159 \em ENXIO - SD card support was not initialized
160*/
161int sd_write_blocks(uint32 block, size_t count, const uint8 *buf);
162
163/** \brief Retrieve the size of the SD card.
164
165 This function reads the size of the SD card from the card's CSD register.
166 This is the raw size of the card, not its formatted capacity. To get the
167 number of blocks from this, divide by 512.
168
169 \return On success, the raw size of the SD card in bytes. On
170 error, (uint64)-1.
171
172 \par Error Conditions:
173 \em EIO - an I/O error occurred in reading data \n
174 \em ENXIO - SD card support was not initialized
175*/
177
178/** \brief Get a block device for a given partition on the SD card.
179
180 This function creates a block device descriptor for the given partition on
181 the attached SD card. This block device is used to interface with various
182 filesystems on the device.
183
184 \param partition The partition number (0-3) to use.
185 \param rv Used to return the block device. Must be non-NULL.
186 \param partition_type Used to return the partition type. Must be non-NULL.
187 \retval 0 On success.
188 \retval -1 On error, errno will be set as appropriate.
189
190 \par Error Conditions:
191 \em ENXIO - SD card support was not initialized \n
192 \em EIO - an I/O error occurred in reading data \n
193 \em EINVAL - invalid partition number was given \n
194 \em EFAULT - rv or partition_type was NULL \n
195 \em ENOENT - no MBR found \n
196 \em ENOENT - no partition at the specified position \n
197 \em ENOMEM - out of memory
198
199 \note This interface currently only supports MBR-formatted SD cards. There
200 is currently no support for GPT partition tables.
201*/
203 uint8 *partition_type);
204
205/** \brief Get a block device for the SD card.
206
207 This function creates a block device descriptor for the attached SD card.
208 This block device is used to interface with various filesystems on the device.
209
210 \param rv Used to return the block device. Must be non-NULL.
211 \retval 0 On success.
212 \retval -1 On error, errno will be set as appropriate.
213
214 \par Error Conditions:
215 \em ENXIO - SD card support was not initialized
216 \em EFAULT - rv was NULL
217 \em ENOMEM - out of memory
218*/
220
221/** @} */
222
223__END_DECLS
224#endif /* !__DC_SD_H */
Definitions for a simple block device interface.
unsigned long long uint64
64-bit unsigned integer
Definition types.h:32
unsigned long uint32
32-bit unsigned integer
Definition types.h:33
unsigned char uint8
8-bit unsigned integer
Definition types.h:35
int sd_write_blocks(uint32 block, size_t count, const uint8 *buf)
Write one or more blocks to the SD card.
uint64 sd_get_size(void)
Retrieve the size of the SD card.
int sd_blockdev_for_device(kos_blockdev_t *rv)
Get a block device for the SD card.
int sd_init(void)
Initialize the SD card for use.
uint8 sd_crc7(const uint8 *data, int size, uint8 crc)
Calculate a SD/MMC-style CRC over a block of data.
int sd_init_ex(const sd_init_params_t *params)
Initialize the SD card with extended parameters.
int sd_read_blocks(uint32 block, size_t count, uint8 *buf)
Read one or more blocks from the SD card.
int sd_shutdown(void)
Shut down SD card support.
int sd_blockdev_for_partition(int partition, kos_blockdev_t *rv, uint8 *partition_type)
Get a block device for a given partition on the SD card.
sd_interface_t
SD card interface type.
Definition sd.h:59
@ SD_IF_SCIF
Use SCIF interface.
Definition sd.h:60
@ SD_IF_SCI
Use SCI interface.
Definition sd.h:61
A simple block device.
Definition blockdev.h:54
SD card initialization parameters.
Definition sd.h:65
sd_interface_t interface
Interface to use (SCIF or SCI)
Definition sd.h:66
bool check_crc
Enable CRC checking (true) or disable (false)
Definition sd.h:67
Common integer types.