RTEMS
6.1-rc2
Loading...
Searching...
No Matches
bsps
powerpc
include
bsp
flashPgm.h
1
#ifndef BSP_FLASH_PGM_API_H
2
#define BSP_FLASH_PGM_API_H
3
4
/* Trivial Flash Programmer */
5
6
/* Author: Till Straumann <strauman@slac.stanford.edu>, 2006
7
* NOTE: copyright info at the bottom of this file
8
*/
9
10
/* IMPORTANT NOTE
11
*
12
* The flash API is NOT THREAD SAFE. During the execution of any of the
13
* BSP_flashXXX() routines, flash (residing in the same device)
14
* MUST NOT be accessed by other threads in ANY way (NOT EVEN READ!).
15
* Read operations may return internal device register contents
16
* instead of memory array data when issued while a flash device
17
* is erased, written or queried by the library.
18
*
19
* The routines are intended for occasional maintenance use only
20
* (i.e., not for implementing a file system or similar).
21
*
22
* While polling for the completion of block erase operations the
23
* CPU is yielded to other threads. Busy waiting (interrupts and
24
* thread dispatching remain enabled) on write operations is employed.
25
*/
26
27
#include <stdio.h>
28
29
#ifdef __cplusplus
30
extern
"C"
{
31
#endif
32
33
/* Disengage flash write protection. Write protection is implemented
34
* at the board or chipset level by disabling all write operations/bus cycles
35
* to the flash device(s).
36
* With write protection enabled, nothing but 'ordinary' (array) read operations
37
* are possible.
38
* Write protection must be disabled not only to erase and write contents
39
* but also in order to read ID, size, status etc.
40
* None of the operations (except for BSP_flashWriteEnable()) are possible
41
* on a write-protected device.
42
*
43
* 'bank': flash bank # (usually 0)
44
* RETURNS: 0 on success, nonzero on error (printing message to stderr).
45
*
46
* NOTES: - some boards (MVME5500) don't support 'bank' granularity but
47
* enable/disable write protection for all devices at once.
48
* - a jumper-based protection mechanism might be in place
49
* in addition to the software-based one. Consult the user's
50
* manual of your board for more information.
51
*/
52
int
53
BSP_flashWriteEnable(
int
bank);
54
55
/* Engage flash write protection (see above)
56
*/
57
int
58
BSP_flashWriteDisable(
int
bank);
59
60
/* Erase a region of flash memory.
61
* 'bank': flash bank # (usually 0).
62
* 'offset': destination address offset (from start of bank).
63
* 'size': number of bytes to erase.
64
* 'quiet': if non-zero, suppress confirmation message / prompt
65
* if > 1 also suppress the progress indicator.
66
*
67
* RETURNS: 0 on success, nonzero on error (printing messages to stderr).
68
*
69
* NOTES: - 'offset' and 'size' must be block-aligned. Common 16-bit devices
70
* have a block size of 0x20000 bytes. If two such devices are
71
* operated in parallel to form a 32-bit word then the 'effective'
72
* block size is 0x40000 bytes. The block size can be queried by
73
* BSP_flashBlockSize(int bank);
74
*
75
* - erase operation is verified.
76
*/
77
int
78
BSP_flashErase(
int
bank, uint32_t offset, uint32_t size,
int
quiet);
79
80
/* Write data from a buffer to flash. The target area is erased if necessary.
81
*
82
* 'bank': flash bank # (usually 0).
83
* 'offset': destination address offset (from start of bank).
84
* 'src': data source block address (in memory).
85
*'n_bytes': number of bytes to copy.
86
* 'quiet': if non-zero, suppress confirmation message / prompt
87
* if > 1 also suppress the progress indicator.
88
*
89
* NOTES: - Erase operations are only performed where necessary. I.e.,
90
* if one or both of the boundaries of the destination region is/are
91
* not block-aligned then adjacent data are preserved provided that
92
* the relevant chunks of the destination are blank (erased).
93
*
94
* | <neighbour> fffffff |
95
* ^--- destination ----- ^
96
* | : block boundary
97
* f : blank/erased pieces
98
*
99
* (If the start of the destination region up to the next block boundary
100
* is blank then '<neighbour>'-data is preserved. The end of the
101
* destination is treated the same way.)
102
*
103
* - user confirmation is requested before changes are made
104
*
105
* - 'src' must not point into the destination bank (no copy
106
* within a flash bank).
107
*
108
* - erase and write operations are verified.
109
*
110
* RETURNS: 0 on success, nonzero on error (message printed to stderr).
111
*/
112
int
113
BSP_flashWrite(
int
bank, uint32_t offset,
const
char
*src, uint32_t n_bytes,
int
quiet);
114
115
/* Copy contents of a file to flash.
116
*
117
* 'fname': Path of a file.
118
* 'quiet': if non-zero, suppress confirmation message / prompt
119
* if > 1 also suppress the progress indicator.
120
*
121
* NOTES: Convenience wrapper around BSP_flashWrite(); see above for
122
* args and return value.
123
*/
124
int
125
BSP_flashWriteFile(
int
bank, uint32_t offset,
const
char
*path,
int
quiet);
126
127
/* Dump info about available flash to file
128
* (stdout is used if f==NULL).
129
*
130
* RETURNS: 0
131
* NOTES: Write protection must be disengaged (see above);
132
*/
133
int
134
BSP_flashDumpInfo(FILE *f);
135
136
/*
137
* Obtain starting-address of flash bank (as seen from CPU)
138
* (returns ((uint32_t) -1) if the bank argument is invalid).
139
*/
140
141
uint32_t
142
BSP_flashStart(
int
bank);
143
144
/*
145
* Obtain size of flash bank (returns ((uint32_t) -1) if the
146
* bank argument is invalid).
147
*/
148
uint32_t
149
BSP_flashSize(
int
bank);
150
151
/*
152
* Obtain block size of flash bank (sector size times
153
* number of devices in parallel; the block size determines
154
* alignment and granularity accepted by BSP_flashErase()
155
* (returns ((uint32_t) -1) if the bank argument is invalid).
156
*/
157
uint32_t
158
BSP_flashBlockSize(
int
bank);
159
160
#ifdef __cplusplus
161
}
162
#endif
163
164
/*
165
* Authorship
166
* ----------
167
* This software was created by
168
* Till Straumann <strauman@slac.stanford.edu>, 2005-2007,
169
* Stanford Linear Accelerator Center, Stanford University.
170
*
171
* Acknowledgement of sponsorship
172
* ------------------------------
173
* The software was produced by
174
* the Stanford Linear Accelerator Center, Stanford University,
175
* under Contract DE-AC03-76SFO0515 with the Department of Energy.
176
*
177
* Government disclaimer of liability
178
* ----------------------------------
179
* Neither the United States nor the United States Department of Energy,
180
* nor any of their employees, makes any warranty, express or implied, or
181
* assumes any legal liability or responsibility for the accuracy,
182
* completeness, or usefulness of any data, apparatus, product, or process
183
* disclosed, or represents that its use would not infringe privately owned
184
* rights.
185
*
186
* Stanford disclaimer of liability
187
* --------------------------------
188
* Stanford University makes no representations or warranties, express or
189
* implied, nor assumes any liability for the use of this software.
190
*
191
* Stanford disclaimer of copyright
192
* --------------------------------
193
* Stanford University, owner of the copyright, hereby disclaims its
194
* copyright and all other rights in this software. Hence, anyone may
195
* freely use it for any purpose without restriction.
196
*
197
* Maintenance of notices
198
* ----------------------
199
* In the interest of clarity regarding the origin and status of this
200
* SLAC software, this and all the preceding Stanford University notices
201
* are to remain affixed to any copy or derivative of this software made
202
* or distributed by the recipient and are to be affixed to any copy of
203
* software made or distributed by the recipient that contains a copy or
204
* derivative of this software.
205
*
206
* ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
207
*/
208
209
#endif
Generated by
1.9.6