From 5f097cbf0715e217cd2fb67731b10ec9a54ed4f3 Mon Sep 17 00:00:00 2001
From: Anup Patel <anup.patel@wdc.com>
Date: Mon, 14 Jan 2019 13:58:29 +0530
Subject: [PATCH] lib: Add documentation for sbi_init() API

This patch adds doxygen style documentation for sbi_init() API.

Signed-off-by: Anup Patel <anup.patel@wdc.com>
---
 include/sbi/sbi_init.h |  2 +-
 lib/sbi_init.c         | 19 ++++++++++++++-----
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/include/sbi/sbi_init.h b/include/sbi/sbi_init.h
index b3aafdc..7c4267b 100644
--- a/include/sbi/sbi_init.h
+++ b/include/sbi/sbi_init.h
@@ -14,6 +14,6 @@
 
 struct sbi_scratch;
 
-void __attribute__((noreturn)) sbi_init(struct sbi_scratch *scratch);
+void __noreturn sbi_init(struct sbi_scratch *scratch);
 
 #endif
diff --git a/lib/sbi_init.c b/lib/sbi_init.c
index f942971..b0d4494 100644
--- a/lib/sbi_init.c
+++ b/lib/sbi_init.c
@@ -27,8 +27,7 @@ static const char *logo =
 	"        | |\n"
 	"        |_|\n";
 
-static void __attribute__((noreturn)) init_coldboot(struct sbi_scratch *scratch,
-						    u32 hartid)
+static void __noreturn init_coldboot(struct sbi_scratch *scratch, u32 hartid)
 {
 	int rc;
 	char str[64];
@@ -93,8 +92,7 @@ static void __attribute__((noreturn)) init_coldboot(struct sbi_scratch *scratch,
 			     scratch->next_addr, scratch->next_mode);
 }
 
-static void __attribute__((noreturn)) init_warmboot(struct sbi_scratch *scratch,
-						    u32 hartid)
+static void __noreturn init_warmboot(struct sbi_scratch *scratch, u32 hartid)
 {
 	int rc;
 	struct sbi_platform *plat = sbi_platform_ptr(scratch);
@@ -141,7 +139,18 @@ static void __attribute__((noreturn)) init_warmboot(struct sbi_scratch *scratch,
 
 static atomic_t coldboot_lottery = ATOMIC_INITIALIZER(0);
 
-void __attribute__((noreturn)) sbi_init(struct sbi_scratch *scratch)
+/**
+ * Initialize OpenSBI library for current HART and jump to next
+ * booting stage.
+ *
+ * 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
+ *
+ * @param scratch pointer to sbi_scratch of current HART
+ */
+void __noreturn sbi_init(struct sbi_scratch *scratch)
 {
 	bool coldboot = FALSE;
 	u32 hartid = sbi_current_hartid();