KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
g2bus.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 g2bus.h
4 Copyright (C) 2002 Megan Potter
5 Copyright (C) 2023 Andy Barajas
6
7*/
8
9/** \file dc/g2bus.h
10 \brief G2 bus memory interface.
11 \ingroup system_g2bus
12
13 This file provides low-level support for accessing devices on the G2 bus in
14 the Dreamcast. The G2 bus contains the AICA, as well as the expansion port.
15 Generally, you won't be dealing with things at this level, but rather on the
16 level of the device you're actually interested in working with. Most of the
17 expansion port devices (the modem, bba, and lan adapter) all have their own
18 drivers that work off of this functionality.
19
20 The G2 bus is notoroiously picky about a lot of things. You have to be
21 careful to use the right access size for whatever you're working with. Also
22 you can't be doing PIO and DMA at the same time. Finally, there's a FIFO to
23 contend with when you're doing PIO stuff as well. Generally, G2 is a pain in
24 the rear, so you really do want to be using the higher-level stuff related
25 to each device if at all possible!
26
27 \author Megan Potter
28 \author Andy Barajas
29*/
30
31#ifndef __DC_G2BUS_H
32#define __DC_G2BUS_H
33
34#include <sys/cdefs.h>
35__BEGIN_DECLS
36
37#include <stdint.h>
38#include <arch/irq.h>
39#include <arch/types.h>
40
41#include <dc/fifo.h>
42
43/** \defgroup system_g2bus G2 Bus
44 \brief Driver for accessing the devices on the G2 Bus
45 \ingroup system
46
47 @{
48*/
49
50/** \name List of G2 Bus channels
51
52 AICA (SPU) is channel 0, BBA uses channel 1. CH2_DMA_G2CHN and
53 CH3_DMA_G2CHN are not currently tied to any specific device.
54
55 \note
56 A change in the implementation has rendered *_DMA_MODE and *_DMA_SHCHN
57 obsolete.
58
59 In the current implementation, *_DMA_MODE should always be set to zero
60 (representing CPU_TRIGGER). There is also no involvement of SH4-DMA with
61 G2-DMA; therefore, the *_DMA_SHCHN values have been deprecated.
62
63 @{
64*/
65#define G2_DMA_CHAN_SPU 0 /**< \brief AICA: G2 channel 0 */
66#define G2_DMA_CHAN_BBA 1 /**< \brief BBA: G2 channel 1 */
67#define G2_DMA_CHAN_CH2 2 /**< \brief CH2: G2 channel 2 */
68#define G2_DMA_CHAN_CH3 3 /**< \brief CH3: G2 channel 3 */
69/** @} */
70
71/** \brief G2Bus DMA direction
72
73 The direction you want the data to go. SH4 to AICA, BBA, etc use
74 SH4TOG2BUS, otherwise G2BUSTOSH4.
75*/
76#define G2_DMA_TO_G2 0
77#define G2_DMA_TO_SH4 1
78
79/** \brief G2Bus DMA interrupt callback type.
80
81 Functions that act as callbacks when G2-DMA completes should be of this type.
82 These functions will be called inside an interrupt context, so don't try to
83 use anything that might stall.
84
85 \param data User data passed in to the g2_dma_transfer()
86 function.
87*/
88typedef void (*g2_dma_callback_t)(void *data);
89
90/** \brief Perform a DMA transfer between SH-4 RAM and G2 Bus
91
92 This function copies a block of data between SH-4 RAM and G2 Bus via DMA.
93 You specify the direction of the copy (SH4TOG2BUS/G2BUSTOSH4). There are all
94 kinds of constraints that must be fulfilled to actually do this, so
95 make sure to read all the fine print with the parameter list.
96
97 If a callback is specified, it will be called in an interrupt context, so
98 keep that in mind in writing the callback.
99
100 \param sh4 Where to copy from/to. Must be 32-byte aligned.
101 \param g2bus Where to copy from/to. Must be 32-byte aligned.
102 \param length The number of bytes to copy. Must be a multiple of
103 32.
104 \param block Non-zero if you want the function to block until the
105 DMA completes.
106 \param callback A function to call upon completion of the DMA.
107 \param cbdata Data to pass to the callback function.
108 \param dir SH4TOG2BUS or G2BUSTOSH4.
109 \param mode Ignored; for compatibility only.
110 \param g2chn See g2b_channels.
111 \param sh4chn Ignored; for compatibility only.
112 \retval 0 On success.
113 \retval -1 On failure. Sets errno as appropriate.
114
115 \par Error Conditions:
116 \em EINPROGRESS - DMA already in progress \n
117 \em EFAULT - sh4 and/or g2bus is not 32-byte aligned \n
118 \em EINVAL - Invalid g2chn
119 \em EIO - I/O error
120
121*/
122int g2_dma_transfer(void *sh4, void *g2bus, size_t length, uint32_t block,
123 g2_dma_callback_t callback, void *cbdata,
124 uint32_t dir, uint32_t mode, uint32_t g2chn, uint32_t sh4chn);
125
126/** \brief Initialize DMA support.
127
128 This function sets up the DMA support for transfers to/from the G2 Bus.
129
130 \retval 0 On success (no error conditions defined).
131*/
132int g2_dma_init(void);
133
134/** \brief Shutdown DMA support. */
136
137/** \brief G2 context
138
139 A G2 context containing the states of IRQs and G2 DMA. This struct
140 is used in with g2_lock() and g2_unlock().
141*/
142typedef struct {
143 int irq_state; /** \brief IRQ state when entering a G2 critical block */
144} g2_ctx_t;
145
146/* Internal constants to access suspend registers for G2 DMA. They are not meant for
147 user-code use. */
148/** \cond */
149#define G2_DMA_SUSPEND_SPU (*((vuint32 *)0xa05f781C))
150#define G2_DMA_SUSPEND_BBA (*((vuint32 *)0xa05f783C))
151#define G2_DMA_SUSPEND_CH2 (*((vuint32 *)0xa05f785C))
152/** \endcond */
153
154/** \brief Disable IRQs and G2 DMA
155
156 This function makes the following g2_read_*()/g2_write_*() functions atomic
157 by disabling IRQs and G2 DMA and storing their states. Pass the context
158 created by this function to g2_unlock() to re-enable IRQs and G2 DMA.
159
160 \return The context containing the IRQ and G2 DMA states.
161*/
162static inline g2_ctx_t g2_lock(void) {
163 g2_ctx_t ctx;
164
165 ctx.irq_state = irq_disable();
166
167 /* Suspend any G2 DMA */
168 G2_DMA_SUSPEND_SPU = 1;
169 G2_DMA_SUSPEND_BBA = 1;
170 G2_DMA_SUSPEND_CH2 = 1;
171
172 while(FIFO_STATUS & (FIFO_SH4 | FIFO_G2));
173
174 return ctx;
175}
176
177/** \brief Enable IRQs and G2 DMA
178
179 This function restores the IRQ and G2 DMA states using the context value
180 generated by g2_lock().
181
182 \param ctx The context containing IRQ and G2 DMA states.
183*/
184static inline void g2_unlock(g2_ctx_t ctx) {
185 /* Restore suspended G2 DMA */
186 G2_DMA_SUSPEND_SPU = 0;
187 G2_DMA_SUSPEND_BBA = 0;
188 G2_DMA_SUSPEND_CH2 = 0;
189
191}
192
193
194#undef G2_DMA_SUSPEND_SPU
195#undef G2_DMA_SUSPEND_BBA
196#undef G2_DMA_SUSPEND_CH2
197
198/** \brief Read one byte from G2.
199
200 This function reads a single byte from the specified address, taking all
201 necessary precautions that are required for accessing G2.
202
203 \param address The address in memory to read.
204 \return The byte read from the address specified.
205*/
206uint8_t g2_read_8(uintptr_t address);
207
208/** \brief Write a single byte to G2.
209
210 This function writes one byte to the specified address, taking all the
211 necessary precautions to ensure your write actually succeeds.
212
213 \param address The address in memory to write to.
214 \param value The value to write to that address.
215*/
216void g2_write_8(uintptr_t address, uint8_t value);
217
218/** \brief Read one 16-bit word from G2.
219
220 This function reads a single word from the specified address, taking all
221 necessary precautions that are required for accessing G2.
222
223 \param address The address in memory to read.
224 \return The word read from the address specified.
225*/
226uint16 g2_read_16(uintptr_t address);
227
228/** \brief Write a 16-bit word to G2.
229
230 This function writes one word to the specified address, taking all the
231 necessary precautions to ensure your write actually succeeds.
232
233 \param address The address in memory to write to.
234 \param value The value to write to that address.
235*/
236void g2_write_16(uintptr_t address, uint16_t value);
237
238/** \brief Read one 32-bit dword from G2.
239
240 This function reads a single dword from the specified address, taking all
241 necessary precautions that are required for accessing G2.
242
243 \param address The address in memory to read.
244 \return The dword read from the address specified.
245*/
246uint32_t g2_read_32(uintptr_t address);
247
248/** \brief Write a 32-bit dword to G2.
249
250 This function writes one dword to the specified address, taking all the
251 necessary precautions to ensure your write actually succeeds.
252
253 \param address The address in memory to write to.
254 \param value The value to write to that address.
255*/
256void g2_write_32(uintptr_t address, uint32_t value);
257
258/** \brief Read a block of bytes from G2.
259
260 This function acts as memcpy() for copying data from G2 to system memory. It
261 will take the necessary precautions before accessing G2 for you as well.
262
263 \param output Pointer in system memory to write to.
264 \param address The address in G2-space to read from.
265 \param amt The number of bytes to read.
266*/
267void g2_read_block_8(uint8_t * output, uintptr_t address, size_t amt);
268
269/** \brief Write a block of bytes to G2.
270
271 This function acts as memcpy() for copying data to G2 from system memory. It
272 will take the necessary precautions for accessing G2.
273
274 \param input The pointer in system memory to read from.
275 \param address The address in G2-space to write to.
276 \param amt The number of bytes to write.
277*/
278void g2_write_block_8(const uint8_t * input, uintptr_t address, size_t amt);
279
280/** \brief Read a block of words from G2.
281
282 This function acts as memcpy() for copying data from G2 to system memory,
283 but it copies 16 bits at a time. It will take the necessary precautions
284 before accessing G2 for you as well.
285
286 \param output Pointer in system memory to write to.
287 \param address The address in G2-space to read from.
288 \param amt The number of words to read.
289*/
290void g2_read_block_16(uint16_t * output, uintptr_t address, size_t amt);
291
292/** \brief Write a block of words to G2.
293
294 This function acts as memcpy() for copying data to G2 from system memory,
295 copying 16 bits at a time. It will take the necessary precautions for
296 accessing G2.
297
298 \param input The pointer in system memory to read from.
299 \param address The address in G2-space to write to.
300 \param amt The number of words to write.
301*/
302void g2_write_block_16(const uint16_t * input, uintptr_t address, size_t amt);
303
304/** \brief Read a block of dwords from G2.
305
306 This function acts as memcpy() for copying data from G2 to system memory,
307 but it copies 32 bits at a time. It will take the necessary precautions
308 before accessing G2 for you as well.
309
310 \param output Pointer in system memory to write to.
311 \param address The address in G2-space to read from.
312 \param amt The number of dwords to read.
313*/
314void g2_read_block_32(uint32_t * output, uintptr_t address, size_t amt);
315
316/** \brief Write a block of dwords to G2.
317
318 This function acts as memcpy() for copying data to G2 from system memory,
319 copying 32 bits at a time. It will take the necessary precautions for
320 accessing G2.
321
322 \param input The pointer in system memory to read from.
323 \param address The address in G2-space to write to.
324 \param amt The number of dwords to write.
325*/
326void g2_write_block_32(const uint32_t * input, uintptr_t address, size_t amt);
327
328/** \brief Set a block of bytes to G2.
329
330 This function acts as memset() for setting a block of bytes on G2. It will
331 take the necessary precautions for accessing G2.
332
333 \param address The address in G2-space to write to.
334 \param c The byte to write.
335 \param amt The number of bytes to write.
336*/
337void g2_memset_8(uintptr_t address, uint8_t c, size_t amt);
338
339/** \brief Wait for the G2 write FIFO to empty.
340
341 This function will spinwait until the G2 FIFO indicates that it has been
342 drained. The FIFO is 32 bytes in length, and thus when accessing AICA you
343 must do this at least for every 8 32-bit writes that you execute.
344*/
345void g2_fifo_wait(void);
346
347/** @} */
348
349__END_DECLS
350
351#endif /* __DC_G2BUS_H */
352
Macros to assess FIFO status.
void irq_restore(irq_mask_t v)
Restore IRQ state.
irq_mask_t irq_disable(void)
Disable interrupts.
#define FIFO_G2
Definition fifo.h:53
#define FIFO_SH4
Definition fifo.h:54
#define FIFO_STATUS
Address of the FIFO status register.
Definition fifo.h:35
void g2_write_32(uintptr_t address, uint32_t value)
Write a 32-bit dword to G2.
uint16 g2_read_16(uintptr_t address)
Read one 16-bit word from G2.
static void g2_unlock(g2_ctx_t ctx)
Enable IRQs and G2 DMA.
Definition g2bus.h:184
void g2_read_block_16(uint16_t *output, uintptr_t address, size_t amt)
Read a block of words from G2.
void g2_write_block_8(const uint8_t *input, uintptr_t address, size_t amt)
Write a block of bytes to G2.
int g2_dma_init(void)
Initialize DMA support.
void g2_memset_8(uintptr_t address, uint8_t c, size_t amt)
Set a block of bytes to G2.
static g2_ctx_t g2_lock(void)
Disable IRQs and G2 DMA.
Definition g2bus.h:162
void(* g2_dma_callback_t)(void *data)
G2Bus DMA interrupt callback type.
Definition g2bus.h:88
void g2_write_8(uintptr_t address, uint8_t value)
Write a single byte to G2.
int g2_dma_transfer(void *sh4, void *g2bus, size_t length, uint32_t block, g2_dma_callback_t callback, void *cbdata, uint32_t dir, uint32_t mode, uint32_t g2chn, uint32_t sh4chn)
Perform a DMA transfer between SH-4 RAM and G2 Bus.
void g2_write_16(uintptr_t address, uint16_t value)
Write a 16-bit word to G2.
uint32_t g2_read_32(uintptr_t address)
Read one 32-bit dword from G2.
uint8_t g2_read_8(uintptr_t address)
Read one byte from G2.
void g2_read_block_8(uint8_t *output, uintptr_t address, size_t amt)
Read a block of bytes from G2.
void g2_dma_shutdown(void)
Shutdown DMA support.
void g2_write_block_16(const uint16_t *input, uintptr_t address, size_t amt)
Write a block of words to G2.
void g2_write_block_32(const uint32_t *input, uintptr_t address, size_t amt)
Write a block of dwords to G2.
void g2_read_block_32(uint32_t *output, uintptr_t address, size_t amt)
Read a block of dwords from G2.
void g2_fifo_wait(void)
Wait for the G2 write FIFO to empty.
unsigned short uint16
16-bit unsigned integer
Definition types.h:34
Interrupt and exception handling.
G2 context.
Definition g2bus.h:142
int irq_state
Definition g2bus.h:143
Common integer types.