4 * This file is part of BeRTOS.
6 * Bertos is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 * As a special exception, you may use this file as part of a free software
21 * library without restriction. Specifically, if other files instantiate
22 * templates or use macros or inline functions from this file, or you compile
23 * this file and link it with other files to produce an executable, this
24 * file does not by itself cause the resulting executable to be covered by
25 * the GNU General Public License. This exception does not however
26 * invalidate any other reasons why the executable file might be covered by
27 * the GNU General Public License.
29 * Copyright 2009 Develer S.r.l. (http://www.develer.com/)
33 * \author Francesco Sacchi <batt@develer.com>
35 * \brief KBlock interface
41 #include <cfg/compiler.h>
42 #include <cfg/debug.h>
43 #include <cfg/macros.h>
45 /** Type for addressing blocks in the device. */
46 typedef uint32_t block_idx_t;
52 * \name Prototypes for KBlock access functions.
54 * A KBlock user can choose which function subset to implement,
55 * but has to set to NULL unimplemented features.
59 typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size);
60 typedef size_t (* kblock_read_t) (struct KBlock *b, void *buf, size_t offset, size_t size);
61 typedef size_t (* kblock_write_t) (struct KBlock *b, const void *buf, size_t offset, size_t size);
62 typedef int (* kblock_load_t) (struct KBlock *b, block_idx_t index);
63 typedef int (* kblock_store_t) (struct KBlock *b, block_idx_t index);
65 typedef int (* kblock_write_block_t) (struct KBlock *b, block_idx_t index, const void *buf);
66 typedef int (* kblock_read_block_t) (struct KBlock *b, block_idx_t index, void *buf);
68 typedef int (* kblock_error_t) (struct KBlock *b);
69 typedef int (* kblock_clearerr_t) (struct KBlock *b);
70 typedef int (* kblock_close_t) (struct KBlock *b);
74 * Table of interface functions for a KBlock device.
76 typedef struct KBlockVTable
78 kblock_read_direct_t readDirect;
80 kblock_read_t readBuf;
81 kblock_write_t writeBuf;
85 kblock_read_block_t readBlock;
86 kblock_write_block_t writeBlock;
88 kblock_error_t error; ///< \sa kblock_error()
89 kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
91 kblock_close_t close; ///< \sa kblock_close()
95 #define KB_BUFFERED BV(0)
98 * KBlock private members.
99 * These are the private members of the KBlock class, please do not
100 * access these directly, use the KBlock API.
102 typedef struct KBlockPriv
104 DB(id_t type); ///< Used to keep track, at runtime, of the class type.
105 int flags; ///< Status and error flags.
107 block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
108 block_idx_t curr_blk;
111 const struct KBlockVTable *vt; ///< Virtual table of interface functions.
115 * KBlock: interface for a generic block device.
117 * A block device is a device which can only be read/written
118 * with data blocks of constant size: flash memories,
119 * SD cards, hard disks, etc...
121 * This interface is designed to adapt to most block devices and
122 * use peculiar features in order to save CPU time and memory space.
124 * You do not have to use this structure directly, specific implementations
125 * will be supplied in the peripheral drivers.
127 typedef struct KBlock
129 KBlockPriv priv; ///< Interface private data, do not use directly.
131 /* Public access members/methods */
132 size_t blk_size; ///< Block size.
133 block_idx_t blk_cnt; ///< Number of blocks available in the device.
138 * Use a subset of the blocks on the device.
140 * This function is useful for partitioning a device and use it for
141 * different purposes at the same time.
143 * This function will limit the number of blocks used on the device by setting
144 * a start index and a number of blocks to be used counting from that index.
146 * The blocks outside this range are no more accessible.
148 * Logical block indexes will be mapped to physical indexes inside this new
149 * range automatically. Even following calls to kblock_trim() will use logical
150 * indexes, so, once trimmed, access can only be limited further and never
155 * //...init KBlock device dev
156 * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
157 * kblock_load(dev, 0); // Load the physical block #200.
158 * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
161 * \param b KBlock device.
162 * \param start The index of the start block for the limiting window in logical addressing units.
163 * \param count The number of blocks to be used.
166 INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
168 ASSERT(start + count <= b->blk_cnt);
169 b->priv.blk_start += start;
174 #define KB_ASSERT_METHOD(b, method) \
178 ASSERT((b)->priv.vt); \
179 ASSERT((b)->priv.vt->method); \
185 * Get the current errors for the device.
187 * \note Calling this function will not clear the errors.
189 * \param b KBlock device.
191 * \return 0 if no error is present, a driver specific mask of errors otherwise.
193 * \sa kblock_clearerr()
195 INLINE int kblock_error(struct KBlock *b)
197 KB_ASSERT_METHOD(b, error);
198 return b->priv.vt->error(b);
202 * Clear the errors of the device.
204 * \param b KBlock device.
206 * \return 0 on success, EOF on errors.
210 INLINE int kblock_clearerr(struct KBlock *b)
212 KB_ASSERT_METHOD(b, clearerr);
213 return b->priv.vt->clearerr(b);
219 * \param b KBlock device.
221 * \return 0 on success, EOF on errors.
223 INLINE int kblock_close(struct KBlock *b)
225 KB_ASSERT_METHOD(b, close);
226 return b->priv.vt->close(b);
229 INLINE int kblock_writeBlock(struct KBlock *b, block_idx_t index, const void *buf)
231 KB_ASSERT_METHOD(b, writeBlock);
232 ASSERT(index < b->blk_cnt);
233 return b->priv.vt->writeBlock(b, b->priv.blk_start + index, buf);
236 INLINE int kblock_readBlock(struct KBlock *b, block_idx_t index, void *buf)
238 KB_ASSERT_METHOD(b, readDirect);
239 ASSERT(index < b->blk_cnt);
240 return b->priv.vt->readBlock(b, b->priv.blk_start + index, buf);
243 INLINE block_idx_t kblock_cachedBlock(struct KBlock *b)
245 return b->priv.curr_blk;
248 INLINE bool kblock_buffered(struct KBlock *b)
251 return (b->priv.flags & KB_BUFFERED);
254 size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, size_t size);
256 int kblock_flush(struct KBlock *b);
258 size_t kblock_write(struct KBlock *b, block_idx_t idx, const void *buf, size_t offset, size_t size);
260 int kblock_copy(struct KBlock *b, block_idx_t idx1, block_idx_t idx2);
263 int kblock_swWriteBlock(struct KBlock *b, block_idx_t index, const void *buf);
264 int kblock_swReadBlock(struct KBlock *b, block_idx_t index, void *buf);
266 size_t kblock_swReadDirect(struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size);
267 int kblock_swLoad(struct KBlock *b, block_idx_t index);
268 int kblock_swStore(struct KBlock *b, block_idx_t index);
269 size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size);
270 size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size);
272 #endif /* IO_KBLOCK_H */