KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
cdrom.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  dc/cdrom.h
4  (c)2000-2001 Dan Potter
5 
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 normal
29  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 thanks 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_status_values CD-ROM status values
95 
96  These are the values that can be returned as the status parameter from the
97  cdrom_get_status() function.
98  @{
99 */
100 #define CD_STATUS_BUSY 0 /**< \brief Drive is busy */
101 #define CD_STATUS_PAUSED 1 /**< \brief Disc is paused */
102 #define CD_STATUS_STANDBY 2 /**< \brief Drive is in standby */
103 #define CD_STATUS_PLAYING 3 /**< \brief Drive is currently playing */
104 #define CD_STATUS_SEEKING 4 /**< \brief Drive is currently seeking */
105 #define CD_STATUS_SCANNING 5 /**< \brief Drive is scanning */
106 #define CD_STATUS_OPEN 6 /**< \brief Disc tray is open */
107 #define CD_STATUS_NO_DISC 7 /**< \brief No disc inserted */
108 /** @} */
109 
110 /** \defgroup cd_disc_types CD-ROM drive disc types
111 
112  These are the values that can be returned as the disc_type parameter from
113  the cdrom_get_status() function.
114  @{
115 */
116 #define CD_CDDA 0 /**< \brief Audio CD (Red book) */
117 #define CD_CDROM 0x10 /**< \brief CD-ROM or CD-R (Yellow book) */
118 #define CD_CDROM_XA 0x20 /**< \brief CD-ROM XA (Yellow book extension) */
119 #define CD_CDI 0x30 /**< \brief CD-i (Green book) */
120 #define CD_GDROM 0x80 /**< \brief GD-ROM */
121 /** @} */
122 
123 /** \brief TOC structure returned by the BIOS.
124 
125  This is the structure that the CMD_GETTOC2 syscall command will return for
126  the TOC. Note the data is in FAD, not LBA/LSN.
127 
128  \headerfile dc/cdrom.h
129 */
130 typedef struct {
131  uint32 entry[99]; /**< \brief TOC space for 99 tracks */
132  uint32 first; /**< \brief Point A0 information (1st track) */
133  uint32 last; /**< \brief Point A1 information (last track) */
134  uint32 leadout_sector; /**< \brief Point A2 information (leadout) */
135 } CDROM_TOC;
136 
137 /** \defgroup cd_toc_access CD-ROM TOC access macros
138  @{
139 */
140 /** \brief Get the FAD address of a TOC entry.
141  \param n The actual entry from the TOC to look at.
142  \return The FAD of the entry.
143 */
144 #define TOC_LBA(n) ((n) & 0x00ffffff)
145 
146 /** \brief Get the address of a TOC entry.
147  \param n The entry from the TOC to look at.
148  \return The entry's address.
149 */
150 #define TOC_ADR(n) ( ((n) & 0x0f000000) >> 24 )
151 
152 /** \brief Get the control data of a TOC entry.
153  \param n The entry from the TOC to look at.
154  \return The entry's control value.
155 */
156 #define TOC_CTRL(n) ( ((n) & 0xf0000000) >> 28 )
157 
158 /** \brief Get the track number of a TOC entry.
159  \param n The entry from the TOC to look at.
160  \return The entry's track.
161 */
162 #define TOC_TRACK(n) ( ((n) & 0x00ff0000) >> 16 )
163 /** @} */
164 
165 /** \brief Set the sector size for read sectors.
166 
167  This function sets the sector size that the cdrom_read_sectors() function
168  will return. Be sure to set this to the correct value for the type of
169  sectors you're trying to read. Common values are 2048 (for reading CD-ROM
170  sectors) or 2352 (for reading raw sectors).
171 
172  \param size The size of the sector data.
173 */
174 void cdrom_set_sector_size(int size);
175 
176 /** \brief Execute a CD-ROM command.
177 
178  This function executes the specified command using the BIOS syscall for
179  executing GD-ROM commands.
180 
181  \param cmd The command number to execute.
182  \param param Data to pass to the syscall.
183 
184  \return \ref cd_cmd_response
185 */
186 int cdrom_exec_cmd(int cmd, void *param);
187 
188 /** \brief Get the status of the GD-ROM drive.
189 
190  \param status Space to return the drive's status.
191  \param disc_type Space to return the type of disc in the drive.
192 
193  \return \ref cd_cmd_response
194  \see cd_status_values
195  \see cd_disc_types
196 */
197 int cdrom_get_status(int *status, int *disc_type);
198 
199 /** \brief Re-initialize the GD-ROM drive.
200 
201  This function is for reinitializing the GD-ROM drive after a disc change,
202  or something of the like.
203 
204  \return \ref cd_cmd_response
205 */
206 int cdrom_reinit();
207 
208 /** \brief Read the table of contents from the disc.
209 
210  This function reads the TOC from the specified session of the disc.
211 
212  \param toc_buffer Space to store the returned TOC in.
213  \param session The session of the disc to read.
214  \return \ref cd_cmd_response
215 */
216 int cdrom_read_toc(CDROM_TOC *toc_buffer, int session);
217 
218 /** \brief Read one or more sector from a CD-ROM.
219 
220  This function reads the specified number of sectors from the disc, starting
221  where requested. This will respect the size of the sectors set with
222  cdrom_set_sector_size(). The buffer must have enough space to store the
223  specified number of sectors.
224 
225  \param buffer Space to store the read sectors.
226  \param sector The sector to start reading from.
227  \param cnt The number of sectors to read.
228  \return \ref cd_cmd_response
229 */
230 int cdrom_read_sectors(void *buffer, int sector, int cnt);
231 
232 /** \brief Locate the sector of the data track.
233 
234  This function will search the toc for the last entry that has a CTRL value
235  of 4, and return its FAD address.
236 
237  \param toc The TOC to search through.
238  \return The FAD of the track, or 0 if none is found.
239 */
241 
242 /** \brief Play CDDA audio tracks or sectors.
243 
244  This function starts playback of CDDA audio.
245 
246  \param start The track or sector to start playback from.
247  \param end The track or sector to end playback at.
248  \param loops The number of times to repeat (max of 15).
249  \param mode The mode to play (see \ref cdda_read_modes).
250  \return \ref cd_cmd_response
251 */
252 int cdrom_cdda_play(uint32 start, uint32 end, uint32 loops, int mode);
253 
254 /** \brief Pause CDDA audio playback.
255 
256  \return \ref cd_cmd_response
257 */
258 int cdrom_cdda_pause();
259 
260 /** \brief Resume CDDA audio playback after a pause.
261 
262  \return \ref cd_cmd_response
263 */
264 int cdrom_cdda_resume();
265 
266 /** \brief Spin down the CD.
267 
268  This stops the disc in the drive from spinning until it is accessed again.
269 
270  \return \ref cd_cmd_response
271 */
272 int cdrom_spin_down();
273 
274 /** \brief Initialize the GD-ROM for reading CDs.
275 
276  This initializes the CD-ROM reading system, reactivating the drive and
277  handling initial setup of the disc.
278 
279  \retval 0 On success.
280  \retval -1 If cdrom_init() has already been called.
281 */
282 int cdrom_init();
283 
284 /** \brief Shutdown the CD reading system. */
285 void cdrom_shutdown();
286 
287 __END_DECLS
288 
289 #endif /* __DC_CDROM_H */