From 4f0dc8cbe7ef8c90384eb28a9423f0207ec14c18 Mon Sep 17 00:00:00 2001
From: Fredrik Noring <noring@nocrew.org>
Date: Wed, 14 Jul 2021 08:37:43 +0200
Subject: [PATCH] Document DMA transfer completion attributes and status

---
 builtin/sif.c                  |  2 +-
 include/iopmod/module/sifcmd.h |  4 ++--
 include/iopmod/module/sifman.h |  2 +-
 include/iopmod/sifman.h        | 34 ++++++++++++++++++++++++----------
 4 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/builtin/sif.c b/builtin/sif.c
index f57c859..387dfb5 100644
--- a/builtin/sif.c
+++ b/builtin/sif.c
@@ -27,7 +27,7 @@
  */
 void sif_dma_relax_for_completion(int dma_id)
 {
-	while (sifman_dma_stat(dma_id) != DMA_STATUS_COMPLETED)
+	while (sifman_dma_stat(dma_id) != SIF_DMA_STATUS_COMPLETED)
 		cpu_relax();
 }
 
diff --git a/include/iopmod/module/sifcmd.h b/include/iopmod/module/sifcmd.h
index b7e2b55..70ae3c2 100644
--- a/include/iopmod/module/sifcmd.h
+++ b/include/iopmod/module/sifcmd.h
@@ -55,7 +55,7 @@ id_(11) void sif_release_cmd(int cid)
  *
  * This call is asynchronous and both the @packet and @src buffers must remain
  * valid until the DMA transfer has completed, when sifman_dma_stat() returns
- * %DMA_STATUS_COMPLETED.
+ * %SIF_DMA_STATUS_COMPLETED.
  *
  * For interrupt context, use sifcmd_send_cmd_irq() instead.
  *
@@ -85,7 +85,7 @@ id_(12) unsigned int sifcmd_send_cmd(u32 cmd,
  *
  * This call is asynchronous and both the @packet and @src buffers must remain
  * valid until the DMA transfer has completed, when sifman_dma_stat() returns
- * %DMA_STATUS_COMPLETED.
+ * %SIF_DMA_STATUS_COMPLETED.
  *
  * For thread context, use sifcmd_send_cmd() instead.
  *
diff --git a/include/iopmod/module/sifman.h b/include/iopmod/module/sifman.h
index 3c804aa..8500cf3 100644
--- a/include/iopmod/module/sifman.h
+++ b/include/iopmod/module/sifman.h
@@ -33,7 +33,7 @@ id_(7) int sifman_set_dma(const struct sif_dma_transfer *dma_tr, int count)
  * Context: any
  * Return: status of given DMA transfer
  */
-id_(8) enum sifman_dma_status sifman_dma_stat(int dma_id)
+id_(8) enum sif_dma_status sifman_dma_stat(int dma_id)
 	alias_(sceSifDmaStat);
 
 id_(9) void sifman_set_one_dma(struct sif_dma_transfer dma_tr)
diff --git a/include/iopmod/sifman.h b/include/iopmod/sifman.h
index d066c1e..2230f04 100644
--- a/include/iopmod/sifman.h
+++ b/include/iopmod/sifman.h
@@ -5,30 +5,44 @@
 
 #include <iopmod/types.h>
 
+/**
+ * enum sif_dma_attr - DMA transfer completion attributes
+ * @SIF_DMA_ATTR_INT_I: FIXME
+ * @SIF_DMA_ATTR_INT_O: assert IOP interrupt on completion
+ * @SIF_DMA_ATTR_ERT: FIXME
+ *
+ * Attributes may be combined into a set by logical or.
+ */
+enum sif_dma_attr {
+	SIF_DMA_ATTR_INT_I = 0x02,
+	SIF_DMA_ATTR_INT_O = 0x04,
+	SIF_DMA_ATTR_ERT   = 0x40,
+};
+
 /**
  * struct sif_dma_transfer - SIF DMA transfer structure
  * @src: sub data to copy from, must be aligned with a 4-byte DMA boundary
  * @dst: main data to copy to, must be aligned with a 16-byte DMA boundary
  * @nbytes: size in bytes to copy, will be rounded up to multiple of 16 bytes
- * @attr: zero or DMA completion attributes
+ * @attr: zero, or a set of DMA transfer completion attributes
  */
 struct sif_dma_transfer {
 	void *src;
 	main_addr_t dst;
 	size_t nbytes;
-	u32 attr;
+	enum sif_dma_attr attr;
 };
 
 /**
- * enum sifman_dma_status - status of DMA transfer
- * @DMA_STATUS_PENDING: DMA transfer has not yet started
- * @DMA_STATUS_BUSY: DMA transfer is in progress
- * @DMA_STATUS_COMPLETED: DMA transfer has completed
+ * enum sif_dma_status - status of DMA transfer
+ * @SIF_DMA_STATUS_PENDING: DMA transfer has not yet started
+ * @SIF_DMA_STATUS_BUSY: DMA transfer is in progress
+ * @SIF_DMA_STATUS_COMPLETED: DMA transfer has completed
  */
-enum sifman_dma_status {
-	DMA_STATUS_PENDING   =  1,
-	DMA_STATUS_BUSY      =  0,
-	DMA_STATUS_COMPLETED = -1
+enum sif_dma_status {
+	SIF_DMA_STATUS_PENDING   =  1,
+	SIF_DMA_STATUS_BUSY      =  0,
+	SIF_DMA_STATUS_COMPLETED = -1
 };
 
 #include "iopmod/module-prototype.h"