1 /**************************************************************************
2 *
3 * Copyright 2007 VMware, Inc.
4 * All Rights Reserved.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a
7 * copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sub license, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
13 *
14 * The above copyright notice and this permission notice (including the
15 * next paragraph) shall be included in all copies or substantial portions
16 * of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
21 * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
22 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 *
26 **************************************************************************/
27
28 /**
29 * \file
30 * Generic code for buffers.
31 *
32 * Behind a pipe buffle handle there can be DMA buffers, client (or user)
33 * buffers, regular malloced buffers, etc. This file provides an abstract base
34 * buffer handle that allows the driver to cope with all those kinds of buffers
35 * in a more flexible way.
36 *
37 * There is no obligation of a winsys driver to use this library. And a pipe
38 * driver should be completly agnostic about it.
39 *
40 * \author Jose Fonseca <jfonseca@vmware.com>
41 */
42
43 #ifndef PB_BUFFER_H_
44 #define PB_BUFFER_H_
45
46
47 #include "pipe/p_compiler.h"
48 #include "util/u_debug.h"
49 #include "util/u_inlines.h"
50 #include "pipe/p_defines.h"
51
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57
58 struct pb_vtbl;
59 struct pb_validate;
60 struct pipe_fence_handle;
61
62
63 #define PB_USAGE_CPU_READ (1 << 0)
64 #define PB_USAGE_CPU_WRITE (1 << 1)
65 #define PB_USAGE_GPU_READ (1 << 2)
66 #define PB_USAGE_GPU_WRITE (1 << 3)
67 #define PB_USAGE_UNSYNCHRONIZED (1 << 10)
68 #define PB_USAGE_DONTBLOCK (1 << 9)
69
70 #define PB_USAGE_CPU_READ_WRITE \
71 ( PB_USAGE_CPU_READ | PB_USAGE_CPU_WRITE )
72 #define PB_USAGE_GPU_READ_WRITE \
73 ( PB_USAGE_GPU_READ | PB_USAGE_GPU_WRITE )
74 #define PB_USAGE_WRITE \
75 ( PB_USAGE_CPU_WRITE | PB_USAGE_GPU_WRITE )
76
77 /**
78 * Buffer description.
79 *
80 * Used when allocating the buffer.
81 */
82 struct pb_desc
83 {
84 unsigned alignment;
85 unsigned usage;
86 };
87
88
89 /**
90 * 64-bit type for GPU buffer sizes and offsets.
91 */
92 typedef uint64_t pb_size;
93
94
95 /**
96 * Base class for all pb_* buffers.
97 */
98 struct pb_buffer
99 {
100 struct pipe_reference reference;
101 unsigned alignment;
102 pb_size size;
103 unsigned usage;
104
105 /**
106 * Pointer to the virtual function table.
107 *
108 * Avoid accessing this table directly. Use the inline functions below
109 * instead to avoid mistakes.
110 */
111 const struct pb_vtbl *vtbl;
112 };
113
114
115 /**
116 * Virtual function table for the buffer storage operations.
117 *
118 * Note that creation is not done through this table.
119 */
120 struct pb_vtbl
121 {
122 void (*destroy)( struct pb_buffer *buf );
123
124 /**
125 * Map the entire data store of a buffer object into the client's address.
126 * flags is bitmask of PB_USAGE_CPU_READ/WRITE.
127 */
128 void *(*map)( struct pb_buffer *buf,
129 unsigned flags, void *flush_ctx );
130
131 void (*unmap)( struct pb_buffer *buf );
132
133 enum pipe_error (*validate)( struct pb_buffer *buf,
134 struct pb_validate *vl,
135 unsigned flags );
136
137 void (*fence)( struct pb_buffer *buf,
138 struct pipe_fence_handle *fence );
139
140 /**
141 * Get the base buffer and the offset.
142 *
143 * A buffer can be subdivided in smaller buffers. This method should return
144 * the underlaying buffer, and the relative offset.
145 *
146 * Buffers without an underlaying base buffer should return themselves, with
147 * a zero offset.
148 *
149 * Note that this will increase the reference count of the base buffer.
150 */
151 void (*get_base_buffer)( struct pb_buffer *buf,
152 struct pb_buffer **base_buf,
153 pb_size *offset );
154
155 };
156
157
158
159 /* Accessor functions for pb->vtbl:
160 */
161 static inline void *
pb_map(struct pb_buffer * buf,unsigned flags,void * flush_ctx)162 pb_map(struct pb_buffer *buf,
163 unsigned flags, void *flush_ctx)
164 {
165 assert(buf);
166 if (!buf)
167 return NULL;
168 assert(pipe_is_referenced(&buf->reference));
169 return buf->vtbl->map(buf, flags, flush_ctx);
170 }
171
172
173 static inline void
pb_unmap(struct pb_buffer * buf)174 pb_unmap(struct pb_buffer *buf)
175 {
176 assert(buf);
177 if (!buf)
178 return;
179 assert(pipe_is_referenced(&buf->reference));
180 buf->vtbl->unmap(buf);
181 }
182
183
184 static inline void
pb_get_base_buffer(struct pb_buffer * buf,struct pb_buffer ** base_buf,pb_size * offset)185 pb_get_base_buffer( struct pb_buffer *buf,
186 struct pb_buffer **base_buf,
187 pb_size *offset )
188 {
189 assert(buf);
190 if (!buf) {
191 base_buf = NULL;
192 offset = 0;
193 return;
194 }
195 assert(pipe_is_referenced(&buf->reference));
196 assert(buf->vtbl->get_base_buffer);
197 buf->vtbl->get_base_buffer(buf, base_buf, offset);
198 assert(*base_buf);
199 assert(*offset < (*base_buf)->size);
200 }
201
202
203 static inline enum pipe_error
pb_validate(struct pb_buffer * buf,struct pb_validate * vl,unsigned flags)204 pb_validate(struct pb_buffer *buf, struct pb_validate *vl, unsigned flags)
205 {
206 assert(buf);
207 if (!buf)
208 return PIPE_ERROR;
209 assert(buf->vtbl->validate);
210 return buf->vtbl->validate(buf, vl, flags);
211 }
212
213
214 static inline void
pb_fence(struct pb_buffer * buf,struct pipe_fence_handle * fence)215 pb_fence(struct pb_buffer *buf, struct pipe_fence_handle *fence)
216 {
217 assert(buf);
218 if (!buf)
219 return;
220 assert(buf->vtbl->fence);
221 buf->vtbl->fence(buf, fence);
222 }
223
224
225 static inline void
pb_destroy(struct pb_buffer * buf)226 pb_destroy(struct pb_buffer *buf)
227 {
228 assert(buf);
229 if (!buf)
230 return;
231 assert(!pipe_is_referenced(&buf->reference));
232 buf->vtbl->destroy(buf);
233 }
234
235 static inline void
pb_reference(struct pb_buffer ** dst,struct pb_buffer * src)236 pb_reference(struct pb_buffer **dst,
237 struct pb_buffer *src)
238 {
239 struct pb_buffer *old = *dst;
240
241 if (pipe_reference(&(*dst)->reference, &src->reference))
242 pb_destroy( old );
243 *dst = src;
244 }
245
246
247 /**
248 * Utility function to check whether the provided alignment is consistent with
249 * the requested or not.
250 */
251 static inline boolean
pb_check_alignment(pb_size requested,pb_size provided)252 pb_check_alignment(pb_size requested, pb_size provided)
253 {
254 if(!requested)
255 return TRUE;
256 if(requested > provided)
257 return FALSE;
258 if(provided % requested != 0)
259 return FALSE;
260 return TRUE;
261 }
262
263
264 /**
265 * Utility function to check whether the provided alignment is consistent with
266 * the requested or not.
267 */
268 static inline boolean
pb_check_usage(unsigned requested,unsigned provided)269 pb_check_usage(unsigned requested, unsigned provided)
270 {
271 return (requested & provided) == requested ? TRUE : FALSE;
272 }
273
274
275 /**
276 * Malloc-based buffer to store data that can't be used by the graphics
277 * hardware.
278 */
279 struct pb_buffer *
280 pb_malloc_buffer_create(pb_size size,
281 const struct pb_desc *desc);
282
283
284 #ifdef __cplusplus
285 }
286 #endif
287
288 #endif /*PB_BUFFER_H_*/
289