loader: Move long DEBUG_REPORT comments into debug report source code

diff --git a/loader/debug_report.h b/loader/debug_report.h
index a617e0e..0c4371d 100644 (file)
--- a/loader/debug_report.h
+++ b/loader/debug_report.h
@@ -29,6 +29,66 @@
 #include "vk_loader_platform.h"
 #include "loader.h"
 #include "vk_debug_report_lunarg.h"
+    /*
+     * CreateMsgCallback is global and needs to be
+     * applied to all layers and ICDs.
+     * What happens if a layer is enabled on both the instance chain
+     * as well as the device chain and a call to CreateMsgCallback is made?
+     * Do we need to make sure that each layer / driver only gets called once?
+     * Should a layer implementing support for CreateMsgCallback only be allowed (?)
+     * to live on one chain? Or maybe make it the application's responsibility.
+     * If the app enables DRAW_STATE on at both CreateInstance time and CreateDevice
+     * time, CreateMsgCallback will call the DRAW_STATE layer twice. Once via
+     * the instance chain and once via the device chain.
+     * The loader should only return the DEBUG_REPORT extension as supported
+     * for the GetGlobalExtensionSupport call. That should help eliminate one
+     * duplication.
+     * Since the instance chain requires us iterating over the available ICDs
+     * and each ICD will have it's own unique MsgCallback object we need to
+     * track those objects to give back the right one.
+     * This also implies that the loader has to intercept vkDestroyObject and
+     * if the extension is enabled and the object type is a MsgCallback then
+     * we must translate the object into the proper ICD specific ones.
+     * DestroyObject works on a device chain. Should not be what's destroying
+     * the MsgCallback object. That needs to be an instance thing. So, since
+     * we used an instance to create it, we need a custom Destroy that also
+     * takes an instance. That way we can iterate over the ICDs properly.
+     * Example use:
+     * CreateInstance: DEBUG_REPORT
+     *   Loader will create instance chain with enabled extensions.
+     *   TODO: Should validation layers be enabled here? If not, they will not be in the instance chain.
+     * fn = GetProcAddr(INSTANCE, "vkCreateMsgCallback") -> point to loader's vkCreateMsgCallback
+     * App creates a callback object: fn(..., &MsgCallbackObject1)
+     * Have only established the instance chain so far. Loader will call the instance chain.
+     * Each layer in the instance chain will call down to the next layer, terminating with
+     * the CreateMsgCallback loader terminator function that creates the actual MsgCallbackObject1 object.
+     * The loader CreateMsgCallback terminator will iterate over the ICDs.
+     * Calling each ICD that supports vkCreateMsgCallback and collect answers in icd_msg_callback_map here.
+     * As result is sent back up the chain each layer has opportunity to record the callback operation and
+     * appropriate MsgCallback object.
+     * ...
+     * Any reports matching the flags set in MsgCallbackObject1 will generate the defined callback behavior
+     * in the layer / ICD that initiated that report.
+     * ...
+     * CreateDevice: MemTracker:...
+     * App does not include DEBUG_REPORT as that is a global extension.
+     * TODO: GetExtensionSupport must not report DEBUG_REPORT when using instance.
+     * App MUST include any desired validation layers or they will not participate in the device call chain.
+     * App creates a callback object: fn(..., &MsgCallbackObject2)
+     * Loader's vkCreateMsgCallback is called.
+     * Loader sends call down instance chain - this is a global extension - any validation layer that was
+     * enabled at CreateInstance will be able to register the callback. Loader will iterate over the ICDs and
+     * will record the ICD's version of the MsgCallback2 object here.
+     * ...
+     * Any report will go to the layer's report function and it will check the flags for MsgCallbackObject1
+     * and MsgCallbackObject2 and take the appropriate action as indicated by the app.
+     * ...
+     * App calls vkDestroyMsgCallback( MsgCallbackObject1 )
+     * Loader's DestroyMsgCallback is where call starts. DestroyMsgCallback will be sent down instance chain
+     * ending in the loader's DestroyMsgCallback terminator which will iterate over the ICD's destroying each
+     * ICD version of that MsgCallback object and then destroy the loader's version of the object.
+     * Any reports generated after this will only have MsgCallbackObject2 available.
+     */
 
 void debug_report_add_instance_extensions(
         struct loader_extension_list *ext_list);

