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