1 /* 2 * xlogrecord.h 3 * 4 * Definitions for the WAL record format. 5 * 6 * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group 7 * Portions Copyright (c) 1994, Regents of the University of California 8 * 9 * src/include/access/xlogrecord.h 10 */ 11 #ifndef XLOGRECORD_H 12 #define XLOGRECORD_H 13 14 #include "access/rmgr.h" 15 #include "access/xlogdefs.h" 16 #include "port/pg_crc32c.h" 17 #include "storage/block.h" 18 #include "storage/relfilenode.h" 19 20 /* 21 * The overall layout of an XLOG record is: 22 * Fixed-size header (XLogRecord struct) 23 * XLogRecordBlockHeader struct 24 * XLogRecordBlockHeader struct 25 * ... 26 * XLogRecordDataHeader[Short|Long] struct 27 * block data 28 * block data 29 * ... 30 * main data 31 * 32 * There can be zero or more XLogRecordBlockHeaders, and 0 or more bytes of 33 * rmgr-specific data not associated with a block. XLogRecord structs 34 * always start on MAXALIGN boundaries in the WAL files, but the rest of 35 * the fields are not aligned. 36 * 37 * The XLogRecordBlockHeader, XLogRecordDataHeaderShort and 38 * XLogRecordDataHeaderLong structs all begin with a single 'id' byte. It's 39 * used to distinguish between block references, and the main data structs. 40 */ 41 typedef struct XLogRecord 42 { 43 uint32 xl_tot_len; /* total len of entire record */ 44 TransactionId xl_xid; /* xact id */ 45 XLogRecPtr xl_prev; /* ptr to previous record in log */ 46 uint8 xl_info; /* flag bits, see below */ 47 RmgrId xl_rmid; /* resource manager for this record */ 48 /* 2 bytes of padding here, initialize to zero */ 49 pg_crc32c xl_crc; /* CRC for this record */ 50 51 /* XLogRecordBlockHeaders and XLogRecordDataHeader follow, no padding */ 52 53 } XLogRecord; 54 55 #define SizeOfXLogRecord (offsetof(XLogRecord, xl_crc) + sizeof(pg_crc32c)) 56 57 /* 58 * The high 4 bits in xl_info may be used freely by rmgr. The 59 * XLR_SPECIAL_REL_UPDATE bit can be passed by XLogInsert caller. The rest 60 * are set internally by XLogInsert. 61 */ 62 #define XLR_INFO_MASK 0x0F 63 #define XLR_RMGR_INFO_MASK 0xF0 64 65 /* 66 * If a WAL record modifies any relation files, in ways not covered by the 67 * usual block references, this flag is set. This is not used for anything 68 * by PostgreSQL itself, but it allows external tools that read WAL and keep 69 * track of modified blocks to recognize such special record types. 70 */ 71 #define XLR_SPECIAL_REL_UPDATE 0x01 72 73 /* 74 * Header info for block data appended to an XLOG record. 75 * 76 * 'data_length' is the length of the rmgr-specific payload data associated 77 * with this block. It does not include the possible full page image, nor 78 * XLogRecordBlockHeader struct itself. 79 * 80 * Note that we don't attempt to align the XLogRecordBlockHeader struct! 81 * So, the struct must be copied to aligned local storage before use. 82 */ 83 typedef struct XLogRecordBlockHeader 84 { 85 uint8 id; /* block reference ID */ 86 uint8 fork_flags; /* fork within the relation, and flags */ 87 uint16 data_length; /* number of payload bytes (not including page 88 * image) */ 89 90 /* If BKPBLOCK_HAS_IMAGE, an XLogRecordBlockImageHeader struct follows */ 91 /* If BKPBLOCK_SAME_REL is not set, a RelFileNode follows */ 92 /* BlockNumber follows */ 93 } XLogRecordBlockHeader; 94 95 #define SizeOfXLogRecordBlockHeader (offsetof(XLogRecordBlockHeader, data_length) + sizeof(uint16)) 96 97 /* 98 * Additional header information when a full-page image is included 99 * (i.e. when BKPBLOCK_HAS_IMAGE is set). 100 * 101 * As a trivial form of data compression, the XLOG code is aware that 102 * PG data pages usually contain an unused "hole" in the middle, which 103 * contains only zero bytes. If the length of "hole" > 0 then we have removed 104 * such a "hole" from the stored data (and it's not counted in the 105 * XLOG record's CRC, either). Hence, the amount of block data actually 106 * present is BLCKSZ - the length of "hole" bytes. 107 * 108 * When wal_compression is enabled, a full page image which "hole" was 109 * removed is additionally compressed using PGLZ compression algorithm. 110 * This can reduce the WAL volume, but at some extra cost of CPU spent 111 * on the compression during WAL logging. In this case, since the "hole" 112 * length cannot be calculated by subtracting the number of page image bytes 113 * from BLCKSZ, basically it needs to be stored as an extra information. 114 * But when no "hole" exists, we can assume that the "hole" length is zero 115 * and no such an extra information needs to be stored. Note that 116 * the original version of page image is stored in WAL instead of the 117 * compressed one if the number of bytes saved by compression is less than 118 * the length of extra information. Hence, when a page image is successfully 119 * compressed, the amount of block data actually present is less than 120 * BLCKSZ - the length of "hole" bytes - the length of extra information. 121 */ 122 typedef struct XLogRecordBlockImageHeader 123 { 124 uint16 length; /* number of page image bytes */ 125 uint16 hole_offset; /* number of bytes before "hole" */ 126 uint8 bimg_info; /* flag bits, see below */ 127 128 /* 129 * If BKPIMAGE_HAS_HOLE and BKPIMAGE_IS_COMPRESSED, an 130 * XLogRecordBlockCompressHeader struct follows. 131 */ 132 } XLogRecordBlockImageHeader; 133 134 #define SizeOfXLogRecordBlockImageHeader \ 135 (offsetof(XLogRecordBlockImageHeader, bimg_info) + sizeof(uint8)) 136 137 /* Information stored in bimg_info */ 138 #define BKPIMAGE_HAS_HOLE 0x01 /* page image has "hole" */ 139 #define BKPIMAGE_IS_COMPRESSED 0x02 /* page image is compressed */ 140 141 /* 142 * Extra header information used when page image has "hole" and 143 * is compressed. 144 */ 145 typedef struct XLogRecordBlockCompressHeader 146 { 147 uint16 hole_length; /* number of bytes in "hole" */ 148 } XLogRecordBlockCompressHeader; 149 150 #define SizeOfXLogRecordBlockCompressHeader \ 151 sizeof(XLogRecordBlockCompressHeader) 152 153 /* 154 * Maximum size of the header for a block reference. This is used to size a 155 * temporary buffer for constructing the header. 156 */ 157 #define MaxSizeOfXLogRecordBlockHeader \ 158 (SizeOfXLogRecordBlockHeader + \ 159 SizeOfXLogRecordBlockImageHeader + \ 160 SizeOfXLogRecordBlockCompressHeader + \ 161 sizeof(RelFileNode) + \ 162 sizeof(BlockNumber)) 163 164 /* 165 * The fork number fits in the lower 4 bits in the fork_flags field. The upper 166 * bits are used for flags. 167 */ 168 #define BKPBLOCK_FORK_MASK 0x0F 169 #define BKPBLOCK_FLAG_MASK 0xF0 170 #define BKPBLOCK_HAS_IMAGE 0x10 /* block data is an XLogRecordBlockImage */ 171 #define BKPBLOCK_HAS_DATA 0x20 172 #define BKPBLOCK_WILL_INIT 0x40 /* redo will re-init the page */ 173 #define BKPBLOCK_SAME_REL 0x80 /* RelFileNode omitted, same as previous */ 174 175 /* 176 * XLogRecordDataHeaderShort/Long are used for the "main data" portion of 177 * the record. If the length of the data is less than 256 bytes, the short 178 * form is used, with a single byte to hold the length. Otherwise the long 179 * form is used. 180 * 181 * (These structs are currently not used in the code, they are here just for 182 * documentation purposes). 183 */ 184 typedef struct XLogRecordDataHeaderShort 185 { 186 uint8 id; /* XLR_BLOCK_ID_DATA_SHORT */ 187 uint8 data_length; /* number of payload bytes */ 188 } XLogRecordDataHeaderShort; 189 190 #define SizeOfXLogRecordDataHeaderShort (sizeof(uint8) * 2) 191 192 typedef struct XLogRecordDataHeaderLong 193 { 194 uint8 id; /* XLR_BLOCK_ID_DATA_LONG */ 195 /* followed by uint32 data_length, unaligned */ 196 } XLogRecordDataHeaderLong; 197 198 #define SizeOfXLogRecordDataHeaderLong (sizeof(uint8) + sizeof(uint32)) 199 200 /* 201 * Block IDs used to distinguish different kinds of record fragments. Block 202 * references are numbered from 0 to XLR_MAX_BLOCK_ID. A rmgr is free to use 203 * any ID number in that range (although you should stick to small numbers, 204 * because the WAL machinery is optimized for that case). A couple of ID 205 * numbers are reserved to denote the "main" data portion of the record. 206 * 207 * The maximum is currently set at 32, quite arbitrarily. Most records only 208 * need a handful of block references, but there are a few exceptions that 209 * need more. 210 */ 211 #define XLR_MAX_BLOCK_ID 32 212 213 #define XLR_BLOCK_ID_DATA_SHORT 255 214 #define XLR_BLOCK_ID_DATA_LONG 254 215 #define XLR_BLOCK_ID_ORIGIN 253 216 217 #endif /* XLOGRECORD_H */ 218