source: rtems/cpukit/libfs/src/jffs2/include/rtems/jffs2.h @ 3c96bee

4.11
Last change on this file since 3c96bee was 3c96bee, checked in by Sebastian Huber <sebastian.huber@…>, on Sep 12, 2013 at 1:32:07 PM

JFFS2: Add RTEMS support

  • Property mode set to 100644
File size: 11.0 KB
Line 
1/*
2 * Copyright (c) 2013 embedded brains GmbH.  All rights reserved.
3 *
4 *  embedded brains GmbH
5 *  Dornierstr. 4
6 *  82178 Puchheim
7 *  Germany
8 *  <rtems@embedded-brains.de>
9 *
10 * The license and distribution terms for this file may be
11 * found in the file LICENSE in this distribution or at
12 * http://www.rtems.com/license/LICENSE.
13 */
14
15#ifndef RTEMS_JFFS2_H
16#define RTEMS_JFFS2_H
17
18#include <rtems/fs.h>
19#include <sys/param.h>
20#include <zlib.h>
21
22#ifdef __cplusplus
23extern "C" {
24#endif /* __cplusplus */
25
26typedef struct rtems_jffs2_flash_control rtems_jffs2_flash_control;
27
28/**
29 * @defgroup JFFS2 Journalling Flash File System Version 2 (JFFS2) Support
30 *
31 * @ingroup FileSystemTypesAndMount
32 *
33 * @brief Mount options for the Journalling Flash File System, Version 2
34 * (JFFS2).
35 *
36 * The application must provide flash device geometry information and flash
37 * device operations in the flash control structure
38 * @ref rtems_jffs2_flash_control.
39 *
40 * The application can optionally provide a compressor control structure to
41 * enable data compression using the selected compression algorithm.
42 *
43 * The application must enable JFFS2 support with rtems_filesystem_register()
44 * or CONFIGURE_FILESYSTEM_JFFS2 via <rtems/confdefs.h>.
45 *
46 * An example mount with a simple memory based flash device simulation follows.
47 * The zlib is used for as the compressor.
48 *
49 * @code
50 * #include <string.h>
51 *
52 * #include <rtems/jffs2.h>
53 * #include <rtems/libio.h>
54 *
55 * #define BLOCK_SIZE (32UL * 1024UL)
56 *
57 * #define FLASH_SIZE (32UL * BLOCK_SIZE)
58 *
59 * typedef struct {
60 *   rtems_jffs2_flash_control super;
61 *   unsigned char area[FLASH_SIZE];
62 * } flash_control;
63 *
64 * static flash_control *get_flash_control(rtems_jffs2_flash_control *super)
65 * {
66 *   return (flash_control *) super;
67 * }
68 *
69 * static int flash_read(
70 *   rtems_jffs2_flash_control *super,
71 *   uint32_t offset,
72 *   unsigned char *buffer,
73 *   size_t size_of_buffer
74 * )
75 * {
76 *   flash_control *self = get_flash_control(super);
77 *   unsigned char *chunk = &self->area[offset];
78 *
79 *   memcpy(buffer, chunk, size_of_buffer);
80 *
81 *   return 0;
82 * }
83 *
84 * static int flash_write(
85 *   rtems_jffs2_flash_control *super,
86 *   uint32_t offset,
87 *   const unsigned char *buffer,
88 *   size_t size_of_buffer
89 * )
90 * {
91 *   flash_control *self = get_flash_control(super);
92 *   unsigned char *chunk = &self->area[offset];
93 *   size_t i;
94 *
95 *   for (i = 0; i < size_of_buffer; ++i) {
96 *     chunk[i] &= buffer[i];
97 *   }
98 *
99 *   return 0;
100 * }
101 *
102 * static int flash_erase(
103 *   rtems_jffs2_flash_control *super,
104 *   uint32_t offset
105 * )
106 * {
107 *   flash_control *self = get_flash_control(super);
108 *   unsigned char *chunk = &self->area[offset];
109 *
110 *   memset(chunk, 0xff, BLOCK_SIZE);
111 *
112 *   return 0;
113 * }
114 *
115 * static flash_control flash_instance = {
116 *   .super = {
117 *     .block_size = BLOCK_SIZE,
118 *     .flash_size = FLASH_SIZE,
119 *     .read = flash_read,
120 *     .write = flash_write,
121 *     .erase = flash_erase
122 *   }
123 * };
124 *
125 * static rtems_jffs2_compressor_zlib_control compressor_instance = {
126 *   .super = {
127 *     .compress = rtems_jffs2_compressor_zlib_compress,
128 *     .decompress = rtems_jffs2_compressor_zlib_decompress
129 *   }
130 * };
131 *
132 * static const rtems_jffs2_mount_data mount_data = {
133 *   .flash_control = &flash_instance.super,
134 *   .compressor_control = &compressor_instance.super
135 * };
136 *
137 * static void erase_all(void)
138 * {
139 *   memset(&flash_instance.area[0], 0xff, FLASH_SIZE);
140 * }
141 *
142 * void example_jffs2_mount(const char *mount_dir)
143 * {
144 *   int rv;
145 *
146 *   erase_all();
147 *
148 *   rv = mount_and_make_target_path(
149 *     NULL,
150 *     mount_dir,
151 *     RTEMS_FILESYSTEM_TYPE_JFFS2,
152 *     RTEMS_FILESYSTEM_READ_WRITE,
153 *     &mount_data
154 *   );
155 *   assert(rv == 0);
156 * }
157 * @endcode
158 *
159 * @{
160 */
161
162/**
163 * @brief Read from flash operation.
164 *
165 * @param[in, out] self The flash control.
166 * @param[in] offset The offset to read from the flash begin in bytes.
167 * @param[out] buffer The buffer receiving the data.
168 * @param[in] size_of_buffer The size of the buffer in bytes.
169 *
170 * @retval 0 Successful operation.
171 * @retval -EIO An error occurred.  Please note that the value is negative.
172 * @retval other All other values are reserved and must not be used.
173 */
174typedef int (*rtems_jffs2_flash_read)(
175  rtems_jffs2_flash_control *self,
176  uint32_t offset,
177  unsigned char *buffer,
178  size_t size_of_buffer
179);
180
181/**
182 * @brief Write to flash operation.
183 *
184 * @param[in, out] self The flash control.
185 * @param[in] offset The offset to write from the flash begin in bytes.
186 * @param[in] buffer The buffer containing the data to write.
187 * @param[in] size_of_buffer The size of the buffer in bytes.
188 *
189 * @retval 0 Successful operation.
190 * @retval -EIO An error occurred.  Please note that the value is negative.
191 * @retval other All other values are reserved and must not be used.
192 */
193typedef int (*rtems_jffs2_flash_write)(
194  rtems_jffs2_flash_control *self,
195  uint32_t offset,
196  const unsigned char *buffer,
197  size_t size_of_buffer
198);
199
200/**
201 * @brief Flash erase operation.
202 *
203 * This operation must erase one block specified by the offset.
204 *
205 * @param[in, out] self The flash control.
206 * @param[in] offset The offset to erase from the flash begin in bytes.
207 *
208 * @retval 0 Successful operation.
209 * @retval -EIO An error occurred.  Please note that the value is negative.
210 * @retval other All other values are reserved and must not be used.
211 */
212typedef int (*rtems_jffs2_flash_erase)(
213  rtems_jffs2_flash_control *self,
214  uint32_t offset
215);
216
217/**
218 * @brief Flash destroy operation.
219 *
220 * The flash destroy operation is called during unmount of the file system
221 * instance.  It can be used to free the resources associated with the now
222 * unused flash control
223 *
224 * @param[in, out] self The flash control.
225 */
226typedef void (*rtems_jffs2_flash_destroy)(
227  rtems_jffs2_flash_control *self
228);
229
230/**
231 * @brief JFFS2 flash device control.
232 */
233struct rtems_jffs2_flash_control {
234  /**
235   * @brief The size in bytes of the erasable unit of the flash device.
236   */
237  uint32_t block_size;
238
239  /**
240   * @brief The size in bytes of the flash device.
241   *
242   * It must be an integral multiple of the block size.  The flash device must
243   * have at least five blocks.
244   */
245  uint32_t flash_size;
246
247  /**
248   * @brief Read from flash operation.
249   */
250  rtems_jffs2_flash_read read;
251
252  /**
253   * @brief Write to flash operation.
254   */
255  rtems_jffs2_flash_write write;
256
257  /**
258   * @brief Flash erase operation.
259   */
260  rtems_jffs2_flash_erase erase;
261
262  /**
263   * @brief Flash destroy operation.
264   *
265   * This operation is optional and the pointer may be @c NULL.
266   */
267  rtems_jffs2_flash_destroy destroy;
268};
269
270typedef struct rtems_jffs2_compressor_control rtems_jffs2_compressor_control;
271
272/**
273 * @brief Compress operation.
274 *
275 * @param[in, out] self The compressor control.
276 * @param[in] data_in The uncompressed data.
277 * @param[out] cdata_out Pointer to buffer with the compressed data.
278 * @param[in, out] datalen On entry, the size in bytes of the uncompressed
279 * data.  On exit, the size in bytes of uncompressed data which was actually
280 * compressed.
281 * @param[in, out] cdatalen On entry, the size in bytes available for
282 * compressed data.  On exit, the size in bytes of the actually compressed
283 * data.
284 *
285 * @return The compressor type.
286 */
287typedef uint16_t (*rtems_jffs2_compressor_compress)(
288  rtems_jffs2_compressor_control *self,
289  unsigned char *data_in,
290  unsigned char *cdata_out,
291  uint32_t *datalen,
292  uint32_t *cdatalen
293);
294
295/**
296 * @brief Decompress operation.
297 *
298 * @param[in, out] self The compressor control.
299 * @param[in] comprtype The compressor type.
300 * @param[in] cdata_in The compressed data.
301 * @param[out] data_out The uncompressed data.
302 * @param[in] cdatalen The size in bytes of the compressed data.
303 * @param[in] datalen The size in bytes of the uncompressed data.
304 *
305 * @retval 0 Successful operation.
306 * @retval -EIO An error occurred.  Please note that the value is negative.
307 * @retval other All other values are reserved and must not be used.
308 */
309typedef int (*rtems_jffs2_compressor_decompress)(
310  rtems_jffs2_compressor_control *self,
311  uint16_t comprtype,
312  unsigned char *cdata_in,
313  unsigned char *data_out,
314  uint32_t cdatalen,
315  uint32_t datalen
316);
317
318/**
319 * @brief Compressor destroy operation.
320 *
321 * The compressor destroy operation is called during unmount of the file system
322 * instance.  It can be used to free the resources associated with the now
323 * unused compressor operations.
324 *
325 * @param[in, out] self The compressor control.
326 */
327typedef void (*rtems_jffs2_compressor_destroy)(
328  rtems_jffs2_compressor_control *self
329);
330
331/**
332 * @brief JFFS2 compressor control.
333 */
334struct rtems_jffs2_compressor_control {
335  /**
336   * @brief Compress operation.
337   */
338  rtems_jffs2_compressor_compress compress;
339
340  /**
341   * @brief Decompress operation.
342   */
343  rtems_jffs2_compressor_decompress decompress;
344
345  /**
346   * @brief Compressor destroy operation.
347   *
348   * This operation is optional and the pointer may be @c NULL.
349   */
350  rtems_jffs2_compressor_destroy destroy;
351
352  /**
353   * @brief Compression buffer.
354   */
355  unsigned char buffer[PAGE_SIZE];
356};
357
358/**
359 * @brief RTIME compressor compress operation.
360 */
361uint16_t rtems_jffs2_compressor_rtime_compress(
362  rtems_jffs2_compressor_control *self,
363  unsigned char *data_in,
364  unsigned char *cdata_out,
365  uint32_t *datalen,
366  uint32_t *cdatalen
367);
368
369/**
370 * @brief RTIME compressor decompress operation.
371 */
372int rtems_jffs2_compressor_rtime_decompress(
373  rtems_jffs2_compressor_control *self,
374  uint16_t comprtype,
375  unsigned char *cdata_in,
376  unsigned char *data_out,
377  uint32_t cdatalen,
378  uint32_t datalen
379);
380
381/**
382 * @brief ZLIB compressor control structure.
383 */
384typedef struct {
385  rtems_jffs2_compressor_control super;
386  z_stream stream;
387} rtems_jffs2_compressor_zlib_control;
388
389/**
390 * @brief ZLIB compressor compress operation.
391 */
392uint16_t rtems_jffs2_compressor_zlib_compress(
393  rtems_jffs2_compressor_control *self,
394  unsigned char *data_in,
395  unsigned char *cdata_out,
396  uint32_t *datalen,
397  uint32_t *cdatalen
398);
399
400/**
401 * @brief ZLIB compressor decompress operation.
402 */
403int rtems_jffs2_compressor_zlib_decompress(
404  rtems_jffs2_compressor_control *self,
405  uint16_t comprtype,
406  unsigned char *cdata_in,
407  unsigned char *data_out,
408  uint32_t cdatalen,
409  uint32_t datalen
410);
411
412/**
413 * @brief JFFS2 mount options.
414 *
415 * For JFFS2 the mount options are mandatory.
416 */
417typedef struct {
418  /**
419   * @brief Flash control.
420   */
421  rtems_jffs2_flash_control *flash_control;
422
423  /**
424   * @brief Compressor control.
425   *
426   * The compressor is optional and this pointer may be @c NULL.
427   */
428  rtems_jffs2_compressor_control *compressor_control;
429} rtems_jffs2_mount_data;
430
431/**
432 * @brief Initialization handler of the JFFS2 file system.
433 *
434 * @param[in, out] mt_entry The mount table entry.
435 * @param[in] data The mount options are mandatory for JFFS2 and data must
436 * point to a valid @ref rtems_jffs2_mount_data structure used for this file
437 * system instance.
438 *
439 * @retval 0 Successful operation.
440 * @retval -1 An error occurred.  The @c errno indicates the error.
441 *
442 * @see mount().
443 */
444int rtems_jffs2_initialize(
445  rtems_filesystem_mount_table_entry_t *mt_entry,
446  const void *data
447);
448
449/** @} */
450
451#ifdef __cplusplus
452}
453#endif /* __cplusplus */
454
455#endif /* RTEMS_JFFS2_H */
Note: See TracBrowser for help on using the repository browser.