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 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * Author: Dustin Graves <dustin (at) lunarg.com> 19 */ 20 21 #ifndef PARAMETER_VALIDATION_UTILS_H 22 #define PARAMETER_VALIDATION_UTILS_H 23 24 #include <algorithm> 25 #include <cstdlib> 26 #include <string> 27 28 #include "vulkan/vulkan.h" 29 #include "vk_enum_string_helper.h" 30 #include "vk_layer_logging.h" 31 #include "vk_validation_error_messages.h" 32 33 #include "parameter_name.h" 34 35 #include "parameter_name.h" 36 37 namespace parameter_validation { 38 39 enum ErrorCode { 40 NONE, // Used for INFO & other non-error messages 41 INVALID_USAGE, // The value of a parameter is not consistent 42 // with the valid usage criteria defined in 43 // the Vulkan specification. 44 INVALID_STRUCT_STYPE, // The sType field of a Vulkan structure does 45 // not contain the value expected for a structure 46 // of that type. 47 INVALID_STRUCT_PNEXT, // The pNext field of a Vulkan structure references 48 // a value that is not compatible with a structure of 49 // that type or is not NULL when a structure of that 50 // type has no compatible pNext values. 51 REQUIRED_PARAMETER, // A required parameter was specified as 0 or NULL. 52 RESERVED_PARAMETER, // A parameter reserved for future use was not 53 // specified as 0 or NULL. 54 UNRECOGNIZED_VALUE, // A Vulkan enumeration, VkFlags, or VkBool32 parameter 55 // contains a value that is not recognized as valid for 56 // that type. 57 DEVICE_LIMIT, // A specified parameter exceeds the limits returned 58 // by the physical device 59 DEVICE_FEATURE, // Use of a requested feature is not supported by 60 // the device 61 FAILURE_RETURN_CODE, // A Vulkan return code indicating a failure condition 62 // was encountered. 63 }; 64 65 struct GenericHeader { 66 VkStructureType sType; 67 const void *pNext; 68 }; 69 70 // Layer name string to be logged with validation messages. 71 const char LayerName[] = "ParameterValidation"; 72 73 // Enables for display-related instance extensions 74 struct instance_extension_enables { 75 bool wsi_enabled; 76 bool xlib_enabled; 77 bool xcb_enabled; 78 bool wayland_enabled; 79 bool mir_enabled; 80 bool android_enabled; 81 bool win32_enabled; 82 }; 83 84 // String returned by string_VkStructureType for an unrecognized type. 85 const std::string UnsupportedStructureTypeString = "Unhandled VkStructureType"; 86 87 // String returned by string_VkResult for an unrecognized type. 88 const std::string UnsupportedResultString = "Unhandled VkResult"; 89 90 // The base value used when computing the offset for an enumeration token value that is added by an extension. 91 // When validating enumeration tokens, any value >= to this value is considered to be provided by an extension. 92 // See Appendix C.10 "Assigning Extension Token Values" from the Vulkan specification 93 const uint32_t ExtEnumBaseValue = 1000000000; 94 95 template <typename T> bool is_extension_added_token(T value) { 96 return (std::abs(static_cast<int32_t>(value)) >= ExtEnumBaseValue); 97 } 98 99 // VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE token is a special case that was converted from a core token to an 100 // extension added token. Its original value was intentionally preserved after the conversion, so it does not use 101 // the base value that other extension added tokens use, and it does not fall within the enum's begin/end range. 102 template <> bool is_extension_added_token(VkSamplerAddressMode value) { 103 bool result = (std::abs(static_cast<int32_t>(value)) >= ExtEnumBaseValue); 104 return (result || (value == VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE)); 105 } 106 107 /** 108 * Validate a minimum value. 109 * 110 * Verify that the specified value is greater than the specified lower bound. 111 * 112 * @param report_data debug_report_data object for routing validation messages. 113 * @param api_name Name of API call being validated. 114 * @param parameter_name Name of parameter being validated. 115 * @param value Value to validate. 116 * @param lower_bound Lower bound value to use for validation. 117 * @return Boolean value indicating that the call should be skipped. 118 */ 119 template <typename T> 120 bool ValidateGreaterThan(debug_report_data *report_data, const char *api_name, const ParameterName ¶meter_name, T value, 121 T lower_bound) { 122 bool skip_call = false; 123 124 if (value <= lower_bound) { 125 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, (VkDebugReportObjectTypeEXT)0, 0, __LINE__, 1, LayerName, 126 "%s: parameter %s must be greater than %d", api_name, parameter_name.get_name().c_str(), lower_bound); 127 } 128 129 return skip_call; 130 } 131 132 /** 133 * Validate a required pointer. 134 * 135 * Verify that a required pointer is not NULL. 136 * 137 * @param report_data debug_report_data object for routing validation messages. 138 * @param apiName Name of API call being validated. 139 * @param parameterName Name of parameter being validated. 140 * @param value Pointer to validate. 141 * @return Boolean value indicating that the call should be skipped. 142 */ 143 static bool validate_required_pointer(debug_report_data *report_data, const char *apiName, const ParameterName ¶meterName, 144 const void *value) { 145 bool skip_call = false; 146 147 if (value == NULL) { 148 149 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 150 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as NULL", apiName, 151 parameterName.get_name().c_str()); 152 } 153 154 return skip_call; 155 } 156 157 /** 158 * Validate array count and pointer to array. 159 * 160 * Verify that required count and array parameters are not 0 or NULL. If the 161 * count parameter is not optional, verify that it is not 0. If the array 162 * parameter is NULL, and it is not optional, verify that count is 0. 163 * 164 * @param report_data debug_report_data object for routing validation messages. 165 * @param apiName Name of API call being validated. 166 * @param countName Name of count parameter. 167 * @param arrayName Name of array parameter. 168 * @param count Number of elements in the array. 169 * @param array Array to validate. 170 * @param countRequired The 'count' parameter may not be 0 when true. 171 * @param arrayRequired The 'array' parameter may not be NULL when true. 172 * @return Boolean value indicating that the call should be skipped. 173 */ 174 template <typename T> 175 bool validate_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 176 const ParameterName &arrayName, T count, const void *array, bool countRequired, bool arrayRequired) { 177 bool skip_call = false; 178 179 // Count parameters not tagged as optional cannot be 0 180 if (countRequired && (count == 0)) { 181 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 182 REQUIRED_PARAMETER, LayerName, "%s: parameter %s must be greater than 0", apiName, 183 countName.get_name().c_str()); 184 } 185 186 // Array parameters not tagged as optional cannot be NULL, unless the count is 0 187 if ((array == NULL) && arrayRequired && (count != 0)) { 188 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 189 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as NULL", apiName, 190 arrayName.get_name().c_str()); 191 } 192 193 return skip_call; 194 } 195 196 /** 197 * Validate pointer to array count and pointer to array. 198 * 199 * Verify that required count and array parameters are not NULL. If count 200 * is not NULL and its value is not optional, verify that it is not 0. If the 201 * array parameter is NULL, and it is not optional, verify that count is 0. 202 * The array parameter will typically be optional for this case (where count is 203 * a pointer), allowing the caller to retrieve the available count. 204 * 205 * @param report_data debug_report_data object for routing validation messages. 206 * @param apiName Name of API call being validated. 207 * @param countName Name of count parameter. 208 * @param arrayName Name of array parameter. 209 * @param count Pointer to the number of elements in the array. 210 * @param array Array to validate. 211 * @param countPtrRequired The 'count' parameter may not be NULL when true. 212 * @param countValueRequired The '*count' value may not be 0 when true. 213 * @param arrayRequired The 'array' parameter may not be NULL when true. 214 * @return Boolean value indicating that the call should be skipped. 215 */ 216 template <typename T> 217 bool validate_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 218 const ParameterName &arrayName, const T *count, const void *array, bool countPtrRequired, 219 bool countValueRequired, bool arrayRequired) { 220 bool skip_call = false; 221 222 if (count == NULL) { 223 if (countPtrRequired) { 224 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 225 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as NULL", apiName, 226 countName.get_name().c_str()); 227 } 228 } 229 else { 230 skip_call |= validate_array(report_data, apiName, countName, arrayName, (*count), array, countValueRequired, arrayRequired); 231 } 232 233 return skip_call; 234 } 235 236 /** 237 * Validate a pointer to a Vulkan structure. 238 * 239 * Verify that a required pointer to a structure is not NULL. If the pointer is 240 * not NULL, verify that each structure's sType field is set to the correct 241 * VkStructureType value. 242 * 243 * @param report_data debug_report_data object for routing validation messages. 244 * @param apiName Name of API call being validated. 245 * @param parameterName Name of struct parameter being validated. 246 * @param sTypeName Name of expected VkStructureType value. 247 * @param value Pointer to the struct to validate. 248 * @param sType VkStructureType for structure validation. 249 * @param required The parameter may not be NULL when true. 250 * @return Boolean value indicating that the call should be skipped. 251 */ 252 template <typename T> 253 bool validate_struct_type(debug_report_data *report_data, const char *apiName, const ParameterName ¶meterName, 254 const char *sTypeName, const T *value, VkStructureType sType, bool required) { 255 bool skip_call = false; 256 257 if (value == NULL) { 258 if (required) { 259 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 260 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as NULL", apiName, 261 parameterName.get_name().c_str()); 262 } 263 } else if (value->sType != sType) { 264 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 265 INVALID_STRUCT_STYPE, LayerName, "%s: parameter %s->sType must be %s", apiName, 266 parameterName.get_name().c_str(), sTypeName); 267 } 268 269 return skip_call; 270 } 271 272 /** 273 * Validate an array of Vulkan structures. 274 * 275 * Verify that required count and array parameters are not NULL. If count 276 * is not NULL and its value is not optional, verify that it is not 0. 277 * If the array contains 1 or more structures, verify that each structure's 278 * sType field is set to the correct VkStructureType value. 279 * 280 * @param report_data debug_report_data object for routing validation messages. 281 * @param apiName Name of API call being validated. 282 * @param countName Name of count parameter. 283 * @param arrayName Name of array parameter. 284 * @param sTypeName Name of expected VkStructureType value. 285 * @param count Pointer to the number of elements in the array. 286 * @param array Array to validate. 287 * @param sType VkStructureType for structure validation. 288 * @param countPtrRequired The 'count' parameter may not be NULL when true. 289 * @param countValueRequired The '*count' value may not be 0 when true. 290 * @param arrayRequired The 'array' parameter may not be NULL when true. 291 * @return Boolean value indicating that the call should be skipped. 292 */ 293 template <typename T> 294 bool validate_struct_type_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 295 const ParameterName &arrayName, const char *sTypeName, const uint32_t *count, const T *array, 296 VkStructureType sType, bool countPtrRequired, bool countValueRequired, bool arrayRequired) { 297 bool skip_call = false; 298 299 if (count == NULL) { 300 if (countPtrRequired) { 301 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 302 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as NULL", apiName, 303 countName.get_name().c_str()); 304 } 305 } else { 306 skip_call |= validate_struct_type_array(report_data, apiName, countName, arrayName, sTypeName, (*count), array, sType, 307 countValueRequired, arrayRequired); 308 } 309 310 return skip_call; 311 } 312 313 /** 314 * Validate an array of Vulkan structures 315 * 316 * Verify that required count and array parameters are not 0 or NULL. If 317 * the array contains 1 or more structures, verify that each structure's 318 * sType field is set to the correct VkStructureType value. 319 * 320 * @param report_data debug_report_data object for routing validation messages. 321 * @param apiName Name of API call being validated. 322 * @param countName Name of count parameter. 323 * @param arrayName Name of array parameter. 324 * @param sTypeName Name of expected VkStructureType value. 325 * @param count Number of elements in the array. 326 * @param array Array to validate. 327 * @param sType VkStructureType for structure validation. 328 * @param countRequired The 'count' parameter may not be 0 when true. 329 * @param arrayRequired The 'array' parameter may not be NULL when true. 330 * @return Boolean value indicating that the call should be skipped. 331 */ 332 template <typename T> 333 bool validate_struct_type_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 334 const ParameterName &arrayName, const char *sTypeName, uint32_t count, const T *array, 335 VkStructureType sType, bool countRequired, bool arrayRequired) { 336 bool skip_call = false; 337 338 if ((count == 0) || (array == NULL)) { 339 skip_call |= validate_array(report_data, apiName, countName, arrayName, count, array, countRequired, arrayRequired); 340 } else { 341 // Verify that all structs in the array have the correct type 342 for (uint32_t i = 0; i < count; ++i) { 343 if (array[i].sType != sType) { 344 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, 345 __LINE__, INVALID_STRUCT_STYPE, LayerName, "%s: parameter %s[%d].sType must be %s", apiName, 346 arrayName.get_name().c_str(), i, sTypeName); 347 } 348 } 349 } 350 351 return skip_call; 352 } 353 354 /** 355 * Validate a Vulkan handle. 356 * 357 * Verify that the specified handle is not VK_NULL_HANDLE. 358 * 359 * @param report_data debug_report_data object for routing validation messages. 360 * @param api_name Name of API call being validated. 361 * @param parameter_name Name of struct parameter being validated. 362 * @param value Handle to validate. 363 * @return Boolean value indicating that the call should be skipped. 364 */ 365 template <typename T> 366 bool validate_required_handle(debug_report_data *report_data, const char *api_name, const ParameterName ¶meter_name, T value) { 367 bool skip_call = false; 368 369 if (value == VK_NULL_HANDLE) { 370 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 371 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s specified as VK_NULL_HANDLE", api_name, 372 parameter_name.get_name().c_str()); 373 } 374 375 return skip_call; 376 } 377 378 /** 379 * Validate an array of Vulkan handles. 380 * 381 * Verify that required count and array parameters are not NULL. If count 382 * is not NULL and its value is not optional, verify that it is not 0. 383 * If the array contains 1 or more handles, verify that no handle is set to 384 * VK_NULL_HANDLE. 385 * 386 * @note This function is only intended to validate arrays of handles when none 387 * of the handles are allowed to be VK_NULL_HANDLE. For arrays of handles 388 * that are allowed to contain VK_NULL_HANDLE, use validate_array() instead. 389 * 390 * @param report_data debug_report_data object for routing validation messages. 391 * @param api_name Name of API call being validated. 392 * @param count_name Name of count parameter. 393 * @param array_name Name of array parameter. 394 * @param count Number of elements in the array. 395 * @param array Array to validate. 396 * @param count_required The 'count' parameter may not be 0 when true. 397 * @param array_required The 'array' parameter may not be NULL when true. 398 * @return Boolean value indicating that the call should be skipped. 399 */ 400 template <typename T> 401 bool validate_handle_array(debug_report_data *report_data, const char *api_name, const ParameterName &count_name, 402 const ParameterName &array_name, uint32_t count, const T *array, bool count_required, 403 bool array_required) { 404 bool skip_call = false; 405 406 if ((count == 0) || (array == NULL)) { 407 skip_call |= validate_array(report_data, api_name, count_name, array_name, count, array, count_required, array_required); 408 } else { 409 // Verify that no handles in the array are VK_NULL_HANDLE 410 for (uint32_t i = 0; i < count; ++i) { 411 if (array[i] == VK_NULL_HANDLE) { 412 skip_call |= 413 log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 414 REQUIRED_PARAMETER, LayerName, "%s: required parameter %s[%d] specified as VK_NULL_HANDLE", api_name, 415 array_name.get_name().c_str(), i); 416 } 417 } 418 } 419 420 return skip_call; 421 } 422 423 /** 424 * Validate string array count and content. 425 * 426 * Verify that required count and array parameters are not 0 or NULL. If the 427 * count parameter is not optional, verify that it is not 0. If the array 428 * parameter is NULL, and it is not optional, verify that count is 0. If the 429 * array parameter is not NULL, verify that none of the strings are NULL. 430 * 431 * @param report_data debug_report_data object for routing validation messages. 432 * @param apiName Name of API call being validated. 433 * @param countName Name of count parameter. 434 * @param arrayName Name of array parameter. 435 * @param count Number of strings in the array. 436 * @param array Array of strings to validate. 437 * @param countRequired The 'count' parameter may not be 0 when true. 438 * @param arrayRequired The 'array' parameter may not be NULL when true. 439 * @return Boolean value indicating that the call should be skipped. 440 */ 441 static bool validate_string_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 442 const ParameterName &arrayName, uint32_t count, const char *const *array, bool countRequired, 443 bool arrayRequired) { 444 bool skip_call = false; 445 446 if ((count == 0) || (array == NULL)) { 447 skip_call |= validate_array(report_data, apiName, countName, arrayName, count, array, countRequired, arrayRequired); 448 } else { 449 // Verify that strings in the array are not NULL 450 for (uint32_t i = 0; i < count; ++i) { 451 if (array[i] == NULL) { 452 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, 453 __LINE__, REQUIRED_PARAMETER, LayerName, "%s: required parameter %s[%d] specified as NULL", 454 apiName, arrayName.get_name().c_str(), i); 455 } 456 } 457 } 458 459 return skip_call; 460 } 461 462 /** 463 * Validate a structure's pNext member. 464 * 465 * Verify that the specified pNext value points to the head of a list of 466 * allowed extension structures. If no extension structures are allowed, 467 * verify that pNext is null. 468 * 469 * @param report_data debug_report_data object for routing validation messages. 470 * @param api_name Name of API call being validated. 471 * @param parameter_name Name of parameter being validated. 472 * @param allowed_struct_names Names of allowed structs. 473 * @param next Pointer to validate. 474 * @param allowed_type_count Total number of allowed structure types. 475 * @param allowed_types Array of strcuture types allowed for pNext. 476 * @param header_version Version of header defining the pNext validation rules. 477 * @return Boolean value indicating that the call should be skipped. 478 */ 479 static bool validate_struct_pnext(debug_report_data *report_data, const char *api_name, const ParameterName ¶meter_name, 480 const char *allowed_struct_names, const void *next, size_t allowed_type_count, 481 const VkStructureType *allowed_types, uint32_t header_version) { 482 bool skip_call = false; 483 const char disclaimer[] = "This warning is based on the Valid Usage documentation for version %d of the Vulkan header. It " 484 "is possible that you are using a struct from a private extension or an extension that was added " 485 "to a later version of the Vulkan header, in which case your use of %s is perfectly valid but " 486 "is not guaranteed to work correctly with validation enabled"; 487 488 if (next != NULL) { 489 if (allowed_type_count == 0) { 490 std::string message = "%s: value of %s must be NULL. "; 491 message += disclaimer; 492 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 493 INVALID_STRUCT_PNEXT, LayerName, message.c_str(), api_name, parameter_name.get_name().c_str(), 494 header_version, parameter_name.get_name().c_str()); 495 } else { 496 const VkStructureType *start = allowed_types; 497 const VkStructureType *end = allowed_types + allowed_type_count; 498 const GenericHeader *current = reinterpret_cast<const GenericHeader *>(next); 499 500 while (current != NULL) { 501 if (std::find(start, end, current->sType) == end) { 502 std::string type_name = string_VkStructureType(current->sType); 503 504 if (type_name == UnsupportedStructureTypeString) { 505 std::string message = "%s: %s chain includes a structure with unexpected VkStructureType (%d); Allowed " 506 "structures are [%s]. "; 507 message += disclaimer; 508 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 509 0, __LINE__, INVALID_STRUCT_PNEXT, LayerName, message.c_str(), api_name, 510 parameter_name.get_name().c_str(), current->sType, allowed_struct_names, 511 header_version, parameter_name.get_name().c_str()); 512 } else { 513 std::string message = 514 "%s: %s chain includes a structure with unexpected VkStructureType %s; Allowed structures are [%s]. "; 515 message += disclaimer; 516 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 517 0, __LINE__, INVALID_STRUCT_PNEXT, LayerName, message.c_str(), api_name, 518 parameter_name.get_name().c_str(), type_name.c_str(), allowed_struct_names, 519 header_version, parameter_name.get_name().c_str()); 520 } 521 } 522 523 current = reinterpret_cast<const GenericHeader *>(current->pNext); 524 } 525 } 526 } 527 528 return skip_call; 529 } 530 531 /** 532 * Validate a VkBool32 value. 533 * 534 * Generate a warning if a VkBool32 value is neither VK_TRUE nor VK_FALSE. 535 * 536 * @param report_data debug_report_data object for routing validation messages. 537 * @param apiName Name of API call being validated. 538 * @param parameterName Name of parameter being validated. 539 * @param value Boolean value to validate. 540 * @return Boolean value indicating that the call should be skipped. 541 */ 542 static bool validate_bool32(debug_report_data *report_data, const char *apiName, const ParameterName ¶meterName, 543 VkBool32 value) { 544 bool skip_call = false; 545 546 if ((value != VK_TRUE) && (value != VK_FALSE)) { 547 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 548 UNRECOGNIZED_VALUE, LayerName, "%s: value of %s (%d) is neither VK_TRUE nor VK_FALSE", apiName, 549 parameterName.get_name().c_str(), value); 550 } 551 552 return skip_call; 553 } 554 555 /** 556 * Validate a Vulkan enumeration value. 557 * 558 * Generate a warning if an enumeration token value does not fall within the core enumeration 559 * begin and end token values, and was not added to the enumeration by an extension. Extension 560 * provided enumerations use the equation specified in Appendix C.10 of the Vulkan specification, 561 * with 1,000,000,000 as the base token value. 562 * 563 * @note This function does not expect to process enumerations defining bitmask flag bits. 564 * 565 * @param report_data debug_report_data object for routing validation messages. 566 * @param apiName Name of API call being validated. 567 * @param parameterName Name of parameter being validated. 568 * @param enumName Name of the enumeration being validated. 569 * @param begin The begin range value for the enumeration. 570 * @param end The end range value for the enumeration. 571 * @param value Enumeration value to validate. 572 * @return Boolean value indicating that the call should be skipped. 573 */ 574 template <typename T> 575 bool validate_ranged_enum(debug_report_data *report_data, const char *apiName, const ParameterName ¶meterName, 576 const char *enumName, T begin, T end, T value) { 577 bool skip_call = false; 578 579 if (((value < begin) || (value > end)) && !is_extension_added_token(value)) { 580 skip_call |= 581 log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 582 UNRECOGNIZED_VALUE, LayerName, "%s: value of %s (%d) does not fall within the begin..end range of the core %s " 583 "enumeration tokens and is not an extension added token", 584 apiName, parameterName.get_name().c_str(), value, enumName); 585 } 586 587 return skip_call; 588 } 589 590 /** 591 * Validate an array of Vulkan enumeration value. 592 * 593 * Process all enumeration token values in the specified array and generate a warning if a value 594 * does not fall within the core enumeration begin and end token values, and was not added to 595 * the enumeration by an extension. Extension provided enumerations use the equation specified 596 * in Appendix C.10 of the Vulkan specification, with 1,000,000,000 as the base token value. 597 * 598 * @note This function does not expect to process enumerations defining bitmask flag bits. 599 * 600 * @param report_data debug_report_data object for routing validation messages. 601 * @param apiName Name of API call being validated. 602 * @param countName Name of count parameter. 603 * @param arrayName Name of array parameter. 604 * @param enumName Name of the enumeration being validated. 605 * @param begin The begin range value for the enumeration. 606 * @param end The end range value for the enumeration. 607 * @param count Number of enumeration values in the array. 608 * @param array Array of enumeration values to validate. 609 * @param countRequired The 'count' parameter may not be 0 when true. 610 * @param arrayRequired The 'array' parameter may not be NULL when true. 611 * @return Boolean value indicating that the call should be skipped. 612 */ 613 template <typename T> 614 static bool validate_ranged_enum_array(debug_report_data *report_data, const char *apiName, const ParameterName &countName, 615 const ParameterName &arrayName, const char *enumName, T begin, T end, uint32_t count, 616 const T *array, bool countRequired, bool arrayRequired) { 617 bool skip_call = false; 618 619 if ((count == 0) || (array == NULL)) { 620 skip_call |= validate_array(report_data, apiName, countName, arrayName, count, array, countRequired, arrayRequired); 621 } else { 622 for (uint32_t i = 0; i < count; ++i) { 623 if (((array[i] < begin) || (array[i] > end)) && !is_extension_added_token(array[i])) { 624 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, 625 __LINE__, UNRECOGNIZED_VALUE, LayerName, 626 "%s: value of %s[%d] (%d) does not fall within the begin..end range of the core %s " 627 "enumeration tokens and is not an extension added token", 628 apiName, arrayName.get_name().c_str(), i, array[i], enumName); 629 } 630 } 631 } 632 633 return skip_call; 634 } 635 636 /** 637 * Verify that a reserved VkFlags value is zero. 638 * 639 * Verify that the specified value is zero, to check VkFlags values that are reserved for 640 * future use. 641 * 642 * @param report_data debug_report_data object for routing validation messages. 643 * @param api_name Name of API call being validated. 644 * @param parameter_name Name of parameter being validated. 645 * @param value Value to validate. 646 * @return Boolean value indicating that the call should be skipped. 647 */ 648 static bool validate_reserved_flags(debug_report_data *report_data, const char *api_name, const ParameterName ¶meter_name, 649 VkFlags value) { 650 bool skip_call = false; 651 652 if (value != 0) { 653 skip_call |= 654 log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 655 RESERVED_PARAMETER, LayerName, "%s: parameter %s must be 0", api_name, parameter_name.get_name().c_str()); 656 } 657 658 return skip_call; 659 } 660 661 /** 662 * Validate a Vulkan bitmask value. 663 * 664 * Generate a warning if a value with a VkFlags derived type does not contain valid flag bits 665 * for that type. 666 * 667 * @param report_data debug_report_data object for routing validation messages. 668 * @param api_name Name of API call being validated. 669 * @param parameter_name Name of parameter being validated. 670 * @param flag_bits_name Name of the VkFlags type being validated. 671 * @param all_flags A bit mask combining all valid flag bits for the VkFlags type being validated. 672 * @param value VkFlags value to validate. 673 * @param flags_required The 'value' parameter may not be 0 when true. 674 * @return Boolean value indicating that the call should be skipped. 675 */ 676 static bool validate_flags(debug_report_data *report_data, const char *api_name, const ParameterName ¶meter_name, 677 const char *flag_bits_name, VkFlags all_flags, VkFlags value, bool flags_required) { 678 bool skip_call = false; 679 680 if (value == 0) { 681 if (flags_required) { 682 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 683 REQUIRED_PARAMETER, LayerName, "%s: value of %s must not be 0", api_name, 684 parameter_name.get_name().c_str()); 685 } 686 } else if ((value & (~all_flags)) != 0) { 687 skip_call |= 688 log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 689 UNRECOGNIZED_VALUE, LayerName, "%s: value of %s contains flag bits that are not recognized members of %s", 690 api_name, parameter_name.get_name().c_str(), flag_bits_name); 691 } 692 693 return skip_call; 694 } 695 696 /** 697 * Validate an array of Vulkan bitmask values. 698 * 699 * Generate a warning if a value with a VkFlags derived type does not contain valid flag bits 700 * for that type. 701 * 702 * @param report_data debug_report_data object for routing validation messages. 703 * @param api_name Name of API call being validated. 704 * @param count_name Name of parameter being validated. 705 * @param array_name Name of parameter being validated. 706 * @param flag_bits_name Name of the VkFlags type being validated. 707 * @param all_flags A bitmask combining all valid flag bits for the VkFlags type being validated. 708 * @param count Number of VkFlags values in the array. 709 * @param array Array of VkFlags value to validate. 710 * @param count_required The 'count' parameter may not be 0 when true. 711 * @param array_required The 'array' parameter may not be NULL when true. 712 * @return Boolean value indicating that the call should be skipped. 713 */ 714 static bool validate_flags_array(debug_report_data *report_data, const char *api_name, const ParameterName &count_name, 715 const ParameterName &array_name, const char *flag_bits_name, VkFlags all_flags, uint32_t count, 716 const VkFlags *array, bool count_required, bool array_required) { 717 bool skip_call = false; 718 719 if ((count == 0) || (array == NULL)) { 720 skip_call |= validate_array(report_data, api_name, count_name, array_name, count, array, count_required, array_required); 721 } else { 722 // Verify that all VkFlags values in the array 723 for (uint32_t i = 0; i < count; ++i) { 724 if (array[i] == 0) { 725 // Current XML registry logic for validity generation uses the array parameter's optional tag to determine if 726 // elements in the array are allowed be 0 727 if (array_required) { 728 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, 729 __LINE__, REQUIRED_PARAMETER, LayerName, "%s: value of %s[%d] must not be 0", api_name, 730 array_name.get_name().c_str(), i); 731 } 732 } else if ((array[i] & (~all_flags)) != 0) { 733 skip_call |= log_msg(report_data, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, 734 __LINE__, UNRECOGNIZED_VALUE, LayerName, 735 "%s: value of %s[%d] contains flag bits that are not recognized members of %s", api_name, 736 array_name.get_name().c_str(), i, flag_bits_name); 737 } 738 } 739 } 740 741 return skip_call; 742 } 743 744 /** 745 * Get VkResult code description. 746 * 747 * Returns a string describing the specified VkResult code. The description is based on the language in the Vulkan API 748 * specification. 749 * 750 * @param value VkResult code to process. 751 * @return String describing the specified VkResult code. 752 */ 753 static std::string get_result_description(VkResult result) { 754 // clang-format off 755 switch (result) { 756 case VK_SUCCESS: return "a command completed successfully"; 757 case VK_NOT_READY: return "a fence or query has not yet completed"; 758 case VK_TIMEOUT: return "a wait operation has not completed in the specified time"; 759 case VK_EVENT_SET: return "an event is signaled"; 760 case VK_EVENT_RESET: return "an event is unsignalled"; 761 case VK_INCOMPLETE: return "a return array was too small for the result"; 762 case VK_ERROR_OUT_OF_HOST_MEMORY: return "a host memory allocation has failed"; 763 case VK_ERROR_OUT_OF_DEVICE_MEMORY: return "a device memory allocation has failed"; 764 case VK_ERROR_INITIALIZATION_FAILED: return "initialization of an object has failed"; 765 case VK_ERROR_DEVICE_LOST: return "the logical device has been lost"; 766 case VK_ERROR_MEMORY_MAP_FAILED: return "mapping of a memory object has failed"; 767 case VK_ERROR_LAYER_NOT_PRESENT: return "the specified layer does not exist"; 768 case VK_ERROR_EXTENSION_NOT_PRESENT: return "the specified extension does not exist"; 769 case VK_ERROR_FEATURE_NOT_PRESENT: return "the requested feature is not available on this device"; 770 case VK_ERROR_INCOMPATIBLE_DRIVER: return "a Vulkan driver could not be found"; 771 case VK_ERROR_TOO_MANY_OBJECTS: return "too many objects of the type have already been created"; 772 case VK_ERROR_FORMAT_NOT_SUPPORTED: return "the requested format is not supported on this device"; 773 case VK_ERROR_SURFACE_LOST_KHR: return "a surface is no longer available"; 774 case VK_ERROR_NATIVE_WINDOW_IN_USE_KHR: return "the requested window is already connected to another " 775 "VkSurfaceKHR object, or some other non-Vulkan surface object"; 776 case VK_SUBOPTIMAL_KHR: return "an image became available, and the swapchain no longer " 777 "matches the surface properties exactly, but can still be used to " 778 "present to the surface successfully."; 779 case VK_ERROR_OUT_OF_DATE_KHR: return "a surface has changed in such a way that it is no " 780 "longer compatible with the swapchain"; 781 case VK_ERROR_INCOMPATIBLE_DISPLAY_KHR: return "the display used by a swapchain does not use the same " 782 "presentable image layout, or is incompatible in a way that prevents " 783 "sharing an image"; 784 case VK_ERROR_VALIDATION_FAILED_EXT: return "API validation has detected an invalid use of the API"; 785 case VK_ERROR_INVALID_SHADER_NV: return "one or more shaders failed to compile or link"; 786 default: return "an error has occurred"; 787 }; 788 // clang-format on 789 } 790 791 /** 792 * Validate return code. 793 * 794 * Print a message describing the reason for failure when an error code is returned. 795 * 796 * @param report_data debug_report_data object for routing validation messages. 797 * @param apiName Name of API call being validated. 798 * @param value VkResult value to validate. 799 */ 800 static void validate_result(debug_report_data *report_data, const char *apiName, VkResult result) { 801 if (result < 0 && result != VK_ERROR_VALIDATION_FAILED_EXT) { 802 std::string resultName = string_VkResult(result); 803 804 if (resultName == UnsupportedResultString) { 805 // Unrecognized result code 806 log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 807 FAILURE_RETURN_CODE, LayerName, "%s: returned a result code indicating that an error has occurred", apiName); 808 } else { 809 std::string resultDesc = get_result_description(result); 810 log_msg(report_data, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 0, __LINE__, 811 FAILURE_RETURN_CODE, LayerName, "%s: returned %s, indicating that %s", apiName, resultName.c_str(), 812 resultDesc.c_str()); 813 } 814 } 815 } 816 817 } // namespace parameter_validation 818 819 #endif // PARAMETER_VALIDATION_UTILS_H 820
