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>
44 /** Type for addressing blocks in the device. */
45 typedef uint32_t block_idx_t;
51 * \name Prototypes for KBlock access functions.
53 * A KBlock user can choose which function subset to implement,
54 * but has to set to NULL unimplemented features.
58 typedef size_t (* kblock_read_t) (struct KBlock *b, void *buf, size_t offset, size_t size);
59 typedef size_t (* kblock_write_t) (struct KBlock *b, const void *buf, size_t offset, size_t size);
60 typedef int (* kblock_load_t) (struct KBlock *b, block_idx_t index);
61 typedef int (* kblock_store_t) (struct KBlock *b, block_idx_t index);
62 typedef void * (* kblock_map_t) (struct KBlock *b, size_t offset, size_t size);
63 typedef int (* kblock_unmap_t) (struct KBlock *b, size_t offset, size_t size);
64 typedef int (* kblock_error_t) (struct KBlock *b);
65 typedef int (* kblock_clearerr_t)(struct KBlock *b);
66 typedef int (* kblock_close_t) (struct KBlock *b);
70 * Table of interface functions for a KBlock device.
72 typedef struct KBlockVTable
74 kblock_read_t readBuf; ///< \sa kblock_readBuf()
75 kblock_write_t writeBuf; ///< \sa kblock_writeBuf()
76 kblock_load_t load; ///< \sa kblock_load()
77 kblock_store_t store; ///< \sa kblock_store()
79 kblock_map_t map; ///< \sa kblock_map()
80 kblock_unmap_t unmap; ///< \sa kblock_unmap()
82 kblock_error_t error; ///< \sa kblock_error()
83 kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
85 kblock_close_t close; ///< \sa kblock_close()
90 * KBlock status and error codes.
92 typedef enum KBlockStatus
95 KBS_MAPPED, ///< Status: The current loaded block from the device is memory mapped.
98 KBS_ERR_ALREADY_MAPPED, ///< Error: trying to memory map a block already mapped.
99 KBS_ERR_NOT_MAPPED, ///< Error: trying to memory unmap a block not yet mapped.
100 KBS_ERR_MAP_NOT_AVAILABLE, ///< Error: mapping methods not implemented.
102 #define KBS_STATUS_MASK (BV(KBS_MAPPER) | 0 /* Add status flags here */)
104 #define KBS_ERROR_MASK (BV(KBS_ERR_ALREADY_MAPPED) | BV(KBS_ERR_ALREADY_MAPPED) \
105 | BV(KBS_ERR_MAP_NOT_AVAILABLE) | 0 /* Add error flags here */)
110 * KBlock private members.
111 * These are the private members of the KBlock class, please do not
112 * access these directly, use the KBlock API.
114 typedef struct KBlockPriv
116 DB(id_t type); ///< Used to keep track, at runtime, of the class type.
117 void *pagebuf; ///< Pointer to a buffer used as page buffer when memory mapping is active. \sa kblock_map(), kblock_unmap()
118 size_t pagebuf_size; ///< Size of the page buffer used for memory mapping. \sa kblock_map(), kblock_unmap()
119 KBlockStatus flags; ///< Status and error flags.
120 block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
121 DB(size_t map_off); ///< When mapping is active, this is the mapped data offset inside the block. \sa kblock_map(), kblock_unmap()
122 DB(size_t map_size); ///< When mapping is active, this is the mapped data size inside the block. \sa kblock_map(), kblock_unmap()
126 * KBlock: interface for a generic block device.
128 * A block device is a device which can only be read/written
129 * with data blocks of constant size: flash memories,
130 * SD cards, hard disks, etc...
132 * This interface is designed to adapt to most block devices and
133 * use peculiar features in order to save CPU time and memory space.
135 * You do not have to use this structure directly, specific implementations
136 * will be supplied in the peripheral drivers.
138 typedef struct KBlock
140 KBlockPriv priv; ///< Interface private data, do not use directly.
142 /* Public access members/methods */
143 size_t blk_size; ///< Block size.
144 block_idx_t blk_cnt; ///< Number of blocks available in the device.
145 struct KBlockVTable *vt; ///< Virtual table of interface functions.
150 * Add generic memory mapping functionality to a block device.
152 * If the device has an hardware page buffer mechanism, the map/unmap
153 * functions are unimplemented.
154 * If you need to use the mapping functions of such device, this function
155 * will add generic software mapping features wrapping the KBlock methods.
157 * \param dev the block device.
158 * \param buf the buffer to be used as page buffer for memory mapping functions.
159 * \param size the size of the buffer. This is the maximum size that can be
160 * memory mapped. If you want to map a full block, a size of at least
161 * dev->blk_size have to be supplied.
163 * \sa kblock_map(), kblock_unmap(), kblock_readBuf(), kblock_writeBuf()
165 void kblock_addMapping(struct KBlock *dev, void *buf, size_t size);
168 * Use a subset of the blocks on the device.
170 * This function is useful for partitioning a device and use it for
171 * different purposes at the same time.
173 * This function will limit the number of blocks used on the device by setting
174 * a start index and a number of blocks to be used counting from that index.
176 * The blocks outside this range are no more accessible.
178 * Logical block indexes will be mapped to physical indexes inside this new
179 * range automatically. Even following calls to kblock_trim() will use logical
180 * indexes, so, once trimmed, access can only be limited further and never
185 * //...init KBlock device dev
186 * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
187 * kblock_load(dev, 0); // Load the physical block #200.
188 * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
191 * \param b KBlock device.
192 * \param start The index of the start block for the limiting window in logical addressing units.
193 * \param count The number of blocks to be used.
196 INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
198 ASSERT(start + count <= b->blk_cnt);
199 b->priv.blk_start += start;
204 * Transfer data from the internal page buffer to user memory.
206 * This function accesses the internal page buffer of the block device and copy
207 * the data to \a buf. The content is copied from the current cached block.
209 * \param b KBlock device.
210 * \param buf User buffer to copy the data to.
211 * \param offset Address offset within the block, from which to copy data.
212 * \param size Size, in bytes, of the data to be copied.
214 * \return The number of bytes copied. Can be less than \a size on errors.
216 * \sa kblock_writeBuf()
218 INLINE size_t kblock_readBuf(struct KBlock *b, void *buf, size_t offset, size_t size)
221 ASSERT(b->vt->readBuf);
222 ASSERT(offset + size <= b->blk_size);
224 return b->vt->readBuf(b, buf, offset, size);
228 * Write to the page buffer.
230 * Copies data from user memory to the device page buffer. The data is written
231 * in the current cached block buffer.
233 * \param b KBlock device.
234 * \param buf User buffer to copy the data from.
235 * \param offset Address offset within the block, from which data has to be written.
236 * \param size Size, in bytes, of the data to be written.
238 * \return The number of bytes written. Can be less than \a size on errors.
240 * \sa kblock_readBuf()
242 INLINE size_t kblock_writeBuf(struct KBlock *b, const void *buf, size_t offset, size_t size)
245 ASSERT(b->vt->writeBuf);
246 ASSERT(offset + size <= b->blk_size);
247 return b->vt->writeBuf(b, buf, offset, size);
251 * Load a block from the device to the page buffer.
253 * The block \a index will be loaded in the internal page buffer.
255 * \param b KBlock device.
256 * \param index Logical index of the block to be loaded.
258 * \return 0 on success, EOF on errors.
260 INLINE int kblock_load(struct KBlock *b, block_idx_t index)
264 ASSERT(index < b->blk_cnt);
266 return b->vt->load(b, b->priv.blk_start + index);
270 * Store a block from the page buffer to the device.
272 * The current content of the page buffer will be flushed to the block \a index.
274 * \param b KBlock device.
275 * \param index Logical index of the block to be stored.
277 * \return 0 on success, EOF on errors.
279 INLINE int kblock_store(struct KBlock *b, block_idx_t index)
282 ASSERT(b->vt->store);
283 ASSERT(index < b->blk_cnt);
285 return b->vt->store(b, b->priv.blk_start + index);
290 * Memory map the current page buffer.
292 * To speed up access, instead of using kblock_readBuf() and kblock_writeBuf(),
293 * you can memory map the page buffer and access it directly through the
294 * returned pointer. You can freely access the pointer in any way you
295 * like. Once done, call kblock_unmap() to release the lock on the page_buffer.
297 * \note This function may be not available on all drivers, since the page
298 * buffer can be in the hardware and not directly accessible through memory.
299 * For this devices you can still add generic software mapping features
300 * thanks to kblock_addMapping().
302 * \note Only one mapping is available at a time, trying to map the page buffer
303 * again before releasing it is an error.
305 * \param b KBlock device.
306 * \param offset Address offset within the page buffer, from which data has to
308 * \param size Size of the memory to be mapped.
310 * \return A pointer to the mapped region of the page buffer or NULL on errors.
312 * \sa kblock_addMapping(), kblock_unmap()
314 INLINE void * kblock_map(struct KBlock *b, size_t offset, size_t size)
319 if (b->priv.flags & BV(KBS_MAPPED))
321 b->priv.flags |= BV(KBS_ERR_ALREADY_MAPPED);
325 ASSERT(size < b->priv.pagebuf_size);
326 ASSERT(offset + size <= b->blk_size);
327 DB(b->priv.map_off = offset);
328 DB(b->priv.map_size = size);
330 void *ret = b->vt->map(b, offset, size);
333 b->priv.flags |= BV(KBS_MAPPED);
340 * Release the memory map on the page buffer.
342 * This function has to be called when memory mapped access has finished.
343 * This is needed because only one mapping is allowed at a time.
344 * The \a offset and \a size passed should be the same passed to
345 * kblock_map() when the page buffer has been mapped.
347 * \note Trying to unmap the page buffer when there is no mapping ongoing is
350 * \param b KBlock device.
351 * \param offset Address offset within the page buffer, from which data has been
352 * memory mapped. Must be the same value passed to kblock_map()
353 * when the memory was mapped.
354 * \param size Size of the memory mapped. Must be the same value passed to
355 * kblock_map() when the memory was mapped.
357 * \return 0 on success, EOF on errors.
359 * \sa kblock_addMapping(), kblock_map()
361 INLINE int kblock_unmap(struct KBlock *b, size_t offset, size_t size)
364 ASSERT(b->vt->unmap);
366 if (!(b->priv.flags & BV(KBS_MAPPED)))
368 b->priv.flags |= BV(KBS_ERR_NOT_MAPPED);
372 ASSERT(b->priv.map_off == offset);
373 ASSERT(b->priv.map_size == size);
374 int ret = b->vt->unmap(b, offset, size);
377 b->priv.flags &= ~BV(KBS_MAPPED);
382 * Get the current errors for the device.
384 * \note Calling this function will not clear the errors.
386 * \param b KBlock device.
388 * \return 0 if no error is present, a driver specific mask of errors otherwise.
390 * \sa kblock_clearerr()
392 INLINE int kblock_error(struct KBlock *b)
395 ASSERT(b->vt->error);
396 /* Automatically mask status flags */
397 return b->vt->error(b) & ~KBS_STATUS_MASK;
401 * Clear the errors of the device.
403 * \param b KBlock device.
405 * \return 0 on success, EOF on errors.
409 INLINE int kblock_clearerr(struct KBlock *b)
412 ASSERT(b->vt->clearerr);
413 /* Automatically clear error flags */
414 b->priv.flags &= ~KBS_ERROR_MASK;
415 return b->vt->clearerr(b);
421 * \param b KBlock device.
423 * \return 0 on success, EOF on errors.
425 INLINE int kblock_close(struct KBlock *b)
428 ASSERT(b->vt->close);
429 return b->vt->close(b);
432 #endif /* IO_KBLOCK_H */