From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9AA43C433F5 for ; Tue, 9 Nov 2021 08:07:50 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id D97DA6112D for ; Tue, 9 Nov 2021 08:07:49 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org D97DA6112D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 0FB1F83651; Tue, 9 Nov 2021 09:07:48 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="MPeaoMyW"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 2D6CF83670; Tue, 9 Nov 2021 09:07:46 +0100 (CET) Received: from mail-ot1-x32c.google.com (mail-ot1-x32c.google.com [IPv6:2607:f8b0:4864:20::32c]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 18F7683630 for ; Tue, 9 Nov 2021 09:07:42 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=rfried.dev@gmail.com Received: by mail-ot1-x32c.google.com with SMTP id g91-20020a9d12e4000000b0055ae68cfc3dso26980833otg.9 for ; Tue, 09 Nov 2021 00:07:42 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=d5YKs17KMMKOhggsQ2Nf5uvhTODhrru3epeiCKMYFxI=; b=MPeaoMyWU5WGZTAjzxua0FBHE/qf0L9vy0n4kwl0r56RQu3gzAThYiM+qH5W/wm19J XwOlAOAfckMjo3VID5dPHxPlUitP4Hx+d36z4TH3k0MQPMnimSbcmoNsm8XiJdJPxVty iL9waKaeuE9ZTmZWQjrLuVjggzTbuRkCZZYfAZbOG5uQOzpBU1WDZz+/2p/DenXK1iFY 10tqMZ+Ikodm1em/89iAwamzVNZpJMhdKQ5dKxlqAsbmyVmR5QmTUBoUD+VcQxw9IMzp a7Ml3JIX1FlDYhpXALOG3GHV1H2ZjeGeh/5OrwzOumeq7ibaf5FncsYUO6uZ+KFqeGxk JZFg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=d5YKs17KMMKOhggsQ2Nf5uvhTODhrru3epeiCKMYFxI=; b=E0VcnDXiQzJVE+OvUWIXe1ZIuYhrlEcfFXR/FuSQA15mtV8m2vJBB4KG+HL21oQgZY 9KcZ9WKDoSXxjj2/oUPN/gX/LCBcX1SMsdbSYZ3xzcrwj730eMt5otg6CXFG1SF2Bkgs MrDQznt0b6GTFka67IdkHBDDdgFNSGAxsKbWsTaOnr1DKs3HEdKJsJUMlatLnJWEtNwF MzpFwLphDSKTaDMBWneXreUXkOY6LKUAuSHpIjJAo8QZzNQl3B1slrqamYjvL/P4uVrZ um+cjx1tZWFGlXs6+wbVf4KQCaWovnm1uHmthWlXCSRPmMe2ai2vo9/ycb9RIZuJNdrG qKiQ== X-Gm-Message-State: AOAM530P5DTWpd3Bo63cY0dk+9i4PjXwyYjcTP2eqnoh7yuOLO4czur8 saf7qOadiW2OSHMb8fGjk+vl1oOUfaJW+gUr8VA= X-Google-Smtp-Source: ABdhPJwrOjHDh/kSm0LDBk9iGzumZ+KEtMyR+tbRjUFwjqsXbNdWSF97KEkRws6HT3yghGRsILg2s7dHRlrqh2EDehs= X-Received: by 2002:a9d:6646:: with SMTP id q6mr4421621otm.327.1636445260462; Tue, 09 Nov 2021 00:07:40 -0800 (PST) MIME-Version: 1.0 References: <20211014184811.482560-1-sjg@chromium.org> <20211014184811.482560-3-sjg@chromium.org> In-Reply-To: <20211014184811.482560-3-sjg@chromium.org> From: Ramon Fried Date: Tue, 9 Nov 2021 10:07:29 +0200 Message-ID: Subject: Re: [PATCH v3 02/18] pxe: Move API comments to the header files To: Simon Glass Cc: U-Boot Mailing List , Patrice Chotard , Artem Lapkin , Tom Rini , Joe Hershberger , Heinrich Schuchardt , Peter Hoyes Content-Type: text/plain; charset="UTF-8" X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean On Thu, Oct 14, 2021 at 9:49 PM Simon Glass wrote: > > Put the function comments in the header file so that the full API can we > examined in one place. > > Expand the comments to cover parameters and return values. > > Signed-off-by: Simon Glass > --- > > (no changes since v1) > > cmd/pxe_utils.c | 45 ----------------------------- > cmd/pxe_utils.h | 77 +++++++++++++++++++++++++++++++++++++++++++++++-- > 2 files changed, 74 insertions(+), 48 deletions(-) > > diff --git a/cmd/pxe_utils.c b/cmd/pxe_utils.c > index 067c24e5ff4..d7f4017efeb 100644 > --- a/cmd/pxe_utils.c > +++ b/cmd/pxe_utils.c > @@ -32,16 +32,6 @@ > > bool is_pxe; > > -/* > - * Convert an ethaddr from the environment to the format used by pxelinux > - * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to > - * the beginning of the ethernet address to indicate a hardware type of > - * Ethernet. Also converts uppercase hex characters into lowercase, to match > - * pxelinux's behavior. > - * > - * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the > - * environment, or some other value < 0 on error. > - */ > int format_mac_pxe(char *outbuf, size_t outbuf_len) > { > uchar ethaddr[6]; > @@ -146,13 +136,6 @@ static int get_relfile(struct cmd_tbl *cmdtp, const char *file_path, > return do_getfile(cmdtp, relfile, addr_buf); > } > > -/* > - * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If > - * 'bootfile' was specified in the environment, the path to bootfile will be > - * prepended to 'file_path' and the resulting path will be used. > - * > - * Returns 1 on success, or < 0 for error. > - */ > int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, > unsigned long file_addr) > { > @@ -187,13 +170,6 @@ int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, > > #define PXELINUX_DIR "pxelinux.cfg/" > > -/* > - * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file > - * to do the hard work, the location of the 'pxelinux.cfg' folder is generated > - * from the bootfile path, as described above. > - * > - * Returns 1 on success or < 0 on error. > - */ > int get_pxelinux_path(struct cmd_tbl *cmdtp, const char *file, > unsigned long pxefile_addr_r) > { > @@ -1309,15 +1285,6 @@ void destroy_pxe_menu(struct pxe_menu *cfg) > free(cfg); > } > > -/* > - * Entry point for parsing a pxe file. This is only used for the top level > - * file. > - * > - * Returns NULL if there is an error, otherwise, returns a pointer to a > - * pxe_menu struct populated with the results of parsing the pxe file (and any > - * files it includes). The resulting pxe_menu struct can be free()'d by using > - * the destroy_pxe_menu() function. > - */ > struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, unsigned long menucfg) > { > struct pxe_menu *cfg; > @@ -1415,18 +1382,6 @@ static void boot_unattempted_labels(struct cmd_tbl *cmdtp, struct pxe_menu *cfg) > } > } > > -/* > - * Boot the system as prescribed by a pxe_menu. > - * > - * Use the menu system to either get the user's choice or the default, based > - * on config or user input. If there is no default or user's choice, > - * attempted to boot labels in the order they were given in pxe files. > - * If the default or user's choice fails to boot, attempt to boot other > - * labels in the order they were given in pxe files. > - * > - * If this function returns, there weren't any labels that successfully > - * booted, or the user interrupted the menu selection via ctrl+c. > - */ > void handle_pxe_menu(struct cmd_tbl *cmdtp, struct pxe_menu *cfg) > { > void *choice; > diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h > index bf58e15347c..441beefa2bc 100644 > --- a/cmd/pxe_utils.h > +++ b/cmd/pxe_utils.h > @@ -80,12 +80,83 @@ extern bool is_pxe; > extern int (*do_getfile)(struct cmd_tbl *cmdtp, const char *file_path, > char *file_addr); > void destroy_pxe_menu(struct pxe_menu *cfg); > + > +/** > + * get_pxe_file() - Read a file > + * > + * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If > + * 'bootfile' was specified in the environment, the path to bootfile will be > + * prepended to 'file_path' and the resulting path will be used. > + * > + * @cmdtp: Pointer to command-table entry for the initiating command > + * @file_path: Path to file > + * @file_addr: Address to place file > + * Returns 1 on success, or < 0 for error > + */ > int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, > - unsigned long file_addr); > + ulong file_addr); > + > +/** > + * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg > + * > + * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file() > + * to do the hard work, the location of the 'pxelinux.cfg' folder is generated > + * from the bootfile path, as described in get_pxe_file(). > + * > + * @cmdtp: Pointer to command-table entry for the initiating command > + * @file: Relative path to file > + * @pxefile_addr_r: Address to load file > + * Returns 1 on success or < 0 on error. > + */ > int get_pxelinux_path(struct cmd_tbl *cmdtp, const char *file, > - unsigned long pxefile_addr_r); > + ulong pxefile_addr_r); > + > +/** > + * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu. > + * > + * Use the menu system to either get the user's choice or the default, based > + * on config or user input. If there is no default or user's choice, > + * attempted to boot labels in the order they were given in pxe files. > + * If the default or user's choice fails to boot, attempt to boot other > + * labels in the order they were given in pxe files. > + * > + * If this function returns, there weren't any labels that successfully > + * booted, or the user interrupted the menu selection via ctrl+c. > + * > + * @cmdtp: Pointer to command-table entry for the initiating command > + * @cfg: PXE menu > + */ > void handle_pxe_menu(struct cmd_tbl *cmdtp, struct pxe_menu *cfg); > -struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, unsigned long menucfg); > + > +/** > + * parse_pxefile() - Parsing a pxe file > + * > + * This is only used for the top-level file. > + * > + * @cmdtp: Pointer to command-table entry for the initiating command > + * @menucfg: Address of PXE file > + * > + * Returns NULL if there is an error, otherwise, returns a pointer to a > + * pxe_menu struct populated with the results of parsing the pxe file (and any > + * files it includes). The resulting pxe_menu struct can be free()'d by using > + * the destroy_pxe_menu() function. > + */ > +struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, ulong menucfg); > + > +/** > + * format_mac_pxe() - Convert a MAC address to PXE format > + * > + * Convert an ethaddr from the environment to the format used by pxelinux > + * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to > + * the beginning of the ethernet address to indicate a hardware type of > + * Ethernet. Also converts uppercase hex characters into lowercase, to match > + * pxelinux's behavior. > + * > + * @outbuf: Buffer to hold the output (must hold 22 bytes) > + * @outbuf_len: Length of buffer > + * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the > + * environment, or some other value < 0 on error. > + */ > int format_mac_pxe(char *outbuf, size_t outbuf_len); > > #endif /* __PXE_UTILS_H */ > -- > 2.33.0.1079.g6e70778dc9-goog > Reviewed-by: Ramon Fried