Re: [PATCH v3 08/18] pxe: Tidy up some comments in pxe_utils
On Thu, Oct 14, 2021 at 12:48:01PM -0600, Simon Glass wrote: > Some of these functions are a big vague in the comments. Tidy them up a > bit. > > Signed-off-by: Simon Glass > Reviewed-by: Artem Lapkin > Tested-by: Artem Lapkin > Reviewed-by: Ramon Fried Applied to u-boot/master, thanks! -- Tom signature.asc Description: PGP signature
Re: [PATCH v3 08/18] pxe: Tidy up some comments in pxe_utils
On Thu, Oct 14, 2021 at 9:50 PM Simon Glass wrote:
>
> Some of these functions are a big vague in the comments. Tidy them up a
> bit.
>
> Signed-off-by: Simon Glass
> ---
>
> (no changes since v1)
>
> boot/pxe_utils.c | 189 ++-
> 1 file changed, 138 insertions(+), 51 deletions(-)
>
> diff --git a/boot/pxe_utils.c b/boot/pxe_utils.c
> index 7d15c75dd87..7a2213a5925 100644
> --- a/boot/pxe_utils.c
> +++ b/boot/pxe_utils.c
> @@ -30,6 +30,21 @@
>
> #define MAX_TFTP_PATH_LEN 512
>
> +/**
> + * format_mac_pxe() - obtain a MAC address in the PXE format
> + *
> + * This produces a MAC-address string in the format for the current ethernet
> + * device:
> + *
> + * 01-aa-bb-cc-dd-ee-ff
> + *
> + * where aa-ff is the MAC address in hex
> + *
> + * @outbuf: Buffer to write string to
> + * @outbuf_len: length of buffer
> + * @return 1 if OK, -ENOSPC if buffer is too small, -ENOENT is there is no
> + * current ethernet device
> + */
> int format_mac_pxe(char *outbuf, size_t outbuf_len)
> {
> uchar ethaddr[6];
> @@ -37,7 +52,7 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len)
> if (outbuf_len < 21) {
> printf("outbuf is too small (%zd < 21)\n", outbuf_len);
>
> - return -EINVAL;
> + return -ENOSPC;
> }
>
> if (!eth_env_get_enetaddr_by_index("eth", eth_get_dev_index(),
> ethaddr))
> @@ -50,10 +65,20 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len)
> return 1;
> }
>
> -/*
> - * Returns the directory the file specified in the bootfile env variable is
> +/**
> + * get_bootfile_path() - Figure out the path of a file to read
> + *
> + * Returns the directory the file specified in the 'bootfile' env variable is
> * in. If bootfile isn't defined in the environment, return NULL, which
> should
> * be interpreted as "don't prepend anything to paths".
> + *
> + * @file_path: File path to read (relative to the PXE file)
> + * @bootfile_path: Place to put the bootfile path
> + * @bootfile_path_size: Size of @bootfile_path in bytes
> + * @allow_abs_path: true to allow an absolute path (where @file_path starts
> with
> + * '/', false to return an empty path (and success) in that case
> + * Returns 1 for success, -ENOSPC if bootfile_path_size is to small to hold
> the
> + * resulting path
> */
> static int get_bootfile_path(const char *file_path, char *bootfile_path,
> size_t bootfile_path_size, bool allow_abs_path)
> @@ -81,7 +106,7 @@ static int get_bootfile_path(const char *file_path, char
> *bootfile_path,
> printf("bootfile_path too small. (%zd < %zd)\n",
>bootfile_path_size, path_len);
>
> - return -1;
> + return -ENOSPC;
> }
>
> strncpy(bootfile_path, bootfile, path_len);
> @@ -92,13 +117,18 @@ static int get_bootfile_path(const char *file_path, char
> *bootfile_path,
> return 1;
> }
>
> -/*
> +/**
> + * get_relfile() - read a file relative to the PXE file
> + *
> * As in pxelinux, paths to files referenced from files we retrieve are
> * relative to the location of bootfile. get_relfile takes such a path and
> * joins it with the bootfile path to get the full path to the target file.
> If
> * the bootfile path is NULL, we use file_path as is.
> *
> - * Returns 1 for success, or < 0 on error.
> + * @ctx: PXE context
> + * @file_path: File path to read (relative to the PXE file)
> + * @file_addr: Address to load file to
> + * Returns 1 for success, or < 0 on error
> */
> static int get_relfile(struct pxe_context *ctx, const char *file_path,
>unsigned long file_addr)
> @@ -132,6 +162,16 @@ static int get_relfile(struct pxe_context *ctx, const
> char *file_path,
> return ctx->getfile(ctx, relfile, addr_buf);
> }
>
> +/**
> + * get_pxe_file() - read a file
> + *
> + * The file is read and nul-terminated
> + *
> + * @ctx: PXE context
> + * @file_path: File path to read (relative to the PXE file)
> + * @file_addr: Address to load file to
> + * Returns 1 for success, or < 0 on error
> + */
> int get_pxe_file(struct pxe_context *ctx, const char *file_path,
> unsigned long file_addr)
> {
> @@ -166,6 +206,14 @@ int get_pxe_file(struct pxe_context *ctx, const char
> *file_path,
>
> #define PXELINUX_DIR "pxelinux.cfg/"
>
> +/**
> + * get_pxelinux_path() - Get a file in the pxelinux.cfg/ directory
> + *
> + * @ctx: PXE context
> + * @file: Filename to process (relative to pxelinux.cfg/)
> + * Returns 1 for success, -ENAMETOOLONG if the resulting path is too long.
> + * or other value < 0 on other error
> + */
> int get_pxelinux_path(struct pxe_context *ctx, const char *file,
> unsigned long pxefile_addr_r)
> {
> @@ -183,12 +231,20 @@ int get_pxelinux_path(struct pxe_context *ctx, const
> char *file,
> return get_pxe_file(ctx, path, pxefile_addr_r);
Re: [PATCH v3 08/18] pxe: Tidy up some comments in pxe_utils
OK Reviewed and Tested on -master Mon 18 Oct 2021 04:40:29 PM CST Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin
[PATCH v3 08/18] pxe: Tidy up some comments in pxe_utils
Some of these functions are a big vague in the comments. Tidy them up a
bit.
Signed-off-by: Simon Glass
---
(no changes since v1)
boot/pxe_utils.c | 189 ++-
1 file changed, 138 insertions(+), 51 deletions(-)
diff --git a/boot/pxe_utils.c b/boot/pxe_utils.c
index 7d15c75dd87..7a2213a5925 100644
--- a/boot/pxe_utils.c
+++ b/boot/pxe_utils.c
@@ -30,6 +30,21 @@
#define MAX_TFTP_PATH_LEN 512
+/**
+ * format_mac_pxe() - obtain a MAC address in the PXE format
+ *
+ * This produces a MAC-address string in the format for the current ethernet
+ * device:
+ *
+ * 01-aa-bb-cc-dd-ee-ff
+ *
+ * where aa-ff is the MAC address in hex
+ *
+ * @outbuf: Buffer to write string to
+ * @outbuf_len: length of buffer
+ * @return 1 if OK, -ENOSPC if buffer is too small, -ENOENT is there is no
+ * current ethernet device
+ */
int format_mac_pxe(char *outbuf, size_t outbuf_len)
{
uchar ethaddr[6];
@@ -37,7 +52,7 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len)
if (outbuf_len < 21) {
printf("outbuf is too small (%zd < 21)\n", outbuf_len);
- return -EINVAL;
+ return -ENOSPC;
}
if (!eth_env_get_enetaddr_by_index("eth", eth_get_dev_index(), ethaddr))
@@ -50,10 +65,20 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len)
return 1;
}
-/*
- * Returns the directory the file specified in the bootfile env variable is
+/**
+ * get_bootfile_path() - Figure out the path of a file to read
+ *
+ * Returns the directory the file specified in the 'bootfile' env variable is
* in. If bootfile isn't defined in the environment, return NULL, which should
* be interpreted as "don't prepend anything to paths".
+ *
+ * @file_path: File path to read (relative to the PXE file)
+ * @bootfile_path: Place to put the bootfile path
+ * @bootfile_path_size: Size of @bootfile_path in bytes
+ * @allow_abs_path: true to allow an absolute path (where @file_path starts
with
+ * '/', false to return an empty path (and success) in that case
+ * Returns 1 for success, -ENOSPC if bootfile_path_size is to small to hold the
+ * resulting path
*/
static int get_bootfile_path(const char *file_path, char *bootfile_path,
size_t bootfile_path_size, bool allow_abs_path)
@@ -81,7 +106,7 @@ static int get_bootfile_path(const char *file_path, char
*bootfile_path,
printf("bootfile_path too small. (%zd < %zd)\n",
bootfile_path_size, path_len);
- return -1;
+ return -ENOSPC;
}
strncpy(bootfile_path, bootfile, path_len);
@@ -92,13 +117,18 @@ static int get_bootfile_path(const char *file_path, char
*bootfile_path,
return 1;
}
-/*
+/**
+ * get_relfile() - read a file relative to the PXE file
+ *
* As in pxelinux, paths to files referenced from files we retrieve are
* relative to the location of bootfile. get_relfile takes such a path and
* joins it with the bootfile path to get the full path to the target file. If
* the bootfile path is NULL, we use file_path as is.
*
- * Returns 1 for success, or < 0 on error.
+ * @ctx: PXE context
+ * @file_path: File path to read (relative to the PXE file)
+ * @file_addr: Address to load file to
+ * Returns 1 for success, or < 0 on error
*/
static int get_relfile(struct pxe_context *ctx, const char *file_path,
unsigned long file_addr)
@@ -132,6 +162,16 @@ static int get_relfile(struct pxe_context *ctx, const char
*file_path,
return ctx->getfile(ctx, relfile, addr_buf);
}
+/**
+ * get_pxe_file() - read a file
+ *
+ * The file is read and nul-terminated
+ *
+ * @ctx: PXE context
+ * @file_path: File path to read (relative to the PXE file)
+ * @file_addr: Address to load file to
+ * Returns 1 for success, or < 0 on error
+ */
int get_pxe_file(struct pxe_context *ctx, const char *file_path,
unsigned long file_addr)
{
@@ -166,6 +206,14 @@ int get_pxe_file(struct pxe_context *ctx, const char
*file_path,
#define PXELINUX_DIR "pxelinux.cfg/"
+/**
+ * get_pxelinux_path() - Get a file in the pxelinux.cfg/ directory
+ *
+ * @ctx: PXE context
+ * @file: Filename to process (relative to pxelinux.cfg/)
+ * Returns 1 for success, -ENAMETOOLONG if the resulting path is too long.
+ * or other value < 0 on other error
+ */
int get_pxelinux_path(struct pxe_context *ctx, const char *file,
unsigned long pxefile_addr_r)
{
@@ -183,12 +231,20 @@ int get_pxelinux_path(struct pxe_context *ctx, const char
*file,
return get_pxe_file(ctx, path, pxefile_addr_r);
}
-/*
+/**
+ * get_relfile_envaddr() - read a file to an address in an env var
+ *
* Wrapper to make it easier to store the file at file_path in the location
* specified by envaddr_name. file_path will be joined to the bootfile path,
* if any is specified.
*
- * Returns 1 on success or < 0 on error.
+ * @c
