KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
sq.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 kernel/arch/dreamcast/include/dc/sq.h
4 Copyright (C) 2000-2001 Andrew Kieschnick
5 Copyright (C) 2023 Falco Girgis
6 Copyright (C) 2023 Ruslan Rostovtsev
7 Copyright (C) 2023-2024 Andy Barajas
8*/
9
10/** \file dc/sq.h
11 \ingroup store_queues
12 \brief Functions to access the SH4 Store Queues.
13
14 \author Andrew Kieschnick
15 \author Falco Girgis
16 \author Andy Barajas
17 \author Ruslan Rostovtsev
18*/
19
20/** \defgroup store_queues Store Queues
21 \brief SH4 CPU Peripheral for burst memory transactions.
22 \ingroup system
23
24 The store queues are a way to do efficient burst transfers from the CPU to
25 external memory. They can be used in a variety of ways, such as to transfer
26 a texture to PVR memory. The transfers are in units of 32-bytes, and the
27 destinations must be 32-byte aligned.
28
29 \note
30 Mastery over knowing when and how to utilize the store queues is
31 important when trying to push the limits of the Dreamcast, specifically
32 when transferring chunks of data between regions of memory. It is often
33 the case that the DMA is faster for transactions which are consistently
34 large; however, the store queues tend to have better performance and
35 have less configuration overhead when bursting smaller chunks of data.
36*/
37
38#ifndef __DC_SQ_H
39#define __DC_SQ_H
40
41#include <sys/cdefs.h>
42__BEGIN_DECLS
43
44#include <stdint.h>
45#include <arch/types.h>
46#include <arch/memory.h>
47#include <arch/cache.h>
48
49/** \brief Mask dest to Store Queue area as address
50 \ingroup store_queues
51*/
52#define SQ_MASK_DEST_ADDR(dest) \
53 (MEM_AREA_SQ_BASE | ((uintptr_t)(dest) & 0x03ffffe0))
54
55/** \brief Mask dest to Store Queue area as pointer
56 \ingroup store_queues
57*/
58#define SQ_MASK_DEST(dest) \
59 ((uint32_t *)(void *) SQ_MASK_DEST_ADDR(dest))
60
61/** \brief Lock Store Queues
62 \ingroup store_queues
63
64 Locks the store queues so that they cannot be used from another thread
65 until unlocked.
66
67 \warning
68 This function is called automatically by the store queue API provided by KOS;
69 however, it must be called manually when driving the SQs directly from outside
70 of this API.
71
72 \sa sq_unlock()
73*/
74void sq_lock(void *dest);
75
76/** \brief Unlock Store Queues
77 \ingroup store_queues
78
79 Unlocks the store queues so that they can be used from any thread.
80
81 \note
82 sq_lock() should've already been called previously.
83
84 \warning
85 sq_lock() and sq_unlock() are called automatically by the store queue API provided
86 by KOS; however, they must be called manually when driving the SQs directly from
87 outside this API.
88
89 \sa sq_lock()
90*/
91void sq_unlock(void);
92
93/** \brief Wait for both Store Queues to complete
94 \ingroup store_queues
95
96 Wait for both store queues to complete by writing to SQ area.
97
98 \sa sq_lock()
99*/
100void sq_wait(void);
101
102/** \brief Write-back one Store Queue
103 \ingroup store_queues
104
105 Initiates write-back from SQ buffer to external memory.
106
107 \param dest The address to copy to (32-byte aligned).
108
109 \sa sq_wait()
110*/
111#define sq_flush(dest) dcache_wback_sq(dest)
112
113/** \brief Copy a block of memory.
114 \ingroup store_queues
115
116 This function is similar to memcpy4(), but uses the store queues to do its
117 work.
118
119 \warning
120 The dest pointer must be at least 32-byte aligned, the src pointer
121 must be at least 4-byte aligned (8-byte aligned uses fast path),
122 and n must be a multiple of 32!
123
124 \param dest The address to copy to (32-byte aligned).
125 \param src The address to copy from (32-bit (4/8-byte) aligned).
126 \param n The number of bytes to copy (multiple of 32).
127 \return The original value of dest.
128
129 \sa sq_fast_cpy()
130*/
131void *sq_cpy(void *dest, const void *src, size_t n);
132
133/** \brief Copy a block of memory.
134 \ingroup store_queues
135
136 This function is similar to sq_cpy() but expects the user to lock/unlock
137 the store queues before and after as well as having different requirements
138 for the params.
139
140 \warning
141 The dest pointer must be at least 32-byte aligned that already has been
142 masked by SQ_MASK_DEST(), the src pointer must be at least 8-byte aligned,
143 and n must be the number of 32-byte blocks you want to copy.
144
145 \param dest The store queue address to copy to (32-byte aligned).
146 \param src The address to copy from (8-byte aligned).
147 \param n The number of 32-byte blocks to copy.
148 \return The original value of dest.
149
150 \sa sq_cpy()
151 */
152void *sq_fast_cpy(void *dest, const void *src, size_t n);
153
154/** \brief Set a block of memory to an 8-bit value.
155 \ingroup store_queues
156
157 This function is similar to calling memset(), but uses the store queues to
158 do its work.
159
160 \warning
161 The dest pointer must be a 32-byte aligned with n being a multiple of 32,
162 and only the low 8-bits are used from c.
163
164 \param dest The address to begin setting at (32-byte aligned).
165 \param c The value to set (in the low 8-bits).
166 \param n The number of bytes to set (multiple of 32).
167 \return The original value of dest.
168
169 \sa sq_set16(), sq_set32()
170*/
171void *sq_set(void *dest, uint32_t c, size_t n);
172
173/** \brief Set a block of memory to a 16-bit value.
174 \ingroup store_queues
175
176 This function is similar to calling memset2(), but uses the store queues to
177 do its work.
178
179 \warning
180 The dest pointer must be a 32-byte aligned with n being a multiple of 32,
181 and only the low 16-bits are used from c.
182
183 \param dest The address to begin setting at (32-byte aligned).
184 \param c The value to set (in the low 16-bits).
185 \param n The number of bytes to set (multiple of 32).
186 \return The original value of dest.
187
188 \sa sq_set(), sq_set32()
189*/
190void *sq_set16(void *dest, uint32_t c, size_t n);
191
192/** \brief Set a block of memory to a 32-bit value.
193 \ingroup store_queues
194
195 This function is similar to calling memset4(), but uses the store queues to
196 do its work.
197
198 \warning
199 The dest pointer must be a 32-byte aligned with n being a multiple of 32!
200
201 \param dest The address to begin setting at (32-byte aligned).
202 \param c The value to set (all 32-bits).
203 \param n The number of bytes to set (multiple of 32).
204 \return The original value of dest.
205
206 \sa sq_set(), sq_set16()
207*/
208void *sq_set32(void *dest, uint32_t c, size_t n);
209
210/** \brief Clear a block of memory.
211 \ingroup store_queues
212
213 This function is similar to calling memset() with a value to set of 0, but
214 uses the store queues to do its work.
215
216 \warning
217 The dest pointer must be a 32-byte aligned with n being a multiple of 32!
218
219 \param dest The address to begin clearing at (32-byte aligned).
220 \param n The number of bytes to clear (multiple of 32).
221*/
222void sq_clr(void *dest, size_t n);
223
224
225__END_DECLS
226
227#endif
cache.h
Cache management functionality.
sq_fast_cpy
void * sq_fast_cpy(void *dest, const void *src, size_t n)
Copy a block of memory.
sq_set
void * sq_set(void *dest, uint32_t c, size_t n)
Set a block of memory to an 8-bit value.
sq_wait
void sq_wait(void)
Wait for both Store Queues to complete.
sq_set16
void * sq_set16(void *dest, uint32_t c, size_t n)
Set a block of memory to a 16-bit value.
sq_set32
void * sq_set32(void *dest, uint32_t c, size_t n)
Set a block of memory to a 32-bit value.
sq_lock
void sq_lock(void *dest)
Lock Store Queues.
sq_unlock
void sq_unlock(void)
Unlock Store Queues.
sq_cpy
void * sq_cpy(void *dest, const void *src, size_t n)
Copy a block of memory.
sq_clr
void sq_clr(void *dest, size_t n)
Clear a block of memory.
memory.h
Constants for areas of the system memory map.
types.h
Common integer types.