1 /************************************************************************** 2 * 3 * Copyright 2007 Tungsten Graphics, Inc., Cedar Park, Texas. 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 TUNGSTEN GRAPHICS 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 <jrfonseca (at) tungstengraphics.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 * Size. Regular (32bit) unsigned for now. 91 */ 92 typedef unsigned 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 size; 102 unsigned alignment; 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 * 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 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 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 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 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 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 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 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 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
