summaryrefslogtreecommitdiffstats
path: root/include/iprt/formats/apfs.h
blob: 7d5f146299b9942362ccdc005626544ab83df836 (plain)
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
/* $Id: apfs.h $ */
/** @file
 * IPRT, APFS (Apple File System) format.
 */

/*
 * Copyright (C) 2019-2023 Oracle and/or its affiliates.
 *
 * This file is part of VirtualBox base platform packages, as
 * available from https://www.virtualbox.org.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation, in version 3 of the
 * License.
 *
 * 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 General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses>.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
 * in the VirtualBox distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
 */

#ifndef IPRT_INCLUDED_formats_apfs_h
#define IPRT_INCLUDED_formats_apfs_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <iprt/types.h>
#include <iprt/assertcompile.h>


/** @defgroup grp_rt_formats_apfs    Apple File System structures and definitions
 * @ingroup grp_rt_formats
 * @{
 */

/*
 * The filesystem structures were retrieved from:
 * https://developer.apple.com/support/downloads/Apple-File-System-Reference.pdf
 */

/** Physical address of an on-disk block. */
typedef int64_t                 APFSPADDR;
/** Object identifier. */
typedef uint64_t                APFSOID;
/** Transaction identifier. */
typedef uint64_t                APFSXID;

/** Invalid object ID. */
#define APFS_OID_INVALID        UINT64_C(0)
/** Number of reserved object IDs for special structures. */
#define APFS_OID_RSVD_CNT       1024
/** Object ID of a super block. */
#define APFS_OID_NX_SUPERBLOCK  UINT64_C(1)


/**
 * Range of physical addresses.
 */
typedef struct
{
    /** Start address of the range. */
    APFSPADDR                   PAddrStart;
    /** Size of the range in blocks.*/
    uint64_t                    cBlocks;
} APFSPRANGE;
/** Pointer to a APFS range. */
typedef APFSPRANGE *PAPFSPRANGE;
/** Pointer to a const APFS range. */
typedef const APFSPRANGE *PCAPFSPRANGE;

/** APFS UUID (compatible with our UUID definition). */
typedef RTUUID                  APFSUUID;

/** Maximum object checksum size. */
#define APFS_OBJ_MAX_CHKSUM_SZ  8

/**
 * APFS Object header.
 */
typedef struct APFSOBJPHYS
{
    /** The stored checksum of the object. */
    uint8_t                     abChkSum[APFS_OBJ_MAX_CHKSUM_SZ];
    /** Object ID. */
    APFSOID                     Oid;
    /** Transaction ID. */
    APFSXID                     Xid;
    /** Object type. */
    uint32_t                    u32Type;
    /** Object sub type. */
    uint32_t                    u32SubType;
} APFSOBJPHYS;
/** Pointer to an APFS object header. */
typedef APFSOBJPHYS *PAPFSOBJPHYS;
/** Pointer to a const APFS object header. */
typedef const APFSOBJPHYS *PCAPFSOBJPHYS;

#define APFS_OBJECT_TYPE_MASK         UINT32_C(0x0000ffff)
#define APFS_OBJECT_TYPE_FLAGS_MASK   UINT32_C(0xffff0000)

/**
 * APFS EFI jumpstart information.
 */
typedef struct APFSEFIJMPSTART
{
    /** Object header. */
    APFSOBJPHYS                 ObjHdr;
    /** The magic value. */
    uint32_t                    u32Magic;
    /** The version of the structure. */
    uint32_t                    u32Version;
    /** EFI file length in bytes. */
    uint32_t                    cbEfiFile;
    /** Number of extents describing the on disk blocks the file is stored in. */
    uint32_t                    cExtents;
    /** Reserved. */
    uint64_t                    au64Rsvd0[16];
    /** After this comes a variable size of APFSPRANGE extent structures. */
} APFSEFIJMPSTART;
/** Pointer to an APFS EFI jumpstart structure. */
typedef APFSEFIJMPSTART *PAPFSEFIJMPSTART;
/** Pointer to a const APFS EFI jumpstart structure. */
typedef const APFSEFIJMPSTART *PCAPFSEFIJMPSTART;

/** EFI jumpstart magic ('RDSJ'). */
#define APFS_EFIJMPSTART_MAGIC             RT_MAKE_U32_FROM_U8('J', 'S', 'D', 'R')
/** EFI jumpstart version. */
#define APFS_EFIJMPSTART_VERSION           UINT32_C(1)

