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/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 Falco Girgis
8*/
9
10/** \file dc/pvr/pvr_dma.h
11 \brief API for utilizing the DMA with the PVR for rendering
12 \ingroup pvr_dma
13
14 \author Megan Potter
15 \author Roger Cattermole
16 \author Paul Boese
17 \author Brian Paul
18 \author Lawrence Sebald
19 \author Benoit Miller
20 \author Ruslan Rostovtsev
21 \author Falco Girgis
22
23 \todo
24 - Top level "Transfer" group
25 a. DMA
26 b. SQs
27*/
28
29#ifndef __DC_PVR_PVR_DMA_H
30#define __DC_PVR_PVR_DMA_H
31
32#include <stdint.h>
33#include <stdbool.h>
34
35#include <sys/cdefs.h>
36__BEGIN_DECLS
37
38/** \defgroup pvr_dma DMA
39 \brief PowerVR DMA driver
40 \ingroup pvr
41*/
42
43/** \brief Transfer modes with TA/PVR DMA and Store Queues
44 \ingroup pvr_dma
45*/
46typedef enum pvr_dma_type {
47 PVR_DMA_VRAM64, /**< Transfer to VRAM using TA bus */
48 PVR_DMA_VRAM32, /**< Transfer to VRAM using TA bus */
49 PVR_DMA_TA, /**< Transfer to the tile accelerator */
50 PVR_DMA_YUV, /**< Transfer to the YUV converter (TA) */
51 PVR_DMA_VRAM32_SB, /**< Transfer to/from VRAM using PVR i/f */
52 PVR_DMA_VRAM64_SB /**< Transfer to/from VRAM using PVR i/f */
53} pvr_dma_type_t;
54
55/** \brief PVR DMA interrupt callback type.
56 \ingroup pvr_dma
57
58 Functions that act as callbacks when DMA completes should be of this type.
59 These functions will be called inside an interrupt context, so don't try to
60 use anything that might stall.
61
62 \param data User data passed in to the pvr_dma_transfer()
63 function.
64*/
65typedef void (*pvr_dma_callback_t)(void *data);
66
67/** \brief Perform a DMA transfer to the PVR RAM over 64-bit TA bus.
68 \ingroup pvr_dma
69
70 This function copies a block of data to the PVR or its memory via DMA. There
71 are all kinds of constraints that must be fulfilled to actually do this, so
72 make sure to read all the fine print with the parameter list.
73
74 If a callback is specified, it will be called in an interrupt context, so
75 keep that in mind in writing the callback.
76
77 \param src Where to copy from. Must be 32-byte aligned.
78 \param dest Where to copy to. Must be 32-byte aligned.
79 \param count The number of bytes to copy. Must be a multiple of
80 32.
81 \param type The type of DMA transfer to do (see list of modes).
82 \param block True if you want the function to block until the
83 DMA completes.
84 \param callback A function to call upon completion of the DMA.
85 \param cbdata Data to pass to the callback function.
86 \retval 0 On success.
87 \retval -1 On failure. Sets errno as appropriate.
88
89 \par Error Conditions:
90 \em EINPROGRESS - DMA already in progress \n
91 \em EFAULT - dest is not 32-byte aligned \n
92 \em EIO - I/O error
93*/
94int pvr_dma_transfer(const void *src, uintptr_t dest, size_t count,
95 pvr_dma_type_t type, bool block,
96 pvr_dma_callback_t callback, void *cbdata);
97
98
99/** \brief Load a texture using TA DMA.
100 \ingroup pvr_dma
101
102 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
103 notes that apply to it also apply here.
104
105 \param src Where to copy from. Must be 32-byte aligned.
106 \param dest Where to copy to. Must be 32-byte aligned.
107 \param count The number of bytes to copy. Must be a multiple of
108 32.
109 \param block True if you want the function to block until the
110 DMA completes.
111 \param callback A function to call upon completion of the DMA.
112 \param cbdata Data to pass to the callback function.
113 \retval 0 On success.
114 \retval -1 On failure. Sets errno as appropriate.
115
116 \par Error Conditions:
117 \em EINPROGRESS - DMA already in progress \n
118 \em EFAULT - dest is not 32-byte aligned \n
119 \em EIO - I/O error
120*/
121int pvr_txr_load_dma(const void *src, pvr_ptr_t dest, size_t count, bool block,
122 pvr_dma_callback_t callback, void *cbdata);
123
124/** \brief Load vertex data to the TA using TA DMA.
125 \ingroup pvr_dma
126
127 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
128 notes that apply to it also apply here.
129
130 \param src Where to copy from. Must be 32-byte aligned.
131 \param count The number of bytes to copy. Must be a multiple of
132 32.
133 \param block True if you want the function to block until the
134 DMA completes.
135 \param callback A function to call upon completion of the DMA.
136 \param cbdata Data to pass to the callback function.
137 \retval 0 On success.
138 \retval -1 On failure. Sets errno as appropriate.
139
140 \par Error Conditions:
141 \em EINPROGRESS - DMA already in progress \n
142 \em EFAULT - dest is not 32-byte aligned \n
143 \em EIO - I/O error
144 */
145int pvr_dma_load_ta(const void *src, size_t count, bool block,
146 pvr_dma_callback_t callback, void *cbdata);
147
148/** \brief Load yuv data to the YUV converter using TA DMA.
149 \ingroup pvr_dma
150
151 This is essentially a convenience wrapper for pvr_dma_transfer(), so all
152 notes that apply to it also apply here.
153
154 \param src Where to copy from. Must be 32-byte aligned.
155 \param count The number of bytes to copy. Must be a multiple of
156 32.
157 \param block True if you want the function to block until the
158 DMA completes.
159 \param callback A function to call upon completion of the DMA.
160 \param cbdata Data to pass to the callback function.
161 \retval 0 On success.
162 \retval -1 On failure. Sets errno as appropriate.
163
164 \par Error Conditions:
165 \em EINPROGRESS - DMA already in progress \n
166 \em EFAULT - dest is not 32-byte aligned \n
167 \em EIO - I/O error
168*/
169int pvr_dma_yuv_conv(const void *src, size_t count, bool block,
170 pvr_dma_callback_t callback, void *cbdata);
171
172/** \brief Is PVR DMA is inactive?
173 \ingroup pvr_dma
174 \return True if there is no PVR DMA active, thus a DMA
175 can begin or false if there is an active DMA.
176*/
177bool pvr_dma_ready(void);
178
179/** \brief Initialize TA/PVR DMA.
180 \ingroup pvr_dma
181 */
182void pvr_dma_init(void);
183
184/** \brief Shut down TA/PVR DMA.
185 \ingroup pvr_dma
186 */
187void pvr_dma_shutdown(void);
188
189/** \brief Copy a block of memory to VRAM
190 \ingroup store_queues
191
192 This function is similar to sq_cpy(), but it has been
193 optimized for writing to a destination residing within VRAM.
194
195 \warning
196 This function cannot be used at the same time as a PVR DMA transfer.
197
198 The dest pointer must be at least 32-byte aligned and reside
199 in video memory, the src pointer must be at least 8-byte aligned,
200 and n must be a multiple of 32.
201
202 \param dest The address to copy to (32-byte aligned).
203 \param src The address to copy from (32-bit (8-byte) aligned).
204 \param n The number of bytes to copy (multiple of 32).
205 \param type The type of SQ/DMA transfer to do (see list of modes).
206 \return The original value of dest.
207
208 \sa pvr_sq_set32()
209*/
210void *pvr_sq_load(void *dest, const void *src,
211 size_t n, pvr_dma_type_t type);
212
213/** \brief Set a block of PVR memory to a 16-bit value.
214 \ingroup store_queues
215
216 This function is similar to sq_set16(), but it has been
217 optimized for writing to a destination residing within VRAM.
218
219 \warning
220 This function cannot be used at the same time as a PVR DMA transfer.
221
222 The dest pointer must be at least 32-byte aligned and reside in video
223 memory, n must be a multiple of 32 and only the low 16-bits are used
224 from c.
225
226 \param dest The address to begin setting at (32-byte aligned).
227 \param c The value to set (in the low 16-bits).
228 \param n The number of bytes to set (multiple of 32).
229 \param type The type of SQ/DMA transfer to do (see list of modes).
230 \return The original value of dest.
231
232 \sa pvr_sq_set32()
233*/
234void *pvr_sq_set16(void *dest, uint32_t c, size_t n, pvr_dma_type_t type);
235
236/** \brief Set a block of PVR memory to a 32-bit value.
237 \ingroup store_queues
238
239 This function is similar to sq_set32(), but it has been
240 optimized for writing to a destination residing within VRAM.
241
242 \warning
243 This function cannot be used at the same time as a PVR DMA transfer.
244
245 The dest pointer must be at least 32-byte aligned and reside in video
246 memory, n must be a multiple of 32.
247
248 \param dest The address to begin setting at (32-byte aligned).
249 \param c The value to set.
250 \param n The number of bytes to set (multiple of 32).
251 \param type The type of SQ/DMA transfer to do (see list of modes).
252 \return The original value of dest.
253
254 \sa pvr_sq_set16()
255*/
256void *pvr_sq_set32(void *dest, uint32_t c, size_t n, pvr_dma_type_t type);
257
258__END_DECLS
259
260#endif /* __DC_PVR_PVR_DMA_H */
pvr_dma_yuv_conv
int pvr_dma_yuv_conv(const void *src, size_t count, bool block, pvr_dma_callback_t callback, void *cbdata)
Load yuv data to the YUV converter using TA DMA.
pvr_dma_callback_t
void(* pvr_dma_callback_t)(void *data)
PVR DMA interrupt callback type.
Definition pvr_dma.h:65
pvr_dma_transfer
int pvr_dma_transfer(const void *src, uintptr_t dest, size_t count, pvr_dma_type_t type, bool block, pvr_dma_callback_t callback, void *cbdata)
Perform a DMA transfer to the PVR RAM over 64-bit TA bus.
pvr_txr_load_dma
int pvr_txr_load_dma(const void *src, pvr_ptr_t dest, size_t count, bool block, pvr_dma_callback_t callback, void *cbdata)
Load a texture using TA DMA.
pvr_dma_ready
bool pvr_dma_ready(void)
Is PVR DMA is inactive?
pvr_dma_type_t
pvr_dma_type_t
Transfer modes with TA/PVR DMA and Store Queues.
Definition pvr_dma.h:46
pvr_dma_load_ta
int pvr_dma_load_ta(const void *src, size_t count, bool block, pvr_dma_callback_t callback, void *cbdata)
Load vertex data to the TA using TA DMA.
pvr_dma_init
void pvr_dma_init(void)
Initialize TA/PVR DMA.
pvr_dma_shutdown
void pvr_dma_shutdown(void)
Shut down TA/PVR DMA.
PVR_DMA_TA
@ PVR_DMA_TA
Transfer to the tile accelerator.
Definition pvr_dma.h:49
PVR_DMA_VRAM32_SB
@ PVR_DMA_VRAM32_SB
Transfer to/from VRAM using PVR i/f.
Definition pvr_dma.h:51
PVR_DMA_VRAM32
@ PVR_DMA_VRAM32
Transfer to VRAM using TA bus.
Definition pvr_dma.h:48
PVR_DMA_YUV
@ PVR_DMA_YUV
Transfer to the YUV converter (TA)
Definition pvr_dma.h:50
PVR_DMA_VRAM64_SB
@ PVR_DMA_VRAM64_SB
Transfer to/from VRAM using PVR i/f.
Definition pvr_dma.h:52
PVR_DMA_VRAM64
@ PVR_DMA_VRAM64
Transfer to VRAM using TA bus.
Definition pvr_dma.h:47
pvr_ptr_t
void * pvr_ptr_t
PVR texture memory pointer.
Definition pvr_mem.h:45
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_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.