aboutsummaryrefslogtreecommitdiff
path: root/ubi-utils/src/bootenv.h
blob: 8fecdbf41797ddeb53fc7593453a8cebfb6e9d3e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
#ifndef __BOOTENV_H__
#define __BOOTENV_H__
/*
 * Copyright (c) International Business Machines Corp., 2006
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
 * the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <stdio.h> /* FILE */
#include <stdint.h>
#include <pfiflash.h>

/* DOXYGEN DOCUMENTATION */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file bootenv.h
 * @author oliloh@de.ibm.com
 * @version 1.3
 *
 * 1.3 Some renaming
 */

/**
 * @mainpage Usage
 *
 * @section intro Introduction
 * This library provides all functionality to handle with the so-called
 * platform description data (PDD) and the bootparameters defined in
 * U-Boot. It is able to apply the defined PDD operations in PDD update
 * scenarios. For more information about the PDD and bootparameter
 * environment "bootenv" confer the PDD documentation.
 *
 * @section ret Return codes
 * This library defines some return codes which will be delivered classified
 * as warnings or errors. See the "Defines" section for details and numeric
 * values.
 *
 * @section benv Bootenv format description
 * There are two different input formats:
 *	- text files
 *	- binary files
 *
 * @subsection txt Text Files
 * Text files have to be specified like:
 * @verbatim key1=value1,value2,value7\n key2=value55,value1\n key4=value1\n@endverbatim
 *
 * @subsection bin Binary files
 * Binary files have to be specified like:
 * @verbatim<CRC32-bit>key1=value1,value2,value7\0key2=value55,value1\0... @endverbatim
 * You can confer the U-Boot documentation for more details.
 *
 * @section benvlists Bootenv lists format description.
 * Values referenced in the preceeding subsection can be
 * defined like lists:
 * @verbatim value1,value2,value3 @endverbatim
 * There are some situation where a conversion of a comma
 * seperated list can be useful, e.g. to get a list
 * of defined PDD entries.
 */

#define BOOTENV_MAXSIZE (1024 * 100) /* max 100kiB space for bootenv */

/**
 * @def BOOTENV_ECRC
 *	@brief Given binary file is to large.
 * @def BOOTENV_EFMT
 *	@brief Given bootenv section has an invalid format
 * @def BOOTENV_EBADENTRY
 *	@brief Bad entry in the bootenv section.
 * @def BOOTENV_EINVAL
 *	@brief Invalid bootenv defintion.
 * @def BOOTENV_ENOPDD
 *	@brief Given bootenv sectoin has no PDD defintion string (pdd=...).
 * @def BOOTENV_EPDDINVAL
 *	@brief Given bootenv section has an invalid PDD defintion.
 * @def BOOTENV_ENOTIMPL
 *	@brief Functionality not implemented.
 * @def BOOTENV_ECOPY
 *	@brief Bootenv memory copy error
 * @def BOOTENV_ENOTFOUND
 *	@brief Given key has has no value.
 * @def BOOTENV_EMAX
 *	@brief Highest error value.
 */
#define BOOTENV_ETOOBIG		1
#define BOOTENV_EFMT		2
#define BOOTENV_EBADENTRY	3
#define BOOTENV_EINVAL		4
#define BOOTENV_ENOPDD		5
#define BOOTENV_EPDDINVAL	6
#define BOOTENV_ENOTIMPL	7
#define BOOTENV_ECOPY		8
#define BOOTENV_ENOTFOUND	9
#define BOOTENV_EMAX		10

/**
 * @def BOOTENV_W
 *	@brief A warning which is handled internally as an error
 *	 but can be recovered by manual effort.
 * @def BOOTENV_WPDD_STRING_DIFFERS
 *	@brief The PDD strings of old and new PDD differ and
 *	can cause update problems, because new PDD values
 *	are removed from the bootenv section completely.
 */
