diff mbox series

[v6,7/7] lib: sbi: Document sbi_ecall_extension members

Message ID 20230515111240.95059-8-ajones@ventanamicro.com
State Accepted
Headers show
Series lib: sbi: Ensure SBI extension is available | expand

Commit Message

Andrew Jones May 15, 2023, 11:12 a.m. UTC 
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>
---
 include/sbi/sbi_ecall.h | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

Comments

Anup Patel May 21, 2023, 3:32 p.m. UTC | #1 
On Mon, May 15, 2023 at 4:42 PM Andrew Jones <ajones@ventanamicro.com> wrote:
>
> 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>

Applied this patch to the riscv/opensbi repo.

Thanks,
Anup

> ---
>  include/sbi/sbi_ecall.h | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
>
> diff --git a/include/sbi/sbi_ecall.h b/include/sbi/sbi_ecall.h
> index fac26429cf5d..90f33bac0bcc 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,
> --
> 2.40.0
>
diff mbox series

Patch

diff --git a/include/sbi/sbi_ecall.h b/include/sbi/sbi_ecall.h
index fac26429cf5d..90f33bac0bcc 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,