include: Add documentation for sbi_trap_regs and friends

This patch adds doxygen style documentation for struct sbi_trap_regs
and related macros/defines/functions.

Signed-off-by: Anup Patel <anup.patel@wdc.com>

4 files changed, 106 insertions, 7 deletions

diff --git a/include/sbi/sbi_scratch.h b/include/sbi/sbi_scratch.h
index ace1a0d..562f7bb 100644
--- a/include/sbi/sbi_scratch.h
+++ b/include/sbi/sbi_scratch.h
@@ -57,7 +57,7 @@ struct sbi_scratch {
 	unsigned long hartid_to_scratch;
 	/** IPI type (or flags) */
 	unsigned long ipi_type;
-} __attribute__((packed));
+} __packed;
 
 /** Get pointer to sbi_scratch for current HART */
 #define sbi_scratch_thishart_ptr()	\
diff --git a/include/sbi/sbi_trap.h b/include/sbi/sbi_trap.h
index 67f7f38..ab94d19 100644
--- a/include/sbi/sbi_trap.h
+++ b/include/sbi/sbi_trap.h
@@ -10,86 +10,158 @@
 #ifndef __SBI_TRAP_H__
 #define __SBI_TRAP_H__
 
+/** Index of zero member in sbi_trap_regs */
 #define SBI_TRAP_REGS_zero			0
+/** Index of ra member in sbi_trap_regs */
 #define SBI_TRAP_REGS_ra			1
+/** Index of sp member in sbi_trap_regs */
 #define SBI_TRAP_REGS_sp			2
+/** Index of gp member in sbi_trap_regs */
 #define SBI_TRAP_REGS_gp			3
+/** Index of tp member in sbi_trap_regs */
 #define SBI_TRAP_REGS_tp			4
+/** Index of t0 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t0			5
+/** Index of t1 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t1			6
+/** Index of t2 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t2			7
+/** Index of s0 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s0			8
+/** Index of s1 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s1			9
+/** Index of a0 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a0			10
+/** Index of a1 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a1			11
+/** Index of a2 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a2			12
+/** Index of a3 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a3			13
+/** Index of a4 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a4			14
+/** Index of a5 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a5			15
+/** Index of a6 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a6			16
+/** Index of a7 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_a7			17
+/** Index of s2 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s2			18
+/** Index of s3 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s3			19
+/** Index of s4 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s4			20
+/** Index of s5 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s5			21
+/** Index of s6 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s6			22
+/** Index of s7 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s7			23
+/** Index of s8 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s8			24
+/** Index of s9 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s9			25
+/** Index of s10 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s10			26
+/** Index of s11 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_s11			27
+/** Index of t3 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t3			28
+/** Index of t4 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t4			29
+/** Index of t5 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t5			30
+/** Index of t6 member in sbi_trap_regs */
 #define SBI_TRAP_REGS_t6			31
+/** Index of mepc member in sbi_trap_regs */
 #define SBI_TRAP_REGS_mepc			32
+/** Index of mstatus member in sbi_trap_regs */
 #define SBI_TRAP_REGS_mstatus			33
+/** Last member index in sbi_trap_regs */
 #define SBI_TRAP_REGS_last			34
 
