1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef NVRAM_CORE_STORAGE_H_ 18 #define NVRAM_CORE_STORAGE_H_ 19 20 extern "C" { 21 #include <stdint.h> 22 } // extern "C" 23 24 #include <nvram/messages/blob.h> 25 26 namespace nvram { 27 namespace storage { 28 29 // Indicates the result of a storage operation. 30 enum class Status { 31 kSuccess, // Operation successful. 32 kNotFound, // The element to be read could not be found. 33 kStorageError, // Failure on the underlying storage layer. 34 }; 35 36 // Load NVRAM header from storage. See the comment on LoadSpace() for details on 37 // semantics and return values. 38 Status LoadHeader(Blob* blob); 39 40 // Write the binary-encoded NVRAM header |blob| to storage. See the comment on 41 // StoreSpace() for details on semantics and return values. 42 Status StoreHeader(const Blob& blob); 43 44 // Load NVRAM space data for a given index from storage. 45 // 46 // This must place the data in |blob| that was provided by the last store 47 // operation If there is evidence that no header data is present in the storage 48 // system, this function must return Status::kNotFound. For all other error 49 // conditions, implementations should return Status::kStorageError. 50 // 51 // It's OK if the data placed in |blob| exceeds the size of the original data, 52 // i.e. contain trailing bytes that haven't actually been written. This allows 53 // implementations to write at block granularity of the underlying storage 54 // system, which may be simpler instead of having to track sizes accurately. 55 Status LoadSpace(uint32_t index, Blob* blob); 56 57 // Write the NVRAM space data for the given index to storage. 58 // 59 // Implementations must atomically replace the current data with the data 60 // provided in |blob|. This must be robust against crashes, i.e. reloading the 61 // data after the crash should either return the previous version of the data, 62 // or the updated data provided in |blob|. In particular, crashes must not 63 // result in any form of data corruption or loss. 64 // 65 // It's OK for the implementation to allocate a larger storage area than 66 // required, i.e. not match blob.size() accurately. This allows implementations 67 // to perform I/O at block granularity of the underlying storage subsystem in 68 // case this simplifies things. There is no requirement as to the values of any 69 // additional trailing bytes. 70 // 71 // This function must make sure that the data actually hits disk before 72 // returning. The return value must be Status::kSuccess if and only if data was 73 // stored successfully, the function should return kStorageError otherwise. 74 Status StoreSpace(uint32_t index, const Blob& blob); 75 76 // Delete the stored NVRAM space data for the given index. 77 // 78 // This function must atomically delete the storage corresponding to the NVRAM 79 // space data associated with index. A subsequent read operation for the same 80 // index should return Status::kNotFound. 81 // 82 // This function must be robust in the event of crashes, i.e. a crash should 83 // leave the system with either the previously existing data still intact and 84 // accessible, or the space data entirely removed. 85 // 86 // This function must return Status::kSuccess upon deleting the space data 87 // successfully and having committed that operation to the underlying storage 88 // medium. Status::kNotFound should be returned in case the space data 89 // positively doesn't exist on the medium, and Status::kStorageError should be 90 // returned for all other error conditions. 91 Status DeleteSpace(uint32_t index); 92 93 } // namespace storage 94 } // namespace nvram 95 96 #endif // NVRAM_CORE_STORAGE_H 97