flash_journal_private.h

00001 /*
00002  * Copyright (c) 2006-2016, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00013  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef __FLASH_JOURNAL_PRIVATE_H__
00019 #define __FLASH_JOURNAL_PRIVATE_H__
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif // __cplusplus
00024 
00025 #include "flash-journal/flash_journal.h"
00026 #include "flash-journal-strategy-sequential/config.h"
00027 
00028 static const uint32_t SEQUENTIAL_FLASH_JOURNAL_INVALD_NEXT_SEQUENCE_NUMBER = 0xFFFFFFFFUL;
00029 static const uint32_t SEQUENTIAL_FLASH_JOURNAL_VERSION = 1;
00030 static const uint32_t SEQUENTIAL_FLASH_JOURNAL_MAGIC   = 0xCE02102AUL;
00031 
00032 typedef enum {
00033     SEQUENTIAL_JOURNAL_STATE_NOT_INITIALIZED,
00034     SEQUENTIAL_JOURNAL_STATE_INIT_SCANNING_LOG_HEADERS,
00035     SEQUENTIAL_JOURNAL_STATE_INITIALIZED,
00036     SEQUENTIAL_JOURNAL_STATE_RESETING,
00037     SEQUENTIAL_JOURNAL_STATE_LOGGING_ERASE,
00038     SEQUENTIAL_JOURNAL_STATE_LOGGING_HEAD,
00039     SEQUENTIAL_JOURNAL_STATE_LOGGING_BODY,
00040     SEQUENTIAL_JOURNAL_STATE_LOGGING_TAIL,
00041     SEQUENTIAL_JOURNAL_STATE_READING,
00042 } SequentialFlashJournalState_t;
00043 
00044 /**
00045  * Meta-data placed at the head of a sequential-log entry.
00046  */
00047 typedef struct _SequentialFlashJournalLogHead {
00048     uint32_t version;
00049     uint32_t magic;
00050     uint32_t sequenceNumber;
00051     uint32_t reserved;
00052 } SequentialFlashJournalLogHead_t;
00053 
00054 #define SEQUENTIAL_JOURNAL_VALID_HEAD(PTR) \
00055     (((PTR)->version == SEQUENTIAL_FLASH_JOURNAL_VERSION) && ((PTR)->magic == SEQUENTIAL_FLASH_JOURNAL_MAGIC))
00056 
00057 /**
00058  * Meta-data placed at the tail of a sequential-log entry.
00059  *
00060  * @note the most crucial items (the ones which play a role in the validation of
00061  *     the log-entry) are placed at the end of this structure; this ensures that
00062  *     a partially written log-entry-tail won't be accepted as valid.
00063  */
00064 typedef struct _SequentialFlashJournalLogTail {
00065     uint64_t sizeofBlob; /**< the size of the payload in this blob. */
00066     uint32_t magic;
00067     uint32_t sequenceNumber;
00068 } SequentialFlashJournalLogTail_t;
00069 
00070 #define SEQUENTIAL_JOURNAL_VALID_TAIL(TAIL_PTR) ((TAIL_PTR)->magic == SEQUENTIAL_FLASH_JOURNAL_MAGIC)
00071 
00072 typedef struct _SequentialFlashJournal_t {
00073     FlashJournal_Ops_t             ops;                /**< the mandatory OPS table defining the strategy. */
00074     FlashJournal_Callback_t        callback;           /**< command completion callback. */
00075     FlashJournal_Info_t            info;               /**< the info structure returned from GetInfo(). */
00076     ARM_DRIVER_STORAGE            *mtd;                /**< The underlying Memory-Technology-Device. */
00077     ARM_STORAGE_CAPABILITIES       mtdCapabilities;    /**< the return from mtd->GetCapabilities(); held for quick reference. */
00078     uint64_t                       mtdStartOffset;     /**< the start of the address range maintained by the underlying MTD. */
00079     uint32_t                       sequentialSkip;     /**< size of the log stride. */
00080     uint32_t                       nextSequenceNumber; /**< the next valid sequence number to be used when logging the next blob. */
00081     uint32_t                       currentBlobIndex;   /**< index of the most recently written blob. */
00082     SequentialFlashJournalState_t  state;              /**< state of the journal. SEQUENTIAL_JOURNAL_STATE_INITIALIZED being the default. */
00083     FlashJournal_OpCode_t          prevCommand;        /**< the last command issued to the journal. */
00084 
00085     /**
00086      * The following is a union of sub-structures meant to keep state relevant
00087      * to the commands during their execution.
00088      */
00089     union {
00090         /** state relevant to initialization. */
00091         struct {
00092             uint64_t currentOffset;
00093             union {
00094                 SequentialFlashJournalLogHead_t head;
00095                 struct {
00096                     uint32_t                        headSequenceNumber;
00097                     SequentialFlashJournalLogTail_t tail;
00098                 };
00099             };
00100         } initScan;
00101 
00102         /** state relevant to logging of data. */
00103         struct {
00104             const uint8_t *blob;           /**< the original buffer holding source data. */
00105             size_t         sizeofBlob;
00106             union {
00107                 struct {
00108                     uint64_t eraseOffset;
00109                 };
00110                 struct {
00111                     uint64_t       offset;          /**< the current offset at which data is being written. */
00112                     uint64_t       tailOffset;      /**< offset at which the SequentialFlashJournalLogTail_t will be logged for this log-entry. */
00113                     const uint8_t *dataBeingLogged; /**< temporary pointer aimed at the next data to be logged. */
00114                     size_t         amountLeftToLog;
00115                     union {
00116                         SequentialFlashJournalLogHead_t head;
00117                         SequentialFlashJournalLogTail_t tail;
00118                     };
00119                 };
00120             };
00121         } log;
00122 
00123         /** state relevant to read-back of data. */
00124         struct {
00125             const uint8_t *blob;               /**< the original buffer holding source data. */
00126             size_t         sizeofBlob;
00127             uint64_t       offset;             /**< the current offset at which data is being written. */
00128             uint8_t       *dataBeingRead;      /**< temporary pointer aimed at the next data to be read-into. */
00129             size_t         amountLeftToRead;
00130             size_t         totalDataRead;      /**< the total data that has been read off the blob so far. */
00131         } read;
00132     };
00133 } SequentialFlashJournal_t;
00134 
00135 /**<
00136  * A static assert to ensure that the size of SequentialJournal is smaller than
00137  * FlashJournal_t. The caller will only allocate a FlashJournal_t and expect the
00138  * Sequential Strategy to reuse that space for a SequentialFlashJournal_t.
00139  */
00140 typedef char AssertSequentialJournalSizeLessThanOrEqualToGenericJournal[sizeof(SequentialFlashJournal_t)<=sizeof(FlashJournal_t)?1:-1];
00141 
00142 #ifdef __cplusplus
00143 }
00144 #endif // __cplusplus
00145 
00146 #endif /* __FLASH_JOURNAL_PRIVATE_H__ */