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