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
|
#ifndef __pfi_h
#define __pfi_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.
*/
/**
* @file pfi.h
*
* @author Oliver Lohmann <oliloh@de.ibm.com>
* Andreas Arnez <arnez@de.ibm.com>
* Joern Engel <engeljoe@de.ibm.com>
* Frank Haverkamp <haverkam@de.ibm.com>
*
* @brief libpfi will hold all code to create and process pfi
* images. Definitions made in this file are equaly usable for the
* development host and the target system.
*
* @note This header additionally holds the official definitions for
* the pfi headers.
*/
#include <stdio.h> /* FILE */
#ifdef __cplusplus
extern "C" {
#endif
/* Definitions. */
#define PFI_HDRVERSION 1 /* current header version */
#define PFI_ENOVERSION 1 /* unknown version */
#define PFI_ENOHEADER 2 /* not a pfi header */
#define PFI_EINSUFF 3 /* insufficient information */
#define PFI_EUNDEF 4 /* key not defined */
#define PFI_ENOMEM 5 /* out of memory */
#define PFI_EBADTYPE 6 /* bad data type */
#define PFI_EFILE 7 /* file I/O error: see errno */
#define PFI_EFILEINVAL 8 /* file format not valid */
#define PFI_EINVAL 9 /* invalid parameter */
#define PFI_ERANGE 10 /* invalid range */
#define PFI_EMODE 11 /* expecting other mode in this header */
#define PFI_DATA_START 12 /* data section starts */
#define PFI_EMAX 13 /* should be always larger as the largest
error code */
#define PFI_LABEL_LEN 64 /* This is the maximum length for a
PFI header label */
#define PFI_KEYWORD_LEN 32 /* This is the maximum length for an
entry in the mode and type fields */
#define PFI_UBI_MAX_VOLUMES 128
#define PFI_UBI_VOL_NAME_LEN 127
/**
* @brief The pfi header allows to set flags which influence the flashing
* behaviour.
*/
#define PFI_FLAG_PROTECTED 0x00000001
/**
* @brief Handle to pfi header. Used in most of the functions associated
* with pfi file handling.
*/
typedef struct pfi_header *pfi_header;
/**
* @brief Initialize a pfi header object.
*
* @param head Pointer to handle. This function allocates memory
* for this data structure.
* @return 0 on success, otherwise:
* PFI_ENOMEM : no memory available for the handle.
*/
int pfi_header_init (pfi_header *head);
/**
* @brief Destroy a pfi header object.
*
* @param head handle. head is invalid after calling this function.
* @return 0 always.
*/
int pfi_header_destroy (pfi_header *head);
/**
* @brief Add a key/value pair to a pfi header object.
*
* @param head handle.
* @param key pointer to key string. Must be 0 terminated.
* @param value pointer to value string. Must be 0 terminated.
* @return 0 on success, otherwise:
* PFI_EUNDEF : key was not found.
* PFI_ENOMEM : no memory available for the handle.
* PFI_EBADTYPE : value is not an hex string. This happens
* when the key stores an integer and the
* new value is not convertable e.g. not in
* 0xXXXXXXXX format.
*/
int pfi_header_setvalue (pfi_header head,
const char *key, const char *value);
/**
* @brief Add a key/value pair to a pfi header object. Provide the
* value as a number.
*
* @param head handle.
* @param key pointer to key string. Must be 0 terminated.
* @param value value to set.
* @return 0 on success, otherwise:
* PFI_EUNDEF : key was not found.
* PFI_EBADTYPE : value is not a string. This happens
* when the key stores a string.
*/
int pfi_header_setnumber (pfi_header head,
const char *key, uint32_t value);
/**
* @brief For a given key, return the numerical value stored in a
* pfi header object.
*
* @param head handle.
* @param key pointer to key string. Must be 0 terminated.
* @param value pointer to value.
* @return 0 on success, otherwise:
* PFI_EUNDEF : key was not found.
* PFI_EBADTYPE : stored value is not an integer but a string.
*/
int pfi_header_getnumber (pfi_header head,
const char *key, uint32_t *value);
static inline uint32_t
pfi_getnumber(pfi_header head, const char *key)
{
uint32_t value;
pfi_header_getnumber(head, key, &value);
return value;
}
/**
* @brief For a given key, return the string value stored in a pfi
* header object.
*
* @param head handle.
* @param key pointer to key string. Must be 0 terminated.
* @param value pointer to value string. Memory must be allocated by the user.
* @return 0 on success, otherwise:
* PFI_EUNDEF : key was not found.
* PFI_EBADTYPE : stored value is not a string but an integer.
*/
int pfi_header_getstring (pfi_header head,
const char *key, char *value, size_t size);
/**
* @brief Write a pfi header object into a given file.
*
* @param out output stream.
* @param head handle.
* @return 0 on success, error values otherwise:
* PFI_EINSUFF : not all mandatory fields are filled.
* PFI_ENOHEADER : wrong header version or magic number.
* -E* : see <asm/errno.h>.
*/
int pfi_header_write (FILE *out, pfi_header head);
/**
* @brief Read a pfi header object from a given file.
*
* @param in input stream.
* @param head handle.
* @return 0 on success, error values otherwise:
* PFI_ENOVERSION: unknown header version.
* PFI_EFILE : cannot read enough data.
* PFI_ENOHEADER : wrong header version or magic number.
* -E* : see <asm/errno.h>.
*
* If the header verification returned success the user can assume that
* all mandatory fields for a particular version are accessible. Checking
* the return code when calling the get-function for those keys is not
* required in those cases. For optional fields the checking must still be
* done.
*/
int pfi_header_read (FILE *in, pfi_header head);
/**
* @brief Display a pfi header in human-readable form.
*
* @param out output stream.
* @param head handle.
* @return always 0.
*
* @note Prints out that it is not implemented and whom you should
* contact if you need it urgently!.
*/
int pfi_header_dump (FILE *out, pfi_header head);
/*
* @brief Iterates over a stream of pfi files. The iterator function
* must advance the file pointer in FILE *in to the next pfi
* header. Function exists on feof(in).
*
* @param in input file descriptor, must be open and valid.
* @param func iterator function called when pfi header could be
* read and was validated. The function must return 0 on
* success.
* @return See pfi_header_init and pfi_header_read.
* PFI_EINVAL : func is not valid
* 0 ok.
*/
typedef int (* pfi_read_func)(FILE *in, pfi_header hdr, void *priv_data);
int pfi_read (FILE *in, pfi_read_func func, void *priv_data);
#ifdef __cplusplus
}
#endif
#endif /* __pfi_h */
|
