source: rtems/c/src/lib/libbsp/powerpc/shared/flash/flashPgmPvt.h @ 9b4422a2

4.11
Last change on this file since 9b4422a2 was 9b4422a2, checked in by Joel Sherrill <joel.sherrill@…>, on May 3, 2012 at 3:09:24 PM

Remove All CVS Id Strings Possible Using a Script

Script does what is expected and tries to do it as
smartly as possible.

+ remove occurrences of two blank comment lines

next to each other after Id string line removed.

+ remove entire comment blocks which only exited to

contain CVS Ids

+ If the processing left a blank line at the top of

a file, it was removed.

  • Property mode set to 100644
File size: 9.4 KB
Line 
1#ifndef FLASH_GLUE_INTERFACE_H
2#define FLASH_GLUE_INTERFACE_H
3
4
5/* Trivial flash programmer (for restrictions see below)     */
6
7/* Author: Till Straumann <strauman@slac.stanford.edu>, 2006 */
8
9/* DO NOT INCLUDE THIS HEADER FROM APPLICATION CODE          */
10
11/*
12 * Glue interface -- to be used only internally by BSP
13 * and chip drivers:
14 * - BSP provides info about what chip drivers to use
15 *   as well as 'wiring' info (how many devices are
16 *   operated in parallel etc).
17 * - Chip drivers provide low-level 'methods' / 'ops'
18 *   for performing basic operations which are used
19 *   by the code in 'flash.c'.
20 */
21
22/* To keep things simple, this API makes a few assumptions about the
23 * hardware:
24 *
25 * - devices operate with 16-bit data width
26 * - two devices are used in parallel (stride 4) to
27 *   provide 32-bit data. I.e., the devices are
28 *   organized like this:
29 *   unsigned short flash[FLASH_SIZE][2];
30 * - no endianness issues (i.e., flash endianness ==  CPU endianness)
31 * - fixed block size
32 * - fixed buffer size
33 * - all devices in a bank are identical
34 * - NOT THREAD SAFE; no locking scheme is implemented.
35 * - cannot copy within same flash bank.
36 * - write-timeout uses polling/busy-wait
37 *
38 * FIXME: code should be revised to remove assumptions on stride and 16-bit
39 *        width to make it more generic.
40 */
41
42/*
43 * Authorship
44 * ----------
45 * This software was created by
46 *     Till Straumann <strauman@slac.stanford.edu>, 2005-2007,
47 *         Stanford Linear Accelerator Center, Stanford University.
48 *
49 * Acknowledgement of sponsorship
50 * ------------------------------
51 * The software was produced by
52 *     the Stanford Linear Accelerator Center, Stanford University,
53 *         under Contract DE-AC03-76SFO0515 with the Department of Energy.
54 *
55 * Government disclaimer of liability
56 * ----------------------------------
57 * Neither the United States nor the United States Department of Energy,
58 * nor any of their employees, makes any warranty, express or implied, or
59 * assumes any legal liability or responsibility for the accuracy,
60 * completeness, or usefulness of any data, apparatus, product, or process
61 * disclosed, or represents that its use would not infringe privately owned
62 * rights.
63 *
64 * Stanford disclaimer of liability
65 * --------------------------------
66 * Stanford University makes no representations or warranties, express or
67 * implied, nor assumes any liability for the use of this software.
68 *
69 * Stanford disclaimer of copyright
70 * --------------------------------
71 * Stanford University, owner of the copyright, hereby disclaims its
72 * copyright and all other rights in this software.  Hence, anyone may
73 * freely use it for any purpose without restriction.
74 *
75 * Maintenance of notices
76 * ----------------------
77 * In the interest of clarity regarding the origin and status of this
78 * SLAC software, this and all the preceding Stanford University notices
79 * are to remain affixed to any copy or derivative of this software made
80 * or distributed by the recipient and are to be affixed to any copy of
81 * software made or distributed by the recipient that contains a copy or
82 * derivative of this software.
83 *
84 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
85 */
86
87#include <stdint.h>
88
89#define NumberOf(arr)           (sizeof(arr)/sizeof(arr[0]))
90
91#define FLASH_STRIDE(b)     4 /* bytes; currently fixed */
92#define FLASH_WIDTH(b)      ((b)->width)
93#define FLASH_NDEVS(b)      (FLASH_STRIDE(b)/FLASH_WIDTH(b))
94
95/* Type declarations */
96
97/* Registers          */
98typedef uint8_t           _u8_a_t  __attribute__((may_alias));
99typedef uint16_t          _u16_a_t __attribute__((may_alias));
100typedef uint32_t          _u32_a_t __attribute__((may_alias));
101
102/* Register addresses */
103typedef volatile _u8_a_t  *A8;
104typedef volatile _u16_a_t *A16;
105typedef volatile _u32_a_t *A32;
106
107struct flash_bank_ops;
108
109/*
110 * Description of a flash bank. Multiple
111 * devices that are used in parallel to
112 * make up words of FLASH_STRIDE bytes
113 * are a 'physical' bank.
114 *
115 * A bank can even be a 'logical' bank
116 * if it includes chip-select logic, i.e.,
117 * int can contain multiple adjacent
118 * 'physical' banks
119 *
120 * The BSP must provide an array of 'bankdesc'
121 * structs and it must initialize the fields
122 *
123 *   'start'
124 *     size of bank; may be set to zero to instruct
125 *     the driver to scan a bank of 'max_size' for
126 *     devices (i.e., bank may not be fully populated)
127 *   'max_size'
128 *     size of fully populated bank (defines address range
129 *     that is scanned for devices).
130 *     If 'max_size' is negative then scanning starts from
131 *     the top rather than from the bottom.
132 *   'width'
133 *     width of a single device (in bytes). E.g., if
134 *     2 16-bit devices are used to form a (ATM fixed)
135 *     stride of 4 then 'width = 2'. If four 8-bit
136 *     devices are employed then 'width=1'.
137 *   'knownVendors'
138 *     array of vendors descriptions to use for scanning
139 *     the bank.
140 *
141 */
142struct bankdesc {
143        uint32_t        start;          /* start of bank (CPU address)              */
144        uint32_t        size;           /* in bytes (figured out automatically)     */
145        int                     max_size;       /* in case multiple banks are adjacent;
146                                 * if max_size < 0 then the bank is scanned
147                                                         * backwards (from top->bottom) for devices
148                                                         */
149        int         width;      /* FIXME there might be implicit assumptions still
150                                 * that width == 2
151                                                         */
152        struct vendesc        *knownVendors;
153        /* TODO: we assume identical devices within a bank... */
154
155        /* The next three variables cache information obtained
156         * from the applicable vendor and device descriptions.
157         * They are written by BSP_flashCheckId().
158         */
159        uint32_t        fblksz;     /* block size in bytes; includes counting
160                                 * parallel 16-bit devices, i.e., if a
161                                                         * single device has a block-size of xxx
162                                                         * then fblksz = xxx*ndevs.
163                                                         */
164        struct devdesc        *dd;
165        struct flash_bank_ops *ops;
166};
167
168struct devdesc {
169        uint32_t        id;     /* numerical ID (matched against
170                             * ID read from device).
171                                                 */
172        char            *name;  /* informational name           */
173        uint32_t        size;   /* bytes                        */
174        uint32_t        bufsz;  /* size of write buffer (bytes) */
175        uint32_t        fblksz; /* sector/block size (bytes)    */
176};
177
178struct vendesc {
179        uint32_t        id;     /* numerical ID (matched against
180                             * ID read from device).
181                                                 */
182        char            *name;  /* informational name */
183
184                            /* array of supported devices;
185                                                 * the 'ops' specified below
186                                                 * are used to access these devices
187                                                 */
188        struct devdesc        *known_devs;
189                                                /* access methods for talking to
190                                                 * devices associated with this
191                                                 * vendor description.
192                                                 */
193        struct flash_bank_ops *ops;
194};
195
196/* Device Access Methods ('ops'); these must be
197 * implemented by low-level chip drivers
198 */
199
200struct flash_bank_ops {
201/* Read vendor/device ID; Return 0 on success, nonzero if unable to read id */
202        int            (*get_id)(struct bankdesc *b, uint32_t addr, uint32_t *pVendorId, uint32_t *pDeviceId);
203/* Unlock block holding 'addr'ess
204 *
205 *   NOTES: - device switched back to array mode on exit.
206 *          - 'addr' must be 32-bit aligned.
207 */
208
209        void           (*unlock_block)(struct bankdesc *b, uint32_t addr);
210/* Lock block holding 'addr'ess
211 *
212 *   NOTES: - device switched back to array mode on exit.
213 *          - 'addr' must be 32-bit aligned.
214 */
215
216        void           (*lock_block)(struct bankdesc *b, uint32_t addr);
217/* Erase single block holding 'addr'ess. The routine may
218 * assume that the address is block/sector aligned.
219 *
220 * RETURNS: zero on error, device status on failure.
221 *
222 *   NOTES: - device switched back to array mode on exit.
223 *          - 'addr' must be 32-bit aligned.
224 */
225        int            (*erase_block)(struct bankdesc *b, uint32_t addr);
226/* Query the status of the device and assert it's readiness
227 * leave off in array-reading mode.
228 *
229 * RETURNS: 0 on success, error status (result of status query) on error.
230 *
231 *   NOTES: - error message is printed to stderr.
232 *          - device switched back to array mode on exit.
233 *          - 'addr' must be 32-bit aligned.
234 */
235        uint32_t       (*check_ready)(struct bankdesc *b, uint32_t addr);
236/* Dump status bits (F_CMD_RD_STA results);
237 * 'verbose' prints non-error bits, too
238 */
239        void           (*print_stat)(struct bankdesc *b, uint32_t sta, int verbose);
240/* Switch to array mode; 'addr' can be assumed to be stride-aligned */
241        void           (*array_mode)(struct bankdesc *b, uint32_t addr);
242/* Write N bytes from 'src' to flash:
243 * 'src[0] .. src[N-1]' -> addr[0]..addr[N-1].
244 * N may be assumed to be a multiple of 'stride'
245 * RETURNS: failure status or zero on success.
246 */
247        uint32_t       (*write_line)(struct bankdesc *b, uint32_t addr, char *src, uint32_t N);
248};
249
250/* BSP ops (detect banks, handle write-protection on board);
251 * these must be implemented by the BSP.
252 */
253
254struct flash_bsp_ops {
255/* Return descriptor for bank # 'bank' or NULL (invalid arg) */
256        struct bankdesc *(*bankcheck)(int bank, int quiet);
257/* set (enbl:1), clear (enbl:0) or query (enbl:-1)
258 * on-board write protection.
259 *
260 * RETURNS 0 on success, nonzero on error.
261 */
262        int              (*flash_wp)(int bank, int enbl);
263/* read a running us clock (for polling timeout) */
264        uint32_t         (*read_us_timer)();
265};
266
267/* This must be provided by the BSP */
268extern struct flash_bsp_ops BSP_flashBspOps;
269
270/* Available low-level flash drivers, so far */
271extern struct vendesc        BSP_flash_vendor_intel[];
272extern struct vendesc        BSP_flash_vendor_spansion[];
273
274#endif
Note: See TracBrowser for help on using the repository browser.