tools/env/fw_env.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * (C) Copyright 2002-2008
   4  * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
   5  */
   6
   7 #include <stdint.h>
   8
   9 /*
  10  * Programs using the library must check which API is available,
  11  * that varies depending on the U-Boot version.
  12  * This can be changed in future
  13  */
  14 #define FW_ENV_API_VERSION      1
  15
  16 struct env_opts {
  17 #ifdef CONFIG_FILE
  18         char *config_file;
  19 #endif
  20         char *lockname;
  21 };
  22
  23 /**
  24  * fw_printenv() - print one or several environment variables
  25  *
  26  * @argc: number of variables names to be printed, prints all if 0
  27  * @argv: array of variable names to be printed, if argc != 0
  28  * @value_only: do not repeat the variable name, print the bare value,
  29  *          only one variable allowed with this option, argc must be 1
  30  * @opts: encryption key, configuration file, defaults are used if NULL
  31  *
  32  * Description:
  33  *  Uses fw_env_open, fw_getenv
  34  *
  35  * Return:
  36  *  0 on success, -1 on failure (modifies errno)
  37  */
  38 int fw_printenv(int argc, char *argv[], int value_only, struct env_opts *opts);
  39
  40 /**
  41  * fw_env_set() - adds or removes one variable to the environment
  42  *
  43  * @argc: number of strings in argv, argv[0] is variable name,
  44  *          argc==1 means erase variable, argc > 1 means add a variable
  45  * @argv: argv[0] is variable name, argv[1..argc-1] are concatenated separated
  46  *           by single blank and set as the new value of the variable
  47  * @opts: how to retrieve environment from flash, defaults are used if NULL
  48  *
  49  * Description:
  50  *  Uses fw_env_open, fw_env_write, fw_env_flush
  51  *
  52  * Return:
  53  *  0 on success, -1 on failure (modifies errno)
  54  *
  55  * ERRORS:
  56  *  EROFS - some variables ("ethaddr", "serial#") cannot be modified
  57  */
  58 int fw_env_set(int argc, char *argv[], struct env_opts *opts);
  59
  60 /**
  61  * fw_parse_script() - adds or removes multiple variables with a batch script
  62  *
  63  * @fname: batch script file name
  64  * @opts: encryption key, configuration file, defaults are used if NULL
  65  *
  66  * Description:
  67  *  Uses fw_env_open, fw_env_write, fw_env_flush
  68  *
  69  * Return:
  70  *  0 success, -1 on failure (modifies errno)
  71  *
  72  * Script Syntax:
  73  *
  74  *  key [ [space]+ value]
  75  *
  76  *  lines starting with '#' treated as comment
  77  *
  78  *  A variable without value will be deleted. Any number of spaces are allowed
  79  *  between key and value. The value starts with the first non-space character
  80  *  and ends with newline. No comments allowed on these lines.  Spaces inside
  81  *  the value are preserved verbatim.
  82  *
  83  * Script Example:
  84  *
  85  *  netdev         eth0
  86  *
  87  *  kernel_addr    400000
  88  *
  89  *  foo            spaces           are copied verbatim
  90  *
  91  *  # delete variable bar
  92  *
  93  *  bar
  94  */
  95 int fw_parse_script(char *fname, struct env_opts *opts);
  96
  97
  98 /**
  99  * fw_env_open() - read enviroment from flash into RAM cache
 100  *
 101  * @opts: encryption key, configuration file, defaults are used if NULL
 102  *
 103  * Return:
 104  *  0 on success, -1 on failure (modifies errno)
 105  */
 106 int fw_env_open(struct env_opts *opts);
 107
 108 /**
 109  * fw_getenv() - lookup variable in the RAM cache
 110  *
 111  * @name: variable to be searched
 112  * Return:
 113  *  pointer to start of value, NULL if not found
 114  */
 115 char *fw_getenv(char *name);
 116
 117 /**
 118  * fw_env_write() - modify a variable held in the RAM cache
 119  *
 120  * @name: variable
 121  * @value: delete variable if NULL, otherwise create or overwrite the variable
 122  *
 123  * This is called in sequence to update the environment in RAM without updating
 124  * the copy in flash after each set
 125  *
 126  * Return:
 127  *  0 on success, -1 on failure (modifies errno)
 128  *
 129  * ERRORS:
 130  *  EROFS - some variables ("ethaddr", "serial#") cannot be modified
 131  */
 132 int fw_env_write(char *name, char *value);
 133
 134 /**
 135  * fw_env_flush - write the environment from RAM cache back to flash
 136  *
 137  * @opts: encryption key, configuration file, defaults are used if NULL
 138  *
 139  * Return:
 140  *  0 on success, -1 on failure (modifies errno)
 141  */
 142 int fw_env_flush(struct env_opts *opts);
 143
 144 /**
 145  * fw_env_close - free allocated structure and close env
 146  *
 147  * @opts: encryption key, configuration file, defaults are used if NULL
 148  *
 149  * Return:
 150  *  0 on success, -1 on failure (modifies errno)
 151  */
 152 int fw_env_close(struct env_opts *opts);
 153
 154
 155 /**
 156  * fw_env_version - return the current version of the library
 157  *
 158  * Return:
 159  *  version string of the library
 160  */
 161 char *fw_env_version(void);
 162
 163 unsigned long crc32(unsigned long, const unsigned char *, unsigned);