1 /* Copyright (c) 2015-2016 The Khronos Group Inc.
2  * Copyright (c) 2015-2016 Valve Corporation
3  * Copyright (c) 2015-2016 LunarG, Inc.
4  * Copyright (C) 2015-2016 Google Inc.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and/or associated documentation files (the "Materials"), to
8  * deal in the Materials without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Materials, and to permit persons to whom the Materials
11  * are furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice(s) and this permission notice shall be included
14  * in all copies or substantial portions of the Materials.
15  *
16  * The Materials are Confidential Information as defined by the Khronos
17  * Membership Agreement until designated non-confidential by Khronos, at which
18  * point this condition clause shall be removed.
19  *
20  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
23  *
24  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
25  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
26  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE
27  * USE OR OTHER DEALINGS IN THE MATERIALS
28  *
29  * Author: Dustin Graves <dustin@lunarg.com>
30  */
31 
32 #ifndef PARAMETER_VALIDATION_UTILS_H
33 #define PARAMETER_VALIDATION_UTILS_H
34 
35 #include <algorithm>
36 #include <string>
37 
38 #include "vulkan/vulkan.h"
39 #include "vk_enum_string_helper.h"
40 #include "vk_layer_logging.h"
41 
42 namespace {
43 struct GenericHeader {
44     VkStructureType sType;
45     const void *pNext;
46 };
47 }
48 
49 // String returned by string_VkStructureType for an unrecognized type
50 const std::string UnsupportedStructureTypeString = "Unhandled VkStructureType";
51 
52 /**
53  * Validate a required pointer.
54  *
55  * Verify that a required pointer is not NULL.
56  *
57  * @param report_data debug_report_data object for routing validation messages.
58  * @param apiName Name of API call being validated.
59  * @param parameterName Name of parameter being validated.
60  * @param value Pointer to validate.
61  * @return Boolean value indicating that the call should be skipped.
62  */
validate_required_pointer(debug_report_data * report_data,const char * apiName,const char * parameterName,const void * value)63 static VkBool32 validate_required_pointer(debug_report_data *report_data, const char *apiName, const char *parameterName,
64                                           const void *value) {
65     VkBool32 skipCall = VK_FALSE;
66 
67     if (value == NULL) {
68         skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
69                             "%s: required parameter %s specified as NULL", apiName, parameterName);
70     }
71 
72     return skipCall;
73 }
74 
75 /**
76  * Validate pointer to array count and pointer to array.
77  *
78  * Verify that required count and array parameters are not NULL.  If count
79  * is not NULL and its value is not optional, verify that it is not 0.  If the
80  * array parameter is NULL, and it is not optional, verify that count is 0.
81  * The array parameter will typically be optional for this case (where count is
82  * a pointer), allowing the caller to retrieve the available count.
83  *
84  * @param report_data debug_report_data object for routing validation messages.
85  * @param apiName Name of API call being validated.
86  * @param countName Name of count parameter.
87  * @param arrayName Name of array parameter.
88  * @param count Pointer to the number of elements in the array.
89  * @param array Array to validate.
90  * @param countPtrRequired The 'count' parameter may not be NULL when true.
91  * @param countValueRequired The '*count' value may not be 0 when true.
92  * @param arrayRequired The 'array' parameter may not be NULL when true.
93  * @return Boolean value indicating that the call should be skipped.
94  */
95 template <typename T>
validate_array(debug_report_data * report_data,const char * apiName,const char * countName,const char * arrayName,const T * count,const void * array,VkBool32 countPtrRequired,VkBool32 countValueRequired,VkBool32 arrayRequired)96 VkBool32 validate_array(debug_report_data *report_data, const char *apiName, const char *countName, const char *arrayName,
97                         const T *count, const void *array, VkBool32 countPtrRequired, VkBool32 countValueRequired,
98                         VkBool32 arrayRequired) {
99     VkBool32 skipCall = VK_FALSE;
100 
101     if (count == NULL) {
102         if (countPtrRequired == VK_TRUE) {
103             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
104                                 "PARAMCHECK", "%s: required parameter %s specified as NULL", apiName, countName);
105         }
106     } else {
107         skipCall |= validate_array(report_data, apiName, countName, arrayName, (*count), array, countValueRequired, arrayRequired);
108     }
109 
110     return skipCall;
111 }
112 
113 /**
114  * Validate array count and pointer to array.
115  *
116  * Verify that required count and array parameters are not 0 or NULL.  If the
117  * count parameter is not optional, verify that it is not 0.  If the array
118  * parameter is NULL, and it is not optional, verify that count is 0.
119  *
120  * @param report_data debug_report_data object for routing validation messages.
121  * @param apiName Name of API call being validated.
122  * @param countName Name of count parameter.
123  * @param arrayName Name of array parameter.
124  * @param count Number of elements in the array.
125  * @param array Array to validate.
126  * @param countRequired The 'count' parameter may not be 0 when true.
127  * @param arrayRequired The 'array' parameter may not be NULL when true.
128  * @return Boolean value indicating that the call should be skipped.
129  */
130 template <typename T>
validate_array(debug_report_data * report_data,const char * apiName,const char * countName,const char * arrayName,T count,const void * array,VkBool32 countRequired,VkBool32 arrayRequired)131 VkBool32 validate_array(debug_report_data *report_data, const char *apiName, const char *countName, const char *arrayName, T count,
132                         const void *array, VkBool32 countRequired, VkBool32 arrayRequired) {
133     VkBool32 skipCall = VK_FALSE;
134 
135     // Count parameters not tagged as optional cannot be 0
136     if ((count == 0) && (countRequired == VK_TRUE)) {
137         skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
138                             "%s: value of %s must be greater than 0", apiName, countName);
139     }
140 
141     // Array parameters not tagged as optional cannot be NULL,
142     // unless the count is 0
143     if ((array == NULL) && (arrayRequired == VK_TRUE) && (count != 0)) {
144         skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
145                             "%s: required parameter %s specified as NULL", apiName, arrayName);
146     }
147 
148     return skipCall;
149 }
150 
151 /**
152  * Validate an Vulkan structure type.
153  *
154  * @param report_data debug_report_data object for routing validation messages.
155  * @param apiName Name of API call being validated.
156  * @param parameterName Name of struct parameter being validated.
157  * @param sTypeName Name of expected VkStructureType value.
158  * @param value Pointer to the struct to validate.
159  * @param sType VkStructureType for structure validation.
160  * @param required The parameter may not be NULL when true.
161  * @return Boolean value indicating that the call should be skipped.
162  */
163 template <typename T>
validate_struct_type(debug_report_data * report_data,const char * apiName,const char * parameterName,const char * sTypeName,const T * value,VkStructureType sType,VkBool32 required)164 VkBool32 validate_struct_type(debug_report_data *report_data, const char *apiName, const char *parameterName, const char *sTypeName,
165                               const T *value, VkStructureType sType, VkBool32 required) {
166     VkBool32 skipCall = VK_FALSE;
167 
168     if (value == NULL) {
169         if (required == VK_TRUE) {
170             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
171                                 "PARAMCHECK", "%s: required parameter %s specified as NULL", apiName, parameterName);
172         }
173     } else if (value->sType != sType) {
174         skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
175                             "%s: parameter %s->sType must be %s", apiName, parameterName, sTypeName);
176     }
177 
178     return skipCall;
179 }
180 
181 /**
182  * Validate an array of Vulkan structures.
183  *
184  * Verify that required count and array parameters are not NULL.  If count
185  * is not NULL and its value is not optional, verify that it is not 0.
186  * If the array contains 1 or more structures, verify that each structure's
187  * sType field is set to the correct VkStructureType value.
188  *
189  * @param report_data debug_report_data object for routing validation messages.
190  * @param apiName Name of API call being validated.
191  * @param countName Name of count parameter.
192  * @param arrayName Name of array parameter.
193  * @param sTypeName Name of expected VkStructureType value.
194  * @param count Pointer to the number of elements in the array.
195  * @param array Array to validate.
196  * @param sType VkStructureType for structure validation.
197  * @param countPtrRequired The 'count' parameter may not be NULL when true.
198  * @param countValueRequired The '*count' value may not be 0 when true.
199  * @param arrayRequired The 'array' parameter may not be NULL when true.
200  * @return Boolean value indicating that the call should be skipped.
201  */
202 template <typename T>
validate_struct_type_array(debug_report_data * report_data,const char * apiName,const char * countName,const char * arrayName,const char * sTypeName,const uint32_t * count,const T * array,VkStructureType sType,VkBool32 countPtrRequired,VkBool32 countValueRequired,VkBool32 arrayRequired)203 VkBool32 validate_struct_type_array(debug_report_data *report_data, const char *apiName, const char *countName,
204                                     const char *arrayName, const char *sTypeName, const uint32_t *count, const T *array,
205                                     VkStructureType sType, VkBool32 countPtrRequired, VkBool32 countValueRequired,
206                                     VkBool32 arrayRequired) {
207     VkBool32 skipCall = VK_FALSE;
208 
209     if (count == NULL) {
210         if (countPtrRequired == VK_TRUE) {
211             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
212                                 "PARAMCHECK", "%s: required parameter %s specified as NULL", apiName, countName);
213         }
214     } else {
215         skipCall |= validate_struct_type_array(report_data, apiName, countName, arrayName, sTypeName, (*count), array, sType,
216                                                countValueRequired, arrayRequired);
217     }
218 
219     return skipCall;
220 }
221 
222 /**
223  * Validate an array of Vulkan structures
224  *
225  * Verify that required count and array parameters are not 0 or NULL.  If
226  * the array contains 1 or more structures, verify that each structure's
227  * sType field is set to the correct VkStructureType value.
228  *
229  * @param report_data debug_report_data object for routing validation messages.
230  * @param apiName Name of API call being validated.
231  * @param countName Name of count parameter.
232  * @param arrayName Name of array parameter.
233  * @param sTypeName Name of expected VkStructureType value.
234  * @param count Number of elements in the array.
235  * @param array Array to validate.
236  * @param sType VkStructureType for structure validation.
237  * @param countRequired The 'count' parameter may not be 0 when true.
238  * @param arrayRequired The 'array' parameter may not be NULL when true.
239  * @return Boolean value indicating that the call should be skipped.
240  */
241 template <typename T>
validate_struct_type_array(debug_report_data * report_data,const char * apiName,const char * countName,const char * arrayName,const char * sTypeName,uint32_t count,const T * array,VkStructureType sType,VkBool32 countRequired,VkBool32 arrayRequired)242 VkBool32 validate_struct_type_array(debug_report_data *report_data, const char *apiName, const char *countName,
243                                     const char *arrayName, const char *sTypeName, uint32_t count, const T *array,
244                                     VkStructureType sType, VkBool32 countRequired, VkBool32 arrayRequired) {
245     VkBool32 skipCall = VK_FALSE;
246 
247     if ((count == 0) || (array == NULL)) {
248         // Count parameters not tagged as optional cannot be 0
249         if ((count == 0) && (countRequired == VK_TRUE)) {
250             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
251                                 "PARAMCHECK", "%s: parameter %s must be greater than 0", apiName, countName);
252         }
253 
254         // Array parameters not tagged as optional cannot be NULL,
255         // unless the count is 0
256         if ((array == NULL) && (arrayRequired == VK_TRUE) && (count != 0)) {
257             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
258                                 "PARAMCHECK", "%s: required parameter %s specified as NULL", apiName, arrayName);
259         }
260     } else {
261         // Verify that all structs in the array have the correct type
262         for (uint32_t i = 0; i < count; ++i) {
263             if (array[i].sType != sType) {
264                 skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
265                                     "PARAMCHECK", "%s: parameter %s[%d].sType must be %s", apiName, arrayName, i, sTypeName);
266             }
267         }
268     }
269 
270     return skipCall;
271 }
272 
273 /**
274  * Validate string array count and content.
275  *
276  * Verify that required count and array parameters are not 0 or NULL.  If the
277  * count parameter is not optional, verify that it is not 0.  If the array
278  * parameter is NULL, and it is not optional, verify that count is 0.  If the
279  * array parameter is not NULL, verify that none of the strings are NULL.
280  *
281  * @param report_data debug_report_data object for routing validation messages.
282  * @param apiName Name of API call being validated.
283  * @param countName Name of count parameter.
284  * @param arrayName Name of array parameter.
285  * @param count Number of strings in the array.
286  * @param array Array of strings to validate.
287  * @param countRequired The 'count' parameter may not be 0 when true.
288  * @param arrayRequired The 'array' parameter may not be NULL when true.
289  * @return Boolean value indicating that the call should be skipped.
290  */
validate_string_array(debug_report_data * report_data,const char * apiName,const char * countName,const char * arrayName,uint32_t count,const char * const * array,VkBool32 countRequired,VkBool32 arrayRequired)291 static VkBool32 validate_string_array(debug_report_data *report_data, const char *apiName, const char *countName,
292                                       const char *arrayName, uint32_t count, const char *const *array, VkBool32 countRequired,
293                                       VkBool32 arrayRequired) {
294     VkBool32 skipCall = VK_FALSE;
295 
296     if ((count == 0) || (array == NULL)) {
297         // Count parameters not tagged as optional cannot be 0
298         if ((count == 0) && (countRequired == VK_TRUE)) {
299             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
300                                 "PARAMCHECK", "%s: parameter %s must be greater than 0", apiName, countName);
301         }
302 
303         // Array parameters not tagged as optional cannot be NULL,
304         // unless the count is 0
305         if ((array == NULL) && (arrayRequired == VK_TRUE) && (count != 0)) {
306             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
307                                 "PARAMCHECK", "%s: required parameter %s specified as NULL", apiName, arrayName);
308         }
309     } else {
310         // Verify that strings in the array not NULL
311         for (uint32_t i = 0; i < count; ++i) {
312             if (array[i] == NULL) {
313                 skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
314                                     "PARAMCHECK", "%s: required parameter %s[%d] specified as NULL", apiName, arrayName, i);
315             }
316         }
317     }
318 
319     return skipCall;
320 }
321 
322 /**
323  * Validate a structure's pNext member.
324  *
325  * Verify that the specified pNext value points to the head of a list of
326  * allowed extension structures.  If no extension structures are allowed,
327  * verify that pNext is null.
328  *
329  * @param report_data debug_report_data object for routing validation messages.
330  * @param apiName Name of API call being validated.
331  * @param parameterName Name of parameter being validated.
332  * @param allowedStructNames Names of allowed structs.
333  * @param next Pointer to validate.
334  * @param allowedTypeCount total number of allowed structure types.
335  * @param allowedTypes array of strcuture types allowed for pNext.
336  * @return Boolean value indicating that the call should be skipped.
337  */
validate_struct_pnext(debug_report_data * report_data,const char * apiName,const char * parameterName,const char * allowedStructNames,const void * next,size_t allowedTypeCount,const VkStructureType * allowedTypes)338 static VkBool32 validate_struct_pnext(debug_report_data *report_data, const char *apiName, const char *parameterName,
339                                       const char *allowedStructNames, const void *next, size_t allowedTypeCount,
340                                       const VkStructureType *allowedTypes) {
341     VkBool32 skipCall = VK_FALSE;
342 
343     if (next != NULL) {
344         if (allowedTypeCount == 0) {
345             skipCall |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1,
346                                 "PARAMCHECK", "%s: value of %s must be NULL", apiName, parameterName);
347         } else {
348             const VkStructureType *start = allowedTypes;
349             const VkStructureType *end = allowedTypes + allowedTypeCount;
350             const GenericHeader *current = reinterpret_cast<const GenericHeader *>(next);
351 
352             while (current != NULL) {
353                 if (std::find(start, end, current->sType) == end) {
354                     std::string typeName = string_VkStructureType(current->sType);
355 
356                     if (typeName == UnsupportedStructureTypeString) {
357                         skipCall |= log_msg(
358                             report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
359                             "%s: %s chain includes a structure with unexpected VkStructureType (%d); Allowed structures are [%s]",
360                             apiName, parameterName, current->sType, allowedStructNames);
361                     } else {
362                         skipCall |= log_msg(
363                             report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, "PARAMCHECK",
364                             "%s: %s chain includes a structure with unexpected VkStructureType %s; Allowed structures are [%s]",
365                             apiName, parameterName, typeName.c_str(), allowedStructNames);
366                     }
367                 }
368 
369                 current = reinterpret_cast<const GenericHeader *>(current->pNext);
370             }
371         }
372     }
373 
374     return skipCall;
375 }
376 
377 #endif // PARAMETER_VALIDATION_UTILS_H
378