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>

diff --git a/include/sbi/sbi_ecall.h b/include/sbi/sbi_ecall.h
index fac2642..90f33ba 100644 (file)
--- 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,