From ae9a72b48b4fe77113d12a5de0cdb5a0746b8d0a Mon Sep 17 00:00:00 2001
From: Chia-I Wu <olvaffe@gmail.com>
Date: Wed, 16 Jan 2019 10:20:33 -0800
Subject: [PATCH] turnip: document tu_cs

---
 src/freedreno/vulkan/tu_cs.c | 21 +++++++++++++++++++++
 src/freedreno/vulkan/tu_cs.h |  9 +++++++++
 2 files changed, 30 insertions(+)

diff --git a/src/freedreno/vulkan/tu_cs.c b/src/freedreno/vulkan/tu_cs.c
index 55e7d3528e0..02bb1bceac4 100644
--- a/src/freedreno/vulkan/tu_cs.c
+++ b/src/freedreno/vulkan/tu_cs.c
@@ -23,6 +23,9 @@
 
 #include "tu_cs.h"
 
+/**
+ * Initialize a command stream.
+ */
 void
 tu_cs_init(struct tu_cs *cs)
 {
@@ -35,6 +38,9 @@ tu_cs_init(struct tu_cs *cs)
    cs->bos = NULL;
 }
 
+/**
+ * Finish and release all resources owned by a command stream.
+ */
 void
 tu_cs_finish(struct tu_device *dev, struct tu_cs *cs)
 {
@@ -47,6 +53,10 @@ tu_cs_finish(struct tu_device *dev, struct tu_cs *cs)
    free(cs->bos);
 }
 
+/**
+ * Begin (or continue) command packet emission.  This will reserve space from
+ * the command stream for at least \a reserve_size uint32_t values.
+ */
 VkResult
 tu_cs_begin(struct tu_device *dev, struct tu_cs *cs, uint32_t reserve_size)
 {
@@ -96,6 +106,10 @@ tu_cs_begin(struct tu_device *dev, struct tu_cs *cs, uint32_t reserve_size)
    return VK_SUCCESS;
 }
 
+/**
+ * End command packet emission by adding an IB entry for the command packets
+ * emitted since the last call to tu_cs_begin.
+ */
 VkResult
 tu_cs_end(struct tu_cs *cs)
 {
@@ -126,6 +140,10 @@ tu_cs_end(struct tu_cs *cs)
    return VK_SUCCESS;
 }
 
+/**
+ * Reset a command stream to its initial state.  This discards all comand
+ * packets in \a cs, but does not necessarily release all resources.
+ */
 void
 tu_cs_reset(struct tu_device *dev, struct tu_cs *cs)
 {
@@ -145,6 +163,9 @@ tu_cs_reset(struct tu_device *dev, struct tu_cs *cs)
    cs->entry_count = 0;
 }
 
+/**
+ * Reserve space from a command stream for \a size uint32_t values.
+ */
 VkResult
 tu_cs_check_space(struct tu_device *dev, struct tu_cs *cs, size_t size)
 {
diff --git a/src/freedreno/vulkan/tu_cs.h b/src/freedreno/vulkan/tu_cs.h
index 952d0262d6a..03a371bdfa1 100644
--- a/src/freedreno/vulkan/tu_cs.h
+++ b/src/freedreno/vulkan/tu_cs.h
@@ -40,6 +40,9 @@ tu_cs_reset(struct tu_device *dev, struct tu_cs *cs);
 VkResult
 tu_cs_check_space(struct tu_device *dev, struct tu_cs *cs, size_t size);
 
+/**
+ * Emit a uint32_t value into a command stream, without boundary checking.
+ */
 static inline void
 tu_cs_emit(struct tu_cs *cs, uint32_t value)
 {
@@ -61,6 +64,9 @@ tu_odd_parity_bit(unsigned val)
    return (~0x6996 >> val) & 1;
 }
 
+/**
+ * Emit a type-4 command packet header into a command stream.
+ */
 static inline void
 tu_cs_emit_pkt4(struct tu_cs *cs, uint16_t regindx, uint16_t cnt)
 {
@@ -69,6 +75,9 @@ tu_cs_emit_pkt4(struct tu_cs *cs, uint16_t regindx, uint16_t cnt)
                      ((tu_odd_parity_bit(regindx) << 27)));
 }
 
+/**
+ * Emit a type-7 command packet header into a command stream.
+ */
 static inline void
 tu_cs_emit_pkt7(struct tu_cs *cs, uint8_t opcode, uint16_t cnt)
 {
-- 
2.30.2