1 /* 2 * Copyright (C) 2024 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 #pragma once 17 18 #include <stdint.h> 19 20 #include <interface/storage/storage.h> 21 #include <lk/compiler.h> 22 #include <uapi/trusty_uuid.h> 23 24 #include "client_session.h" 25 #include "file.h" 26 27 /** 28 * struct storage_op_flags - Flags shared by all storage operations 29 * @allow_repaired: If true, encountering a repaired filesystem will _not_ 30 * result in an error. 31 * @complete_transaction: If true, complete the currently active transaction 32 * after performing this operation. 33 * @update_checkpoint: If true, update the checkpoint with the post-operation 34 * filesystem state. 35 */ 36 struct storage_op_flags { 37 bool allow_repaired; 38 bool complete_transaction; 39 bool update_checkpoint; 40 }; 41 42 __BEGIN_CDECLS 43 44 /** 45 * storage_client_session_init() - Initialize a new &struct 46 * storage_client_session. 47 * @session: The session to be initialized. 48 * @fs: The filesystem this session will modify. 49 * @peer: Id of the peer this session was created for. 50 */ 51 void storage_client_session_init(struct storage_client_session* session, 52 struct fs* fs, 53 const uuid_t* peer); 54 55 /** 56 * storage_client_session_destroy() - Destroy a &struct storage_client_session. 57 * @session: The session to be destroyed. 58 */ 59 void storage_client_session_destroy(struct storage_client_session* session); 60 61 /** 62 * storage_transaction_end() - End the currently active transaction and start a 63 * new one. If @flags.complete_transaction is true, try to complete the current 64 * transaction. Otherwise, abandon it. 65 * @session: The session to perform the operation. 66 * @flags: Flags for performing this operation. @flags.complete_transaction 67 * controls whether the transaction will be completed or abandoned; see above. 68 * See &struct storage_op_flags for further details. 69 */ 70 enum storage_err storage_transaction_end(struct storage_client_session* session, 71 struct storage_op_flags flags); 72 73 /** 74 * storage_file_delete() - Delete a file. 75 * @session: The session to perform the operation. 76 * @fname: The string containing the name of the file to be deleted. 77 * @fname_len: The length of the name of the file to be deleted. 78 * @flags: Flags for performing this operation. See &struct storage_op_flags for 79 * details. 80 */ 81 enum storage_err storage_file_delete(struct storage_client_session* session, 82 const char* fname, 83 size_t fname_len, 84 struct storage_op_flags flags); 85 86 /** 87 * storage_file_move() - Move a file from ``src`` to location ``dst``. 88 * @session: The session to perform the operation. 89 * @handle: The opened file handle for the ``src`` file. Ignored if 90 * @src_already_opened is false. 91 * @src_already_opened: True if the ``src`` file is already opened and @handle 92 * conatins its file handle. 93 * @src_name: The string containing the name of the ``src`` file. If 94 * @src_already_opened is true, this must match the name of the file @handle 95 * points to or be null. 96 * @src_name_len: The length of the @src_name. 97 * @dst_name: The string containing the name of the file's destination. 98 * @dst_name_len: The length of @dst_name. 99 * @dst_file_create_mode: Creation behavior for the ``dst`` file. 100 * @flags: Flags for performing this operation. See &struct storage_op_flags for 101 * details. 102 */ 103 enum storage_err storage_file_move(struct storage_client_session* session, 104 uint32_t handle, 105 bool src_already_opened, 106 const char* src_name, 107 size_t src_name_len, 108 const char* dst_name, 109 size_t dst_name_len, 110 enum file_create_mode dst_file_create_mode, 111 struct storage_op_flags flags); 112 113 /** 114 * storage_file_open() - Open a file and provide a handle to it. 115 * @session: The session to perform the operation. 116 * @fname: The string containing the name of the file to open. 117 * @fname_len: The length of the name of the file to open. 118 * @file_create_mode: Creation behavior for the file. 119 * @truncate: If true, clear the file's contents while opening it. 120 * @flags: Flags for performing this operation. See &struct storage_op_flags for 121 * details. 122 * @handle: Out-param that will contain the opened file's handle. Only populated 123 * on success. 124 */ 125 enum storage_err storage_file_open(struct storage_client_session* session, 126 const char* fname, 127 size_t fname_len, 128 enum file_create_mode file_create_mode, 129 bool truncate, 130 struct storage_op_flags flags, 131 uint32_t* handle); 132 133 /** 134 * storage_file_close() - Close a previously opened file. 135 * @session: The session to perform the operation. 136 * @handle: The file handle previously created by storage_file_open(). 137 * @flags: Flags for performing this operation. See &struct storage_op_flags for 138 * details. 139 */ 140 enum storage_err storage_file_close(struct storage_client_session* session, 141 uint32_t handle, 142 struct storage_op_flags flags); 143 144 /** 145 * storage_file_read() - Read a sequence of bytes from an open file. 146 * @session: The session to perform the operation. 147 * @handle: The file handle previously created by storage_file_open(). 148 * @size: The size of the byte sequence to read. 149 * @offset: The offset from the beginning of the file at which to start reading. 150 * The bytes read will be ``file[offset..offset + size]``. 151 * @flags: Flags for performing this operation. See &struct storage_op_flags for 152 * details. 153 * @resp: Out-param. The buffer into which the read bytes will be written. 154 * @resp_len: Before the calling ``*resp_len`` should contain the length of the 155 * &resp buffer. After a successful call returns, ``*resp_len`` will contain the 156 * total number of bytes written to &resp. 157 */ 158 enum storage_err storage_file_read(struct storage_client_session* session, 159 uint32_t handle, 160 uint32_t size, 161 uint64_t offset, 162 struct storage_op_flags flags, 163 uint8_t* resp, 164 size_t* resp_len); 165 166 /** 167 * storage_file_write() - Write a sequence of bytes to an open file. 168 * @session: The session to perform the operation. 169 * @handle: The file handle previously created by storage_file_open(). 170 * @offset: The offset from the beginning of the file at which to start writing. 171 * The bytes will be written to ``file[offset..offset + data.len]``. 172 * @data: Buffer containing the data to write. 173 * @data_len: Length of the data to write, in bytes. 174 * @flags: Flags for performing this operation. See &struct storage_op_flags for 175 * details. 176 */ 177 enum storage_err storage_file_write(struct storage_client_session* session, 178 uint32_t handle, 179 uint64_t offset, 180 const uint8_t* data, 181 size_t data_len, 182 struct storage_op_flags flags); 183 184 /** 185 * storage_file_list() - Lists the names of files. 186 * @session: The session to perform the operation. 187 * @max_count: The maximum number of file path entries to be recorded with 188 * @record_path. 189 * @last_state: Either %STORAGE_FILE_LIST_START or the @flags arg of the last 190 * call to @record_path during the previous call to storage_file_list(). 191 * @last_fname: Ignored if @last_state is %STORAGE_FILE_LIST_START. Otherwise, 192 * @last_fname should contain the @path arg of the last call to @record_path 193 * during the previous call to storage_file_list(). 194 * @last_fname_len: The length of @last_fname if @last_fname is present. Ignored 195 * otherwise. 196 * @flags: Flags for performing this operation. See &struct storage_op_flags for 197 * details. 198 * @can_record_path: Checks whether a path (with a length less than or equal to 199 * @can_record_path.max_path_len) can be recorded using the @record_path 200 * callback. 201 * @record_path: Records a @record_path.path that is @record_path.path_len bytes 202 * long. @record_path.path may be null if @record_path.flags is 203 * %STORAGE_FILE_LIST_END. 204 * @callback_data: Will be passed as the first argument to calls to 205 * @can_record_path and @record_path. 206 */ 207 enum storage_err storage_file_list( 208 struct storage_client_session* session, 209 uint8_t max_count, 210 enum storage_file_list_flag last_state, 211 const char* last_fname, 212 size_t last_fname_len, 213 struct storage_op_flags flags, 214 bool (*can_record_path)(void* callback_data, size_t max_path_len), 215 void (*record_path)(void* callback_data, 216 enum storage_file_list_flag flags, 217 const char* path, 218 size_t path_len), 219 void* callback_data); 220 221 /** 222 * storage_file_get_size() - Gets the size of a file. 223 * @session: The session to perform the operation. 224 * @handle: The file handle previously created by storage_file_open(). 225 * @flags: Flags for performing this operation. See &struct storage_op_flags for 226 * details. 227 * @size: Out-param. After a successful call, contains the file's size. 228 */ 229 enum storage_err storage_file_get_size(struct storage_client_session* session, 230 uint32_t handle, 231 struct storage_op_flags flags, 232 uint64_t* size); 233 234 /** 235 * storage_file_set_size() - Sets the size of a file. Truncates if the file is 236 * larger than @new_size. 237 * @session: The session to perform the operation. 238 * @handle: The file handle previously created by storage_file_open(). 239 * @new_size: The file's target size. 240 * @flags: Flags for performing this operation. See &struct storage_op_flags for 241 * details. 242 */ 243 enum storage_err storage_file_set_size(struct storage_client_session* session, 244 uint32_t handle, 245 uint64_t new_size, 246 struct storage_op_flags flags); 247 248 __END_CDECLS