summaryrefslogtreecommitdiff
path: root/lib/x1000-installer/include/xf_nandio.h
diff options
context:
space:
mode:
Diffstat (limited to 'lib/x1000-installer/include/xf_nandio.h')
-rw-r--r--lib/x1000-installer/include/xf_nandio.h130
1 files changed, 0 insertions, 130 deletions
diff --git a/lib/x1000-installer/include/xf_nandio.h b/lib/x1000-installer/include/xf_nandio.h
deleted file mode 100644
index a10b71992c..0000000000
--- a/lib/x1000-installer/include/xf_nandio.h
+++ /dev/null
@@ -1,130 +0,0 @@
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
29enum xf_nandio_mode {
30 XF_NANDIO_READ = 0,
31 XF_NANDIO_PROGRAM,
32 XF_NANDIO_VERIFY,
33};
34
35struct 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
52int xf_nandio_init(struct xf_nandio* nio);
53void 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 */
78int 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 */
88int 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 */
101int xf_nandio_read(struct xf_nandio* nio, void* buf, size_t count);
102int 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 */
120int 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 */
128int xf_nandio_flush(struct xf_nandio* nio);
129
130#endif /* _XF_NANDIO_H_ */