1 /*
2 * Copyright © 2021 Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice (including the next
12 * paragraph) shall be included in all copies or substantial portions of the
13 * Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 */
23 #ifndef VK_PIPELINE_CACHE_H
24 #define VK_PIPELINE_CACHE_H
25
26 #include "vk_object.h"
27 #include "vk_util.h"
28
29 #include "util/simple_mtx.h"
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /* #include "util/blob.h" */
36 struct blob;
37 struct blob_reader;
38
39 /* #include "util/set.h" */
40 struct set;
41
42 /* #include "compiler/nir/nir.h" */
43 struct nir_shader;
44 struct nir_shader_compiler_options;
45
46 struct vk_pipeline_cache;
47 struct vk_pipeline_cache_object;
48
49 #define VK_PIPELINE_CACHE_BLOB_ALIGN 8
50
51 struct vk_pipeline_cache_object_ops {
52 /** Writes this cache object to the given blob
53 *
54 * Because the cache works with both raw blob data and driver object data
55 * and can't always tell the difference between the two, we have to be very
56 * careful about alignments when [de]serializing. When serialize() is
57 * called, the blob will be aligned to VK_PIPELINE_CACHE_BLOB_ALIGN. The
58 * driver must be careful to not [de]serialize any data types which require
59 * a higher alignment. When deserialize() is called, the blob_reader is
60 * also guaranteed to be aligned to VK_PIPELINE_CACHE_BLOB_ALIGN.
61 *
62 * Returns true on success
63 *
64 * This function is optional. Objects without [de]serialization support
65 * will still be cached in memory but will not be placed in the disk cache
66 * and will not exported to the client when vkGetPipelineCacheData() is
67 * called.
68 */
69 bool (*serialize)(struct vk_pipeline_cache_object *object,
70 struct blob *blob);
71
72 /** Constructs an object from cached data
73 *
74 * See serialize() for details about data alignment.
75 *
76 * returns the created object
77 *
78 * This function is optional.
79 */
80 struct vk_pipeline_cache_object *(*deserialize)(struct vk_pipeline_cache *cache,
81 const void *key_data,
82 size_t key_size,
83 struct blob_reader *blob);
84
85 /** Destroys the object
86 *
87 * Called when vk_pipeline_cache_object.ref_cnt hits 0.
88 */
89 void (*destroy)(struct vk_device *device,
90 struct vk_pipeline_cache_object *object);
91 };
92
93 /** Base struct for cached objects
94 *
95 * A vk_pipeline_cache stores any number of vk_pipeline_cache_object's, each
96 * of which has an associated key of arbitrary size. Cached objects are
97 * reference counted so that they can exist in multiple caches (for example,
98 * when vkMergePipelineCaches() is called) and so that they can persist after
99 * the pipeline cache is destroyed. Each object also has a pointer to a
100 * vk_pipeline_cache_object_ops table which the pipeline cache uses to
101 * [de]serialize the object and clean it up when the reference count hits 0.
102 *
103 * The rest of the details of any given object are entirely up to the driver.
104 * The driver may even have multiple types of objects (distinguished by their
105 * vk_pipeline_cache_object_ops table) in the cache so long as it guarantees
106 * it never has two objects of different types with the same key.
107 */
108 struct vk_pipeline_cache_object {
109 const struct vk_pipeline_cache_object_ops *ops;
110 struct vk_pipeline_cache *weak_owner;
111 uint32_t ref_cnt;
112
113 uint32_t data_size;
114 const void *key_data;
115 uint32_t key_size;
116 };
117
118 static inline void
vk_pipeline_cache_object_init(struct vk_device * device,struct vk_pipeline_cache_object * object,const struct vk_pipeline_cache_object_ops * ops,const void * key_data,uint32_t key_size)119 vk_pipeline_cache_object_init(struct vk_device *device,
120 struct vk_pipeline_cache_object *object,
121 const struct vk_pipeline_cache_object_ops *ops,
122 const void *key_data, uint32_t key_size)
123 {
124 memset(object, 0, sizeof(*object));
125 object->ops = ops;
126 p_atomic_set(&object->ref_cnt, 1);
127 object->data_size = 0; /* Unknown */
128 object->key_data = key_data;
129 object->key_size = key_size;
130 }
131
132 static inline void
vk_pipeline_cache_object_finish(struct vk_pipeline_cache_object * object)133 vk_pipeline_cache_object_finish(struct vk_pipeline_cache_object *object)
134 {
135 assert(p_atomic_read(&object->ref_cnt) <= 1);
136 }
137
138 static inline struct vk_pipeline_cache_object *
vk_pipeline_cache_object_ref(struct vk_pipeline_cache_object * object)139 vk_pipeline_cache_object_ref(struct vk_pipeline_cache_object *object)
140 {
141 assert(object && p_atomic_read(&object->ref_cnt) >= 1);
142 p_atomic_inc(&object->ref_cnt);
143 return object;
144 }
145
146 void
147 vk_pipeline_cache_object_unref(struct vk_device *device,
148 struct vk_pipeline_cache_object *object);
149
150 /** A generic implementation of VkPipelineCache */
151 struct vk_pipeline_cache {
152 struct vk_object_base base;
153
154 /* pCreateInfo::flags */
155 VkPipelineCacheCreateFlags flags;
156 bool weak_ref;
157 bool skip_disk_cache;
158
159 struct vk_pipeline_cache_header header;
160
161 /** Protects object_cache */
162 simple_mtx_t lock;
163
164 struct set *object_cache;
165 };
166
167 VK_DEFINE_NONDISP_HANDLE_CASTS(vk_pipeline_cache, base, VkPipelineCache,
168 VK_OBJECT_TYPE_PIPELINE_CACHE)
169
170 struct vk_pipeline_cache_create_info {
171 /* The pCreateInfo for this pipeline cache, if any.
172 *
173 * For driver-internal caches, this is allowed to be NULL.
174 */
175 const VkPipelineCacheCreateInfo *pCreateInfo;
176
177 /** If true, ignore VK_ENABLE_PIPELINE_CACHE and enable anyway */
178 bool force_enable;
179
180 /** If true, the cache operates in weak reference mode.
181 *
182 * The weak reference mode is designed for device-global caches for the
183 * purpose of de-duplicating identical shaders and pipelines. In the weak
184 * reference mode, an object's reference count is not incremented when it is
185 * added to the cache. Therefore the object will be destroyed as soon as
186 * there's no external references to it, and the runtime will perform the
187 * necessary bookkeeping to remove the dead reference from this cache's table.
188 *
189 * As the weak reference mode is designed for driver-internal use, it has
190 * several limitations:
191 * - Merging against a weak reference mode cache is not supported.
192 * - Lazy deserialization from vk_raw_data_cache_object_ops is not supported.
193 * - An object can only belong to up to one weak reference mode cache.
194 * - The cache must outlive the object, as the object will try to access its
195 * owner when it's destroyed.
196 */
197 bool weak_ref;
198
199 /** If true, do not attempt to use the disk cache */
200 bool skip_disk_cache;
201 };
202
203 struct vk_pipeline_cache *
204 vk_pipeline_cache_create(struct vk_device *device,
205 const struct vk_pipeline_cache_create_info *info,
206 const VkAllocationCallbacks *pAllocator);
207 void
208 vk_pipeline_cache_destroy(struct vk_pipeline_cache *cache,
209 const VkAllocationCallbacks *pAllocator);
210
211 /** Attempts to look up an object in the cache by key
212 *
213 * If an object is found in the cache matching the given key, *cache_hit is
214 * set to true and a reference to that object is returned.
215 *
216 * If the driver sets vk_device.disk_cache, we attempt to look up any missing
217 * objects in the disk cache before declaring failure. If an object is found
218 * in the disk cache but not the in-memory cache, *cache_hit is set to false.
219 *
220 * The deserialization of pipeline cache objects found in the cache data
221 * provided via VkPipelineCacheCreateInfo::pInitialData happens during
222 * vk_pipeline_cache_lookup() rather than during vkCreatePipelineCache().
223 * Prior to the first vk_pipeline_cache_lookup() of a given object, it is
224 * stored as an internal raw data object with the same hash. This allows us
225 * to avoid any complex object type tagging in the serialized cache. It does,
226 * however, mean that drivers need to be careful to ensure that objects with
227 * different types (ops) have different keys.
228 *
229 * Returns a reference to the object, if found
230 */
231 struct vk_pipeline_cache_object * MUST_CHECK
232 vk_pipeline_cache_lookup_object(struct vk_pipeline_cache *cache,
233 const void *key_data, size_t key_size,
234 const struct vk_pipeline_cache_object_ops *ops,
235 bool *cache_hit);
236
237 /** Adds an object to the pipeline cache
238 *
239 * This function adds the given object to the pipeline cache. We do not
240 * specify a key here because the key is part of the object. See also
241 * vk_pipeline_cache_object_init().
242 *
243 * This function consumes a reference to the object and returns a reference to
244 * the (possibly different) object in the cache. The intended usage pattern
245 * is as follows:
246 *
247 * key = compute_key();
248 * struct vk_pipeline_cache_object *object =
249 * vk_pipeline_cache_lookup_object(cache, &key, sizeof(key),
250 * &driver_type_ops, &cache_hit);
251 * if (object != NULL)
252 * return container_of(object, driver_type, base);
253 *
254 * object = do_compile();
255 * assert(object != NULL);
256 *
257 * object = vk_pipeline_cache_add_object(cache, object);
258 * return container_of(object, driver_type, base);
259 */
260 struct vk_pipeline_cache_object * MUST_CHECK
261 vk_pipeline_cache_add_object(struct vk_pipeline_cache *cache,
262 struct vk_pipeline_cache_object *object);
263
264 /** Creates and inserts an object into the pipeline cache
265 *
266 * This function takes serialized data and emplaces the deserialized object
267 * into the pipeline cache. It is the responsibility of the caller to
268 * specify a deserialize() function that properly initializes the object.
269 *
270 * This function can be used to avoid an extra serialize() step for
271 * disk-cache insertion. For the intended usage pattern, see
272 * vk_pipeline_cache_add_object().
273 *
274 */
275 struct vk_pipeline_cache_object *
276 vk_pipeline_cache_create_and_insert_object(struct vk_pipeline_cache *cache,
277 const void *key_data, uint32_t key_size,
278 const void *data, size_t data_size,
279 const struct vk_pipeline_cache_object_ops *ops);
280
281 struct nir_shader *
282 vk_pipeline_cache_lookup_nir(struct vk_pipeline_cache *cache,
283 const void *key_data, size_t key_size,
284 const struct nir_shader_compiler_options *nir_options,
285 bool *cache_hit, void *mem_ctx);
286 void
287 vk_pipeline_cache_add_nir(struct vk_pipeline_cache *cache,
288 const void *key_data, size_t key_size,
289 const struct nir_shader *nir);
290
291 /** Specialized type of vk_pipeline_cache_object for raw data objects.
292 *
293 * This cache object implementation, together with vk_raw_data_cache_object_ops,
294 * can be used to cache plain objects as well as already serialized data.
295 */
296 struct vk_raw_data_cache_object {
297 struct vk_pipeline_cache_object base;
298
299 const void *data;
300 size_t data_size;
301 };
302
303 struct vk_raw_data_cache_object *
304 vk_raw_data_cache_object_create(struct vk_device *device,
305 const void *key_data, size_t key_size,
306 const void *data, size_t data_size);
307
308 extern const struct vk_pipeline_cache_object_ops vk_raw_data_cache_object_ops;
309
310 #ifdef __cplusplus
311 }
312 #endif
313
314 #endif /* VK_PIPELINE_CACHE_H */
315