+/** Get offset of member with name 'x' in sbi_trap_regs */
 #define SBI_TRAP_REGS_OFFSET(x)			\
 				((SBI_TRAP_REGS_##x) * __SIZEOF_POINTER__)
+/** Size (in bytes) of sbi_trap_regs */
 #define SBI_TRAP_REGS_SIZE			SBI_TRAP_REGS_OFFSET(last)
 
 #ifndef __ASSEMBLY__
 
 #include <sbi/sbi_types.h>
 
+/** Representation of register state at time of trap/interrupt */
 struct sbi_trap_regs {
+	/** zero register state */
 	unsigned long zero;
+	/** ra register state */
 	unsigned long ra;
+	/** sp register state */
 	unsigned long sp;
+	/** gp register state */
 	unsigned long gp;
+	/** tp register state */
 	unsigned long tp;
+	/** t0 register state */
 	unsigned long t0;
+	/** t1 register state */
 	unsigned long t1;
+	/** t2 register state */
 	unsigned long t2;
+	/** s0 register state */
 	unsigned long s0;
+	/** s1 register state */
 	unsigned long s1;
+	/** a0 register state */
 	unsigned long a0;
+	/** a1 register state */
 	unsigned long a1;
+	/** a2 register state */
 	unsigned long a2;
+	/** a3 register state */
 	unsigned long a3;
+	/** a4 register state */
 	unsigned long a4;
+	/** a5 register state */
 	unsigned long a5;
+	/** a6 register state */
 	unsigned long a6;
+	/** a7 register state */
 	unsigned long a7;
+	/** s2 register state */
 	unsigned long s2;
+	/** s3 register state */
 	unsigned long s3;
+	/** s4 register state */
 	unsigned long s4;
+	/** s5 register state */
 	unsigned long s5;
+	/** s6 register state */
 	unsigned long s6;
+	/** s7 register state */
 	unsigned long s7;
+	/** s8 register state */
 	unsigned long s8;
+	/** s9 register state */
 	unsigned long s9;
+	/** s10 register state */
 	unsigned long s10;
+	/** s11 register state */
 	unsigned long s11;
+	/** t3 register state */
 	unsigned long t3;
+	/** t4 register state */
 	unsigned long t4;
+	/** t5 register state */
 	unsigned long t5;
+	/** t6 register state */
 	unsigned long t6;
+	/** mepc register state */
 	unsigned long mepc;
+	/** mstatus register state */
 	unsigned long mstatus;
-} __attribute__((packed));
+} __packed;
 
 struct sbi_scratch;
 
diff --git a/lib/sbi_init.c b/lib/sbi_init.c
index b0d4494..b92c1fd 100644
--- a/lib/sbi_init.c
+++ b/lib/sbi_init.c
@@ -146,7 +146,8 @@ static atomic_t coldboot_lottery = ATOMIC_INITIALIZER(0);
  * The function expects following:
  * 1. The 'mscratch' CSR is pointing to sbi_scratch of current HART
  * 2. Stack pointer (SP) is setup for current HART
- * 3. All interrupts are disabled in MIE CSR except MSIP
+ * 3. Interrupts are disabled in MSTATUS CSR
+ * 4. All interrupts are disabled in MIE CSR except MSIP
  *
  * @param scratch pointer to sbi_scratch of current HART
  */
diff --git a/lib/sbi_trap.c b/lib/sbi_trap.c
index 0e731e4..9f212c1 100644
--- a/lib/sbi_trap.c
+++ b/lib/sbi_trap.c
@@ -19,10 +19,10 @@
 #include <sbi/sbi_timer.h>
 #include <sbi/sbi_trap.h>
 
-static void __attribute__((noreturn)) sbi_trap_error(const char *msg,
-						int rc, u32 hartid,
-						ulong mcause, ulong mtval,
-						struct sbi_trap_regs *regs)
+static void __noreturn sbi_trap_error(const char *msg,
+				      int rc, u32 hartid,
+				      ulong mcause, ulong mtval,
+				      struct sbi_trap_regs *regs)
 {
 	sbi_printf("%s: hart%d: %s (error %d)\n",
 		   __func__, hartid, msg, rc);
@@ -66,6 +66,17 @@ static void __attribute__((noreturn)) sbi_trap_error(const char *msg,
 	sbi_hart_hang();
 }
 
+/**
+ * Redirect trap to lower privledge mode (S-mode or U-mode)
+ *
+ * @param regs pointer to register state
+ * @param scratch pointer to sbi_scratch of current HART
+ * @param epc error PC for lower privledge mode
+ * @param cause exception cause for lower privledge mode
+ * @param tval trap value for lower privledge mode
+ *
+ * Returns 0 on success and error code (< 0) on failure
+ */
 int sbi_trap_redirect(struct sbi_trap_regs *regs,
 		      struct sbi_scratch *scratch,
 		      ulong epc, ulong cause, ulong tval)
@@ -109,6 +120,21 @@ int sbi_trap_redirect(struct sbi_trap_regs *regs,
 	return 0;
 }
 
+/**
+ * Handle trap/interrupt
+ *
+ * This function is called by firmware linked to OpenSBI
+ * library for handling trap/interrupt. It expects the
+ * following:
+ * 1. The 'mscratch' CSR is pointing to sbi_scratch of current HART
+ * 2. The 'mcause' CSR is having exception/interrupt cause
+ * 3. The 'mtval' CSR is having additional trap information
+ * 4. Stack pointer (SP) is setup for current HART
+ * 5. Interrupts are disabled in MSTATUS CSR
+ *
+ * @param regs pointer to register state
+ * @param scratch pointer to sbi_scratch of current HART
+ */
 void sbi_trap_handler(struct sbi_trap_regs *regs,
 		      struct sbi_scratch *scratch)
 {