1/* SPDX-License-Identifier: GPL-2.0-or-later */
2/*
3 * logfile.h - Defines for NTFS kernel journal ($LogFile) handling. Part of
4 * the Linux-NTFS project.
5 *
6 * Copyright (c) 2000-2005 Anton Altaparmakov
7 */
8
9#ifndef _LINUX_NTFS_LOGFILE_H
10#define _LINUX_NTFS_LOGFILE_H
11
12#ifdef NTFS_RW
13
14#include <linux/fs.h>
15
16#include "types.h"
17#include "endian.h"
18#include "layout.h"
19
20/*
21 * Journal ($LogFile) organization:
22 *
23 * Two restart areas present in the first two pages (restart pages, one restart
24 * area in each page). When the volume is dismounted they should be identical,
25 * except for the update sequence array which usually has a different update
26 * sequence number.
27 *
28 * These are followed by log records organized in pages headed by a log record
29 * header going up to log file size. Not all pages contain log records when a
30 * volume is first formatted, but as the volume ages, all records will be used.
31 * When the log file fills up, the records at the beginning are purged (by
32 * modifying the oldest_lsn to a higher value presumably) and writing begins
33 * at the beginning of the file. Effectively, the log file is viewed as a
34 * circular entity.
35 *
36 * NOTE: Windows NT, 2000, and XP all use log file version 1.1 but they accept
37 * versions <= 1.x, including 0.-1. (Yes, that is a minus one in there!) We
38 * probably only want to support 1.1 as this seems to be the current version
39 * and we don't know how that differs from the older versions. The only
40 * exception is if the journal is clean as marked by the two restart pages
41 * then it doesn't matter whether we are on an earlier version. We can just
42 * reinitialize the logfile and start again with version 1.1.
43 */
44
45/* Some $LogFile related constants. */
46#define MaxLogFileSize 0x100000000ULL
47#define DefaultLogPageSize 4096
48#define MinLogRecordPages 48
49
50/*
51 * Log file restart page header (begins the restart area).
52 */
53typedef struct {
54/*Ofs*/
55/* 0 NTFS_RECORD; -- Unfolded here as gcc doesn't like unnamed structs. */
56/* 0*/ NTFS_RECORD_TYPE magic; /* The magic is "RSTR". */
57/* 4*/ le16 usa_ofs; /* See NTFS_RECORD definition in layout.h.
58 When creating, set this to be immediately
59 after this header structure (without any
60 alignment). */
61/* 6*/ le16 usa_count; /* See NTFS_RECORD definition in layout.h. */
62
63/* 8*/ leLSN chkdsk_lsn; /* The last log file sequence number found by
64 chkdsk. Only used when the magic is changed
65 to "CHKD". Otherwise this is zero. */
66/* 16*/ le32 system_page_size; /* Byte size of system pages when the log file
67 was created, has to be >= 512 and a power of
68 2. Use this to calculate the required size
69 of the usa (usa_count) and add it to usa_ofs.
70 Then verify that the result is less than the
71 value of the restart_area_offset. */
72/* 20*/ le32 log_page_size; /* Byte size of log file pages, has to be >=
73 512 and a power of 2. The default is 4096
74 and is used when the system page size is
75 between 4096 and 8192. Otherwise this is
76 set to the system page size instead. */
77/* 24*/ le16 restart_area_offset;/* Byte offset from the start of this header to
78 the RESTART_AREA. Value has to be aligned
79 to 8-byte boundary. When creating, set this
80 to be after the usa. */
81/* 26*/ sle16 minor_ver; /* Log file minor version. Only check if major
82 version is 1. */
83/* 28*/ sle16 major_ver; /* Log file major version. We only support
84 version 1.1. */
85/* sizeof() = 30 (0x1e) bytes */
86} __attribute__ ((__packed__)) RESTART_PAGE_HEADER;
87
88/*
89 * Constant for the log client indices meaning that there are no client records
90 * in this particular client array. Also inside the client records themselves,
91 * this means that there are no client records preceding or following this one.
92 */
93#define LOGFILE_NO_CLIENT cpu_to_le16(0xffff)
94#define LOGFILE_NO_CLIENT_CPU 0xffff
95
96/*
97 * These are the so far known RESTART_AREA_* flags (16-bit) which contain
98 * information about the log file in which they are present.
99 */
100enum {
101 RESTART_VOLUME_IS_CLEAN = cpu_to_le16(0x0002),
102 RESTART_SPACE_FILLER = cpu_to_le16(0xffff), /* gcc: Force enum bit width to 16. */
103} __attribute__ ((__packed__));
104
105typedef le16 RESTART_AREA_FLAGS;
106
107/*
108 * Log file restart area record. The offset of this record is found by adding
109 * the offset of the RESTART_PAGE_HEADER to the restart_area_offset value found
110 * in it. See notes at restart_area_offset above.
111 */
112typedef struct {
113/*Ofs*/
114/* 0*/ leLSN current_lsn; /* The current, i.e. last LSN inside the log
115 when the restart area was last written.
116 This happens often but what is the interval?
117 Is it just fixed time or is it every time a
118 check point is written or somethine else?
119 On create set to 0. */
120/* 8*/ le16 log_clients; /* Number of log client records in the array of
121 log client records which follows this
122 restart area. Must be 1. */
123/* 10*/ le16 client_free_list; /* The index of the first free log client record
124 in the array of log client records.
125 LOGFILE_NO_CLIENT means that there are no
126 free log client records in the array.
127 If != LOGFILE_NO_CLIENT, check that
128 log_clients > client_free_list. On Win2k
129 and presumably earlier, on a clean volume
130 this is != LOGFILE_NO_CLIENT, and it should
131 be 0, i.e. the first (and only) client
132 record is free and thus the logfile is
133 closed and hence clean. A dirty volume
134 would have left the logfile open and hence
135 this would be LOGFILE_NO_CLIENT. On WinXP
136 and presumably later, the logfile is always
137 open, even on clean shutdown so this should
138 always be LOGFILE_NO_CLIENT. */
139/* 12*/ le16 client_in_use_list;/* The index of the first in-use log client
140 record in the array of log client records.
141 LOGFILE_NO_CLIENT means that there are no
142 in-use log client records in the array. If
143 != LOGFILE_NO_CLIENT check that log_clients
144 > client_in_use_list. On Win2k and
145 presumably earlier, on a clean volume this
146 is LOGFILE_NO_CLIENT, i.e. there are no
147 client records in use and thus the logfile
148 is closed and hence clean. A dirty volume
149 would have left the logfile open and hence
150 this would be != LOGFILE_NO_CLIENT, and it
151 should be 0, i.e. the first (and only)
152 client record is in use. On WinXP and
153 presumably later, the logfile is always
154 open, even on clean shutdown so this should
155 always be 0. */
156/* 14*/ RESTART_AREA_FLAGS flags;/* Flags modifying LFS behaviour. On Win2k
157 and presumably earlier this is always 0. On
158 WinXP and presumably later, if the logfile
159 was shutdown cleanly, the second bit,
160 RESTART_VOLUME_IS_CLEAN, is set. This bit
161 is cleared when the volume is mounted by
162 WinXP and set when the volume is dismounted,
163 thus if the logfile is dirty, this bit is
164 clear. Thus we don't need to check the
165 Windows version to determine if the logfile
166 is clean. Instead if the logfile is closed,
167 we know it must be clean. If it is open and
168 this bit is set, we also know it must be
169 clean. If on the other hand the logfile is
170 open and this bit is clear, we can be almost
171 certain that the logfile is dirty. */
172/* 16*/ le32 seq_number_bits; /* How many bits to use for the sequence
173 number. This is calculated as 67 - the
174 number of bits required to store the logfile
175 size in bytes and this can be used in with
176 the specified file_size as a consistency
177 check. */
178/* 20*/ le16 restart_area_length;/* Length of the restart area including the
179 client array. Following checks required if
180 version matches. Otherwise, skip them.
181 restart_area_offset + restart_area_length
182 has to be <= system_page_size. Also,
183 restart_area_length has to be >=
184 client_array_offset + (log_clients *
185 sizeof(log client record)). */
186/* 22*/ le16 client_array_offset;/* Offset from the start of this record to
187 the first log client record if versions are
188 matched. When creating, set this to be
189 after this restart area structure, aligned
190 to 8-bytes boundary. If the versions do not
191 match, this is ignored and the offset is
192 assumed to be (sizeof(RESTART_AREA) + 7) &
193 ~7, i.e. rounded up to first 8-byte
194 boundary. Either way, client_array_offset
195 has to be aligned to an 8-byte boundary.
196 Also, restart_area_offset +
197 client_array_offset has to be <= 510.
198 Finally, client_array_offset + (log_clients
199 * sizeof(log client record)) has to be <=
200 system_page_size. On Win2k and presumably
201 earlier, this is 0x30, i.e. immediately
202 following this record. On WinXP and
203 presumably later, this is 0x40, i.e. there
204 are 16 extra bytes between this record and
205 the client array. This probably means that
206 the RESTART_AREA record is actually bigger
207 in WinXP and later. */
208/* 24*/ sle64 file_size; /* Usable byte size of the log file. If the
209 restart_area_offset + the offset of the
210 file_size are > 510 then corruption has
211 occurred. This is the very first check when
212 starting with the restart_area as if it
213 fails it means that some of the above values
214 will be corrupted by the multi sector
215 transfer protection. The file_size has to
216 be rounded down to be a multiple of the
217 log_page_size in the RESTART_PAGE_HEADER and
218 then it has to be at least big enough to
219 store the two restart pages and 48 (0x30)
220 log record pages. */
221/* 32*/ le32 last_lsn_data_length;/* Length of data of last LSN, not including
222 the log record header. On create set to
223 0. */
224/* 36*/ le16 log_record_header_length;/* Byte size of the log record header.
225 If the version matches then check that the
226 value of log_record_header_length is a
227 multiple of 8, i.e.
228 (log_record_header_length + 7) & ~7 ==
229 log_record_header_length. When creating set
230 it to sizeof(LOG_RECORD_HEADER), aligned to
231 8 bytes. */
232/* 38*/ le16 log_page_data_offset;/* Offset to the start of data in a log record
233 page. Must be a multiple of 8. On create
234 set it to immediately after the update
235 sequence array of the log record page. */
236/* 40*/ le32 restart_log_open_count;/* A counter that gets incremented every
237 time the logfile is restarted which happens
238 at mount time when the logfile is opened.
239 When creating set to a random value. Win2k
240 sets it to the low 32 bits of the current
241 system time in NTFS format (see time.h). */
242/* 44*/ le32 reserved; /* Reserved/alignment to 8-byte boundary. */
243/* sizeof() = 48 (0x30) bytes */
244} __attribute__ ((__packed__)) RESTART_AREA;
245
246/*
247 * Log client record. The offset of this record is found by adding the offset
248 * of the RESTART_AREA to the client_array_offset value found in it.
249 */
250typedef struct {
251/*Ofs*/
252/* 0*/ leLSN oldest_lsn; /* Oldest LSN needed by this client. On create
253 set to 0. */
254/* 8*/ leLSN client_restart_lsn;/* LSN at which this client needs to restart
255 the volume, i.e. the current position within
256 the log file. At present, if clean this
257 should = current_lsn in restart area but it
258 probably also = current_lsn when dirty most
259 of the time. At create set to 0. */
260/* 16*/ le16 prev_client; /* The offset to the previous log client record
261 in the array of log client records.
262 LOGFILE_NO_CLIENT means there is no previous
263 client record, i.e. this is the first one.
264 This is always LOGFILE_NO_CLIENT. */
265/* 18*/ le16 next_client; /* The offset to the next log client record in
266 the array of log client records.
267 LOGFILE_NO_CLIENT means there are no next
268 client records, i.e. this is the last one.
269 This is always LOGFILE_NO_CLIENT. */
270/* 20*/ le16 seq_number; /* On Win2k and presumably earlier, this is set
271 to zero every time the logfile is restarted
272 and it is incremented when the logfile is
273 closed at dismount time. Thus it is 0 when
274 dirty and 1 when clean. On WinXP and
275 presumably later, this is always 0. */
276/* 22*/ u8 reserved[6]; /* Reserved/alignment. */
277/* 28*/ le32 client_name_length;/* Length of client name in bytes. Should
278 always be 8. */
279/* 32*/ ntfschar client_name[64];/* Name of the client in Unicode. Should
280 always be "NTFS" with the remaining bytes
281 set to 0. */
282/* sizeof() = 160 (0xa0) bytes */
283} __attribute__ ((__packed__)) LOG_CLIENT_RECORD;
284
285extern bool ntfs_check_logfile(struct inode *log_vi,
286 RESTART_PAGE_HEADER **rp);
287
288extern bool ntfs_is_logfile_clean(struct inode *log_vi,
289 const RESTART_PAGE_HEADER *rp);
290
291extern bool ntfs_empty_logfile(struct inode *log_vi);
292
293#endif /* NTFS_RW */
294
295#endif /* _LINUX_NTFS_LOGFILE_H */
296

source code of linux/fs/ntfs/logfile.h