1 /* 2 * Copyright (C) 2015-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 #pragma once 18 19 #include <lk/compiler.h> 20 #include <stdbool.h> 21 #include <stdint.h> 22 #include <sys/types.h> 23 #include <trusty_ipc.h> 24 25 #include <interface/storage/storage.h> 26 27 #define STORAGE_MAX_NAME_LENGTH_BYTES 159 28 29 __BEGIN_CDECLS 30 31 typedef handle_t storage_session_t; 32 typedef uint64_t file_handle_t; 33 typedef uint64_t storage_off_t; 34 35 struct storage_open_dir_state; 36 37 #define STORAGE_INVALID_SESSION ((storage_session_t)INVALID_IPC_HANDLE) 38 39 /** 40 * storage_ops_flags - storage related operation flags 41 * @STORAGE_OP_COMPLETE: forces to commit current transaction 42 * @STORAGE_OP_CHECKPOINT: checkpoint file-system state during transaction 43 * commit (only valid when committing a transaction and 44 * only allowed if provisioning is allowed) 45 * @STORAGE_OP_FS_REPAIRED_ACK: acknowledge that an error in the file system may 46 * have been repaired, and therefore rollback may 47 * have occurred. Do not use this flag unless 48 * accessing files where partial rollback of file 49 * system state is acceptable. 50 */ 51 #define STORAGE_OP_COMPLETE 0x1U 52 #define STORAGE_OP_CHECKPOINT 0x2U 53 #define STORAGE_OP_FS_REPAIRED_ACK 0x4U 54 55 /** 56 * storage_open_session() - Opens a storage session. 57 * @session_p: pointer to location in which to store session handle 58 * in case of success. 59 * @type: One of STORAGE_CLIENT_TD_PORT, STORAGE_CLIENT_TDEA_PORT or 60 * STORAGE_CLIENT_TP_PORT. 61 * 62 * Return: NO_ERROR on success, or an error code < 0 on failure. 63 */ 64 int storage_open_session(storage_session_t* session_p, const char* type); 65 66 /** 67 * storage_close_session() - Closes the session. 68 * @session: the session to close 69 * 70 */ 71 void storage_close_session(storage_session_t session); 72 73 /** 74 * storage_open_file() - Opens a file 75 * @session: the storage_session_t returned from a call to storage_open_session 76 * @handle_p: pointer to location in which to store file handle in case of 77 * success 78 * @name: a null-terminated string identifier of the file to open. 79 * Cannot be more than STORAGE_MAX_NAME_LENGTH_BYTES in length. 80 * @flags: A bitmask consisting any storage_file_flag value or'ed together: 81 * - STORAGE_FILE_OPEN_CREATE: if this file does not exist, create it. 82 * - STORAGE_FILE_OPEN_CREATE_EXCLUSIVE: when specified, opening file with 83 * STORAGE_OPEN_FILE_CREATE flag will 84 * fail if the file already exists. 85 * Only meaningful if used in combination 86 * with STORAGE_FILE_OPEN_CREATE flag. 87 * - STORAGE_FILE_OPEN_TRUNCATE: if this file already exists, discard existing 88 * content and open it as a new file. No change 89 * in semantics if the file does not exist. 90 * @opflags: a combination of @storage_op_flags 91 * 92 * Return: NO_ERROR on success, or an error code < 0 on failure. 93 */ 94 int storage_open_file(storage_session_t session, 95 file_handle_t* handle_p, 96 const char* name, 97 uint32_t flags, 98 uint32_t opflags); 99 100 /** 101 * storage_close_file() - Closes a file. 102 * @handle: the file_handle_t retrieved from storage_open_file 103 * 104 */ 105 void storage_close_file(file_handle_t handle); 106 107 /** 108 * storage_move_file - Moves/renames a file. 109 * @session: storage_session_t returned from a call to storage_open_session. 110 * @handle: file_handle_t retrieved from storage_open_file, if @flags 111 * contains STORAGE_FILE_MOVE_OPEN_FILE. 112 * @old_name: the current name of the file to move 113 * @new_name: the new name that the file should be moved to. 114 * @flags: A bitmask consisting any storage_file_flag value or'ed together: 115 * - STORAGE_FILE_MOVE_CREATE: if a file does not exist at @new_name, 116 * create it. 117 * - STORAGE_FILE_MOVE_CREATE_EXCLUSIVE: when specified, opening file with 118 * STORAGE_OPEN_MOVE_CREATE flag will 119 * fail if the file already exists. 120 * Only meaningful if used in combination 121 * with STORAGE_FILE_MOVE_CREATE flag. 122 * - STORAGE_FILE_MOVE_OPEN_FILE: The file is already open as @handle. 123 * @opflags: a combination of @storage_op_flags 124 * 125 * Return: 0 on success, or an error code < 0 on failure. 126 */ 127 int storage_move_file(storage_session_t session, 128 file_handle_t handle, 129 const char* old_name, 130 const char* new_name, 131 uint32_t flags, 132 uint32_t opflags); 133 134 /** 135 * storage_delete_file - Deletes a file. 136 * @session: the storage_session_t returned from a call to storage_open_session 137 * @name: the name of the file to delete 138 * @opflags: a combination of @storage_op_flags 139 * 140 * Return: 0 on success, or an error code < 0 on failure. 141 */ 142 int storage_delete_file(storage_session_t session, 143 const char* name, 144 uint32_t opflags); 145 146 /** 147 * storage_open_dir - Open directory. 148 * @session: the storage_session_t returned from a call to storage_open_session 149 * @path: Must be "" or %NULL. 150 * @state: Pointer to return state object in. 151 * 152 * Return: 0 on success, or an error code < 0 on failure. 153 */ 154 155 int storage_open_dir(storage_session_t session, 156 const char* path, 157 struct storage_open_dir_state** state); 158 159 /** 160 * storage_close_dir() - Close open directory iterator. 161 * @session: the storage_session_t returned from a call to storage_open_session 162 * @state: directory state object retrieved from storage_open_dir 163 */ 164 void storage_close_dir(storage_session_t session, 165 struct storage_open_dir_state* state); 166 167 /** 168 * storage_read_dir() - Read a file name from directory. 169 * @session: the storage_session_t returned from a call to 170 * storage_open_session 171 * @state: directory state object retrieved from storage_open_dir 172 * @flags: storage_file_list_flag for committed, added, removed or end. 173 * @name: buffer to write file name info. 174 * @name_size: size of @name buffer. 175 * 176 * Return: The number of bytes written to @name if another directory entry was 177 * read. Note that this is the length of the string written to @name plus one to 178 * account for the terminating nul byte. Returns 0 If @flags is 179 * STORAGE_FILE_LIST_END, i.e. there are no more directory entries to list. 180 */ 181 int storage_read_dir(storage_session_t session, 182 struct storage_open_dir_state* state, 183 uint8_t* flags, 184 char* name, 185 size_t name_size); 186 187 /** 188 * storage_read() - Reads a file at a given offset. 189 * @handle: the file_handle_t retrieved from storage_open_file 190 * @off: the start offset from whence to read in the file 191 * @buf: the buffer in which to write the data read 192 * @size: the size of buf and number of bytes to read 193 * 194 * Return: the number of bytes read on success, negative error code on failure 195 * 196 */ 197 ssize_t storage_read(file_handle_t handle, 198 storage_off_t off, 199 void* buf, 200 size_t size); 201 202 /** 203 * storage_write() - Writes to a file at a given offset. Grows the file if 204 * necessary. 205 * @handle: the file_handle_t retrieved from storage_open_file 206 * @off: the start offset from whence to write in the file 207 * @buf: the buffer containing the data to write 208 * @size: the size of buf and number of bytes to write 209 * @opflags: a combination of @storage_op_flags 210 * 211 * Return: the number of bytes written on success, negative error code on 212 * failure 213 */ 214 ssize_t storage_write(file_handle_t handle, 215 storage_off_t off, 216 const void* buf, 217 size_t size, 218 uint32_t opflags); 219 220 /** 221 * storage_set_file_size() - Sets the size of the file. 222 * @handle: the file_handle_t retrieved from storage_open_file 223 * @off: the number of bytes to set as the new size of the file 224 * @opflags: a combination of @storage_op_flags 225 * 226 * Return: NO_ERROR on success, negative error code on failure. 227 */ 228 int storage_set_file_size(file_handle_t handle, 229 storage_off_t file_size, 230 uint32_t opflags); 231 232 /** 233 * storage_get_file_size() - Gets the size of the file. 234 * @handle: the file_handle_t retrieved from storage_open_file 235 * @size: pointer to storage_off_t in which to store the file size 236 * 237 * Return: NO_ERROR on success, negative error code on failure. 238 */ 239 int storage_get_file_size(file_handle_t handle, storage_off_t* size); 240 241 /** 242 * storage_end_transaction: End current transaction 243 * @session: the storage_session_t returned from a call to storage_open_session 244 * @complete: if true, commit current transaction, discard it otherwise 245 * 246 * Return: 0 on success, negative error code on failure. 247 */ 248 int storage_end_transaction(storage_session_t session, bool complete); 249 250 /** 251 * storage_commit_checkpoint: Commit current transaction and add to checkpoint 252 * @session: the storage_session_t returned from a call to storage_open_session 253 * 254 * Commits the changes in the current transaction and updates the currently 255 * checkpointed state of all files modified by the transaction to their state 256 * after the current transaction commits. Checkpoints are only allowed to be 257 * made when provisioning is allowed. 258 * 259 * Return: 0 on success, negative error code on failure. 260 */ 261 int storage_commit_checkpoint(storage_session_t session); 262 263 __END_CDECLS 264