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
|
/* SPDX-License-Identifier: LGPL-3.0-or-later */
/*
* block_writer.h - This file is part of libsquashfs
*
* Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
#ifndef SQFS_BLOCK_WRITER_H
#define SQFS_BLOCK_WRITER_H
#include "sqfs/predef.h"
/**
* @file block_writer.h
*
* @brief Contains declarations for the @ref sqfs_block_writer_t structure.
*/
/**
* @struct sqfs_block_writer_t
*
* @brief Abstracts writing and deduplicating of data and fragment blocks.
*/
/**
* @struct sqfs_block_hooks_t
*
* @brief A set of hooks for tapping into the data writer.
*
* This structure can be registered with an @ref sqfs_block_writer_t and
* contains function pointers that will be called during various stages
* when writing data to disk.
*
* The callbacks can not only be used for accounting but may also write extra
* data to the output file or make modifications to the blocks before they are
* writtien.
*
* The callbacks can be individually set to NULL to disable them.
*/
struct sqfs_block_hooks_t {
/**
* @brief Set this to the size of the struct.
*
* This is required for future expandabillity while maintaining ABI
* compatibillity. At the current time, the implementation of
* @ref sqfs_block_writer_set_hooks rejects any hook struct where
* this isn't the exact size. If new hooks are added in the future,
* the struct grows and the future implementation can tell by the size
* whether the application uses the new version or the old one.
*/
size_t size;
/**
* @brief Gets called before writing a block to disk.
*
* If this is not NULL, it gets called before a block is written to
* disk. If the block has the @ref SQFS_BLK_ALIGN flag set, the
* function is called before padding the file.
*
* The function may modify the block itself or write data to the file.
* which is taken into account when padding the file.
*
* @param user A user pointer.
* @param block The block that is about to be written.
* @param file The file that the block will be written to.
*/
void (*pre_block_write)(void *user, sqfs_block_t *block,
sqfs_file_t *file);
/**
* @brief Gets called after writing a block to disk.
*
* If this is not NULL, it gets called after a block is written to
* disk. If the block has the @ref SQFS_BLK_ALIGN flag set, the
* function is called before padding the file.
*
* Modifying the block is rather pointless, but the function may
* write data to the file which is taken into account when padding
* the file.
*
* @param user A user pointer.
* @param block The block that is about to be written.
* @param file The file that the block was written to.
*/
void (*post_block_write)(void *user, const sqfs_block_t *block,
sqfs_file_t *file);
/**
* @brief Gets called before storing a fragment in a fragment block.
*
* The function can modify the block before it is stored.
*
* @param user A user pointer.
* @param block The data chunk that is about to be merged into the
* fragment block.
*/
void (*pre_fragment_store)(void *user, sqfs_block_t *block);
/**
* @brief Gets called if block deduplication managed to get
* rid of the data blocks of a file.
*
* @param user A user pointer.
* @param count The number of blocks that have been erased.
* @param bytes The number of bytes that have been erased. Includes
* potential padding before and after the end.
*/
void (*notify_blocks_erased)(void *user, size_t count,
sqfs_u64 bytes);
/**
* @brief Gets called before throwing away a fragment that turned out
* to be a duplicate.
*
* @param user A user pointer.
* @param block The data chunk that is about to be merged into the
* fragment block.
*/
void (*notify_fragment_discard)(void *user, const sqfs_block_t *block);
/**
* @brief Gets called before writing a block of padding bytes to disk.
*
* @param user A user pointer.
* @param block The padding bytes that are about to be written.
* @param count The number of padding bytes in the block.
*/
void (*prepare_padding)(void *user, sqfs_u8 *block, size_t count);
};
/**
* @struct sqfs_block_writer_stats_t
*
* @brief Collects run time statistics of the @ref sqfs_block_writer_t
*/
struct sqfs_block_writer_stats_t {
/**
* @brief Holds the size of the structure.
*
* If a later version of libsquashfs expands this structure, the value
* of this field can be used to check at runtime whether the newer
* fields are avaialable or not.
*/
size_t size;
/**
* @brief Total number of bytes submitted, including blocks that were
* removed by deduplication and not counting any padding.
*/
sqfs_u64 bytes_submitted;
/**
* @brief Actual number of bytes written to disk, excluding deduplicated
* blocks and including padding.
*/
sqfs_u64 bytes_written;
/**
* @brief Total number of submitted blocks, including ones later
* removed by deduplication.
*/
sqfs_u64 blocks_submitted;
/**
* @brief Total number of blocks actually written, excluding
* deduplicated blocks.
*/
sqfs_u64 blocks_written;
};
#ifdef __cplusplus
extern "C" {
#endif
SQFS_API sqfs_block_writer_t *sqfs_block_writer_create(sqfs_file_t *file,
size_t devblksz,
sqfs_u32 flags);
SQFS_API int sqfs_block_writer_set_hooks(sqfs_block_writer_t *wr,
void *user_ptr,
const sqfs_block_hooks_t *hooks);
SQFS_API void sqfs_block_writer_destroy(sqfs_block_writer_t *wr);
SQFS_API int sqfs_block_writer_write(sqfs_block_writer_t *wr,
sqfs_block_t *block,
sqfs_u64 *location);
SQFS_API const sqfs_block_writer_stats_t
*sqfs_block_writer_get_stats(const sqfs_block_writer_t *wr);
#ifdef __cplusplus
}
#endif
#endif /* SQFS_BLOCK_WRITER_H */
|
