From 33f1722f2b6e1ad8f8bd0675271e3c7998d448c2 Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Mon, 15 May 2023 13:12:40 +0200 Subject: [PATCH] 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 Reviewed-by: Anup Patel --- 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 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, -- 2.7.4