lib: sbi: Document sbi_ecall_extension members

With the introduction of the register_extensions callback the
range members (extid_start and extid_end) may now change and it
has become a bit subtle as to when a probe function should be
implemented. Document all the members and their relationship to
the register_extensions callback.

Signed-off-by: Andrew Jones <ajones@ventanamicro.com>
Reviewed-by: Anup Patel <anup@brainfault.org>

1 files changed, 35 insertions, 0 deletions

diff --git a/include/sbi/sbi_ecall.h b/include/sbi/sbi_ecall.h
index fac2642..90f33ba 100644
--- a/include/sbi/sbi_ecall.h
+++ b/include/sbi/sbi_ecall.h
@@ -21,11 +21,46 @@ struct sbi_trap_regs;
 struct sbi_trap_info;
 
 struct sbi_ecall_extension {
+	/* head is used by the extension list */
 	struct sbi_dlist head;
+	/*
+	 * extid_start and extid_end specify the range for this extension. As
+	 * the initial range may be wider than the valid runtime range, the
+	 * register_extensions callback is responsible for narrowing the range
+	 * before other callbacks may be invoked.
+	 */
 	unsigned long extid_start;
 	unsigned long extid_end;
+	/*
+	 * register_extensions
+	 *
+	 * Calls sbi_ecall_register_extension() one or more times to register
+	 * extension ID range(s) which should be handled by this extension.
+	 * More than one sbi_ecall_extension struct and
+	 * sbi_ecall_register_extension() call is necessary when the supported
+	 * extension ID ranges have gaps. Additionally, extension availability
+	 * must be checked before registering, which means, when this callback
+	 * returns, only valid extension IDs from the initial range, which are
+	 * also available, have been registered.
+	 */
 	int (* register_extensions)(void);
+	/*
+	 * probe
+	 *
+	 * Implements the Base extension's probe function for the extension. As
+	 * the register_extensions callback ensures that no other extension
+	 * callbacks will be invoked when the extension is not available, then
+	 * probe can never fail. However, an extension may choose to set
+	 * out_val to a nonzero value other than one. In those cases, it should
+	 * implement this callback.
+	 */
 	int (* probe)(unsigned long extid, unsigned long *out_val);
+	/*
+	 * handle
+	 *
+	 * This is the extension handler. register_extensions ensures it is
+	 * never invoked with an invalid or unavailable extension ID.
+	 */
 	int (* handle)(unsigned long extid, unsigned long funcid,
 		       const struct sbi_trap_regs *regs,
 		       unsigned long *out_val,