1// Copyright (c) 2018-2020 Advanced Micro Devices, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[copies-buffer-markers]] 6== Buffer Markers 7 8ifdef::VK_KHR_synchronization2[] 9 10[open,refpage='vkCmdWriteBufferMarker2AMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos'] 11-- 12:refpage: vkCmdWriteBufferMarker2AMD 13 14To write a 32-bit marker value into a buffer as a pipelined operation, call: 15 16include::{generated}/api/protos/vkCmdWriteBufferMarker2AMD.txt[] 17 18 * pname:commandBuffer is the command buffer into which the command will be 19 recorded. 20 * pname:stage specifies the pipeline stage whose completion triggers the 21 marker write. 22 * pname:dstBuffer is the buffer where the marker will be written. 23 * pname:dstOffset is the byte offset into the buffer where the marker will 24 be written. 25 * pname:marker is the 32-bit value of the marker. 26 27The command will write the 32-bit marker value into the buffer only after 28all preceding commands have finished executing up to at least the specified 29pipeline stage. 30This includes the completion of other preceding 31fname:vkCmdWriteBufferMarker2AMD commands so long as their specified 32pipeline stages occur either at the same time or earlier than this command's 33specified pname:stage. 34 35While consecutive buffer marker writes with the same pname:stage parameter 36implicitly complete in submission order, memory and execution dependencies 37between buffer marker writes and other operations must: still be explicitly 38ordered using synchronization commands. 39The access scope for buffer marker writes falls under the 40ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying 41the synchronization scope must: include both pname:stage and 42ename:VK_PIPELINE_STAGE_TRANSFER_BIT. 43 44[NOTE] 45.Note 46==== 47Similar to fname:vkCmdWriteTimestamp2KHR, if an implementation is unable to 48write a marker at any specific pipeline stage, it may: instead do so at any 49logically later stage. 50==== 51 52[NOTE] 53.Note 54==== 55Implementations may: only support a limited number of pipelined marker write 56operations in flight at a given time. 57Thus an excessive number of marker write operations may: degrade command 58execution performance. 59==== 60 61.Valid Usage 62**** 63:stageMaskName: stage 64include::{chapters}/commonvalidity/stage_mask_2_common.txt[] 65 * [[VUID-vkCmdWriteBufferMarker2AMD-synchronization2-03893]] 66 The <<features-synchronization2, pname:synchronization2>> feature must: 67 be enabled 68 * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03894]] 69 pname:stage must: include only a single pipeline stage 70 * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03895]] 71 pname:stage must: include only stages that are valid for the queue 72 family that was used to create the command pool that pname:commandBuffer 73 was allocated from 74 * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03896]] 75 pname:dstOffset must: be less than or equal to the size of 76 pname:dstBuffer minus `4` 77 * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03897]] 78 pname:dstBuffer must: have been created with the 79 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 80 * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03898]] 81 If pname:dstBuffer is non-sparse then it must: be bound completely and 82 contiguously to a single sname:VkDeviceMemory object 83 * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03899]] 84 pname:dstOffset must: be a multiple of `4` 85**** 86 87include::{generated}/validity/protos/vkCmdWriteBufferMarker2AMD.txt[] 88-- 89endif::VK_KHR_synchronization2[] 90 91[open,refpage='vkCmdWriteBufferMarkerAMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos'] 92-- 93:refpage: vkCmdWriteBufferMarkerAMD 94 95To write a 32-bit marker value into a buffer as a pipelined operation, call: 96 97include::{generated}/api/protos/vkCmdWriteBufferMarkerAMD.txt[] 98 99 * pname:commandBuffer is the command buffer into which the command will be 100 recorded. 101 * pname:pipelineStage is a elink:VkPipelineStageFlagBits value specifying 102 the pipeline stage whose completion triggers the marker write. 103 * pname:dstBuffer is the buffer where the marker will be written to. 104 * pname:dstOffset is the byte offset into the buffer where the marker will 105 be written to. 106 * pname:marker is the 32-bit value of the marker. 107 108The command will write the 32-bit marker value into the buffer only after 109all preceding commands have finished executing up to at least the specified 110pipeline stage. 111This includes the completion of other preceding 112fname:vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline 113stages occur either at the same time or earlier than this command's 114specified pname:pipelineStage. 115 116While consecutive buffer marker writes with the same pname:pipelineStage 117parameter are implicitly complete in submission order, memory and execution 118dependencies between buffer marker writes and other operations must still be 119explicitly ordered using synchronization commands. 120The access scope for buffer marker writes falls under the 121ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying 122the synchronization scope must: include both pname:pipelineStage and 123ename:VK_PIPELINE_STAGE_TRANSFER_BIT. 124 125[NOTE] 126.Note 127==== 128Similar to fname:vkCmdWriteTimestamp, if an implementation is unable to 129write a marker at any specific pipeline stage, it may: instead do so at any 130logically later stage. 131==== 132 133[NOTE] 134.Note 135==== 136Implementations may: only support a limited number of pipelined marker write 137operations in flight at a given time, thus excessive number of marker write 138operations may: degrade command execution performance. 139==== 140 141.Valid Usage 142**** 143include::{chapters}/commonvalidity/pipeline_stage_common.txt[] 144 * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798]] 145 pname:dstOffset must: be less than or equal to the size of 146 pname:dstBuffer minus `4` 147 * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799]] 148 pname:dstBuffer must: have been created with 149 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 150 * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01800]] 151 If pname:dstBuffer is non-sparse then it must: be bound completely and 152 contiguously to a single sname:VkDeviceMemory object 153 * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801]] 154 pname:dstOffset must: be a multiple of `4` 155**** 156 157include::{generated}/validity/protos/vkCmdWriteBufferMarkerAMD.txt[] 158-- 159