From: Sean Anderson <sean.anderson@seco.com>
Date: Tue, 22 Mar 2022 20:59:17 +0000 (-0400)
Subject: arm: smh: Document functions in header
X-Git-Url: http://git.dujemihanovic.xyz/?a=commitdiff_plain;h=79f6ad6a7b9c30bacb135b91a268fd9767bca79d;p=u-boot.git

arm: smh: Document functions in header

This adds some documentation for semihosting functions in the header.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
---

diff --git a/arch/arm/lib/semihosting.c b/arch/arm/lib/semihosting.c
index 1686457685..2943f7b82f 100644
--- a/arch/arm/lib/semihosting.c
+++ b/arch/arm/lib/semihosting.c
@@ -80,9 +80,6 @@ long smh_open(const char *fname, enum smh_open_mode mode)
 	return fd;
 }
 
-/*
- * Read 'len' bytes of file into 'memp'. Returns 0 on success, else failure
- */
 long smh_read(long fd, void *memp, size_t len)
 {
 	long ret;
@@ -104,9 +101,6 @@ long smh_read(long fd, void *memp, size_t len)
 	return len - ret;
 }
 
-/*
- * Close the file using the file descriptor
- */
 long smh_close(long fd)
 {
 	long ret;
@@ -119,9 +113,6 @@ long smh_close(long fd)
 	return 0;
 }
 
-/*
- * Get the file length from the file descriptor
- */
 long smh_flen(long fd)
 {
 	long ret;
diff --git a/include/semihosting.h b/include/semihosting.h
index cf54819192..d8337b6269 100644
--- a/include/semihosting.h
+++ b/include/semihosting.h
@@ -29,9 +29,41 @@ enum smh_open_mode {
 	MODE_APPEND	= 0x8,
 };
 
+/**
+ * smh_open() - Open a file on the host
+ * @fname: The name of the file to open
+ * @mode: The mode to use when opening the file
+ *
+ * Return: Either a file descriptor or a negative error on failure
+ */
 long smh_open(const char *fname, enum smh_open_mode mode);
+
+/**
+ * smh_read() - Read data from a file
+ * @fd: A file descriptor returned from smh_open()
+ * @memp: Pointer to a buffer of memory of at least @len bytes
+ * @len: The number of bytes to read
+ *
+ * Return:
+ * * The number of bytes read on success, with 0 indicating %EOF
+ * * A negative error on failure
+ */
 long smh_read(long fd, void *memp, size_t len);
+
+/**
+ * smh_close() - Close an open file
+ * @fd: A file descriptor returned from smh_open()
+ *
+ * Return: 0 on success or negative error on failure
+ */
 long smh_close(long fd);
+
+/**
+ * smh_flen() - Get the length of a file
+ * @fd: A file descriptor returned from smh_open()
+ *
+ * Return: The length of the file, in bytes, or a negative error on failure
+ */
 long smh_flen(long fd);
 
 #endif /* _SEMIHOSTING_H */