core: kernel: Address comments for semihosting facilities

Add more comments for functions. Refine return type of the functions.

Signed-off-by: Alvin Chang <[email protected]>

core/include/kernel/semihosting.h

@@ -20,18 +20,18 @@ char semihosting_readc(void);
 void semihosting_writec(char c);
 
 /* Request the semihosting host to open a file on the host system. */
-int semihosting_open(const char *fname, int flags);
+intptr_t semihosting_open(const char *fname, int flags);
 
 /* Request the semihosting host to read data from a file on the host system. */
-ssize_t semihosting_read(int fd, void *ptr, size_t len);
+size_t semihosting_read(int fd, void *ptr, size_t len);
 
 /* Request the semihosting host to write data into a file on the host system. */
-ssize_t semihosting_write(int fd, const void *ptr, size_t len);
+size_t semihosting_write(int fd, const void *ptr, size_t len);
 
 /*
  * Request the semihosting host to close a file, which has been opened by
  * semihosting_open(), on the host system.
  */
-int semihosting_close(int fd);
+intptr_t semihosting_close(int fd);
 
 #endif /* __KERNEL_SEMIHOSTING_H */

core/kernel/semihosting.c

@@ -39,7 +39,7 @@ enum semihosting_open_mode {
 #endif
 
 enum semihosting_sys_ops {
-	// Regular operations
+	/* Regular operations */
 	SEMIHOSTING_SYS_OPEN = 0x01,
 	SEMIHOSTING_SYS_CLOSE = 0x02,
 	SEMIHOSTING_SYS_WRITEC = 0x03,
@@ -54,22 +54,38 @@ struct semihosting_param_t {
 	uintptr_t param2;
 };
 
+/**
+ * @brief Read one character byte from the semihosting host
+ *
+ * @retval the character read from the semihosting host
+ */
 char semihosting_readc(void)
 {
 	return __do_semihosting(SEMIHOSTING_SYS_READC, 0);
 }
 
+/**
+ * @brief Write one character byte to the semihosting host
+ * @param c: the character to be written
+ */
 void semihosting_writec(char c)
 {
 	__do_semihosting(SEMIHOSTING_SYS_WRITEC, (uintptr_t)&c);
 }
 
-int semihosting_open(const char *fname, int flags)
+/**
+ * @brief Request the semihosting host to open a file on the host system
+ * @param fname: the path or name of the file
+ * @param flags: the flags to open the file
+ *
+ * @retval nonzero if OK, or -1 if fails
+ */
+intptr_t semihosting_open(const char *fname, int flags)
 {
 	int semi_open_flags = 0;
 	const int flags_mask = O_RDONLY | O_WRONLY | O_RDWR |
 			       O_CREAT | O_TRUNC | O_APPEND;
-	struct semihosting_param_t arg = {0};
+	struct semihosting_param_t arg = { };
 
 	/* Convert the flags to semihosting open. */
 	switch (flags & flags_mask) {
@@ -104,38 +120,63 @@ int semihosting_open(const char *fname, int flags)
 	arg.param1 = (uintptr_t)semi_open_flags;
 	arg.param2 = (uintptr_t)strlen(fname);
 
-	return __do_semihosting(SEMIHOSTING_SYS_OPEN, (uintptr_t)&arg);
+	return (intptr_t)__do_semihosting(SEMIHOSTING_SYS_OPEN,
+					  (uintptr_t)&arg);
 }
 
-ssize_t semihosting_read(int fd, void *ptr, size_t len)
+/**
+ * @brief Read data from a file on the semihosting host system
+ * @param fd: a handle for a file previously opened
+ * @param ptr: pointer to a buffer
+ * @param len: the number of bytes to read to the buffer from the file
+ *
+ * @retval zero if OK, the same value as @len if fails, smaller value than @len
+ * for partial success
+ */
+size_t semihosting_read(int fd, void *ptr, size_t len)
 {
 	struct semihosting_param_t arg = {
 		.param0 = (uintptr_t)fd,
 		.param1 = (uintptr_t)ptr,
 		.param2 = (uintptr_t)len
 	};
 
-	return __do_semihosting(SEMIHOSTING_SYS_READ, (uintptr_t)&arg);
+	return (size_t)__do_semihosting(SEMIHOSTING_SYS_READ, (uintptr_t)&arg);
 }
 
-ssize_t semihosting_write(int fd, const void *ptr, size_t len)
+/**
+ * @brief Write data into a file on the semihosting host system
+ * @param fd: a handle for a file previously opened
+ * @param ptr: pointer to a buffer
+ * @param len: the number of bytes to be written from the buffer to the file
+ *
+ * @retval zero if OK, otherwise the number of bytes that are not written
+ */
+size_t semihosting_write(int fd, const void *ptr, size_t len)
 {
 	struct semihosting_param_t arg = {
 		.param0 = (uintptr_t)fd,
 		.param1 = (uintptr_t)ptr,
 		.param2 = (uintptr_t)len
 	};
 
-	return __do_semihosting(SEMIHOSTING_SYS_WRITE, (uintptr_t)&arg);
+	return (size_t)__do_semihosting(SEMIHOSTING_SYS_WRITE, (uintptr_t)&arg);
 }
 
-int semihosting_close(int fd)
+/**
+ * @brief Close a file on the semihosting host system
+ * @param fd: a handle for a file previously opened
+ *
+ * @retval zero if OK, -1 if fails
+ */
+intptr_t semihosting_close(int fd)
 {
 	struct semihosting_param_t arg = {
 		.param0 = (uintptr_t)fd,
 		.param1 = 0,
 		.param2 = 0
 	};
 
-	return __do_semihosting(SEMIHOSTING_SYS_CLOSE, (uintptr_t)&arg);
+	return (intptr_t)__do_semihosting(SEMIHOSTING_SYS_CLOSE,
+					  (uintptr_t)&arg);
 }