KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
pvr_dma.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 dc/pvr_dma.h
4 Copyright (C) 2002 Megan Potter
5 Copyright (C) 2014 Lawrence Sebald
6 Copyright (C) 2023 Ruslan Rostovtsev
7 Copyright (C) 2024 Andress Barajas
8*/
9
10/** \file dc/pvr_dma.h
11 \brief PVR/TA DMA interface.
12 \ingroup pvr
13
14 This file provides support for PVR DMA and TA DMA transfers in the
15 Dreamcast. These DMA types can be used independently of each other,
16 and both can operate concurrently. Depending on the transfer method
17 specified, the appropriate DMA mechanism is selected.
18
19 TA DMA (Tile Accelerator DMA): This is a one-way transfer method used
20 primarily for submitting data directly to the Tile Accelerator (TA). It is
21 commonly used for submitting vertex data, texture data, and YUV conversion
22 data.
23
24 PVR DMA (PowerVR DMA): This is a more flexible, two-way transfer mechanism
25 that supports both uploading and downloading data. PVR DMA is used for
26 transferring textures and palette data to VRAM, downloading data from VRAM
27 to the SH4, and for handling register data (e. palettes, fog tables).
28
29 \author Megan Potter
30 \author Roger Cattermole
31 \author Paul Boese
32 \author Brian Paul
33 \author Lawrence Sebald
34 \author Benoit Miller
35 \author Ruslan Rostovtsev
36*/
37
38#ifndef __DC_PVR_DMA_H
39#define __DC_PVR_DMA_H
40
41#include <sys/cdefs.h>
42__BEGIN_DECLS
43
44#include <dc/sq.h>
45
46/* Forward declare pvr_ptr_t to avoid including pvr.h */
47typedef void * pvr_ptr_t;
48
49/** \defgroup pvr_dma DMA
50 \brief PowerVR DMA driver
51 \ingroup pvr
52
53 @{
54*/
55
56/** \defgroup pvr_dma_type Transfer Modes
57 \brief Transfer modes with TA/PVR DMA and Store Queues
58 \ingroup pvr_dma
59
60 @{
61*/
62typedef enum pvr_dma_type {
63 PVR_DMA_VRAM64, /**< \brief Transfer to VRAM using TA bus */
64 PVR_DMA_VRAM32, /**< \brief Transfer to VRAM using TA bus */
65 PVR_DMA_TA, /**< \brief Transfer to the tile accelerator */
66 PVR_DMA_YUV, /**< \brief Transfer to the YUV converter (TA) */
67 PVR_DMA_VRAM32_SB, /**< \brief Transfer to/from VRAM using PVR i/f */
68 PVR_DMA_VRAM64_SB, /**< \brief Transfer to/from VRAM using PVR i/f */
69 PVR_DMA_REGISTERS /**< \brief Transfer to/from PVR registers */
70} pvr_dma_type_t;
71/** @} */
72
73/** \brief PVR DMA interrupt callback type.
74
75 Functions that act as callbacks when DMA completes should be of this type.
76 These functions will be called inside an interrupt context, so don't try to
77 use anything that might stall.
78
79 \param data User data passed in to the pvr_dma_transfer()
80 function.
81*/
82typedef void (*pvr_dma_callback_t)(void *data);
83
84/** \brief Perform a DMA transfer to/from the TA/PVR RAM.
85
86 This function copies a block of data to/from the TA/PVR or its memory via
87 DMA. There are all kinds of constraints that must be fulfilled to actually
88 do this, so make sure to read all the fine print with the parameter list.
89
90 If a callback is specified, it will be called in an interrupt context, so
91 keep that in mind in writing the callback.
92
93 \param src Where to copy from. Must be 32-byte aligned.
94 \param dest Where to copy to. Must be 32-byte aligned.
95 \param count The number of bytes to copy. Must be a multiple of
96 32.
97 \param type The type of DMA transfer to do (see list of modes).
98 \param block Non-zero if you want the function to block until the
99 DMA completes.
100 \param callback A function to call upon completion of the DMA.
101 \param cbdata Data to pass to the callback function.
102 \retval 0 On success.
103 \retval -1 On failure. Sets errno as appropriate.
104
105 \par Error Conditions:
106 \em EINPROGRESS - DMA already in progress \n
107 \em EFAULT - src or dest is not 32-byte aligned \n
108 \em EIO - I/O error
109
110 \see pvr_dma_modes
111*/
112int pvr_dma_transfer(const void *src, void *dest, size_t count,
113 pvr_dma_type_t type, int block,
114 pvr_dma_callback_t callback, void *cbdata);
115
116/** \brief Load a texture using TA DMA.
117
118 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
119 notes that apply to it also apply here.
120
121 \deprecated
122 This function is formally deprecated and should not be used in new code.
123 Instead you should use the pvr_dma_ta_load_txr() function.
124
125 \param src Where to copy from. Must be 32-byte aligned.
126 \param dest Where to copy to. Must be 32-byte aligned.
127 \param count The number of bytes to copy. Must be a multiple of
128 32.
129 \param block Non-zero if you want the function to block until the
130 DMA completes.
131 \param callback A function to call upon completion of the DMA.
132 \param cbdata Data to pass to the callback function.
133 \retval 0 On success.
134 \retval -1 On failure. Sets errno as appropriate.
135
136 \par Error Conditions:
137 \em EINPROGRESS - DMA already in progress \n
138 \em EFAULT - src or dest is not 32-byte aligned \n
139 \em EIO - I/O error
140*/
141int pvr_txr_load_dma(const void *src, pvr_ptr_t dest, size_t count,
142 int block, pvr_dma_callback_t callback, void *cbdata)
143 __depr("Use pvr_dma_ta_load_txr instead.");
144
145/** \brief Load a texture using TA DMA.
146
147 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
148 notes that apply to it also apply here.
149
150 \param src Where to copy from. Must be 32-byte aligned.
151 \param dest Where to copy to. Must be 32-byte aligned.
152 \param count The number of bytes to copy. Must be a multiple of
153 32.
154 \param block Non-zero if you want the function to block until the
155 DMA completes.
156 \param callback A function to call upon completion of the DMA.
157 \param cbdata Data to pass to the callback function.
158 \retval 0 On success.
159 \retval -1 On failure. Sets errno as appropriate.
160
161 \par Error Conditions:
162 \em EINPROGRESS - DMA already in progress \n
163 \em EFAULT - src or dest is not 32-byte aligned \n
164 \em EIO - I/O error
165*/
166int pvr_dma_ta_load_txr(const void *src, pvr_ptr_t dest, size_t count,
167 int block, pvr_dma_callback_t callback, void *cbdata);
168
169/** \brief Load a texture using PVR DMA.
170
171 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
172 notes that apply to it also apply here.
173
174 \param src Where to copy from. Must be 32-byte aligned.
175 \param dest Where to copy to. Must be 32-byte aligned.
176 \param count The number of bytes to copy. Must be a multiple of
177 32.
178 \param block Non-zero if you want the function to block until the
179 DMA completes.
180 \param callback A function to call upon completion of the DMA.
181 \param cbdata Data to pass to the callback function.
182 \retval 0 On success.
183 \retval -1 On failure. Sets errno as appropriate.
184
185 \par Error Conditions:
186 \em EINPROGRESS - DMA already in progress \n
187 \em EFAULT - src or dest is not 32-byte aligned \n
188 \em EIO - I/O error
189*/
190int pvr_dma_rb_load_txr(const void *src, pvr_ptr_t dest, size_t count,
191 int block, pvr_dma_callback_t callback, void *cbdata);
192
193/** \brief Download a texture using PVR DMA.
194
195 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
196 notes that apply to it also apply here.
197
198 \param src Where to copy to. Must be 32-byte aligned.
199 \param dest Where to copy from. Must be 32-byte aligned.
200 \param count The number of bytes to copy. Must be a multiple of
201 32.
202 \param block Non-zero if you want the function to block until the
203 DMA completes.
204 \param callback A function to call upon completion of the DMA.
205 \param cbdata Data to pass to the callback function.
206 \retval 0 On success.
207 \retval -1 On failure. Sets errno as appropriate.
208
209 \par Error Conditions:
210 \em EINPROGRESS - DMA already in progress \n
211 \em EFAULT - src or dest is not 32-byte aligned \n
212 \em EIO - I/O error
213*/
214int pvr_dma_download_txr(const void *src, void *dest, size_t count, int block,
215 pvr_dma_callback_t callback, void *cbdata);
216
217/** \brief Load vertex data to the TA using TA DMA.
218
219 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
220 notes that apply to it also apply here.
221
222 \param src Where to copy from. Must be 32-byte aligned.
223 \param count The number of bytes to copy. Must be a multiple of
224 32.
225 \param block Non-zero if you want the function to block until the
226 DMA completes.
227 \param callback A function to call upon completion of the DMA.
228 \param cbdata Data to pass to the callback function.
229 \retval 0 On success.
230 \retval -1 On failure. Sets errno as appropriate.
231
232 \par Error Conditions:
233 \em EINPROGRESS - DMA already in progress \n
234 \em EFAULT - src is not 32-byte aligned \n
235 \em EIO - I/O error
236 */
237int pvr_dma_load_ta(const void *src, size_t count, int block,
238 pvr_dma_callback_t callback, void *cbdata);
239
240/** \brief Load yuv data to the YUV converter using TA DMA.
241
242 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
243 notes that apply to it also apply here.
244
245 \param src Where to copy from. Must be 32-byte aligned.
246 \param count The number of bytes to copy. Must be a multiple of
247 32.
248 \param block Non-zero if you want the function to block until the
249 DMA completes.
250 \param callback A function to call upon completion of the DMA.
251 \param cbdata Data to pass to the callback function.
252 \retval 0 On success.
253 \retval -1 On failure. Sets errno as appropriate.
254
255 \par Error Conditions:
256 \em EINPROGRESS - DMA already in progress \n
257 \em EFAULT - src is not 32-byte aligned \n
258 \em EIO - I/O error
259*/
260int pvr_dma_yuv_conv(const void *src, size_t count, int block,
261 pvr_dma_callback_t callback, void *cbdata);
262
263/** \brief Checks if the TA DMA is inactive.
264
265 \deprecated
266 This function is formally deprecated, and should not be used in newly
267 written code. Instead, please use pvr_dma_ta_ready().
268
269 \return Non-zero if there is no TA DMA active, thus a DMA
270 can begin or 0 if there is an active DMA.
271*/
272int pvr_dma_ready(void) __depr("Use pvr_dma_ta_ready instead.");
273
274/** \brief Checks if the TA DMA is inactive.
275 \return Non-zero if there is no TA DMA active, thus a DMA
276 can begin or 0 if there is an active DMA.
277*/
278int pvr_dma_ta_ready(void);
279
280/** \brief Checks if the PVR DMA is inactive.
281 \return Non-zero if there is no PVR DMA active, thus a DMA
282 can begin or 0 if there is an active DMA.
283*/
284int pvr_dma_rb_ready(void);
285
286/** \brief Initialize TA/PVR DMA. */
287void pvr_dma_init(void);
288
289/** \brief Shut down TA/PVR DMA. */
290void pvr_dma_shutdown(void);
291
292/** \brief Copy a block of memory to VRAM
293
294 This function is similar to sq_cpy(), but it has been
295 optimized for writing to a destination residing within VRAM.
296
297 \warning
298 This function cannot be used at the same time as a PVR DMA transfer.
299
300 The dest pointer must be at least 32-byte aligned and reside
301 in video memory, the src pointer must be at least 8-byte aligned,
302 and n must be a multiple of 32.
303
304 \param dest The address to copy to (32-byte aligned).
305 \param src The address to copy from (32-bit (8-byte) aligned).
306 \param n The number of bytes to copy (multiple of 32).
307 \param type The type of SQ/DMA transfer to do (see list of modes).
308 \return The original value of dest.
309
310 \sa pvr_sq_set32()
311*/
312void *pvr_sq_load(void *dest, const void *src, size_t n, pvr_dma_type_t type);
313
314/** \brief Set a block of PVR memory to a 16-bit value.
315
316 This function is similar to sq_set16(), but it has been
317 optimized for writing to a destination residing within VRAM.
318
319 \warning
320 This function cannot be used at the same time as a PVR DMA transfer.
321
322 The dest pointer must be at least 32-byte aligned and reside in video
323 memory, n must be a multiple of 32 and only the low 16-bits are used
324 from c.
325
326 \param dest The address to begin setting at (32-byte aligned).
327 \param c The value to set (in the low 16-bits).
328 \param n The number of bytes to set (multiple of 32).
329 \param type The type of SQ/DMA transfer to do (see list of modes).
330 \return The original value of dest.
331
332 \sa pvr_sq_set32()
333*/
334void *pvr_sq_set16(void *dest, uint32_t c, size_t n, pvr_dma_type_t type);
335
336/** \brief Set a block of PVR memory to a 32-bit value.
337
338 This function is similar to sq_set32(), but it has been
339 optimized for writing to a destination residing within VRAM.
340
341 \warning
342 This function cannot be used at the same time as a PVR DMA transfer.
343
344 The dest pointer must be at least 32-byte aligned and reside in video
345 memory, n must be a multiple of 32.
346
347 \param dest The address to begin setting at (32-byte aligned).
348 \param c The value to set.
349 \param n The number of bytes to set (multiple of 32).
350 \param type The type of SQ/DMA transfer to do (see list of modes).
351 \return The original value of dest.
352
353 \sa pvr_sq_set16
354*/
355void *pvr_sq_set32(void *dest, uint32_t c, size_t n, pvr_dma_type_t type);
356
357/** @} */
358
359__END_DECLS
360
361#endif /* __DC_PVR_DMA_H */
pvr_dma_type_t
pvr_dma_type_t
Definition pvr_dma.h:62
PVR_DMA_TA
@ PVR_DMA_TA
Transfer to the tile accelerator.
Definition pvr_dma.h:65
PVR_DMA_VRAM32_SB
@ PVR_DMA_VRAM32_SB
Transfer to/from VRAM using PVR i/f.
Definition pvr_dma.h:67
PVR_DMA_REGISTERS
@ PVR_DMA_REGISTERS
Transfer to/from PVR registers.
Definition pvr_dma.h:69
PVR_DMA_VRAM32
@ PVR_DMA_VRAM32
Transfer to VRAM using TA bus.
Definition pvr_dma.h:64
PVR_DMA_YUV
@ PVR_DMA_YUV
Transfer to the YUV converter (TA)
Definition pvr_dma.h:66
PVR_DMA_VRAM64_SB
@ PVR_DMA_VRAM64_SB
Transfer to/from VRAM using PVR i/f.
Definition pvr_dma.h:68
PVR_DMA_VRAM64
@ PVR_DMA_VRAM64
Transfer to VRAM using TA bus.
Definition pvr_dma.h:63
pvr_dma_ready
int pvr_dma_ready(void) __depr("Use pvr_dma_ta_ready instead.")
Checks if the TA DMA is inactive.
pvr_dma_callback_t
void(* pvr_dma_callback_t)(void *data)
PVR DMA interrupt callback type.
Definition pvr_dma.h:82
pvr_sq_set16
void * pvr_sq_set16(void *dest, uint32_t c, size_t n, pvr_dma_type_t type)
Set a block of PVR memory to a 16-bit value.
pvr_dma_download_txr
int pvr_dma_download_txr(const void *src, void *dest, size_t count, int block, pvr_dma_callback_t callback, void *cbdata)
Download a texture using PVR DMA.
pvr_dma_transfer
int pvr_dma_transfer(const void *src, void *dest, size_t count, pvr_dma_type_t type, int block, pvr_dma_callback_t callback, void *cbdata)
Perform a DMA transfer to/from the TA/PVR RAM.
pvr_sq_set32
void * pvr_sq_set32(void *dest, uint32_t c, size_t n, pvr_dma_type_t type)
Set a block of PVR memory to a 32-bit value.
pvr_sq_load
void * pvr_sq_load(void *dest, const void *src, size_t n, pvr_dma_type_t type)
Copy a block of memory to VRAM.
pvr_dma_ta_ready
int pvr_dma_ta_ready(void)
Checks if the TA DMA is inactive.
pvr_dma_load_ta
int pvr_dma_load_ta(const void *src, size_t count, int block, pvr_dma_callback_t callback, void *cbdata)
Load vertex data to the TA using TA DMA.
pvr_dma_ta_load_txr
int pvr_dma_ta_load_txr(const void *src, pvr_ptr_t dest, size_t count, int block, pvr_dma_callback_t callback, void *cbdata)
Load a texture using TA DMA.
pvr_dma_init
void pvr_dma_init(void)
Initialize TA/PVR DMA.
pvr_dma_yuv_conv
int pvr_dma_yuv_conv(const void *src, size_t count, int block, pvr_dma_callback_t callback, void *cbdata)
Load yuv data to the YUV converter using TA DMA.
pvr_dma_shutdown
void pvr_dma_shutdown(void)
Shut down TA/PVR DMA.
pvr_dma_rb_ready
int pvr_dma_rb_ready(void)
Checks if the PVR DMA is inactive.
pvr_txr_load_dma
int pvr_txr_load_dma(const void *src, pvr_ptr_t dest, size_t count, int block, pvr_dma_callback_t callback, void *cbdata) __depr("Use pvr_dma_ta_load_txr instead.")
Load a texture using TA DMA.
pvr_dma_rb_load_txr
int pvr_dma_rb_load_txr(const void *src, pvr_ptr_t dest, size_t count, int block, pvr_dma_callback_t callback, void *cbdata)
Load a texture using PVR DMA.
pvr_ptr_t
void * pvr_ptr_t
PVR texture memory pointer.
Definition pvr.h:68
__depr
#define __depr(m)
Mark something as deprecated, with an informative message.
Definition cdefs.h:119
pvr_ptr_t
void * pvr_ptr_t
Definition pvr_dma.h:47
sq.h
Functions to access the SH4 Store Queues.