#define BOOTENV_W		     20
#define BOOTENV_WPDD_STRING_DIFFERS  21
#define BOOTENV_WMAX 22 /* highest warning value */


typedef struct bootenv *bootenv_t;
	/**< A bootenv library handle. */

typedef struct bootenv_list *bootenv_list_t;
	/**< A handle for a value list. */

typedef int(*pdd_func_t)(bootenv_t, bootenv_t, bootenv_t*,
		int*, char*, size_t);


/**
 * @brief Get a new handle.
 * @return 0
 * @return or error
 * */
int bootenv_create(bootenv_t *env);

/**
 * @brief	Cleanup structure.
 * @param env	Bootenv structure which shall be destroyed.
 * @return 0
 * @return or error
 */
int bootenv_destroy(bootenv_t *env);

/**
 * @brief Copy a bootenv handle.
 * @param in	The input bootenv.
 * @param out	The copied output bootenv. Discards old data.
 * @return 0
 * @return or error
 */
int bootenv_copy_bootenv(bootenv_t in, bootenv_t *out);

/**
 * @brief Looks for a value inside the bootenv data.
 * @param env Handle to a bootenv structure.
 * @param key The key.
 * @return NULL	 key not found
 * @return !NULL ptr to value
 */
int bootenv_get(bootenv_t env, const char *key, const char **value);


/**
 * @brief Looks for a value inside the bootenv data and converts it to num.
 * @param env Handle to a bootenv structure.
 * @param key The key.
 * @param value A pointer to the resulting numerical value
 * @return NULL	 key not found
 * @return !NULL ptr to value
 */
int bootenv_get_num(bootenv_t env, const char *key, uint32_t *value);

/**
 * @brief Set a bootenv value by key.
 * @param env   Handle to a bootenv structure.
 * @param key	Key.
 * @param value	Value to set.
 * @return 0
 * @return or error
 */
int bootenv_set(bootenv_t env, const char *key, const char *value);

/**
 * @brief Remove the given key (and its value) from a bootenv structure.
 * @param env	Handle to a bootenv structure.
 * @param key	Key.
 * @return 0
 * @return or error
 */
int bootenv_unset(bootenv_t env, const char *key);


/**
 * @brief Get a vector of all keys which are currently set
 *        within a bootenv handle.
 * @param env	Handle to a bootenv structure.
 * @param size	The size of the allocated array structure.
 * @param sort	Flag, if set the vector is sorted ascending.
 * @return NULL on error.
 * @return !NULL a pointer to the first element the allocated vector.
 * @warning Free the allocate memory yourself!
 */
int bootenv_get_key_vector(bootenv_t env, size_t *size, int sort,
				const char ***vector);

/**
 * @brief Calculate the size in bytes which are necessary to write the
 *        current bootenv section in a *binary file.
 * @param env	bootenv handle.
 * @param size  The size in bytes of the bootenv handle.
 * @return 0
 * @return or ERROR.
 */
int bootenv_size(bootenv_t env, size_t *size);

/**
 * @brief Read a binary bootenv file.
 * @param fp	File pointer to input stream.
 * @param env	bootenv handle.
 * @param size  maximum data size.
 * @return 0
 * @return or ERROR.
 */
int bootenv_read(FILE* fp, bootenv_t env, size_t size);

/**
 * @param ret_crc  return value of crc of read data
 */
int bootenv_read_crc(FILE* fp, bootenv_t env, size_t size, uint32_t *ret_crc);

/**
 * @brief Read bootenv data from an text/ascii file.
 * @param fp	File pointer to ascii PDD file.
 * @param env	bootenv handle
 * @return 0
 * @return or ERROR.
 */
int bootenv_read_txt(FILE* fp, bootenv_t env);

/**
 * @brief Write a bootenv structure to the given location (binary).
 * @param fp	Filepointer to binary file.
 * @param env	Bootenv structure which shall be written.
 * @return 0
 * @return or error
 */
int bootenv_write(FILE* fp, bootenv_t env);

