svga_winsys.h revision af69d88d 
1/**********************************************************
2 * Copyright 2008-2009 VMware, Inc.  All rights reserved.
3 *
4 * Permission is hereby granted, free of charge, to any person
5 * obtaining a copy of this software and associated documentation
6 * files (the "Software"), to deal in the Software without
7 * restriction, including without limitation the rights to use, copy,
8 * modify, merge, publish, distribute, sublicense, and/or sell copies
9 * of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 *
24 **********************************************************/
25
26/**
27 * @file
28 * VMware SVGA specific winsys interface.
29 *
30 * @author Jose Fonseca <jfonseca@vmware.com>
31 *
32 * Documentation taken from the VMware SVGA DDK.
33 */
34
35#ifndef SVGA_WINSYS_H_
36#define SVGA_WINSYS_H_
37
38
39#include "svga_types.h"
40#include "svga_reg.h"
41#include "svga3d_reg.h"
42
43#include "pipe/p_compiler.h"
44#include "pipe/p_defines.h"
45
46
47struct svga_winsys_screen;
48struct svga_winsys_buffer;
49struct pipe_screen;
50struct pipe_context;
51struct pipe_fence_handle;
52struct pipe_resource;
53struct svga_region;
54struct winsys_handle;
55
56
57#define SVGA_BUFFER_USAGE_PINNED  (1 << 0)
58#define SVGA_BUFFER_USAGE_WRAPPED (1 << 1)
59#define SVGA_BUFFER_USAGE_SHADER  (1 << 2)
60
61/**
62 * Relocation flags to help with dirty tracking
63 * SVGA_RELOC_WRITE -   The command will cause a GPU write to this
64 *                      resource.
65 * SVGA_RELOC_READ -    The command will cause a GPU read from this
66 *                      resource.
67 * SVGA_RELOC_INTERNAL  The command will only transfer data internally
68 *                      within the resource, and optionally clear
69 *                      dirty bits
70 * SVGA_RELOC_DMA -     Only set for resource buffer DMA uploads for winsys
71 *                      implementations that want to track the amount
72 *                      of such data referenced in the command stream.
73 */
74#define SVGA_RELOC_WRITE          (1 << 0)
75#define SVGA_RELOC_READ           (1 << 1)
76#define SVGA_RELOC_INTERNAL       (1 << 2)
77#define SVGA_RELOC_DMA            (1 << 3)
78
79#define SVGA_FENCE_FLAG_EXEC      (1 << 0)
80#define SVGA_FENCE_FLAG_QUERY     (1 << 1)
81
82#define SVGA_SURFACE_USAGE_SHARED (1 << 0)
83
84/** Opaque surface handle */
85struct svga_winsys_surface;
86
87
88/** Opaque guest-backed objects */
89struct svga_winsys_gb_shader;
90
91
92
93/**
94 * SVGA per-context winsys interface.
95 */
96struct svga_winsys_context
97{
98   void
99   (*destroy)(struct svga_winsys_context *swc);
100
101   void *
102   (*reserve)(struct svga_winsys_context *swc,
103	      uint32_t nr_bytes, uint32_t nr_relocs );
104
105   /**
106    * Emit a relocation for a host surface.
107    *
108    * @param flags bitmask of SVGA_RELOC_* flags
109    *
110    * NOTE: Order of this call does matter. It should be the same order
111    * as relocations appear in the command buffer.
112    */
113   void
114   (*surface_relocation)(struct svga_winsys_context *swc,
115	                 uint32 *sid,
116                         uint32 *mobid,
117	                 struct svga_winsys_surface *surface,
118	                 unsigned flags);
119
120   /**
121    * Emit a relocation for a guest memory region.
122    *
123    * @param flags bitmask of SVGA_RELOC_* flags
124    *
125    * NOTE: Order of this call does matter. It should be the same order
126    * as relocations appear in the command buffer.
127    */
128   void
129   (*region_relocation)(struct svga_winsys_context *swc,
130	                struct SVGAGuestPtr *ptr,
131	                struct svga_winsys_buffer *buffer,
132	                uint32 offset,
133                        unsigned flags);
134
135   /**
136    * Emit a relocation for a guest-backed shader object.
137    *
138    * NOTE: Order of this call does matter. It should be the same order
139    * as relocations appear in the command buffer.
140    */
141   void
142   (*shader_relocation)(struct svga_winsys_context *swc,
143	                uint32 *shid,
144			uint32 *mobid,
145			uint32 *offset,
146	                struct svga_winsys_gb_shader *shader);
147
148   /**
149    * Emit a relocation for a guest-backed context.
150    *
151    * NOTE: Order of this call does matter. It should be the same order
152    * as relocations appear in the command buffer.
153    */
154   void
155   (*context_relocation)(struct svga_winsys_context *swc, uint32 *cid);
156
157   /**
158    * Emit a relocation for a guest Memory OBject.
159    *
160    * @param flags bitmask of SVGA_RELOC_* flags
161    * @param offset_into_mob Buffer starts at this offset into the MOB.
162    *
163    * Note that not all commands accept an offset into the MOB and
164    * those commands can't use suballocated buffer pools. To trap
165    * errors from improper buffer pool usage, set the offset_into_mob
166    * pointer to NULL.
167    */
168   void
169   (*mob_relocation)(struct svga_winsys_context *swc,
170		     SVGAMobId *id,
171		     uint32 *offset_into_mob,
172		     struct svga_winsys_buffer *buffer,
173		     uint32 offset,
174		     unsigned flags);
175
176   void
177   (*commit)(struct svga_winsys_context *swc);
178
179   enum pipe_error
180   (*flush)(struct svga_winsys_context *swc,
181	    struct pipe_fence_handle **pfence);
182
183   /**
184    * Context ID used to fill in the commands
185    *
186    * Context IDs are arbitrary small non-negative integers,
187    * global to the entire SVGA device.
188    */
189   uint32 cid;
190
191   /**
192    ** BEGIN new functions for guest-backed surfaces.
193    **/
194
195   boolean have_gb_objects;
196
197   /**
198    * Map a guest-backed surface.
199    * \param flags  bitmaks of PIPE_TRANSFER_x flags
200    *
201    * The surface_map() member is allowed to fail due to a
202    * shortage of command buffer space, if the
203    * PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE bit is set in flags.
204    * In that case, the caller must flush the current command
205    * buffer and reissue the map.
206    */
207   void *
208   (*surface_map)(struct svga_winsys_context *swc,
209                  struct svga_winsys_surface *surface,
210                  unsigned flags, boolean *retry);
211
212   /**
213    * Unmap a guest-backed surface.
214    * \param rebind  returns a flag indicating whether the caller should
215    *                issue a SVGA3D_BindGBSurface() call.
216    */
217   void
218   (*surface_unmap)(struct svga_winsys_context *swc,
219                    struct svga_winsys_surface *surface,
220                    boolean *rebind);
221
222};
223
224
225/**
226 * SVGA per-screen winsys interface.
227 */
228struct svga_winsys_screen
229{
230   void
231   (*destroy)(struct svga_winsys_screen *sws);
232
233   SVGA3dHardwareVersion
234   (*get_hw_version)(struct svga_winsys_screen *sws);
235
236   boolean
237   (*get_cap)(struct svga_winsys_screen *sws,
238              SVGA3dDevCapIndex index,
239              SVGA3dDevCapResult *result);
240
241   /**
242    * Create a new context.
243    *
244    * Context objects encapsulate all render state, and shader
245    * objects are per-context.
246    *
247    * Surfaces are not per-context. The same surface can be shared
248    * between multiple contexts, and surface operations can occur
249    * without a context.
250    */
251   struct svga_winsys_context *
252   (*context_create)(struct svga_winsys_screen *sws);
253
254
255   /**
256    * This creates a "surface" object in the SVGA3D device.
257    *
258    * \param sws Pointer to an svga_winsys_context
259    * \param flags Device surface create flags
260    * \param format Format Device surface format
261    * \param usage Winsys usage: bitmask of SVGA_SURFACE_USAGE_x flags
262    * \param size Surface size given in device format
263    * \param numFaces Number of faces of the surface (1 or 6)
264    * \param numMipLevels Number of mipmap levels for each face
265    *
266    * Returns the surface ID (sid). Surfaces are generic
267    * containers for host VRAM objects like textures, vertex
268    * buffers, and depth/stencil buffers.
269    *
270    * Surfaces are hierarchial:
271    *
272    * - Surface may have multiple faces (for cube maps)
273    *
274    * - Each face has a list of mipmap levels
275    *
276    * - Each mipmap image may have multiple volume
277    *   slices, if the image is three dimensional.
278    *
279    * - Each slice is a 2D array of 'blocks'
280    *
281    * - Each block may be one or more pixels.
282    *   (Usually 1, more for DXT or YUV formats.)
283    *
284    * Surfaces are generic host VRAM objects. The SVGA3D device
285    * may optimize surfaces according to the format they were
286    * created with, but this format does not limit the ways in
287    * which the surface may be used. For example, a depth surface
288    * can be used as a texture, or a floating point image may
289    * be used as a vertex buffer. Some surface usages may be
290    * lower performance, due to software emulation, but any
291    * usage should work with any surface.
292    */
293   struct svga_winsys_surface *
294   (*surface_create)(struct svga_winsys_screen *sws,
295                     SVGA3dSurfaceFlags flags,
296                     SVGA3dSurfaceFormat format,
297                     unsigned usage,
298                     SVGA3dSize size,
299                     uint32 numFaces,
300                     uint32 numMipLevels);
301
302   /**
303    * Creates a surface from a winsys handle.
304    * Used to implement pipe_screen::resource_from_handle.
305    */
306   struct svga_winsys_surface *
307   (*surface_from_handle)(struct svga_winsys_screen *sws,
308                          struct winsys_handle *whandle,
309                          SVGA3dSurfaceFormat *format);
310
311   /**
312    * Get a winsys_handle from a surface.
313    * Used to implement pipe_screen::resource_get_handle.
314    */
315   boolean
316   (*surface_get_handle)(struct svga_winsys_screen *sws,
317                         struct svga_winsys_surface *surface,
318                         unsigned stride,
319                         struct winsys_handle *whandle);
320
321   /**
322    * Whether this surface is sitting in a validate list
323    */
324   boolean
325   (*surface_is_flushed)(struct svga_winsys_screen *sws,
326                         struct svga_winsys_surface *surface);
327
328   /**
329    * Reference a SVGA3D surface object. This allows sharing of a
330    * surface between different objects.
331    */
332   void
333   (*surface_reference)(struct svga_winsys_screen *sws,
334			struct svga_winsys_surface **pdst,
335			struct svga_winsys_surface *src);
336
337   /**
338    * Check if a resource (texture, buffer) of the given size
339    * and format can be created.
340    * \Return TRUE if OK, FALSE if too large.
341    */
342   boolean
343   (*surface_can_create)(struct svga_winsys_screen *sws,
344                         SVGA3dSurfaceFormat format,
345                         SVGA3dSize size,
346                         uint32 numFaces,
347                         uint32 numMipLevels);
348
349   /**
350    * Buffer management. Buffer attributes are mostly fixed over its lifetime.
351    *
352    * @param usage bitmask of SVGA_BUFFER_USAGE_* flags.
353    *
354    * alignment indicates the client's alignment requirements, eg for
355    * SSE instructions.
356    */
357   struct svga_winsys_buffer *
358   (*buffer_create)( struct svga_winsys_screen *sws,
359	             unsigned alignment,
360	             unsigned usage,
361	             unsigned size );
362
363   /**
364    * Map the entire data store of a buffer object into the client's address.
365    * usage is a bitmask of PIPE_TRANSFER_*
366    */
367   void *
368   (*buffer_map)( struct svga_winsys_screen *sws,
369	          struct svga_winsys_buffer *buf,
370		  unsigned usage );
371
372   void
373   (*buffer_unmap)( struct svga_winsys_screen *sws,
374                    struct svga_winsys_buffer *buf );
375
376   void
377   (*buffer_destroy)( struct svga_winsys_screen *sws,
378	              struct svga_winsys_buffer *buf );
379
380
381   /**
382    * Reference a fence object.
383    */
384   void
385   (*fence_reference)( struct svga_winsys_screen *sws,
386                       struct pipe_fence_handle **pdst,
387                       struct pipe_fence_handle *src );
388
389   /**
390    * Checks whether the fence has been signalled.
391    * \param flags  driver-specific meaning
392    * \return zero on success.
393    */
394   int (*fence_signalled)( struct svga_winsys_screen *sws,
395                           struct pipe_fence_handle *fence,
396                           unsigned flag );
397
398   /**
399    * Wait for the fence to finish.
400    * \param flags  driver-specific meaning
401    * \return zero on success.
402    */
403   int (*fence_finish)( struct svga_winsys_screen *sws,
404                        struct pipe_fence_handle *fence,
405                        unsigned flag );
406
407
408   /**
409    ** BEGIN new functions for guest-backed surfaces.
410    **/
411
412   /** Are guest-backed objects enabled? */
413   bool have_gb_objects;
414
415   /** Can we do DMA with guest-backed objects enabled? */
416   bool have_gb_dma;
417
418   /**
419    * Create and define a GB shader.
420    */
421   struct svga_winsys_gb_shader *
422   (*shader_create)(struct svga_winsys_screen *sws,
423		    SVGA3dShaderType type,
424		    const uint32 *bytecode,
425		    uint32 bytecodeLen);
426
427   /**
428    * Destroy a GB shader. It's safe to call this function even
429    * if the shader is referenced in a context's command stream.
430    */
431   void
432   (*shader_destroy)(struct svga_winsys_screen *sws,
433		     struct svga_winsys_gb_shader *shader);
434
435};
436
437
438struct svga_winsys_screen *
439svga_winsys_screen(struct pipe_screen *screen);
440
441struct svga_winsys_context *
442svga_winsys_context(struct pipe_context *context);
443
444struct pipe_resource *
445svga_screen_buffer_wrap_surface(struct pipe_screen *screen,
446				enum SVGA3dSurfaceFormat format,
447				struct svga_winsys_surface *srf);
448
449struct svga_winsys_surface *
450svga_screen_buffer_get_winsys_surface(struct pipe_resource *buffer);
451
452#endif /* SVGA_WINSYS_H_ */
453