More implementation progress -- Still not functional

inc/flogfs.h

@@ -1,77 +1,151 @@
+/*
+Copyright (c) 2013, Ben Nahill <[email protected]>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, of the FLogFS Project.
+*/
+
+/*!
+ * @file flogfs.h
+ * @author Ben Nahill <[email protected]>
+ *
+ * @ingroup FLogFS
+ *
+ */
+
 #ifndef __FLOGFS_H_
 #define __FLOGFS_H_
 
 #include "stdint.h"
 
+//! @addtogroup FLogPublic
+//! @{
 
-// Compile as C++
-#define FLOG_BUILD_CPP (1)
-
+//! Compile as C++
+#define FLOG_BUILD_CPP (0)
 
+//! @name Version Number
+//! @{
 #define FLOG_VSN_MAJOR (0)
 #define FLOG_VSN_MINOR (1)
+//! @}
+
 
+//! @name Configuration Options
+//! Some compilation options to customize the build
+//! @{
+//! The maximum file name length allowed
 #define FLOG_MAX_FNAME_LEN (32)
+//! @}
+
 
 #if !FLOG_BUILD_CPP
 #ifdef __cplusplus
 extern "C" {
 #endif
 #endif
 
+
 typedef enum {
  FLOG_FAILURE,
  FLOG_SUCCESS
 } flog_result_t;
 
+typedef enum {
+ FLOG_FLASH_SUCCESS = 0,
+ FLOG_FLASH_ERR_CORRECT = 1,
+ FLOG_FLASH_ERR_DETECT = -1
+} flog_flash_read_result_t;
+
 #define FLOG_RESULT(x) ((x)?FLOG_SUCCESS:FLOG_FAILURE)
 
-typedef enum {
- FLOG_MODE_READ = 1,
- FLOG_MODE_WRITE = 2
-} flog_mode_t;
-
-typedef struct flog_read_file_s {
- uint32_t read_head; //!< Offset of read head from the start of the file
- uint16_t block; //!< Block index of read head
- uint16_t sector; //!< Chunk index of read head
- uint16_t offset; //!< Index of the read head inside chunk
- uint16_t nbytes_in_sector;
+/*!
+ @typedef flog_read_file_t
+ @brief The state of a currently-open file
+
+ This should be allocated by the application and provided to the file system
+ for access to a file
+ */
+typedef struct flog_read_file_t {
+ //! Offset of read head from the start of the file
+ uint32_t read_head;
+ //! Block index of read head
+ uint16_t block;
+ //! Sector index of read head
+ uint16_t sector;
+ //! Index of the read head inside sector
+ uint16_t offset;
+ //! Number of bytes remaining in current sector
+ uint16_t sector_remaining_bytes;
  uint8_t at_eof;
 
  uint32_t id;
 
- struct flog_read_file_s * next;
+ struct flog_read_file_t * next;
 } flog_read_file_t;
 
-typedef struct flog_write_file_s {
+typedef struct flog_write_file_t {
  uint32_t write_head; //!< Offset of write head from start of file
  uint16_t write_block; //! Block index of write head
  uint16_t write_chunk; //! Chunk index of write head
  uint16_t write_index; //! Write index of current chunk
 
  uint32_t id;
 
- struct flog_write_file_s * next;
+ struct flog_write_file_t * next;
 } flog_write_file_t;
 
 /*!
  @brief Initialize flogfs filesystem structures
  */
 flog_result_t flogfs_init();
 
+/*!
+ @brief Format the flash memory for FLogFS
+ */
 flog_result_t flogfs_format();
 
+/*!
+ @brief Mount the FLogFS filesystem and prepare it for use
+ */
 flog_result_t flogfs_mount();
 
-flog_result_t flogfs_open_read(flog_write_file_t * file, char const * filename);
+flog_result_t flogfs_open_read(flog_read_file_t * file, char const * filename);
 
 flog_result_t flogfs_open_write(flog_write_file_t * file, char const * filename);
 
+flog_result_t flogfs_close_read(flog_read_file_t * file);
+
+flog_result_t flogfs_close_write(flog_write_file_t * file);
+
 #if !FLOG_BUILD_CPP
 #ifdef __cplusplus
 };
 #endif
 #endif
 
+//! @} // Public
+
 #endif // __FLOGFS_H_

inc/flogfs_private.h

@@ -1,14 +1,57 @@
+/*
+Copyright (c) 2013, Ben Nahill <[email protected]>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, of the FLogFS Project.
+*/
+
+/*!
+ * @file flogfs_private.h
+ * @author Ben Nahill <[email protected]>
+ *
+ * @ingroup FLogFS
+ *
+ */
+
 #ifndef __FLOGFS_PRIVATE_H_
 #define __FLOGFS_PRIVATE_H_
 
 #include "flogfs.h"
 #include "flogfs_conf.h"
 
 #define MAX(a,b) ((a > b) ? a : b)
+#define MIN(a,b) ((a > b) ? b : a)
+
+
+//! @addtogroup FLogPrivate
+//! @{
 
 typedef enum {
  FLOG_STATE_RESET,
- FLOG_STATE_MOUNTED
+ FLOG_STATE_MOUNTED,
+ FLOG_STATE_EDIBLE
 } flog_state_t;
 
 /*!
@@ -22,25 +65,30 @@ typedef enum {
  FLOG_BLOCK_TYPE_FILE = 2
 } flog_block_type_t;
 
-
+//! @name Type size definitions
+//! @{
 typedef uint32_t flog_timestamp_t;
 typedef uint16_t flog_block_idx_t;
 typedef uint32_t flog_block_age_t;
 typedef uint32_t flog_file_id_t;
 typedef uint16_t flog_sector_nbytes_t;
 typedef uint16_t inode_index_t;
+//! @}
 
+//! @name Invalid values
+//! @{
 #define FLOG_BLOCK_IDX_INVALID ((flog_block_idx_t)(-1))
 #define FLOG_FILE_ID_INVALID ((flog_file_id_t)(-1))
 #define FLOG_TIMESTAMP_INVALID ((flog_timestamp_t)(-1))
+//! @}
 
+//! A marker value to identify a completed inode copy
 static uint8_t const flog_copy_complete_marker = 0x55;
 
-/*!
- @name Inode block structures
- @{
- */
 
+//! @defgroup FLogInodeBlockStructs Inode block structures
+//! @brief Descriptions of the data in inode blocks
+//! @{
 typedef struct {
  flog_block_age_t age;
  flog_timestamp_t timestamp;
@@ -85,16 +133,19 @@ typedef struct {
  flog_block_idx_t last_block;
 } flog_inode_file_invalidation_t;
 
-/*!
- @}
- */
+//! @} // Inode structures
 
+typedef struct {
+ flog_block_age_t age;
+} flog_universal_sector0_header_t;
 
+typedef struct {
+ flog_timestamp_t timestamp;
+} flog_universal_invalidation_header_t;
 
-/*!
- @name File block structures
- @{
- */
+//! @defgroup FLogFileBlockStructs File block structures
+//! @brief Descriptions of the data in file blocks
+//! @{
 
 typedef struct {
  flog_block_age_t age;
@@ -128,24 +179,18 @@ typedef struct {
  flog_block_age_t next_age;
 } flog_file_invalidation_sector_t;
 
-/*!
- @}
- */
+//! @}
+
 
+//! @name Special sector indices
+//! @{
 #define FLOG_FILE_TAIL_SECTOR (FS_SECTORS_PER_PAGE - 2)
 #define FLOG_FILE_INVALIDATION_SECTOR (FS_SECTORS_PER_PAGE - 1)
 #define FLOG_INODE_TAIL_SECTOR (FS_SECTORS_PER_PAGE - 2)
 #define FLOG_INODE_INVALIDATION_SECTOR (FS_SECTORS_PER_PAGE - 1)
+//! @}
+
+//! @} // FLogPrivate
 
-/*!
- @brief 
- 
- @note This is in an unprotected area and some error checking must be done
- */
-typedef enum {
- FLOG_HEADER_CHUNK_STAT_FREE = 0xFF,
- FLOG_HEADER_CHUNK_STAT_INUSE = 0x0F,
- FLOG_HEADER_CHUNK_STAT_DISCARD = 0x00
-} flog_header_chunk_status_t;
 
 #endif // __FLOGFS_PRIVATE_H_