env.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Common environment functions and definitions
  4. *
  5. * (C) Copyright 2000-2009
  6. * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
  7. */
  8. #ifndef __ENV_H
  9. #define __ENV_H
  10. #include <compiler.h>
  11. #include <stdbool.h>
  12. #include <linux/types.h>
  13. struct environment_s;
  14. /* Value for environment validity */
  15. enum env_valid {
  16. ENV_INVALID, /* No valid environment */
  17. ENV_VALID, /* First or only environment is valid */
  18. ENV_REDUND, /* Redundant environment is valid */
  19. };
  20. /** enum env_op - environment callback operation */
  21. enum env_op {
  22. env_op_create,
  23. env_op_delete,
  24. env_op_overwrite,
  25. };
  26. /** struct env_clbk_tbl - declares a new callback */
  27. struct env_clbk_tbl {
  28. const char *name; /* Callback name */
  29. int (*callback)(const char *name, const char *value, enum env_op op,
  30. int flags);
  31. };
  32. /*
  33. * Define a callback that can be associated with variables.
  34. * when associated through the ".callbacks" environment variable, the callback
  35. * will be executed any time the variable is inserted, overwritten, or deleted.
  36. *
  37. * For SPL these are silently dropped to reduce code size, since environment
  38. * callbacks are not supported with SPL.
  39. */
  40. #ifdef CONFIG_SPL_BUILD
  41. #define U_BOOT_ENV_CALLBACK(name, callback) \
  42. static inline __maybe_unused void _u_boot_env_noop_##name(void) \
  43. { \
  44. (void)callback; \
  45. }
  46. #else
  47. #define U_BOOT_ENV_CALLBACK(name, callback) \
  48. ll_entry_declare(struct env_clbk_tbl, name, env_clbk) = \
  49. {#name, callback}
  50. #endif
  51. /** enum env_redund_flags - Flags for the redundand_environment */
  52. enum env_redund_flags {
  53. ENV_REDUND_OBSOLETE = 0,
  54. ENV_REDUND_ACTIVE = 1,
  55. };
  56. /**
  57. * env_get_id() - Gets a sequence number for the environment
  58. *
  59. * This value increments every time the environment changes, so can be used an
  60. * an indication of this
  61. *
  62. * Return: environment ID
  63. */
  64. int env_get_id(void);
  65. /**
  66. * env_init() - Set up the pre-relocation environment
  67. *
  68. * This locates the environment or uses the default if nothing is available.
  69. * This must be called before env_get() will work.
  70. *
  71. * Return: 0 if OK, -ENODEV if no environment drivers are enabled
  72. */
  73. int env_init(void);
  74. /**
  75. * env_relocate() - Set up the post-relocation environment
  76. *
  77. * This loads the environment into RAM so that it can be modified. This is
  78. * called after relocation, before the environment is used
  79. */
  80. void env_relocate(void);
  81. /**
  82. * env_get() - Look up the value of an environment variable
  83. *
  84. * In U-Boot proper this can be called before relocation (which is when the
  85. * environment is loaded from storage, i.e. GD_FLG_ENV_READY is 0). In that
  86. * case this function calls env_get_f().
  87. *
  88. * @varname: Variable to look up
  89. * Return: value of variable, or NULL if not found
  90. */
  91. char *env_get(const char *varname);
  92. /*
  93. * Like env_get, but prints an error if envvar isn't defined in the
  94. * environment. It always returns what env_get does, so it can be used in
  95. * place of env_get without changing error handling otherwise.
  96. *
  97. * @varname: Variable to look up
  98. * Return: value of variable, or NULL if not found
  99. */
  100. char *from_env(const char *envvar);
  101. /**
  102. * env_get_f() - Look up the value of an environment variable (early)
  103. *
  104. * This function is called from env_get() if the environment has not been
  105. * loaded yet (GD_FLG_ENV_READY flag is 0). Some environment locations will
  106. * support reading the value (slowly) and some will not.
  107. *
  108. * @varname: Variable to look up
  109. * Return: actual length of the variable value excluding the terminating
  110. * NULL-byte, or -1 if the variable is not found
  111. */
  112. int env_get_f(const char *name, char *buf, unsigned int len);
  113. /**
  114. * env_get_yesno() - Read an environment variable as a boolean
  115. *
  116. * Return: 1 if yes/true (Y/y/T/t), -1 if variable does not exist (i.e. default
  117. * to true), 0 if otherwise
  118. */
  119. int env_get_yesno(const char *var);
  120. /**
  121. * env_get_autostart() - Check if autostart is enabled
  122. *
  123. * Return: true if the "autostart" env var exists and is set to "yes"
  124. */
  125. bool env_get_autostart(void);
  126. /**
  127. * env_set() - set an environment variable
  128. *
  129. * This sets or deletes the value of an environment variable. For setting the
  130. * value the variable is created if it does not already exist.
  131. *
  132. * @varname: Variable to adjust
  133. * @value: Value to set for the variable, or NULL or "" to delete the variable
  134. * Return: 0 if OK, 1 on error
  135. */
  136. int env_set(const char *varname, const char *value);
  137. /**
  138. * env_get_ulong() - Return an environment variable as an integer value
  139. *
  140. * Most U-Boot environment variables store hex values. For those which store
  141. * (e.g.) base-10 integers, this function can be used to read the value.
  142. *
  143. * @name: Variable to look up
  144. * @base: Base to use (e.g. 10 for base 10, 2 for binary)
  145. * @default_val: Default value to return if no value is found
  146. * Return: the value found, or @default_val if none
  147. */
  148. ulong env_get_ulong(const char *name, int base, ulong default_val);
  149. /**
  150. * env_set_ulong() - set an environment variable to an integer
  151. *
  152. * @varname: Variable to adjust
  153. * @value: Value to set for the variable (will be converted to a string)
  154. * Return: 0 if OK, 1 on error
  155. */
  156. int env_set_ulong(const char *varname, ulong value);
  157. /**
  158. * env_get_hex() - Return an environment variable as a hex value
  159. *
  160. * Decode an environment as a hex number (it may or may not have a 0x
  161. * prefix). If the environment variable cannot be found, or does not start
  162. * with hex digits, the default value is returned.
  163. *
  164. * @varname: Variable to decode
  165. * @default_val: Value to return on error
  166. */
  167. ulong env_get_hex(const char *varname, ulong default_val);
  168. /**
  169. * env_set_hex() - set an environment variable to a hex value
  170. *
  171. * @varname: Variable to adjust
  172. * @value: Value to set for the variable (will be converted to a hex string)
  173. * Return: 0 if OK, 1 on error
  174. */
  175. int env_set_hex(const char *varname, ulong value);
  176. /**
  177. * env_set_addr - Set an environment variable to an address in hex
  178. *
  179. * @varname: Environment variable to set
  180. * @addr: Value to set it to
  181. * Return: 0 if ok, 1 on error
  182. */
  183. static inline int env_set_addr(const char *varname, const void *addr)
  184. {
  185. return env_set_hex(varname, (ulong)addr);
  186. }
  187. /**
  188. * env_complete() - return an auto-complete for environment variables
  189. *
  190. * @var: partial name to auto-complete
  191. * @maxv: Maximum number of matches to return
  192. * @cmdv: Returns a list of possible matches
  193. * @maxsz: Size of buffer to use for matches
  194. * @buf: Buffer to use for matches
  195. * @dollar_comp: non-zero to wrap each match in ${...}
  196. * Return: number of matches found (in @cmdv)
  197. */
  198. int env_complete(char *var, int maxv, char *cmdv[], int maxsz, char *buf,
  199. bool dollar_comp);
  200. /**
  201. * eth_env_get_enetaddr() - Get an ethernet address from the environmnet
  202. *
  203. * @name: Environment variable to get (e.g. "ethaddr")
  204. * @enetaddr: Place to put MAC address (6 bytes)
  205. * Return: 1 if OK, 0 on error
  206. */
  207. int eth_env_get_enetaddr(const char *name, uint8_t *enetaddr);
  208. /**
  209. * eth_env_set_enetaddr() - Set an ethernet address in the environmnet
  210. *
  211. * @name: Environment variable to set (e.g. "ethaddr")
  212. * @enetaddr: Pointer to MAC address to put into the variable (6 bytes)
  213. * Return: 0 if OK, non-zero otherwise
  214. */
  215. int eth_env_set_enetaddr(const char *name, const uint8_t *enetaddr);
  216. /**
  217. * env_fix_drivers() - Updates envdriver as per relocation
  218. */
  219. void env_fix_drivers(void);
  220. /**
  221. * env_set_default_vars() - reset variables to their default value
  222. *
  223. * This resets individual variables to their value in the default environment
  224. *
  225. * @nvars: Number of variables to set/reset
  226. * @vars: List of variables to set/reset
  227. * @flags: Flags controlling matching (H_... - see search.h)
  228. */
  229. int env_set_default_vars(int nvars, char *const vars[], int flags);
  230. /**
  231. * env_load() - Load the environment from storage
  232. *
  233. * Return: 0 if OK, -ve on error
  234. */
  235. int env_load(void);
  236. /**
  237. * env_reload() - Re-Load the environment from current storage
  238. *
  239. * Return: 0 if OK, -ve on error
  240. */
  241. int env_reload(void);
  242. /**
  243. * env_save() - Save the environment to storage
  244. *
  245. * Return: 0 if OK, -ve on error
  246. */
  247. int env_save(void);
  248. /**
  249. * env_erase() - Erase the environment on storage
  250. *
  251. * Return: 0 if OK, -ve on error
  252. */
  253. int env_erase(void);
  254. /**
  255. * env_select() - Select the environment storage
  256. *
  257. * Return: 0 if OK, -ve on error
  258. */
  259. int env_select(const char *name);
  260. /**
  261. * env_import() - Import from a binary representation into hash table
  262. *
  263. * This imports the environment from a buffer. The format for each variable is
  264. * var=value\0 with a double \0 at the end of the buffer.
  265. *
  266. * @buf: Buffer containing the environment (struct environemnt_s *)
  267. * @check: non-zero to check the CRC at the start of the environment, 0 to
  268. * ignore it
  269. * @flags: Flags controlling matching (H_... - see search.h)
  270. * Return: 0 if imported successfully, -ENOMSG if the CRC was bad, -EIO if
  271. * something else went wrong
  272. */
  273. int env_import(const char *buf, int check, int flags);
  274. /**
  275. * env_export() - Export the environment to a buffer
  276. *
  277. * Export from hash table into binary representation
  278. *
  279. * @env_out: Buffer to contain the environment (must be large enough!)
  280. * Return: 0 if OK, 1 on error
  281. */
  282. int env_export(struct environment_s *env_out);
  283. /**
  284. * env_check_redund() - check the two redundant environments
  285. * and find out, which is the valid one.
  286. *
  287. * @buf1: First environment (struct environemnt_s *)
  288. * @buf1_read_fail: 0 if buf1 is valid, non-zero if invalid
  289. * @buf2: Second environment (struct environemnt_s *)
  290. * @buf2_read_fail: 0 if buf2 is valid, non-zero if invalid
  291. * Return: 0 if OK,
  292. * -EIO if no environment is valid,
  293. * -ENOMSG if the CRC was bad
  294. */
  295. int env_check_redund(const char *buf1, int buf1_read_fail,
  296. const char *buf2, int buf2_read_fail);
  297. /**
  298. * env_import_redund() - Select and import one of two redundant environments
  299. *
  300. * @buf1: First environment (struct environemnt_s *)
  301. * @buf1_read_fail: 0 if buf1 is valid, non-zero if invalid
  302. * @buf2: Second environment (struct environemnt_s *)
  303. * @buf2_read_fail: 0 if buf2 is valid, non-zero if invalid
  304. * @flags: Flags controlling matching (H_... - see search.h)
  305. * Return: 0 if OK, -EIO if no environment is valid, -ENOMSG if the CRC was bad
  306. */
  307. int env_import_redund(const char *buf1, int buf1_read_fail,
  308. const char *buf2, int buf2_read_fail,
  309. int flags);
  310. /**
  311. * env_get_default() - Look up a variable from the default environment
  312. *
  313. * @name: Variable to look up
  314. * Return: value if found, NULL if not found in default environment
  315. */
  316. char *env_get_default(const char *name);
  317. /* [re]set to the default environment */
  318. void env_set_default(const char *s, int flags);
  319. /**
  320. * env_reloc() - Relocate the 'env' sub-commands
  321. *
  322. * This is used for those unfortunate archs with crappy toolchains
  323. */
  324. void env_reloc(void);
  325. /**
  326. * env_import_fdt() - Import environment values from device tree blob
  327. *
  328. * This uses the value of the environment variable "env_fdt_path" as a
  329. * path to an fdt node, whose property/value pairs are added to the
  330. * environment.
  331. */
  332. #ifdef CONFIG_ENV_IMPORT_FDT
  333. void env_import_fdt(void);
  334. #else
  335. static inline void env_import_fdt(void) {}
  336. #endif
  337. #endif