KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
cdrom.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dc/cdrom.h
4  Copyright (C) 2000-2001 Dan Potter
5  Copyright (C) 2014 Donald Haase
6 */
7 
8 #ifndef __DC_CDROM_H
9 #define __DC_CDROM_H
10 
11 #include <sys/cdefs.h>
12 __BEGIN_DECLS
13 
14 #include <arch/types.h>
15 
16 /** \file dc/cdrom.h
17  \brief CD access to the GD-ROM drive.
18 
19  This file contains the interface to the Dreamcast's GD-ROM drive. It is
20  simply called cdrom.h and cdrom.c because, by design, you cannot directly
21  use this code to read the high-density area of GD-ROMs. This is the way it
22  always has been, and always will be.
23 
24  The way things are set up, as long as you're using fs_iso9660 to access the
25  CD, it will automatically detect and react to disc changes for you.
26 
27  This file only facilitates reading raw sectors and doing other fairly low-
28  level things with CDs. If you're looking for higher-level stuff, like
29  normal file reading, consult with the stuff for the fs and for fs_iso9660.
30 
31  \author Dan Potter
32  \see kos/fs.h
33  \see dc/fs_iso9660.h
34 */
35 
36 /** \defgroup cd_cmd_codes CD-ROM syscall command codes
37 
38  These are the syscall command codes used to actually do stuff with the
39  GD-ROM drive. These were originally provided by maiwe.
40 
41  @{
42 */
43 #define CMD_PIOREAD 16 /**< \brief Read via PIO */
44 #define CMD_DMAREAD 17 /**< \brief Read via DMA */
45 #define CMD_GETTOC 18 /**< \brief Read TOC */
46 #define CMD_GETTOC2 19 /**< \brief Read TOC */
47 #define CMD_PLAY 20 /**< \brief Play track */
48 #define CMD_PLAY2 21 /**< \brief Play sectors */
49 #define CMD_PAUSE 22 /**< \brief Pause playback */
50 #define CMD_RELEASE 23 /**< \brief Resume from pause */
51 #define CMD_INIT 24 /**< \brief Initialize the drive */
52 #define CMD_SEEK 27 /**< \brief Seek to a new position */
53 #define CMD_READ 28 /**< \brief Read raw sectors */
54 #define CMD_STOP 33 /**< \brief Stop the disc from spinning */
55 #define CMD_GETSCD 34 /**< \brief Get subcode data */
56 #define CMD_GETSES 35 /**< \brief Get session */
57 /** @} */
58 
59 /** \defgroup cd_cmd_response CD-ROM command responses
60 
61  These are the values that the various functions can return as error codes.
62  @{
63 */
64 #define ERR_OK 0 /**< \brief No error */
65 #define ERR_NO_DISC 1 /**< \brief No disc in drive */
66 #define ERR_DISC_CHG 2 /**< \brief Disc changed, but not reinitted yet */
67 #define ERR_SYS 3 /**< \brief System error */
68 #define ERR_ABORTED 4 /**< \brief Command aborted */
69 #define ERR_NO_ACTIVE 5 /**< \brief System inactive? */
70 /** @} */
71 
72 /** \defgroup cd_cmd_status CD-ROM Command Status responses
73 
74  These are the raw values the status syscall returns.
75  @{
76 */
77 #define FAILED -1 /**< \brief Command failed */
78 #define NO_ACTIVE 0 /**< \brief System inactive? */
79 #define PROCESSING 1 /**< \brief Processing command */
80 #define COMPLETED 2 /**< \brief Command completed successfully */
81 #define ABORTED 3 /**< \brief Command aborted before completion */
82 /** @} */
83 
84 /** \defgroup cdda_read_modes CDDA read modes
85 
86  Valid values to pass to the cdrom_cdda_play() function for the mode
87  parameter.
88  @{
89 */
90 #define CDDA_TRACKS 1 /**< \brief Play by track number */
91 #define CDDA_SECTORS 2 /**< \brief Play by sector number */
92 /** @} */
93 
94 /** \defgroup cd_read_sector_part CD-ROM Read Sector Part
95 
96  Parts of the a CD-ROM sector to read. These are possible values for the
97  third parameter word sent with the change data type syscall.
98  @{
99 */
100 #define CDROM_READ_WHOLE_SECTOR 0x1000 /**< \brief Read the whole sector */
101 #define CDROM_READ_DATA_AREA 0x2000 /**< \brief Read the data area */
102 /** @} */
103 
104 /** \defgroup cd_read_subcode_type CD-ROM Read Subcode Type
105 
106  Types of data available to read from the sector subcode. These are
107  possible values for the first parameter sent to the GETSCD syscall.
108  @{
109 */
110 #define CD_SUB_Q_CHANNEL 0 /**< \brief Read Q Channel Subcode Data */
111 #define CD_SUB_CURRENT_POSITION 1 /**< \brief Read all Subcode Data for
112  most recent sector */
113 #define CD_SUB_MEDIA_CATALOG 2 /**< \brief Read the Media Catalog
114  Subcode Data */
115 #define CD_SUB_TRACK_ISRC 3 /**< \brief Read the ISRC Subcode Data */
116 /** @} */
118 /** \defgroup cd_read_sector_mode CD-ROM Read Sector Mode
119 
120  How to read the sectors of a CD, via PIO or DMA. 4th parameter of
121  cdrom_read_sectors_ex.
122  @{
123 */
124 #define CDROM_READ_PIO 0 /**< \brief Read sector(s) in PIO mode */
125 #define CDROM_READ_DMA 1 /**< \brief Read sector(s) in DMA mode */
126 /** @} */
128 /** \defgroup cd_status_values CD-ROM status values
129 
130  These are the values that can be returned as the status parameter from the
131  cdrom_get_status() function.
132  @{
133 */
134 #define CD_STATUS_BUSY 0 /**< \brief Drive is busy */
135 #define CD_STATUS_PAUSED 1 /**< \brief Disc is paused */
136 #define CD_STATUS_STANDBY 2 /**< \brief Drive is in standby */
137 #define CD_STATUS_PLAYING 3 /**< \brief Drive is currently playing */
138 #define CD_STATUS_SEEKING 4 /**< \brief Drive is currently seeking */
139 #define CD_STATUS_SCANNING 5 /**< \brief Drive is scanning */
140 #define CD_STATUS_OPEN 6 /**< \brief Disc tray is open */
141 #define CD_STATUS_NO_DISC 7 /**< \brief No disc inserted */
142 /** @} */
144 /** \defgroup cd_disc_types CD-ROM drive disc types
145 
146  These are the values that can be returned as the disc_type parameter from
147  the cdrom_get_status() function.
148  @{
149 */
150 #define CD_CDDA 0 /**< \brief Audio CD (Red book) */
151 #define CD_CDROM 0x10 /**< \brief CD-ROM or CD-R (Yellow book) */
152 #define CD_CDROM_XA 0x20 /**< \brief CD-ROM XA (Yellow book extension) */
153 #define CD_CDI 0x30 /**< \brief CD-i (Green book) */
154 #define CD_GDROM 0x80 /**< \brief GD-ROM */
155 /** @} */
157 /** \brief TOC structure returned by the BIOS.
158 
159  This is the structure that the CMD_GETTOC2 syscall command will return for
160  the TOC. Note the data is in FAD, not LBA/LSN.
161 
162  \headerfile dc/cdrom.h
163 */
164 typedef struct {
165  uint32 entry[99]; /**< \brief TOC space for 99 tracks */
166  uint32 first; /**< \brief Point A0 information (1st track) */
167  uint32 last; /**< \brief Point A1 information (last track) */
168  uint32 leadout_sector; /**< \brief Point A2 information (leadout) */
171 /** \defgroup cd_toc_access CD-ROM TOC access macros
172  @{
173 */
174 /** \brief Get the FAD address of a TOC entry.
175  \param n The actual entry from the TOC to look at.
176  \return The FAD of the entry.
177 */
178 #define TOC_LBA(n) ((n) & 0x00ffffff)
179 
180 /** \brief Get the address of a TOC entry.
181  \param n The entry from the TOC to look at.
182  \return The entry's address.
183 */
184 #define TOC_ADR(n) ( ((n) & 0x0f000000) >> 24 )
185 
186 /** \brief Get the control data of a TOC entry.
187  \param n The entry from the TOC to look at.
188  \return The entry's control value.
189 */
190 #define TOC_CTRL(n) ( ((n) & 0xf0000000) >> 28 )
191 
192 /** \brief Get the track number of a TOC entry.
193  \param n The entry from the TOC to look at.
194  \return The entry's track.
195 */
196 #define TOC_TRACK(n) ( ((n) & 0x00ff0000) >> 16 )
197 /** @} */
199 /** \brief Set the sector size for read sectors.
200 
201  This function sets the sector size that the cdrom_read_sectors() function
202  will return. Be sure to set this to the correct value for the type of
203  sectors you're trying to read. Common values are 2048 (for reading CD-ROM
204  sectors) or 2352 (for reading raw sectors).
205 
206  \param size The size of the sector data.
207 
208  \return \ref cd_cmd_response
209 */
210 int cdrom_set_sector_size(int size);
211 
212 /** \brief Execute a CD-ROM command.
213 
214  This function executes the specified command using the BIOS syscall for
215  executing GD-ROM commands. This is now thread-safe to be called by users.
216 
217  \param cmd The command number to execute.
218  \param param Data to pass to the syscall.
219 
220  \return \ref cd_cmd_response
221 */
222 int cdrom_exec_cmd(int cmd, void *param);
223 
224 /** \brief Get the status of the GD-ROM drive.
225 
226  \param status Space to return the drive's status.
227  \param disc_type Space to return the type of disc in the drive.
228 
229  \return \ref cd_cmd_response
230  \see cd_status_values
231  \see cd_disc_types
232 */
233 int cdrom_get_status(int *status, int *disc_type);
234 
235 /** \brief Change the datatype of disc.
236 
237  This function will take in all parameters to pass to the change_datatype
238  syscall. This allows these parameters to be modified without a reinit.
239  Each parameter allows -1 as a default, which is tied to the former static
240  values provided by cdrom_reinit and cdrom_set_sector_size.
241 
242  \param sector_part How much of each sector to return.
243  \param cdxa What CDXA mode to read as (if applicable).
244  \param sector_size What sector size to read (eg. - 2048, 2532).
245 
246  \return \ref cd_cmd_response
247  \see cd_read_sector_part
248 */
249 int cdrom_change_dataype(int sector_part, int cdxa, int sector_size);
250 
251 /** \brief Re-initialize the GD-ROM drive.
252 
253  This function is for reinitializing the GD-ROM drive after a disc change to
254  its default settings. Calls cdrom_reinit(-1,-1,-1)
255 
256  \return \ref cd_cmd_response
257  \see cdrom_reinit_ex
258 */
259 int cdrom_reinit();
260 
261 /** \brief Re-initialize the GD-ROM drive with custom parameters.
262 
263  At the end of each cdrom_reinit(), cdrom_change_datatype is called.
264  This passes in the requested values to that function after
265  reinitialization, as opposed to defaults.
266 
267  \param sector_part How much of each sector to return.
268  \param cdxa What CDXA mode to read as (if applicable).
269  \param sector_size What sector size to read (eg. - 2048, 2532).
270 
271  \return \ref cd_cmd_response
272  \see cd_read_sector_part
273  \see cdrom_change_datatype
274 */
275 int cdrom_reinit_ex(int sector_part, int cdxa, int sector_size);
276 
277 /** \brief Read the table of contents from the disc.
278 
279  This function reads the TOC from the specified session of the disc.
280 
281  \param toc_buffer Space to store the returned TOC in.
282  \param session The session of the disc to read.
283  \return \ref cd_cmd_response
284 */
285 int cdrom_read_toc(CDROM_TOC *toc_buffer, int session);
286 
287 /** \brief Read one or more sector from a CD-ROM.
288 
289  This function reads the specified number of sectors from the disc, starting
290  where requested. This will respect the size of the sectors set with
291  cdrom_change_dataype(). The buffer must have enough space to store the
292  specified number of sectors.
293 
294  \param buffer Space to store the read sectors.
295  \param sector The sector to start reading from.
296  \param cnt The number of sectors to read.
297  \param mode DMA or PIO
298  \return \ref cd_cmd_response
299  \see cd_read_sector_mode
300 */
301 int cdrom_read_sectors_ex(void *buffer, int sector, int cnt, int mode);
302 
303 /** \brief Read one or more sector from a CD-ROM in PIO mode.
304 
305  Default version of cdrom_read_sectors_ex, which forces PIO mode.
306 
307  \param buffer Space to store the read sectors.
308  \param sector The sector to start reading from.
309  \param cnt The number of sectors to read.
310  \return \ref cd_cmd_response
311  \see cdrom_read_sectors_ex
312 */
313 int cdrom_read_sectors(void *buffer, int sector, int cnt);
314 
315 /** \brief Read subcode data from the most recently read sectors.
316 
317  After reading sectors, this can pull subcode data regarding the sectors
318  read. If reading all subcode data with CD_SUB_CURRENT_POSITION, this needs
319  to be performed one sector at a time.
320 
321  \param buffer Space to store the read subcode data.
322  \param buflen Amount of data to be read.
323  \param which Which subcode type do you wish to get.
324 
325  \return \ref cd_cmd_response
326  \see cd_read_subcode_type
327 */
328 int cdrom_get_subcode(void *buffer, int buflen, int which);
329 
330 /** \brief Locate the sector of the data track.
331 
332  This function will search the toc for the last entry that has a CTRL value
333  of 4, and return its FAD address.
334 
335  \param toc The TOC to search through.
336  \return The FAD of the track, or 0 if none is found.
337 */
339 
340 /** \brief Play CDDA audio tracks or sectors.
341 
342  This function starts playback of CDDA audio.
343 
344  \param start The track or sector to start playback from.
345  \param end The track or sector to end playback at.
346  \param loops The number of times to repeat (max of 15).
347  \param mode The mode to play (see \ref cdda_read_modes).
348  \return \ref cd_cmd_response
349 */
350 int cdrom_cdda_play(uint32 start, uint32 end, uint32 loops, int mode);
351 
352 /** \brief Pause CDDA audio playback.
353 
354  \return \ref cd_cmd_response
355 */
356 int cdrom_cdda_pause();
357 
358 /** \brief Resume CDDA audio playback after a pause.
359 
360  \return \ref cd_cmd_response
361 */
362 int cdrom_cdda_resume();
363 
364 /** \brief Spin down the CD.
365 
366  This stops the disc in the drive from spinning until it is accessed again.
367 
368  \return \ref cd_cmd_response
369 */
370 int cdrom_spin_down();
371 
372 /** \brief Initialize the GD-ROM for reading CDs.
373 
374  This initializes the CD-ROM reading system, reactivating the drive and
375  handling initial setup of the disc.
376 
377  \retval 0 On success.
378  \retval -1 Already initted, shutdown before initting again.
379 */
380 int cdrom_init();
381 
382 /** \brief Shutdown the CD reading system. */
383 void cdrom_shutdown();
384 
385 __END_DECLS
386 
387 #endif /* __DC_CDROM_H */
int cdrom_reinit()
Re-initialize the GD-ROM drive.
Common integer types.
void cdrom_shutdown()
Shutdown the CD reading system.
TOC structure returned by the BIOS.
Definition: cdrom.h:166
int cdrom_read_sectors_ex(void *buffer, int sector, int cnt, int mode)
Read one or more sector from a CD-ROM.
int cdrom_set_sector_size(int size)
Set the sector size for read sectors.
int cdrom_read_sectors(void *buffer, int sector, int cnt)
Read one or more sector from a CD-ROM in PIO mode.
int cdrom_init()
Initialize the GD-ROM for reading CDs.
int cdrom_exec_cmd(int cmd, void *param)
Execute a CD-ROM command.
int cdrom_cdda_pause()
Pause CDDA audio playback.
uint32 cdrom_locate_data_track(CDROM_TOC *toc)
Locate the sector of the data track.
int cdrom_change_dataype(int sector_part, int cdxa, int sector_size)
Change the datatype of disc.
int cdrom_cdda_resume()
Resume CDDA audio playback after a pause.
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
int cdrom_cdda_play(uint32 start, uint32 end, uint32 loops, int mode)
Play CDDA audio tracks or sectors.
int cdrom_get_status(int *status, int *disc_type)
Get the status of the GD-ROM drive.
int cdrom_read_toc(CDROM_TOC *toc_buffer, int session)
Read the table of contents from the disc.
int cdrom_reinit_ex(int sector_part, int cdxa, int sector_size)
Re-initialize the GD-ROM drive with custom parameters.
int cdrom_get_subcode(void *buffer, int buflen, int which)
Read subcode data from the most recently read sectors.
int cdrom_spin_down()
Spin down the CD.