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 20extern "C" { 21#include <stdint.h> 22} // extern "C" 23 24#include <nvram/messages/blob.h> 25 26namespace nvram { 27namespace storage { 28 29// Indicates the result of a storage operation. 30enum 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. 38Status 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. 42Status 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. 55Status 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. 74Status 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. 91Status DeleteSpace(uint32_t index); 92 93} // namespace storage 94} // namespace nvram 95 96#endif // NVRAM_CORE_STORAGE_H 97