From 84b74599cb29a9185ea8b7e06ab57e8d3d2657da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Pi=C3=B1eiro?= Date: Thu, 6 Jun 2024 11:58:21 +0200 Subject: [PATCH] v3d,v3dv: document cl_emit_with_prepacked In addition to always being good to have some documentation, it was added to clarify that if you use the macro to fill up values, it will not override the values coming from the prepacked buffer, but doing an OR. Reviewed-by: Iago Toral Quiroga Reviewed-by: Jose Maria Casanova Crespo Part-of: --- src/broadcom/vulkan/v3dv_cl.h | 11 ++++++++++- src/gallium/drivers/v3d/v3d_cl.h | 11 ++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/src/broadcom/vulkan/v3dv_cl.h b/src/broadcom/vulkan/v3dv_cl.h index 96721530f77..bbace412461 100644 --- a/src/broadcom/vulkan/v3dv_cl.h +++ b/src/broadcom/vulkan/v3dv_cl.h @@ -157,7 +157,7 @@ void v3dv_cl_ensure_space_with_branch(struct v3dv_cl *cl, uint32_t space); #define cl_packet_pack(packet) V3DX(packet ## _pack) #define cl_packet_struct(packet) V3DX(packet) -/* Macro for setting up an emit of a CL struct. A temporary unpacked struct +/* Macro for setting up and emit of a CL struct. A temporary unpacked struct * is created, which you get to set fields in of the form: * * cl_emit(bcl, FLAT_SHADE_FLAGS, flags) { @@ -185,6 +185,15 @@ void v3dv_cl_ensure_space_with_branch(struct v3dv_cl *cl, uint32_t space); assert(v3dv_cl_offset(cl) <= (cl)->size); \ })) \ +/* Macro for setting up and emit of a CL struct, where part of the setting up + * comes from a prepacked buffer. So the use is similar to cl_emit, where you + * set individual values, and the rest of values come from prepacked. + * + * Note that setting a value with this macro will not override the values + * coming from the prepacked buffer, as it does an OR operation. That means + * that the prepacked buffer is usually reserved for values that we know that + * will not change in advance before the emission. + */ #define cl_emit_with_prepacked(cl, packet, prepacked, name) \ for (struct cl_packet_struct(packet) name = { \ cl_packet_header(packet) \ diff --git a/src/gallium/drivers/v3d/v3d_cl.h b/src/gallium/drivers/v3d/v3d_cl.h index 76d8c3aa300..f8e1449e97b 100644 --- a/src/gallium/drivers/v3d/v3d_cl.h +++ b/src/gallium/drivers/v3d/v3d_cl.h @@ -208,7 +208,7 @@ cl_get_emit_space(struct v3d_cl_out **cl, size_t size) return addr; } -/* Macro for setting up an emit of a CL struct. A temporary unpacked struct +/* Macro for setting up and emit of a CL struct. A temporary unpacked struct * is created, which you get to set fields in of the form: * * cl_emit(bcl, FLAT_SHADE_FLAGS, flags) { @@ -237,6 +237,15 @@ cl_get_emit_space(struct v3d_cl_out **cl, size_t size) assert(cl_offset(cl) <= (cl)->size); \ })) \ +/* Macro for setting up and emit of a CL struct, where part of the setting up + * comes from a prepacked buffer. So the use is similar to cl_emit, where you + * set individual values, and the rest of values come from prepacked. + * + * Note that setting a value with this macro will not override the values + * coming from the prepacked buffer, as it does an OR operation. That means + * that the prepacked buffer is usually reserved for values that we know that + * will not change in advance before the emission. + */ #define cl_emit_with_prepacked(cl, packet, prepacked, name) \ for (struct cl_packet_struct(packet) name = { \ cl_packet_header(packet) \