/** Maximum number of filesystems supported in a single container. */
#define APFS_NX_SUPERBLOCK_FS_MAX          UINT32_C(100)
/** Maximum number of counters in the superblock. */
#define APFS_NX_SUPERBLOCK_COUNTERS_MAX    UINT32_C(32)
/** Number of entries in the ephemeral information array. */
#define APFS_NX_SUPERBLOCK_EPH_INFO_COUNT  UINT32_C(4)

/**
 * APFS super block.
 */
typedef struct
{
    /** Object header. */
    APFSOBJPHYS                 ObjHdr;
    /** The magic value. */
    uint32_t                    u32Magic;
    /** Block size in bytes. */
    uint32_t                    cbBlock;
    /** Number of blocks in the volume. */
    uint64_t                    cBlocks;
    /** Feature flags of the volume. */
    uint64_t                    fFeatures;
    /** Readonly compatible features. */
    uint64_t                    fRdOnlyCompatFeatures;
    /** Incompatible features. */
    uint64_t                    fIncompatFeatures;
    /** UUID of the volume. */
    APFSUUID                    Uuid;
    /** Next free object identifier to use for new objects. */
    APFSOID                     OidNext;
    /** Next free transaction identifier to use for new transactions. */
    APFSOID                     XidNext;
    /** Number of blocks used by the checkpoint descriptor area. */
    uint32_t                    cXpDescBlocks;
    /** Number of blocks used by the checkpoint data area. */
    uint32_t                    cXpDataBlocks;
    /** Base address of checkpoint descriptor area. */
    APFSPADDR                   PAddrXpDescBase;
    /** Base address of checkpoint data area. */
    APFSPADDR                   PAddrXpDataBase;
    /** Next index to use in the checkpoint descriptor area. */
    uint32_t                    idxXpDescNext;
    /** Next index to use in the checkpoint data area. */
    uint32_t                    idxXpDataNext;
    /** Number of blocks in the checkpoint descriptor area used by the checkpoint that this superblock belongs to. */
    uint32_t                    cXpDescLen;
    /** Index of the first valid item in the checkpoint data area. */
    uint32_t                    idxXpDataFirst;
    /** Number of blocks in the checkpoint data area used by the checkpoint that this superblock belongs to. */
    uint32_t                    cXpDataLen;
    /** Ephemeral object identifer of the space manager. */
    APFSOID                     OidSpaceMgr;
    /** Physical object identifier for the containers object map. */
    APFSOID                     OidOMap;
    /** Ephemeral object identifer for the reaper. */
    APFSOID                     OidReaper;
    /** Reserved for testing should be always zero on disk. */
    uint32_t                    u32TestType;
    /** Maximum number of filesystems which can be stored in this container. */
    uint32_t                    cFsMax;
    /** Array of filesystem object identifiers. */
    APFSOID                     aFsOids[APFS_NX_SUPERBLOCK_FS_MAX];
    /** Array of counters primarily used during debugging. */
    uint64_t                    aCounters[APFS_NX_SUPERBLOCK_COUNTERS_MAX];
    /** Range of blocks where no space will be allocated, used for shrinking a partition. */
    APFSPRANGE                  RangeBlocked;
    /** Physical object identifier of a tree keeping track of objects needing to be moved out of the block range. */
    APFSOID                     OidTreeEvictMapping;
    /** Container flags. */
    uint64_t                    fFlags;
    /** Address of the EFI jumpstart structure. */
    APFSPADDR                   PAddrEfiJmpStart;
    /** UUID of the containers Fusion set if available. */
    APFSUUID                    UuidFusion;
    /** Address of the containers keybag. */
    APFSPADDR                   PAddrKeyLocker;
    /** Array of fields used in the management of ephemeral data. */
    uint64_t                    au64EphemeralInfo[APFS_NX_SUPERBLOCK_EPH_INFO_COUNT];
    /** Reserved for testing. */
    APFSOID                     OidTest;
    /** Physical object identifier of the Fusion middle tree. */
    APFSOID                     OidFusionMt;
    /** Ephemeral object identifier of the Fusion write-back cache state. */
    APFSOID                     OidFusionWbc;
    /** Blocks used for the Fusion write-back cache area. */
    APFSPRANGE                  RangeFusionWbc;
} APFSNXSUPERBLOCK;
/** Pointer to a APFS super block structure. */
typedef APFSNXSUPERBLOCK *PAPFSNXSUPERBLOCK;
/** Pointer to a const APFS super block structure. */
typedef const APFSNXSUPERBLOCK *PCAPFSNXSUPERBLOCK;

/** Superblock magic value ('BSXN'). */
#define APFS_NX_SUPERBLOCK_MAGIC           RT_MAKE_U32_FROM_U8('N', 'X', 'S', 'B')

/** @} */

#endif /* !IPRT_INCLUDED_formats_apfs_h */