pxe_utils.h 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. #ifndef __PXE_UTILS_H
  3. #define __PXE_UTILS_H
  4. #include <linux/list.h>
  5. /*
  6. * A note on the pxe file parser.
  7. *
  8. * We're parsing files that use syslinux grammar, which has a few quirks.
  9. * String literals must be recognized based on context - there is no
  10. * quoting or escaping support. There's also nothing to explicitly indicate
  11. * when a label section completes. We deal with that by ending a label
  12. * section whenever we see a line that doesn't include.
  13. *
  14. * As with the syslinux family, this same file format could be reused in the
  15. * future for non pxe purposes. The only action it takes during parsing that
  16. * would throw this off is handling of include files. It assumes we're using
  17. * pxe, and does a tftp download of a file listed as an include file in the
  18. * middle of the parsing operation. That could be handled by refactoring it to
  19. * take a 'include file getter' function.
  20. */
  21. /*
  22. * Describes a single label given in a pxe file.
  23. *
  24. * Create these with the 'label_create' function given below.
  25. *
  26. * name - the name of the menu as given on the 'menu label' line.
  27. * kernel - the path to the kernel file to use for this label.
  28. * append - kernel command line to use when booting this label
  29. * initrd - path to the initrd to use for this label.
  30. * attempted - 0 if we haven't tried to boot this label, 1 if we have.
  31. * localboot - 1 if this label specified 'localboot', 0 otherwise.
  32. * kaslrseed - 1 if generate kaslrseed from hw_rng
  33. * list - lets these form a list, which a pxe_menu struct will hold.
  34. */
  35. struct pxe_label {
  36. char num[4];
  37. char *name;
  38. char *menu;
  39. char *kernel;
  40. char *config;
  41. char *append;
  42. char *initrd;
  43. char *fdt;
  44. char *fdtdir;
  45. char *fdtoverlays;
  46. int ipappend;
  47. int attempted;
  48. int localboot;
  49. int localboot_val;
  50. int kaslrseed;
  51. struct list_head list;
  52. };
  53. /*
  54. * Describes a pxe menu as given via pxe files.
  55. *
  56. * title - the name of the menu as given by a 'menu title' line.
  57. * default_label - the name of the default label, if any.
  58. * bmp - the bmp file name which is displayed in background
  59. * timeout - time in tenths of a second to wait for a user key-press before
  60. * booting the default label.
  61. * prompt - if 0, don't prompt for a choice unless the timeout period is
  62. * interrupted. If 1, always prompt for a choice regardless of
  63. * timeout.
  64. * labels - a list of labels defined for the menu.
  65. */
  66. struct pxe_menu {
  67. char *title;
  68. char *default_label;
  69. char *bmp;
  70. int timeout;
  71. int prompt;
  72. struct list_head labels;
  73. };
  74. struct pxe_context;
  75. typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
  76. char *file_addr, ulong *filesizep);
  77. /**
  78. * struct pxe_context - context information for PXE parsing
  79. *
  80. * @cmdtp: Pointer to command table to use when calling other commands
  81. * @getfile: Function called by PXE to read a file
  82. * @userdata: Data the caller requires for @getfile
  83. * @allow_abs_path: true to allow absolute paths
  84. * @bootdir: Directory that files are loaded from ("" if no directory). This is
  85. * allocated
  86. * @pxe_file_size: Size of the PXE file
  87. */
  88. struct pxe_context {
  89. struct cmd_tbl *cmdtp;
  90. /**
  91. * getfile() - read a file
  92. *
  93. * @ctx: PXE context
  94. * @file_path: Path to the file
  95. * @file_addr: String containing the hex address to put the file in
  96. * memory
  97. * @filesizep: Returns the file size in bytes
  98. * Return 0 if OK, -ve on error
  99. */
  100. pxe_getfile_func getfile;
  101. void *userdata;
  102. bool allow_abs_path;
  103. char *bootdir;
  104. ulong pxe_file_size;
  105. };
  106. /**
  107. * destroy_pxe_menu() - Destroy an allocated pxe structure
  108. *
  109. * Free the memory used by a pxe_menu and its labels
  110. *
  111. * @cfg: Config to destroy, previous returned from parse_pxefile()
  112. */
  113. void destroy_pxe_menu(struct pxe_menu *cfg);
  114. /**
  115. * get_pxe_file() - Read a file
  116. *
  117. * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If
  118. * 'bootfile' was specified in the environment, the path to bootfile will be
  119. * prepended to 'file_path' and the resulting path will be used.
  120. *
  121. * @ctx: PXE context
  122. * @file_path: Path to file
  123. * @file_addr: Address to place file
  124. * Returns 1 on success, or < 0 for error
  125. */
  126. int get_pxe_file(struct pxe_context *ctx, const char *file_path,
  127. ulong file_addr);
  128. /**
  129. * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg
  130. *
  131. * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file()
  132. * to do the hard work, the location of the 'pxelinux.cfg' folder is generated
  133. * from the bootfile path, as described in get_pxe_file().
  134. *
  135. * @ctx: PXE context
  136. * @file: Relative path to file
  137. * @pxefile_addr_r: Address to load file
  138. * Returns 1 on success or < 0 on error.
  139. */
  140. int get_pxelinux_path(struct pxe_context *ctx, const char *file,
  141. ulong pxefile_addr_r);
  142. /**
  143. * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu.
  144. *
  145. * Use the menu system to either get the user's choice or the default, based
  146. * on config or user input. If there is no default or user's choice,
  147. * attempted to boot labels in the order they were given in pxe files.
  148. * If the default or user's choice fails to boot, attempt to boot other
  149. * labels in the order they were given in pxe files.
  150. *
  151. * If this function returns, there weren't any labels that successfully
  152. * booted, or the user interrupted the menu selection via ctrl+c.
  153. *
  154. * @ctx: PXE context
  155. * @cfg: PXE menu
  156. */
  157. void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);
  158. /**
  159. * parse_pxefile() - Parsing a pxe file
  160. *
  161. * This is only used for the top-level file.
  162. *
  163. * @ctx: PXE context (provided by the caller)
  164. * Returns NULL if there is an error, otherwise, returns a pointer to a
  165. * pxe_menu struct populated with the results of parsing the pxe file (and any
  166. * files it includes). The resulting pxe_menu struct can be free()'d by using
  167. * the destroy_pxe_menu() function.
  168. */
  169. struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg);
  170. /**
  171. * format_mac_pxe() - Convert a MAC address to PXE format
  172. *
  173. * Convert an ethaddr from the environment to the format used by pxelinux
  174. * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to
  175. * the beginning of the ethernet address to indicate a hardware type of
  176. * Ethernet. Also converts uppercase hex characters into lowercase, to match
  177. * pxelinux's behavior.
  178. *
  179. * @outbuf: Buffer to hold the output (must hold 22 bytes)
  180. * @outbuf_len: Length of buffer
  181. * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the
  182. * environment, or some other value < 0 on error.
  183. */
  184. int format_mac_pxe(char *outbuf, size_t outbuf_len);
  185. /**
  186. * pxe_setup_ctx() - Setup a new PXE context
  187. *
  188. * @ctx: Context to set up
  189. * @cmdtp: Command table entry which started this action
  190. * @getfile: Function to call to read a file
  191. * @userdata: Data the caller requires for @getfile - stored in ctx->userdata
  192. * @allow_abs_path: true to allow absolute paths
  193. * @bootfile: Bootfile whose directory loaded files are relative to, NULL if
  194. * none
  195. * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than
  196. * MAX_TFTP_PATH_LEN bytes
  197. */
  198. int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp,
  199. pxe_getfile_func getfile, void *userdata,
  200. bool allow_abs_path, const char *bootfile);
  201. /**
  202. * pxe_destroy_ctx() - Destroy a PXE context
  203. *
  204. * @ctx: Context to destroy
  205. */
  206. void pxe_destroy_ctx(struct pxe_context *ctx);
  207. /**
  208. * pxe_process() - Process a PXE file through to boot
  209. *
  210. * @ctx: PXE context created with pxe_setup_ctx()
  211. * @pxefile_addr_r: Address to load file
  212. * @prompt: Force a prompt for the user
  213. */
  214. int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);
  215. /**
  216. * pxe_get_file_size() - Read the value of the 'filesize' environment variable
  217. *
  218. * @sizep: Place to put the value
  219. * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
  220. */
  221. int pxe_get_file_size(ulong *sizep);
  222. /**
  223. * pxe_get() - Get the PXE file from the server
  224. *
  225. * This tries various filenames to obtain a PXE file
  226. *
  227. * @pxefile_addr_r: Address to put file
  228. * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile'
  229. * option provided by the DHCP server. If none, returns NULL. For example,
  230. * "rpi/info", which indicates that all files should be fetched from the
  231. * "rpi/" subdirectory
  232. * @sizep: Size of the PXE file (not bootfile)
  233. */
  234. int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep);
  235. #endif /* __PXE_UTILS_H */