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  * Buffer management.
31  *
32  * A buffer manager does only one basic thing: it creates buffers. Actually,
33  * "buffer factory" would probably a more accurate description.
34  *
35  * You can chain buffer managers so that you can have a finer grained memory
36  * management.
37  *
38  * For example, for a simple batch buffer manager you would chain:
39  * - the native buffer manager, which provides DMA memory from the graphics
40  * memory space;
41  * - the fenced buffer manager, which will delay buffer destruction until the
42  * the moment the card finishing processing it.
43  *
44  * \author Jose Fonseca <jfonseca@vmware.com>
45  */
46 
47 #ifndef PB_BUFMGR_H_
48 #define PB_BUFMGR_H_
49 
50 
51 #include "pb_buffer.h"
52 
53 
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57 
58 
59 struct pb_desc;
60 
61 
62 /**
63  * Abstract base class for all buffer managers.
64  */
65 struct pb_manager
66 {
67    void
68    (*destroy)( struct pb_manager *mgr );
69 
70    struct pb_buffer *
71    (*create_buffer)( struct pb_manager *mgr,
72 	             pb_size size,
73 	             const struct pb_desc *desc);
74 
75    /**
76     * Flush all temporary-held buffers.
77     *
78     * Used mostly to aid debugging memory issues or to clean up resources when
79     * the drivers are long lived.
80     */
81    void
82    (*flush)( struct pb_manager *mgr );
83 
84    boolean
85    (*is_buffer_busy)( struct pb_manager *mgr,
86                       struct pb_buffer *buf );
87 };
88 
89 /**
90  * Static sub-allocator based the old memory manager.
91  *
92  * It managers buffers of different sizes. It does so by allocating a buffer
93  * with the size of the heap, and then using the old mm memory manager to manage
94  * that heap.
95  */
96 struct pb_manager *
97 mm_bufmgr_create(struct pb_manager *provider,
98                  pb_size size, pb_size align2);
99 
100 /**
101  * Same as mm_bufmgr_create.
102  *
103  * Buffer will be release when the manager is destroyed.
104  */
105 struct pb_manager *
106 mm_bufmgr_create_from_buffer(struct pb_buffer *buffer,
107                              pb_size size, pb_size align2);
108 
109 
110 /**
111  * Slab sub-allocator.
112  */
113 struct pb_manager *
114 pb_slab_manager_create(struct pb_manager *provider,
115                        pb_size bufSize,
116                        pb_size slabSize,
117                        const struct pb_desc *desc);
118 
119 /**
120  * Allow a range of buffer size, by aggregating multiple slabs sub-allocators
121  * with different bucket sizes.
122  */
123 struct pb_manager *
124 pb_slab_range_manager_create(struct pb_manager *provider,
125                              pb_size minBufSize,
126                              pb_size maxBufSize,
127                              pb_size slabSize,
128                              const struct pb_desc *desc);
129 
130 
131 /**
132  * Time-based buffer cache.
133  *
134  * This manager keeps a cache of destroyed buffers during a time interval.
135  */
136 struct pb_manager *
137 pb_cache_manager_create(struct pb_manager *provider,
138                         unsigned usecs,
139                         float size_factor,
140                         unsigned bypass_usage,
141                         uint64_t maximum_cache_size);
142 
143 /**
144  * Remove a buffer from the cache, but keep it alive.
145  */
146 void
147 pb_cache_manager_remove_buffer(struct pb_buffer *buf);
148 
149 struct pb_fence_ops;
150 
151 /**
152  * Fenced buffer manager.
153  *
154  * This manager is just meant for convenience. It wraps the buffers returned
155  * by another manager in fenced buffers, so that
156  *
157  * NOTE: the buffer manager that provides the buffers will be destroyed
158  * at the same time.
159  */
160 struct pb_manager *
161 fenced_bufmgr_create(struct pb_manager *provider,
162                      struct pb_fence_ops *ops,
163                      pb_size max_buffer_size,
164                      pb_size max_cpu_total_size);
165 
166 /**
167  * Debug buffer manager to detect buffer under- and overflows.
168  *
169  * Under/overflow sizes should be a multiple of the largest alignment
170  */
171 struct pb_manager *
172 pb_debug_manager_create(struct pb_manager *provider,
173                         pb_size underflow_size, pb_size overflow_size);
174 
175 
176 #ifdef __cplusplus
177 }
178 #endif
179 
180 #endif /*PB_BUFMGR_H_*/
181