185f812c41
Sphinx expects Return: and not @return to indicate a return value.
find . -name '*.c' -exec \
sed -i 's/^\(\s\)\*\(\s*\)@return\(\s\)/\1*\2Return:\3/' {} \;
find . -name '*.h' -exec \
sed -i 's/^\(\s\)\*\(\s*\)@return\(\s\)/\1*\2Return:\3/' {} \;
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
254 lines
8.2 KiB
C
254 lines
8.2 KiB
C
/* SPDX-License-Identifier: GPL-2.0+ */
|
|
|
|
#ifndef __PXE_UTILS_H
|
|
#define __PXE_UTILS_H
|
|
|
|
#include <linux/list.h>
|
|
|
|
/*
|
|
* A note on the pxe file parser.
|
|
*
|
|
* We're parsing files that use syslinux grammar, which has a few quirks.
|
|
* String literals must be recognized based on context - there is no
|
|
* quoting or escaping support. There's also nothing to explicitly indicate
|
|
* when a label section completes. We deal with that by ending a label
|
|
* section whenever we see a line that doesn't include.
|
|
*
|
|
* As with the syslinux family, this same file format could be reused in the
|
|
* future for non pxe purposes. The only action it takes during parsing that
|
|
* would throw this off is handling of include files. It assumes we're using
|
|
* pxe, and does a tftp download of a file listed as an include file in the
|
|
* middle of the parsing operation. That could be handled by refactoring it to
|
|
* take a 'include file getter' function.
|
|
*/
|
|
|
|
/*
|
|
* Describes a single label given in a pxe file.
|
|
*
|
|
* Create these with the 'label_create' function given below.
|
|
*
|
|
* name - the name of the menu as given on the 'menu label' line.
|
|
* kernel - the path to the kernel file to use for this label.
|
|
* append - kernel command line to use when booting this label
|
|
* initrd - path to the initrd to use for this label.
|
|
* attempted - 0 if we haven't tried to boot this label, 1 if we have.
|
|
* localboot - 1 if this label specified 'localboot', 0 otherwise.
|
|
* list - lets these form a list, which a pxe_menu struct will hold.
|
|
*/
|
|
struct pxe_label {
|
|
char num[4];
|
|
char *name;
|
|
char *menu;
|
|
char *kernel;
|
|
char *config;
|
|
char *append;
|
|
char *initrd;
|
|
char *fdt;
|
|
char *fdtdir;
|
|
char *fdtoverlays;
|
|
int ipappend;
|
|
int attempted;
|
|
int localboot;
|
|
int localboot_val;
|
|
struct list_head list;
|
|
};
|
|
|
|
/*
|
|
* Describes a pxe menu as given via pxe files.
|
|
*
|
|
* title - the name of the menu as given by a 'menu title' line.
|
|
* default_label - the name of the default label, if any.
|
|
* bmp - the bmp file name which is displayed in background
|
|
* timeout - time in tenths of a second to wait for a user key-press before
|
|
* booting the default label.
|
|
* prompt - if 0, don't prompt for a choice unless the timeout period is
|
|
* interrupted. If 1, always prompt for a choice regardless of
|
|
* timeout.
|
|
* labels - a list of labels defined for the menu.
|
|
*/
|
|
struct pxe_menu {
|
|
char *title;
|
|
char *default_label;
|
|
char *bmp;
|
|
int timeout;
|
|
int prompt;
|
|
struct list_head labels;
|
|
};
|
|
|
|
struct pxe_context;
|
|
typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
|
|
char *file_addr, ulong *filesizep);
|
|
|
|
/**
|
|
* struct pxe_context - context information for PXE parsing
|
|
*
|
|
* @cmdtp: Pointer to command table to use when calling other commands
|
|
* @getfile: Function called by PXE to read a file
|
|
* @userdata: Data the caller requires for @getfile
|
|
* @allow_abs_path: true to allow absolute paths
|
|
* @bootdir: Directory that files are loaded from ("" if no directory). This is
|
|
* allocated
|
|
* @pxe_file_size: Size of the PXE file
|
|
*/
|
|
struct pxe_context {
|
|
struct cmd_tbl *cmdtp;
|
|
/**
|
|
* getfile() - read a file
|
|
*
|
|
* @ctx: PXE context
|
|
* @file_path: Path to the file
|
|
* @file_addr: String containing the hex address to put the file in
|
|
* memory
|
|
* @filesizep: Returns the file size in bytes
|
|
* Return 0 if OK, -ve on error
|
|
*/
|
|
pxe_getfile_func getfile;
|
|
|
|
void *userdata;
|
|
bool allow_abs_path;
|
|
char *bootdir;
|
|
ulong pxe_file_size;
|
|
};
|
|
|
|
/**
|
|
* destroy_pxe_menu() - Destroy an allocated pxe structure
|
|
*
|
|
* Free the memory used by a pxe_menu and its labels
|
|
*
|
|
* @cfg: Config to destroy, previous returned from parse_pxefile()
|
|
*/
|
|
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.
|
|
*
|
|
* @ctx: PXE context
|
|
* @file_path: Path to file
|
|
* @file_addr: Address to place file
|
|
* Returns 1 on success, or < 0 for error
|
|
*/
|
|
int get_pxe_file(struct pxe_context *ctx, const char *file_path,
|
|
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().
|
|
*
|
|
* @ctx: PXE context
|
|
* @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 pxe_context *ctx, const char *file,
|
|
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.
|
|
*
|
|
* @ctx: PXE context
|
|
* @cfg: PXE menu
|
|
*/
|
|
void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);
|
|
|
|
/**
|
|
* parse_pxefile() - Parsing a pxe file
|
|
*
|
|
* This is only used for the top-level file.
|
|
*
|
|
* @ctx: PXE context (provided by the caller)
|
|
* 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 pxe_context *ctx, 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);
|
|
|
|
/**
|
|
* pxe_setup_ctx() - Setup a new PXE context
|
|
*
|
|
* @ctx: Context to set up
|
|
* @cmdtp: Command table entry which started this action
|
|
* @getfile: Function to call to read a file
|
|
* @userdata: Data the caller requires for @getfile - stored in ctx->userdata
|
|
* @allow_abs_path: true to allow absolute paths
|
|
* @bootfile: Bootfile whose directory loaded files are relative to, NULL if
|
|
* none
|
|
* Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than
|
|
* MAX_TFTP_PATH_LEN bytes
|
|
*/
|
|
int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp,
|
|
pxe_getfile_func getfile, void *userdata,
|
|
bool allow_abs_path, const char *bootfile);
|
|
|
|
/**
|
|
* pxe_destroy_ctx() - Destroy a PXE context
|
|
*
|
|
* @ctx: Context to destroy
|
|
*/
|
|
void pxe_destroy_ctx(struct pxe_context *ctx);
|
|
|
|
/**
|
|
* pxe_process() - Process a PXE file through to boot
|
|
*
|
|
* @ctx: PXE context created with pxe_setup_ctx()
|
|
* @pxefile_addr_r: Address to load file
|
|
* @prompt: Force a prompt for the user
|
|
*/
|
|
int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);
|
|
|
|
/**
|
|
* pxe_get_file_size() - Read the value of the 'filesize' environment variable
|
|
*
|
|
* @sizep: Place to put the value
|
|
* Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
|
|
*/
|
|
int pxe_get_file_size(ulong *sizep);
|
|
|
|
/**
|
|
* pxe_get() - Get the PXE file from the server
|
|
*
|
|
* This tries various filenames to obtain a PXE file
|
|
*
|
|
* @pxefile_addr_r: Address to put file
|
|
* @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile'
|
|
* option provided by the DHCP server. If none, returns NULL. For example,
|
|
* "rpi/info", which indicates that all files should be fetched from the
|
|
* "rpi/" subdirectory
|
|
* @sizep: Size of the PXE file (not bootfile)
|
|
*/
|
|
int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep);
|
|
|
|
#endif /* __PXE_UTILS_H */
|