/**
 * @param ret_crc  return value of crc of read data
 */
int bootenv_write_crc(FILE* fp, bootenv_t env, uint32_t* ret_crc);

/**
 * @brief Write a bootenv structure to the given location (text).
 * @param fp	Filepointer to text file.
 * @param env	Bootenv structure which shall be written.
 * @return 0
 * @return or error
 */
int bootenv_write_txt(FILE* fp, bootenv_t env);

/**
 * @brief Compare bootenvs using memcmp().
 * @param first	First bootenv.
 * @param second	Second bootenv.
 * @return 0 if bootenvs are equal
 * @return < 0 if error
 * @return > 0 if unequal
 */
int bootenv_compare(bootenv_t first, bootenv_t second);

/**
 * @brief Prototype for a PDD handling funtion
 */

/**
 * @brief The PDD keep operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of PDD keep.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_keep(bootenv_t env_old, bootenv_t env_new,
		bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);


/**
 * @brief The PDD merge operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of merge-pdd.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_merge(bootenv_t env_old, bootenv_t env_new,
		bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);

/**
 * @brief The PDD overwrite operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of overwrite-pdd.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_overwrite(bootenv_t env_new,
		bootenv_t env_old, bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);

/**
 * @brief Dump a bootenv structure to stdout. (Debug)
 * @param env	Handle to a bootenv structure.
 * @return 0
 * @return or error
 */
int bootenv_dump(bootenv_t env);

/**
 * @brief Validate a bootenv structure.
 * @param env Handle to a bootenv structure.
 * @return 0
 * @return or error
 */
int bootenv_valid(bootenv_t env);

/**
 * @brief Create a new bootenv list structure.
 * @return NULL on error
 * @return or a new list handle.
 * @note This structure is used to store values in a list.
 *       A useful addition when handling PDD strings.
 */
int bootenv_list_create(bootenv_list_t *list);

/**
 * @brief Destroy a bootenv list structure
 * @param list	Handle to a bootenv list structure.
 * @return 0
 * @return or error
 */
int bootenv_list_destroy(bootenv_list_t *list);

/**
 * @brief Import a list from a comma seperated string
 * @param list	Handle to a bootenv list structure.
 * @param str		Comma seperated string list.
 * @return 0
 * @return or error
 */
int bootenv_list_import(bootenv_list_t list, const char *str);

/**
 * @brief Export a list to a string of comma seperated values.
 * @param list	Handle to a bootenv list structure.
 * @return NULL one error
 * @return or pointer to a newly allocated string.
 * @warning Free the allocated memory by yourself!
 */
int bootenv_list_export(bootenv_list_t list, char **string);

/**
 * @brief Add an item to the list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 0
 * @return or error
 */
int bootenv_list_add(bootenv_list_t list, const char *item);

/**
 * @brief Remove an item from the list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 0
 * @return or error
 */
int bootenv_list_remove(bootenv_list_t list, const char *item);

/**
 * @brief Check if a given item is in a given list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 1 Item is in list.
 * @return 0 Item is not in list.
 */
int bootenv_list_is_in(bootenv_list_t list, const char *item);


/**
 * @brief Convert a list into a vector of all values inside the list.
 * @param list	Handle to a bootenv structure.
 * @param size	The size of the allocated vector structure.
 * @return 0
 * @return or error
 * @warning Free the allocate memory yourself!
 */
int bootenv_list_to_vector(bootenv_list_t list, size_t *size,
			   const char ***vector);

/**
 * @brief Convert a list into a vector of all values inside the list.
 * @param list	Handle to a bootenv structure.
 * @param size	The size of the allocated vector structure.
 * @return 0
 * @return or error
 * @warning Free the allocate memory yourself!
 */
int bootenv_list_to_num_vector(bootenv_list_t list, size_t *size,
					uint32_t **vector);

#ifdef __cplusplus
}
#endif
#endif /*__BOOTENV_H__ */