KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
g1ata.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dc/g1ata.h
4  Copyright (C) 2013, 2014 Lawrence Sebald
5 */
6 
7 /** \file dc/g1ata.h
8  \brief G1 bus ATA interface.
9 
10  This file provides support for accessing an ATA device on the G1 bus in the
11  Dreamcast. The G1 bus usually contains a few useful pieces of the system,
12  including the flashrom and the GD-ROM drive. The interesting piece here is
13  that the GD-ROM drive itself is actually an ATA device.
14 
15  Luckily, Sega left everything in place to access both a master and slave
16  device on this ATA port. The GD-ROM drive should always be the master device
17  on the chain, but you can hook up a hard drive or some other device as a
18  slave. The functions herein are for accessing just such a slave device.
19 
20  \note The functions herein do not provide for direct access to the GD-ROM
21  drive. There is not really any sort of compelling reason to access
22  the GD-ROM drive directly instead of using the system calls, so you
23  should continue to use the normal cdrom_* functions for accessing
24  the GD-ROM drive. Also, currently there is no locking done to
25  prevent you from doing "bad things" with concurrent access on the
26  bus, so be careful. ;)
27 
28  \author Lawrence Sebald
29 */
30 
31 #ifndef __DC_G1ATA_H
32 #define __DC_G1ATA_H
33 
34 #include <sys/cdefs.h>
35 __BEGIN_DECLS
36 
37 #include <stdint.h>
38 #include <kos/blockdev.h>
39 
40 /** \defgroup ata_devices ATA device definitions
41 
42  The constants here represent the valid values that can be set as the active
43  device on the ATA bus. You should pass one of these values to the
44  g1_ata_select_device() function to select the appropriate device.
45 
46  \note Many times, the value returned by the g1_ata_select_device()
47  function will have other bits set than the constants below. You
48  should AND the value returned from that function with 0x10 if you
49  really need to know what device is actually selected. If the value
50  returned is true when ANDed with 0x10, then the slave device was
51  selected, otherwise the master device was. The other bits are either
52  command-specific or are reserved for compatibility sake.
53 
54  @{
55 */
56 /** \brief ATA master device.
57 
58  This constant selects the master device on the ATA bus. This is normally the
59  GD-ROM drive.
60 
61  \note The GD-ROM really does not like the reserved bits being set in the
62  device select register, hence why this constant doesn't select them.
63  Some hard drives may require them, however. If you find one that
64  does, then you should use the \ref G1_ATA_MASTER_ALT constant to
65  access it if it is the master device on the bus.
66 */
67 #define G1_ATA_MASTER 0x00
68 
69 /** \brief ATA master device (compatible with old drives).
70 
71  This constant selects the master device on the ATA bus, with the old
72  reserved bits set to 1. If you have a drive that predates ATA-2, then this
73  will probably be the constant you want to access it as the master device.
74 
75  \note Do not use this constant to access the GD-ROM. It will not work. Use
76  \ref G1_ATA_MASTER instead.
77 */
78 #define G1_ATA_MASTER_ALT 0x90
79 
80 /** \brief ATA slave device.
81 
82  This constant selects the slave device on the ATA bus. This is where you
83  would find a hard drive, if the user has an adapter installed.
84 */
85 #define G1_ATA_SLAVE 0xB0
86 
87 /** \brief Select LBA addressing mode.
88 
89  OR this constant with one of the device constants (\ref G1_ATA_MASTER or
90  \ref G1_ATA_SLAVE) to select LBA addressing mode. The various g1_ata_*
91  functions all do this as appropriate already, so you shouldn't have to worry
92  about this one at all. This bit is irrelevant for packet devices.
93 */
94 #define G1_ATA_LBA_MODE 0x40
95 /** @} */
96 
97 /** \brief Is there a G1 DMA in progress currently?
98 
99  This function returns non-zero if a DMA is in progress. This can be used to
100  check on the completion of DMA transfers when non-blocking mode was selected
101  at transfer time.
102 
103  \return 0 if no DMA is in progress, nonzero otherwise.
104 */
105 int g1_dma_in_progress(void);
106 
107 /** \brief Lock the G1 ATA mutex.
108 
109  This function locks the mutex that arbitrates access to the ATA bus. You
110  should never have to do this on your own unless you're accessing devices
111  manually yourself.
112 
113  \return 0 on success, -1 on failure.
114  \note Failure conditions are exactly the same as the
115  \ref mutex_lock() function.
116 */
117 int g1_ata_mutex_lock(void);
118 
119 /** \brief Unlock the G1 ATA mutex.
120 
121  This function unlocks the mutex that arbitrates access to the ATA bus. You
122  should never have to do this on your own unless you're accessing devices
123  manually yourself.
124 
125  \return 0 on success, -1 on failure.
126  \note Failure conditions are exactly the same as the
127  \ref mutex_unlock() function.
128 */
129 int g1_ata_mutex_unlock(void);
130 
131 /** \brief Set the active ATA device.
132 
133  This function sets the device that any further ATA commands will go to. You
134  shouldn't have to ever call this yourself, as it should be done for you by
135  any of the access functions. This must be called with the ATA lock held.
136 
137  \param dev The device to access (generally either
138  \ref G1_ATA_MASTER or \ref G1_ATA_SLAVE).
139  \return The previous active device (or 0x0F if the function
140  would block in an IRQ handler).
141 
142  \note This function may block if there is a transfer
143  ongoing. If called in an IRQ handler and the call
144  would otherwise block, 0x0F is returned.
145 */
146 uint8_t g1_ata_select_device(uint8_t dev);
147 
148 /** \brief Read one or more disk sectors with Cylinder-Head-Sector addressing.
149 
150  This function reads one or more 512-byte disk blocks from the slave device
151  on the G1 ATA bus using Cylinder-Head-Sector addressing. This function uses
152  PIO and blocks until the data is read in.
153 
154  \param c The cylinder to start reading from.
155  \param h The head to start reading from.
156  \param s The sector to start reading from.
157  \param count The number of disk sectors to read.
158  \param buf Storage for the read-in disk sectors. This should be
159  at least (count * 512) bytes in length, and must be
160  at least 16-bit aligned.
161  \return 0 on success. < 0 on failure, setting errno as
162  appropriate.
163 
164  \note Unless you're accessing a really old hard drive, you
165  probably do not want to use this function to access
166  the disk. Use the g1_ata_read_lba() function instead
167  of this one, unless you get an error from that
168  function indicating that LBA addressing is not
169  supported.
170 
171  \par Error Conditions:
172  \em EIO - an I/O error occurred in reading data \n
173  \em ENXIO - ATA support not initialized or no device attached \n
174  \em EOVERFLOW - one or more of the requested sectors is out of the
175  range of the disk
176 */
177 int g1_ata_read_chs(uint16_t c, uint8_t h, uint8_t s, size_t count,
178  uint16_t *buf);
179 
180 /** \brief Write one or more disk sectors with Cylinder-Head-Sector addressing.
181 
182  This function writes one or more 512-byte disk blocks to the slave device
183  on the G1 ATA bus using Cylinder-Head-Sector addressing. This function uses
184  PIO and blocks until the data is written.
185 
186  \param c The cylinder to start writing to.
187  \param h The head to start writing to.
188  \param s The sector to start writing to.
189  \param count The number of disk sectors to write.
190  \param buf The data to write to the disk. This should be
191  (count * 512) bytes in length and must be at least
192  16-bit aligned.
193  \return 0 on success. < 0 on failure, setting errno as
194  appropriate.
195 
196  \note Unless you're accessing a really old hard drive, you
197  probably do not want to use this function to access
198  the disk. Use the g1_ata_write_lba() function
199  instead of this one, unless you get an error from
200  that function indicating that LBA addressing is not
201  supported.
202 
203  \par Error Conditions:
204  \em ENXIO - ATA support not initialized or no device attached \n
205  \em EOVERFLOW - one or more of the requested sectors is out of the
206  range of the disk
207 */
208 int g1_ata_write_chs(uint16_t c, uint8_t h, uint8_t s, size_t count,
209  const uint16_t *buf);
210 
211 /** \brief Read one or more disk sectors with Linear Block Addressing (LBA).
212 
213  This function reads one or more 512-byte disk blocks from the slave device
214  on the G1 ATA bus using LBA mode (either 28 or 48 bits, as appropriate).
215  This function uses PIO and blocks until the data is read.
216 
217  \param sector The sector to start reading from.
218  \param count The number of disk sectors to read.
219  \param buf Storage for the read-in disk sectors. This should be
220  at least (count * 512) bytes in length, and must be
221  at least 16-bit aligned.
222  \return 0 on success. < 0 on failure, setting errno as
223  appropriate.
224 
225  \note If errno is set to ENOTSUP after calling this
226  function, you must use the g1_ata_read_chs()
227  function instead.
228 
229  \par Error Conditions:
230  \em EIO - an I/O error occurred in reading data \n
231  \em ENXIO - ATA support not initialized or no device attached \n
232  \em EOVERFLOW - one or more of the requested sectors is out of the
233  range of the disk \n
234  \em ENOTSUP - LBA mode not supported by the device
235 */
236 int g1_ata_read_lba(uint64_t sector, size_t count, uint16_t *buf);
237 
238 /** \brief DMA read disk sectors with Linear Block Addressing (LBA).
239 
240  This function reads one or more 512-byte disk blocks from the slave device
241  on the G1 ATA bus using LBA mode (either 28 or 48 bits, as appropriate).
242  This function uses DMA and optionally blocks until the data is read.
243 
244  \param sector The sector to start reading from.
245  \param count The number of disk sectors to read.
246  \param buf Storage for the read-in disk sectors. This should be
247  at least (count * 512) bytes in length, and must be
248  at least 32-byte aligned.
249  \param block Non-zero to block until the transfer completes.
250  \return 0 on success. < 0 on failure, setting errno as
251  appropriate.
252 
253  \note If errno is set to ENOTSUP after calling this
254  function, you must use a CHS addressed transfer
255  function instead, like g1_ata_read_chs().
256 
257  \note If errno is set to EPERM after calling this
258  function, DMA mode is not supported. You should use
259  a PIO transfer function like g1_ata_read_lba()
260  instead.
261 
262  \par Error Conditions:
263  \em EIO - an I/O error occurred in reading data \n
264  \em ENXIO - ATA support not initialized or no device attached \n
265  \em EOVERFLOW - one or more of the requested sectors is out of the
266  range of the disk \n
267  \em ENOTSUP - LBA mode not supported by the device \n
268  \em EPERM - device does not support DMA
269 */
270 int g1_ata_read_lba_dma(uint64_t sector, size_t count, uint16_t *buf,
271  int block);
272 
273 /** \brief Write one or more disk sectors with Linear Block Addressing (LBA).
274 
275  This function writes one or more 512-byte disk blocks to the slave device
276  on the G1 ATA bus using LBA mode (either 28 or 48 bits, as appropriate).
277  This function uses PIO and blocks until the data is written.
278 
279  \param sector The sector to start writing to.
280  \param count The number of disk sectors to write.
281  \param buf The data to write to the disk. This should be
282  (count * 512) bytes in length and must be at least
283  16-bit aligned.
284  \return 0 on success. < 0 on failure, setting errno as
285  appropriate.
286 
287  \note If errno is set to ENOTSUP after calling this
288  function, you must use the g1_ata_write_chs()
289  function instead.
290 
291  \par Error Conditions:
292  \em ENXIO - ATA support not initialized or no device attached \n
293  \em EOVERFLOW - one or more of the requested sectors is out of the
294  range of the disk \n
295  \em ENOTSUP - LBA mode not supported by the device
296 */
297 int g1_ata_write_lba(uint64_t sector, size_t count, const uint16_t *buf);
298 
299 /** \brief DMA Write disk sectors with Linear Block Addressing (LBA).
300 
301  This function writes one or more 512-byte disk blocks to the slave device
302  on the G1 ATA bus using LBA mode (either 28 or 48 bits, as appropriate).
303  This function uses DMA and optionally blocks until the data is written.
304 
305  \param sector The sector to start writing to.
306  \param count The number of disk sectors to write.
307  \param buf The data to write to the disk. This should be
308  (count * 512) bytes in length and must be at least
309  32-byte aligned.
310  \param block Non-zero to block until the transfer completes.
311  \return 0 on success. < 0 on failure, setting errno as
312  appropriate.
313 
314  \note If errno is set to ENOTSUP after calling this
315  function, you must use the g1_ata_write_chs()
316  function instead.
317 
318  \note If errno is set to EPERM after calling this
319  function, DMA mode is not supported. You should use
320  a PIO transfer function like g1_ata_write_lba()
321  instead.
322 
323  \par Error Conditions:
324  \em ENXIO - ATA support not initialized or no device attached \n
325  \em EOVERFLOW - one or more of the requested sectors is out of the
326  range of the disk \n
327  \em ENOTSUP - LBA mode not supported by the device \n
328  \em EPERM - device does not support DMA
329 */
330 int g1_ata_write_lba_dma(uint64_t sector, size_t count, const uint16_t *buf,
331  int block);
332 
333 /** \brief Flush the write cache on the attached disk.
334 
335  This function flushes the write cache on the disk attached as the slave
336  device on the G1 ATA bus. This ensures that all writes that have previously
337  completed are fully persisted to the disk. You should do this before
338  unmounting any disks or exiting your program if you have called any of the
339  write functions in here.
340 
341  \return 0 on success. <0 on error, setting errno as
342  appropriate.
343 
344  \par Error Conditions:
345  \em ENXIO - ATA support not initialized or no device attached
346 */
347 int g1_ata_flush(void);
348 
349 /** \brief Get a block device for a given partition on the slave ATA device.
350 
351  This function creates a block device descriptor for the given partition on
352  the attached ATA device. This block device is used to interface with various
353  filesystems on the device.
354 
355  \param partition The partition number (0-3) to use.
356  \param dma Set to 1 to use DMA for reads/writes on the device,
357  if available.
358  \param rv Used to return the block device. Must be non-NULL.
359  \param partition_type Used to return the partition type. Must be non-NULL.
360  \retval 0 On success.
361  \retval -1 On error, errno will be set as appropriate.
362 
363  \par Error Conditions:
364  \em ENXIO - ATA support not initialized or no device attached \n
365  \em EIO - an I/O error occurred in reading data \n
366  \em EINVAL - invalid partition number was given \n
367  \em EFAULT - rv or partition_type was NULL \n
368  \em ENOENT - no MBR found \n
369  \em ENOENT - no partition at the specified position \n
370  \em ENOMEM - out of memory
371 
372  \note This interface currently only supports MBR-formatted disks. There
373  is currently no support for GPT partition tables.
374 */
375 int g1_ata_blockdev_for_partition(int partition, int dma, kos_blockdev_t *rv,
376  uint8_t *partition_type);
377 
378 /** \brief Initialize G1 ATA support.
379 
380  This function initializes the rest of this subsystem and completes a scan of
381  the G1 ATA bus for devices. This function may take a while to complete with
382  some devices. Currently only the slave device is scanned, as the master
383  device should always be the GD-ROM drive.
384 
385  \return 0 on success, <0 on error or if no device is present
386 */
387 int g1_ata_init(void);
388 
389 /** \brief Shut down G1 ATA support.
390 
391  This function shuts down the rest of this subsystem, and attempts to flush
392  the write cache of any attached slave devices. Accessing any ATA devices
393  using this subsystem after this function is called may produce undefined
394  results.
395 */
396 void g1_ata_shutdown(void);
397 
398 #endif /* __DC_G1ATA_H */
kos_blockdev
A simple block device.
Definition: blockdev.h:46
g1_ata_write_lba_dma
int g1_ata_write_lba_dma(uint64_t sector, size_t count, const uint16_t *buf, int block)
DMA Write disk sectors with Linear Block Addressing (LBA).
g1_ata_select_device
uint8_t g1_ata_select_device(uint8_t dev)
Set the active ATA device.
g1_ata_read_chs
int g1_ata_read_chs(uint16_t c, uint8_t h, uint8_t s, size_t count, uint16_t *buf)
Read one or more disk sectors with Cylinder-Head-Sector addressing.
g1_dma_in_progress
int g1_dma_in_progress(void)
Is there a G1 DMA in progress currently?
g1_ata_write_chs
int g1_ata_write_chs(uint16_t c, uint8_t h, uint8_t s, size_t count, const uint16_t *buf)
Write one or more disk sectors with Cylinder-Head-Sector addressing.
g1_ata_blockdev_for_partition
int g1_ata_blockdev_for_partition(int partition, int dma, kos_blockdev_t *rv, uint8_t *partition_type)
Get a block device for a given partition on the slave ATA device.
g1_ata_mutex_unlock
int g1_ata_mutex_unlock(void)
Unlock the G1 ATA mutex.
g1_ata_flush
int g1_ata_flush(void)
Flush the write cache on the attached disk.
blockdev.h
Definitions for a simple block device interface.
g1_ata_mutex_lock
int g1_ata_mutex_lock(void)
Lock the G1 ATA mutex.
g1_ata_init
int g1_ata_init(void)
Initialize G1 ATA support.
g1_ata_read_lba
int g1_ata_read_lba(uint64_t sector, size_t count, uint16_t *buf)
Read one or more disk sectors with Linear Block Addressing (LBA).
g1_ata_shutdown
void g1_ata_shutdown(void)
Shut down G1 ATA support.
g1_ata_read_lba_dma
int g1_ata_read_lba_dma(uint64_t sector, size_t count, uint16_t *buf, int block)
DMA read disk sectors with Linear Block Addressing (LBA).
g1_ata_write_lba
int g1_ata_write_lba(uint64_t sector, size_t count, const uint16_t *buf)
Write one or more disk sectors with Linear Block Addressing (LBA).
Generated by   doxygen 1.8.7