summaryrefslogtreecommitdiffstats
path: root/cpukit/include/rtems/jffs2.h
diff options
context:
space:
mode:
Diffstat (limited to 'cpukit/include/rtems/jffs2.h')
-rw-r--r--cpukit/include/rtems/jffs2.h604
1 files changed, 604 insertions, 0 deletions
diff --git a/cpukit/include/rtems/jffs2.h b/cpukit/include/rtems/jffs2.h
new file mode 100644
index 0000000000..a856c46c41
--- /dev/null
+++ b/cpukit/include/rtems/jffs2.h
@@ -0,0 +1,604 @@
+/*
+ * Copyright (c) 2013, 2016 embedded brains GmbH. All rights reserved.
+ *
+ * embedded brains GmbH
+ * Dornierstr. 4
+ * 82178 Puchheim
+ * Germany
+ * <rtems@embedded-brains.de>
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.org/license/LICENSE.
+ */
+
+#ifndef RTEMS_JFFS2_H
+#define RTEMS_JFFS2_H
+
+#include <rtems/fs.h>
+#include <sys/param.h>
+#include <sys/ioccom.h>
+#include <zlib.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+typedef struct rtems_jffs2_flash_control rtems_jffs2_flash_control;
+
+/**
+ * @defgroup JFFS2 Journalling Flash File System Version 2 (JFFS2) Support
+ *
+ * @ingroup FileSystemTypesAndMount
+ *
+ * @brief Mount options for the Journalling Flash File System, Version 2
+ * (JFFS2).
+ *
+ * The application must provide flash device geometry information and flash
+ * device operations in the flash control structure
+ * @ref rtems_jffs2_flash_control.
+ *
+ * The application can optionally provide a compressor control structure to
+ * enable data compression using the selected compression algorithm.
+ *
+ * The application must enable JFFS2 support with rtems_filesystem_register()
+ * or CONFIGURE_FILESYSTEM_JFFS2 via <rtems/confdefs.h>.
+ *
+ * An example mount with a simple memory based flash device simulation follows.
+ * The zlib is used for as the compressor.
+ *
+ * @code
+ * #include <string.h>
+ *
+ * #include <rtems/jffs2.h>
+ * #include <rtems/libio.h>
+ *
+ * #define BLOCK_SIZE (32UL * 1024UL)
+ *
+ * #define FLASH_SIZE (32UL * BLOCK_SIZE)
+ *
+ * typedef struct {
+ * rtems_jffs2_flash_control super;
+ * unsigned char area[FLASH_SIZE];
+ * } flash_control;
+ *
+ * static flash_control *get_flash_control(rtems_jffs2_flash_control *super)
+ * {
+ * return (flash_control *) super;
+ * }
+ *
+ * static int flash_read(
+ * rtems_jffs2_flash_control *super,
+ * uint32_t offset,
+ * unsigned char *buffer,
+ * size_t size_of_buffer
+ * )
+ * {
+ * flash_control *self = get_flash_control(super);
+ * unsigned char *chunk = &self->area[offset];
+ *
+ * memcpy(buffer, chunk, size_of_buffer);
+ *
+ * return 0;
+ * }
+ *
+ * static int flash_write(
+ * rtems_jffs2_flash_control *super,
+ * uint32_t offset,
+ * const unsigned char *buffer,
+ * size_t size_of_buffer
+ * )
+ * {
+ * flash_control *self = get_flash_control(super);
+ * unsigned char *chunk = &self->area[offset];
+ * size_t i;
+ *
+ * for (i = 0; i < size_of_buffer; ++i) {
+ * chunk[i] &= buffer[i];
+ * }
+ *
+ * return 0;
+ * }
+ *
+ * static int flash_erase(
+ * rtems_jffs2_flash_control *super,
+ * uint32_t offset
+ * )
+ * {
+ * flash_control *self = get_flash_control(super);
+ * unsigned char *chunk = &self->area[offset];
+ *
+ * memset(chunk, 0xff, BLOCK_SIZE);
+ *
+ * return 0;
+ * }
+ *
+ * static flash_control flash_instance = {
+ * .super = {
+ * .block_size = BLOCK_SIZE,
+ * .flash_size = FLASH_SIZE,
+ * .read = flash_read,
+ * .write = flash_write,
+ * .erase = flash_erase,
+ * .device_identifier = 0xc01dc0fe
+ * }
+ * };
+ *
+ * static rtems_jffs2_compressor_zlib_control compressor_instance = {
+ * .super = {
+ * .compress = rtems_jffs2_compressor_zlib_compress,
+ * .decompress = rtems_jffs2_compressor_zlib_decompress
+ * }
+ * };
+ *
+ * static const rtems_jffs2_mount_data mount_data = {
+ * .flash_control = &flash_instance.super,
+ * .compressor_control = &compressor_instance.super
+ * };
+ *
+ * static void erase_all(void)
+ * {
+ * memset(&flash_instance.area[0], 0xff, FLASH_SIZE);
+ * }
+ *
+ * void example_jffs2_mount(const char *mount_dir)
+ * {
+ * int rv;
+ *
+ * erase_all();
+ *
+ * rv = mount_and_make_target_path(
+ * NULL,
+ * mount_dir,
+ * RTEMS_FILESYSTEM_TYPE_JFFS2,
+ * RTEMS_FILESYSTEM_READ_WRITE,
+ * &mount_data
+ * );
+ * assert(rv == 0);
+ * }
+ * @endcode
+ *
+ * @{
+ */
+
+/**
+ * @brief Read from flash operation.
+ *
+ * @param[in, out] self The flash control.
+ * @param[in] offset The offset to read from the flash begin in bytes.
+ * @param[out] buffer The buffer receiving the data.
+ * @param[in] size_of_buffer The size of the buffer in bytes.
+ *
+ * @retval 0 Successful operation.
+ * @retval -EIO An error occurred. Please note that the value is negative.
+ * @retval other All other values are reserved and must not be used.
+ */
+typedef int (*rtems_jffs2_flash_read)(
+ rtems_jffs2_flash_control *self,
+ uint32_t offset,
+ unsigned char *buffer,
+ size_t size_of_buffer
+);
+
+/**
+ * @brief Write to flash operation.
+ *
+ * @param[in, out] self The flash control.
+ * @param[in] offset The offset to write from the flash begin in bytes.
+ * @param[in] buffer The buffer containing the data to write.
+ * @param[in] size_of_buffer The size of the buffer in bytes.
+ *
+ * @retval 0 Successful operation.
+ * @retval -EIO An error occurred. Please note that the value is negative.
+ * @retval other All other values are reserved and must not be used.
+ */
+typedef int (*rtems_jffs2_flash_write)(
+ rtems_jffs2_flash_control *self,
+ uint32_t offset,
+ const unsigned char *buffer,
+ size_t size_of_buffer
+);
+
+/**
+ * @brief Flash erase operation.
+ *
+ * This operation must erase one block specified by the offset.
+ *
+ * @param[in, out] self The flash control.
+ * @param[in] offset The offset to erase from the flash begin in bytes.
+ *
+ * @retval 0 Successful operation.
+ * @retval -EIO An error occurred. Please note that the value is negative.
+ * @retval other All other values are reserved and must not be used.
+ */
+typedef int (*rtems_jffs2_flash_erase)(
+ rtems_jffs2_flash_control *self,
+ uint32_t offset
+);
+
+/**
+ * @brief Flash destroy operation.
+ *
+ * The flash destroy operation is called during unmount of the file system
+ * instance. It can be used to free the resources associated with the now
+ * unused flash control
+ *
+ * @param[in, out] self The flash control.
+ */
+typedef void (*rtems_jffs2_flash_destroy)(
+ rtems_jffs2_flash_control *self
+);
+
+/**
+ * @brief Trigger garbage collection operation.
+ *
+ * An optional garbage collection thread may perform now a garbage collection
+ * using the RTEMS_JFFS2_ON_DEMAND_GARBAGE_COLLECTION IO control.
+ *
+ * The garbage collection must not run in the executing context.
+ *
+ * @param[in] self The flash control.
+ */
+typedef void (*rtems_jffs2_trigger_garbage_collection)(
+ rtems_jffs2_flash_control *self
+);
+
+/**
+ * @brief JFFS2 flash device control.
+ */
+struct rtems_jffs2_flash_control {
+ /**
+ * @brief The size in bytes of the erasable unit of the flash device.
+ */
+ uint32_t block_size;
+
+ /**
+ * @brief The size in bytes of the flash device.
+ *
+ * It must be an integral multiple of the block size. The flash device must
+ * have at least five blocks.
+ */
+ uint32_t flash_size;
+
+ /**
+ * @brief Read from flash operation.
+ */
+ rtems_jffs2_flash_read read;
+
+ /**
+ * @brief Write to flash operation.
+ */
+ rtems_jffs2_flash_write write;
+
+ /**
+ * @brief Flash erase operation.
+ */
+ rtems_jffs2_flash_erase erase;
+
+ /**
+ * @brief Flash destroy operation.
+ *
+ * This operation is optional and the pointer may be @c NULL.
+ */
+ rtems_jffs2_flash_destroy destroy;
+
+ /**
+ * @brief The device identifier of the flash device.
+ *
+ * It is used in combination with the inode number to uniquely identify a
+ * file system node in the system.
+ */
+ dev_t device_identifier;
+
+ /**
+ * @brief Trigger garbage collection operation.
+ *
+ * This operation is optional and may be NULL. This operation should wake up
+ * a garbage collection thread. The garbage collection thread should use the
+ * RTEMS_JFFS2_ON_DEMAND_GARBAGE_COLLECTION IO control to carry out the work.
+ */
+ rtems_jffs2_trigger_garbage_collection trigger_garbage_collection;
+};
+
+typedef struct rtems_jffs2_compressor_control rtems_jffs2_compressor_control;
+
+/**
+ * @brief Compress operation.
+ *
+ * @param[in, out] self The compressor control.
+ * @param[in] data_in The uncompressed data.
+ * @param[out] cdata_out Pointer to buffer with the compressed data.
+ * @param[in, out] datalen On entry, the size in bytes of the uncompressed
+ * data. On exit, the size in bytes of uncompressed data which was actually
+ * compressed.
+ * @param[in, out] cdatalen On entry, the size in bytes available for
+ * compressed data. On exit, the size in bytes of the actually compressed
+ * data.
+ *
+ * @return The compressor type.
+ */
+typedef uint16_t (*rtems_jffs2_compressor_compress)(
+ rtems_jffs2_compressor_control *self,
+ unsigned char *data_in,
+ unsigned char *cdata_out,
+ uint32_t *datalen,
+ uint32_t *cdatalen
+);
+
+/**
+ * @brief Decompress operation.
+ *
+ * @param[in, out] self The compressor control.
+ * @param[in] comprtype The compressor type.
+ * @param[in] cdata_in The compressed data.
+ * @param[out] data_out The uncompressed data.
+ * @param[in] cdatalen The size in bytes of the compressed data.
+ * @param[in] datalen The size in bytes of the uncompressed data.
+ *
+ * @retval 0 Successful operation.
+ * @retval -EIO An error occurred. Please note that the value is negative.
+ * @retval other All other values are reserved and must not be used.
+ */
+typedef int (*rtems_jffs2_compressor_decompress)(
+ rtems_jffs2_compressor_control *self,
+ uint16_t comprtype,
+ unsigned char *cdata_in,
+ unsigned char *data_out,
+ uint32_t cdatalen,
+ uint32_t datalen
+);
+
+/**
+ * @brief Compressor destroy operation.
+ *
+ * The compressor destroy operation is called during unmount of the file system
+ * instance. It can be used to free the resources associated with the now
+ * unused compressor operations.
+ *
+ * @param[in, out] self The compressor control.
+ */
+typedef void (*rtems_jffs2_compressor_destroy)(
+ rtems_jffs2_compressor_control *self
+);
+
+/**
+ * @brief JFFS2 compressor control.
+ */
+struct rtems_jffs2_compressor_control {
+ /**
+ * @brief Compress operation.
+ */
+ rtems_jffs2_compressor_compress compress;
+
+ /**
+ * @brief Decompress operation.
+ */
+ rtems_jffs2_compressor_decompress decompress;
+
+ /**
+ * @brief Compressor destroy operation.
+ *
+ * This operation is optional and the pointer may be @c NULL.
+ */
+ rtems_jffs2_compressor_destroy destroy;
+
+ /**
+ * @brief Compression buffer.
+ */
+ unsigned char buffer[PAGE_SIZE];
+};
+
+/**
+ * @brief RTIME compressor compress operation.
+ */
+uint16_t rtems_jffs2_compressor_rtime_compress(
+ rtems_jffs2_compressor_control *self,
+ unsigned char *data_in,
+ unsigned char *cdata_out,
+ uint32_t *datalen,
+ uint32_t *cdatalen
+);
+
+/**
+ * @brief RTIME compressor decompress operation.
+ */
+int rtems_jffs2_compressor_rtime_decompress(
+ rtems_jffs2_compressor_control *self,
+ uint16_t comprtype,
+ unsigned char *cdata_in,
+ unsigned char *data_out,
+ uint32_t cdatalen,
+ uint32_t datalen
+);
+
+/**
+ * @brief ZLIB compressor control structure.
+ */
+typedef struct {
+ rtems_jffs2_compressor_control super;
+ z_stream stream;
+} rtems_jffs2_compressor_zlib_control;
+
+/**
+ * @brief ZLIB compressor compress operation.
+ */
+uint16_t rtems_jffs2_compressor_zlib_compress(
+ rtems_jffs2_compressor_control *self,
+ unsigned char *data_in,
+ unsigned char *cdata_out,
+ uint32_t *datalen,
+ uint32_t *cdatalen
+);
+
+/**
+ * @brief ZLIB compressor decompress operation.
+ */
+int rtems_jffs2_compressor_zlib_decompress(
+ rtems_jffs2_compressor_control *self,
+ uint16_t comprtype,
+ unsigned char *cdata_in,
+ unsigned char *data_out,
+ uint32_t cdatalen,
+ uint32_t datalen
+);
+
+/**
+ * @brief JFFS2 mount options.
+ *
+ * For JFFS2 the mount options are mandatory.
+ */
+typedef struct {
+ /**
+ * @brief Flash control.
+ */
+ rtems_jffs2_flash_control *flash_control;
+
+ /**
+ * @brief Compressor control.
+ *
+ * The compressor is optional and this pointer may be @c NULL.
+ */
+ rtems_jffs2_compressor_control *compressor_control;
+} rtems_jffs2_mount_data;
+
+/**
+ * @brief Initialization handler of the JFFS2 file system.
+ *
+ * @param[in, out] mt_entry The mount table entry.
+ * @param[in] data The mount options are mandatory for JFFS2 and data must
+ * point to a valid @ref rtems_jffs2_mount_data structure used for this file
+ * system instance.
+ *
+ * @retval 0 Successful operation.
+ * @retval -1 An error occurred. The @c errno indicates the error.
+ *
+ * @see mount().
+ */
+int rtems_jffs2_initialize(
+ rtems_filesystem_mount_table_entry_t *mt_entry,
+ const void *data
+);
+
+/**
+ * @brief JFFS2 filesystem instance information.
+ *
+ * @see RTEMS_JFFS2_GET_INFO.
+ */
+typedef struct {
+ /**
+ * @brief Flash size in bytes.
+ */
+ uint32_t flash_size;
+
+ /**
+ * @brief Count of flash blocks (erasable units).
+ */
+ uint32_t flash_blocks;
+
+ /**
+ * @brief Size of a flash block in bytes.
+ */
+ uint32_t flash_block_size;
+
+ /**
+ * @brief Used size in bytes.
+ *
+ * Used areas contain valid data.
+ */
+ uint32_t used_size;
+
+ /**
+ * @brief Dirty size in bytes.
+ *
+ * Used areas contain no longer used data.
+ */
+ uint32_t dirty_size;
+
+ /**
+ * @brief Wasted size in bytes.
+ *
+ * Wasted areas are unusable.
+ */
+ uint32_t wasted_size;
+
+ /**
+ * @brief Free size in bytes.
+ *
+ * Free areas may be used to store new data.
+ */
+ uint32_t free_size;
+
+ /**
+ * @brief Bad size in bytes.
+ *
+ * Bad areas indicate damaged flash blocks.
+ */
+ uint32_t bad_size;
+
+ /**
+ * @brief Count of clean blocks.
+ *
+ * Clean blocks contain only used areas.
+ */
+ uint32_t clean_blocks;
+
+ /**
+ * @brief Count of dirty blocks.
+ *
+ * Dirty blocks contain dirty and used areas.
+ */
+ uint32_t dirty_blocks;
+
+ /**
+ * @brief Count of erasable blocks.
+ *
+ * Erase blocks contain only dirty or wasted areas.
+ */
+ uint32_t erasable_blocks;
+
+ /**
+ * @brief Count of free blocks.
+ *
+ * Free blocks contain a free area.
+ */
+ uint32_t free_blocks;
+
+ /**
+ * @brief Count of bad blocks.
+ *
+ * Bad blocks are damaged.
+ */
+ uint32_t bad_blocks;
+} rtems_jffs2_info;
+
+/**
+ * @brief IO control to get the JFFS2 filesystem instance information.
+ *
+ * @see rtems_jffs2_info.
+ */
+#define RTEMS_JFFS2_GET_INFO _IOR('F', 1, rtems_jffs2_info)
+
+/**
+ * @brief IO control to perform an on demand garbage collection in a JFFS2
+ * filesystem instance.
+ *
+ * This operation is intended to be used by an optional garbage collection
+ * thread. See rtems_jffs2_flash_control::trigger_garbage_collection.
+ */
+#define RTEMS_JFFS2_ON_DEMAND_GARBAGE_COLLECTION _IO('F', 2)
+
+/**
+ * @brief IO control to force a garbage collection in a JFFS2 filesystem
+ * instance.
+ *
+ * Use this operation with care since it may wear out your flash.
+ */
+#define RTEMS_JFFS2_FORCE_GARBAGE_COLLECTION _IO('F', 3)
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* RTEMS_JFFS2_H */