From: Philippe Mathieu-Daudé <phi...@linaro.org>
Since it is not obvious the get/put_user*() methods
can return an error, add brief docstrings about it.
Also remind to use *unlock_user() when appropriate.
Signed-off-by: Philippe Mathieu-Daudé <phi...@linaro.org>
Reviewed-by: Richard Henderson <richard.hender...@linaro.org>
Message-Id: <20241212115413.42109-1-phi...@linaro.org>
Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
---
include/semihosting/uaccess.h | 55 +++++++++++++++++++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/include/semihosting/uaccess.h b/include/semihosting/uaccess.h
index c2fa5a655d..6bc90b12d6 100644
--- a/include/semihosting/uaccess.h
+++ b/include/semihosting/uaccess.h
@@ -19,41 +19,96 @@
#include "exec/tswap.h"
#include "exec/page-protection.h"
+/**
+ * get_user_u64:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define get_user_u64(val, addr) \
({ uint64_t val_ = 0; \
int ret_ = cpu_memory_rw_debug(env_cpu(env), (addr), \
&val_, sizeof(val_), 0); \
(val) = tswap64(val_); ret_; })
+/**
+ * get_user_u32:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define get_user_u32(val, addr) \
({ uint32_t val_ = 0; \
int ret_ = cpu_memory_rw_debug(env_cpu(env), (addr), \
&val_, sizeof(val_), 0); \
(val) = tswap32(val_); ret_; })
+/**
+ * get_user_u8:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define get_user_u8(val, addr) \
({ uint8_t val_ = 0; \
int ret_ = cpu_memory_rw_debug(env_cpu(env), (addr), \
&val_, sizeof(val_), 0); \
(val) = val_; ret_; })
+/**
+ * get_user_ual:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define get_user_ual(arg, p) get_user_u32(arg, p)
+/**
+ * put_user_u64:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define put_user_u64(val, addr) \
({ uint64_t val_ = tswap64(val); \
cpu_memory_rw_debug(env_cpu(env), (addr), &val_, sizeof(val_), 1); })
+/**
+ * put_user_u32:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define put_user_u32(val, addr) \
({ uint32_t val_ = tswap32(val); \
cpu_memory_rw_debug(env_cpu(env), (addr), &val_, sizeof(val_), 1); })
+/**
+ * put_user_ual:
+ *
+ * Returns: 0 on success, -1 on error.
+ */
#define put_user_ual(arg, p) put_user_u32(arg, p)
+/**
+ * uaccess_lock_user:
+ *
+ * The returned pointer should be freed using uaccess_unlock_user().
+ */
void *uaccess_lock_user(CPUArchState *env, target_ulong addr,
target_ulong len, bool copy);
+/**
+ * lock_user:
+ *
+ * The returned pointer should be freed using unlock_user().
+ */
#define lock_user(type, p, len, copy) uaccess_lock_user(env, p, len, copy)
+/**
+ * uaccess_lock_user_string:
+ *
+ * The returned string should be freed using uaccess_unlock_user().
+ */
char *uaccess_lock_user_string(CPUArchState *env, target_ulong addr);
+/**
+ * uaccess_lock_user_string:
+ *
+ * The returned string should be freed using unlock_user().
+ */
#define lock_user_string(p) uaccess_lock_user_string(env, p)
void uaccess_unlock_user(CPUArchState *env, void *p,
--
2.39.5
