diff options
author | Aidan MacDonald <amachronic@protonmail.com> | 2021-11-23 20:13:52 +0000 |
---|---|---|
committer | Aidan MacDonald <amachronic@protonmail.com> | 2021-11-27 15:28:19 -0500 |
commit | 06423cab58569ef01eb526e5f0d2f5c0c8917aa0 (patch) | |
tree | b1a356600f6f218de8d8d1ad1e839aff65c96a0f /lib/x1000-installer/include/xf_nandio.h | |
parent | 98f1271aec1fd461ab20a1ae145bba630a5750fb (diff) | |
download | rockbox-06423cab58569ef01eb526e5f0d2f5c0c8917aa0.tar.gz rockbox-06423cab58569ef01eb526e5f0d2f5c0c8917aa0.zip |
x1000-installer: Initial commit of new framework
This is a new flash installer framework for the X1000 targets.
A bunch of this code is *UNTESTED* but there is an external test
harness which allows the library to be built and tested on a PC.
Once tests are written and the bugs are ironed out this framework
will replace the existing installer code.
New features:
- Update tarballs are MD5-checksummed to guarantee integrity.
- The flash map is no longer fixed -- updates are self describing and
carry a map file which specifies the areas to update.
- Can take full or partial backups with checksums computed on the fly.
- Supports an additional verification mode which reads back data after
writing to ensure the flash contents were not silently corrupted.
Change-Id: I29a89190c7ff566019f6a844ad0571f01fb7192f
Diffstat (limited to 'lib/x1000-installer/include/xf_nandio.h')
-rw-r--r-- | lib/x1000-installer/include/xf_nandio.h | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/lib/x1000-installer/include/xf_nandio.h b/lib/x1000-installer/include/xf_nandio.h new file mode 100644 index 0000000000..a10b71992c --- /dev/null +++ b/lib/x1000-installer/include/xf_nandio.h | |||
@@ -0,0 +1,130 @@ | |||
1 | /*************************************************************************** | ||
2 | * __________ __ ___. | ||
3 | * Open \______ \ ____ ____ | | _\_ |__ _______ ___ | ||
4 | * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / | ||
5 | * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < | ||
6 | * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ | ||
7 | * \/ \/ \/ \/ \/ | ||
8 | * $Id$ | ||
9 | * | ||
10 | * Copyright (C) 2021 Aidan MacDonald | ||
11 | * | ||
12 | * This program is free software; you can redistribute it and/or | ||
13 | * modify it under the terms of the GNU General Public License | ||
14 | * as published by the Free Software Foundation; either version 2 | ||
15 | * of the License, or (at your option) any later version. | ||
16 | * | ||
17 | * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY | ||
18 | * KIND, either express or implied. | ||
19 | * | ||
20 | ****************************************************************************/ | ||
21 | |||
22 | #ifndef _XF_NANDIO_H_ | ||
23 | #define _XF_NANDIO_H_ | ||
24 | |||
25 | #include "nand-x1000.h" | ||
26 | #include <stdint.h> | ||
27 | #include <stddef.h> | ||
28 | |||
29 | enum xf_nandio_mode { | ||
30 | XF_NANDIO_READ = 0, | ||
31 | XF_NANDIO_PROGRAM, | ||
32 | XF_NANDIO_VERIFY, | ||
33 | }; | ||
34 | |||
35 | struct xf_nandio { | ||
36 | nand_drv* ndrv; | ||
37 | int nand_err; /* copy of the last NAND error code */ | ||
38 | int alloc_handle; | ||
39 | enum xf_nandio_mode mode; | ||
40 | |||
41 | size_t block_size; /* size of a block, in bytes */ | ||
42 | size_t page_size; /* size of a page, in bytes */ | ||
43 | |||
44 | uint8_t* old_buf; /* contains the 'old' block data already on chip */ | ||
45 | uint8_t* new_buf; /* contains the possibly modified 'new' block data */ | ||
46 | |||
47 | nand_block_t cur_block; /* address of the current block */ | ||
48 | size_t offset_in_block; /* byte offset in the current block */ | ||
49 | unsigned block_valid: 1; /* 1 if buffered block data is valid */ | ||
50 | }; | ||
51 | |||
52 | int xf_nandio_init(struct xf_nandio* nio); | ||
53 | void xf_nandio_destroy(struct xf_nandio* nio); | ||
54 | |||
55 | /** Sets the operational mode, which determines read/write/flush semantics. | ||
56 | * | ||
57 | * - XF_NANDIO_READ: Accesses the chip in read-only mode. Writes are allowed, | ||
58 | * but should not be used. (Writes will modify a temporary buffer but this | ||
59 | * will not alter the flash contents.) | ||
60 | * | ||
61 | * - XF_NANDIO_PROGRAM: Writes are allowed to modify the flash contents. | ||
62 | * Writes within a block are accumulated in a temporary buffer. When | ||
63 | * crossing a block boundary, either by writing past the end the current | ||
64 | * block or by seeking to a new one, the data written to the temporary | ||
65 | * buffer is compared against the current flash contents. If the block | ||
66 | * has been modified, it is erased and any non-blank pages are programmed | ||
67 | * with the new data. | ||
68 | * | ||
69 | * - XF_NANDIO_VERIFY: This mode allows callers to easily check whether the | ||
70 | * flash contents match some expected contents. Callers "write" the expected | ||
71 | * contents as if programming it with XF_NANDIO_PROGRAM. When a block is | ||
72 | * flushed, if the written data doesn't match the block contents, an | ||
73 | * XF_E_VERIFY_FAILED error is returned. The flash contents will not be | ||
74 | * altered in this mode. | ||
75 | * | ||
76 | * \returns XF_E_SUCCESS or a negative error code on failure. | ||
77 | */ | ||
78 | int xf_nandio_set_mode(struct xf_nandio* nio, enum xf_nandio_mode mode); | ||
79 | |||
80 | /** Seek to a given byte offset in the NAND flash. | ||
81 | * | ||
82 | * If the new offset is outside the current block, the current block will | ||
83 | * be automatically flushed. Note this can result in verification or program | ||
84 | * failures as with any other flush. | ||
85 | * | ||
86 | * \returns XF_E_SUCCESS or a negative error code on failure. | ||
87 | */ | ||
88 | int xf_nandio_seek(struct xf_nandio* nio, size_t offset); | ||
89 | |||
90 | /** Read or write a contiguous sequence of bytes from flash. | ||
91 | * | ||
92 | * The read or write starts at the current position and continues for `count` | ||
93 | * bytes. Both reads and writes may cross block boundaries. Modified blocks | ||
94 | * will be flushed automatically if the operation crosses a block boundary. | ||
95 | * | ||
96 | * After a successful read or write, the current position is advanced by | ||
97 | * exactly `count` bytes. After a failure, the position is indeterminate. | ||
98 | * | ||
99 | * \returns XF_E_SUCCESS or a negative error code on failure. | ||
100 | */ | ||
101 | int xf_nandio_read(struct xf_nandio* nio, void* buf, size_t count); | ||
102 | int xf_nandio_write(struct xf_nandio* nio, const void* buf, size_t count); | ||
103 | |||
104 | /** Get a pointer to the block buffer for direct read/write access. | ||
105 | * | ||
106 | * These functions can be used to read or write data without intermediate | ||
107 | * buffers. The caller passes in the amount of data to be transferred in | ||
108 | * `*count`. A pointer to part of the block buffer is returned in `*buf` | ||
109 | * and the number of bytes available in `*buf` is returned in `*count`. | ||
110 | * | ||
111 | * Data at the current position can be read from the returned buffer and | ||
112 | * it may be modified by writing to the buffer. The buffer is only valid | ||
113 | * until the next call to an `xf_nandio` function. | ||
114 | * | ||
115 | * The read/write position is advanced by the returned `*count` on success, | ||
116 | * and is unchanged on failure. | ||
117 | * | ||
118 | * \returns XF_E_SUCCESS or a negative error code on failure. | ||
119 | */ | ||
120 | int xf_nandio_get_buffer(struct xf_nandio* nio, void** buf, size_t* count); | ||
121 | |||
122 | /** Flush the buffered block to ensure all outstanding program or verification | ||
123 | * operations have been performed. This should only be called to ensure the | ||
124 | * final modified block is flushed after you have finished writing all data. | ||
125 | * | ||
126 | * \returns XF_E_SUCCESS or a negative error code on failure. | ||
127 | */ | ||
128 | int xf_nandio_flush(struct xf_nandio* nio); | ||
129 | |||
130 | #endif /* _XF_NANDIO_H_ */ | ||