pxe_utils.h 8.6 KB

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