icd/README.md

   1 # Vulkan Mock ICD
   2
   3 This directory contains a mock ICD driver designed for validation layer testing.
   4
   5 ## Introduction
   6
   7 The mock ICD is focused on enabling validation testing apart from an actual device. Because the validation layers
   8 sit on top of the ICD and don't depend upon the results of Vulkan rendering, they can be tested without having actual
   9 GPU hardware backing the ICD. The final mock driver will be composed of three main features: a null driver, flexible
  10 device configuration, and entrypoint tracking & verification.
  11
  12 ### Null Driver
  13 The intial mock driver features just the null driver capability. This allows all of the validation tests to be run
  14 on a fixed device configuration that is hard-coded into the ICD.
  15
  16 ### Device Configuration
  17 Device configuration can be added by running the DevSim layer below the validation layers, but above the mock driver.
  18 The current plan is that if device customization beyond DevSim's capabilities are required for validation layer testing
  19 then the DevSim layer will be enhanced with the required features. The mock layer itself is just planned to have some
  20 hard-coded device settings that will enable it to run all of the validation tests.
  21
  22 ### Entrypoint Tracking & Verification
  23 Entrypoint tracking and verification will be added to the mock layer as a later feature. The idea is that all expected
  24 Vulkan function calls and their parameters can be stored in the ICD and then a separate call can be made to verify that
  25 the exepected calls and parameters actually entered the ICD. This allows verification that the validation layers are
  26 correctly passing calls and their parameters through to the ICD unchanged.
  27
  28 ## Using the Mock ICD
  29
  30 To enable the mock ICD, set VK\_ICD\_FILENAMES environment variable to point to your {BUILD_DIR}/icd/VkICD\_mock\_icd.json.
  31
  32 ## Plans
  33
  34 The initial mock ICD is just the null driver which can be used in combination with DevSim to test validation layers on
  35 simulated devices. Here's a rough sequence of tasks planned for the mock driver going forward:
  36 - [X] Get all LVL tests passing on the bare null driver
  37 - [X] Get failing tests passing
  38 - [X] Get skipped tests passing as able
  39 - [ ] Get all LVL tests to run without unexpected errors
  40 - [X] Develop automated test flow using mock ICD (alternative to or replacement for run\_all\_tests.sh)
  41 - [X] Get all LVL tests to pass on a selection of device profiles using DevSim layer
  42 - [ ] Update LVL tests with device dependencies to target specific device profiles
  43 - [ ] Add entrypoint tracking & verification
  44 - [ ] Initially track expected calls
  45 - [ ] Update some tests to verify expected capability
  46 - [ ] Expand tracking to include parameters
  47
  48 ## Beyond Validation Layer Testing
  49
  50 The focus of the mock icd is for validation testing, but the code is available to use and enhance for anyone wishing to apply it for alternative
  51 purposes.
  52 With the following enhancements, the mock driver state available to the app should very closely mimic an actual ICD:
  53 - Update various function return codes
  54 - Simulated synchronization objects
  55 - Simulated query with mock data
  56 - Basic command buffer state tracking to note synch object transitions and query state updates
  57
  58 Beyond that it's certainly possible that the mock icd could be hooked up to a SW renderer and serve as a virtual GPU with complete rendering/compute
  59 capabilities.
  60
  61 ## Status
  62
  63 This is a temporary section used for tracking as the mock icd is being developed. Once all tests are passing with the mock, this section can be removed.
  64 Currently 333/333 tests are passing with the mock icd, but many passing tests have unexpected validation errors that need to be cleaned up.
  65
  66 ### Failing Tests
  67
  68 NONE
  69
  70 ### Passing Tests With Unexpected Errors
  71
  72 - VkLayerTest.RenderPassInUseDestroyedSignaled
  73 - VkLayerTest.RenderPassIncompatible
  74
  75 ### Skipped Tests
  76
  77 - VkLayerTest.BindImageInvalidMemoryType
  78 - VkLayerTest.CreatePipelineBadVertexAttributeFormat
  79 - VkLayerTest.MiscBlitImageTests
  80 - VkLayerTest.TemporaryExternalSemaphore
  81 - VkLayerTest.TemporaryExternalFence
  82 - VkLayerTest.InvalidBarriers
  83 - VkLayerTest.CommandQueueFlags
  84 - VkPositiveLayerTest.TwoQueuesEnsureCorrectRetirementWithWorkStolen
  85 - VkPositiveLayerTest.ExternalSemaphore
  86 - VkPositiveLayerTest.ExternalFence
  87 - VkPositiveLayerTest.ExternalMemory