diff --git a/loader/loader.h b/loader/loader.h
index 6bfe45d..743b9bc 100644 (file)
--- a/loader/loader.h
+++ b/loader/loader.h
@@ -176,66 +176,6 @@ struct loader_instance {
 
     /* TODO: Should keep track of application provided allocation functions */
 
-    /*
-     * CreateMsgCallback is global and needs to be
-     * applied to all layers and ICDs.
-     * What happens if a layer is enabled on both the instance chain
-     * as well as the device chain and a call to CreateMsgCallback is made?
-     * Do we need to make sure that each layer / driver only gets called once?
-     * Should a layer implementing support for CreateMsgCallback only be allowed (?)
-     * to live on one chain? Or maybe make it the application's responsibility.
-     * If the app enables DRAW_STATE on at both CreateInstance time and CreateDevice
-     * time, CreateMsgCallback will call the DRAW_STATE layer twice. Once via
-     * the instance chain and once via the device chain.
-     * The loader should only return the DEBUG_REPORT extension as supported
-     * for the GetGlobalExtensionSupport call. That should help eliminate one
-     * duplication.
-     * Since the instance chain requires us iterating over the available ICDs
-     * and each ICD will have it's own unique MsgCallback object we need to
-     * track those objects to give back the right one.
-     * This also implies that the loader has to intercept vkDestroyObject and
-     * if the extension is enabled and the object type is a MsgCallback then
-     * we must translate the object into the proper ICD specific ones.
-     * DestroyObject works on a device chain. Should not be what's destroying
-     * the MsgCallback object. That needs to be an instance thing. So, since
-     * we used an instance to create it, we need a custom Destroy that also
-     * takes an instance. That way we can iterate over the ICDs properly.
-     * Example use:
-     * CreateInstance: DEBUG_REPORT
-     *   Loader will create instance chain with enabled extensions.
-     *   TODO: Should validation layers be enabled here? If not, they will not be in the instance chain.
-     * fn = GetProcAddr(INSTANCE, "vkCreateMsgCallback") -> point to loader's vkCreateMsgCallback
-     * App creates a callback object: fn(..., &MsgCallbackObject1)
-     * Have only established the instance chain so far. Loader will call the instance chain.
-     * Each layer in the instance chain will call down to the next layer, terminating with
-     * the CreateMsgCallback loader terminator function that creates the actual MsgCallbackObject1 object.
-     * The loader CreateMsgCallback terminator will iterate over the ICDs.
-     * Calling each ICD that supports vkCreateMsgCallback and collect answers in icd_msg_callback_map here.
-     * As result is sent back up the chain each layer has opportunity to record the callback operation and
-     * appropriate MsgCallback object.
-     * ...
-     * Any reports matching the flags set in MsgCallbackObject1 will generate the defined callback behavior
-     * in the layer / ICD that initiated that report.
-     * ...
-     * CreateDevice: MemTracker:...
-     * App does not include DEBUG_REPORT as that is a global extension.
-     * TODO: GetExtensionSupport must not report DEBUG_REPORT when using instance.
-     * App MUST include any desired validation layers or they will not participate in the device call chain.
-     * App creates a callback object: fn(..., &MsgCallbackObject2)
-     * Loader's vkCreateMsgCallback is called.
-     * Loader sends call down instance chain - this is a global extension - any validation layer that was
-     * enabled at CreateInstance will be able to register the callback. Loader will iterate over the ICDs and
-     * will record the ICD's version of the MsgCallback2 object here.
-     * ...
-     * Any report will go to the layer's report function and it will check the flags for MsgCallbackObject1
-     * and MsgCallbackObject2 and take the appropriate action as indicated by the app.
-     * ...
-     * App calls vkDestroyMsgCallback( MsgCallbackObject1 )
-     * Loader's DestroyMsgCallback is where call starts. DestroyMsgCallback will be sent down instance chain
-     * ending in the loader's DestroyMsgCallback terminator which will iterate over the ICD's destroying each
-     * ICD version of that MsgCallback object and then destroy the loader's version of the object.
-     * Any reports generated after this will only have MsgCallbackObject2 available.
-     */
     struct loader_msg_callback_map_entry *icd_msg_callback_map;
 
     struct loader_layer_list activated_layer_list;