Skip to content

Commit c92bb1f

Browse files
asdfugilasdfugil
committed
disk tutorial
1 parent 2bc9b3e commit c92bb1f

File tree

4 files changed

+247
-18
lines changed

4 files changed

+247
-18
lines changed

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ Supported firmware versions: iOS/iPadOS/tvOS 9.0 - 18.0
1616
Check [SETUP.md](./tutorials/SETUP.md). There are two methods but you are recommended
1717
to use the pongoOS method.
1818

19+
Internal storage is supported on Apple A11. Compiled [tools](./tools/README.md) are
20+
provided to help you partition the disk.
21+
1922
Click [here](./images/m1n1/README.md) to see how the screen looks like while in m1n1.
2023

2124
## Support & Community

‎features/A11.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,11 @@ These are features/hardware blocks that are present on all devices with the give
3939
| cpufreq | 6.2 / 6.15 (dts) |
4040
| USB2 Device Mode | linux-apple |
4141
| RTC | linux-apple |
42-
| NVMe | 6.18 |
42+
| NVMe | 6.18[1] |
4343
| GPU | TBA |
4444

45-
-[1]: Currently require iOS 14 or above iBoot
45+
- [1]: There are some instability which may result in the error:
46+
`duplicate tag error for tag 0, host_id 0x0. status_reg: 0x1000`
4647

4748
## A11 devices
4849

‎tools/README.md‎

Lines changed: 26 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,30 @@ They are intended to be ran under jailbroken iOS/tvOS/bridgeOS, or a SSH ramdisk
55

66
Download precompiled tools: [iOS/iPadOS](https://nightly.link/hoolocklinux/docs/workflows/build/master/hoolock-support-iphoneos.zip) | [tvOS](https://nightly.link/hoolocklinux/docs/workflows/build/master/hoolock-support-appletvos.zip) | [bridgeOS](https://nightly.link/hoolocklinux/docs/workflows/build/master/hoolock-support-bridgeos.zip)
77

8+
The recommended environment to run these tools is with [palera1n](https://palera.in) jailbreak.
9+
For older systems, [checkra1n](https://checkra.in) may be used. You need to run these tools
10+
until you can access SSH / Terminal. "Rootless" or "Rootful" does not matter. For details on
11+
jailbreaking devices, check https://ios.cfw.guide/.
12+
813
## Disk partition tools
914

1015
> [!WARNING]
1116
> These tools could potentially destroy all data on the main disk, so double check.
1217
13-
### gdisk
14-
15-
This is the usual gpt partitioning tool found on many unixes.
16-
17-
It is used to inspect and modify the partition table.
18-
19-
It should be signed with entitlements in `gdisk.xml`.
20-
21-
Each sector/block in gdisk is 4096 bytes long.
18+
These tools allow you to make space on the disk for Linux. Note internal storage is
19+
currently supported on Apple A11 only.
2220

2321
### resize.c / resize_apfs
2422

25-
This is an apfs container resize tool.
26-
27-
It should be signed with entitlements in `resize.xml`.
23+
This is an apfs container resize tool. It should be signed with
24+
entitlements in `resize.xml`. Due to limitations in
25+
embedded SDK, headers must be copied from macOS SDK and edited.
26+
Check the [CI script](../.github/workflows/build.yml) for details.
2827

2928
Usage: `./resize_apfs <container BSD name> <size in bytes>`
3029

3130
Resize the container to N bytes, such as 21474836480 in the following example.
32-
There are alignment restrictions so pick a 1048576-byte aligned size.
31+
There are alignment restrictions so pick a 4096-byte aligned size.
3332

3433
```
3534
./resize_apfs disk0s1 21474836480
@@ -48,16 +47,27 @@ During an online resize, all file system operations will be frozen, so in normal
4847

4948
After resizing, the gpt can be modified with gdisk.
5049

50+
### gdisk
51+
52+
This is the usual gpt partitioning tool found on many unixes.
53+
54+
It is used to inspect and modify the partition table. It should be
55+
signed with entitlements in `gdisk.xml`. Due to limitations in
56+
embedded SDK, headers must be copied from macOS SDK and edited.
57+
Check the [CI script](../.github/workflows/build.yml) for details.
58+
59+
Each sector/block in gdisk is 4096 bytes long. [Tutorial](../tutorials/gdisk.md)
5160

5261
### Caveats
5362

5463
On iOS 11-13 the default snapshot makes the container unresizable.
5564
One can delete and recreate the snapshot with a tool like [`snaputil`](https://github.com/ahl/apfs) from ramdisk and resizing should work.
5665

5766
In order for a resize to work, the SEP firmware must be loaded, and gigalocker
58-
must be initialized. This is already done in normal iOS. In a ramdisk, this can
59-
also be done on iOS/iPadOS 15 and below.
60-
(Might also be possible on higher tvOS/bridgeOS versions)
67+
must be initialized. This is already done in normal iOS. In a ramdisk, this
68+
may not be possible on Apple A10(X), A11 on iOS 16/17.
69+
70+
(May be possible on higher tvOS/bridgeOS versions)
6171

6272
If you use [SSHRD_Script](https://github.com/verygenericname/SSHRD_Script.git), the following command should do:
6373

‎tutorials/gdisk.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# gdisk Tutorial
2+
3+
Tutorial using gdisk on jailbroken iOS/tvOS/bridgeOS.
4+
5+
## Notes
6+
7+
This tutorial is for people that do not have experience with command-line
8+
partitioning with gdisk on Linux/Unix. If you know already, you may skip
9+
reading. Keep in mind that the sector size is `4096`.
10+
11+
### Common Partition codes
12+
13+
These partition codes may be used later.
14+
```
15+
0700 = Microsoft basic data
16+
8200 = Linux swap
17+
8300 = Linux filesystem
18+
AF00 = Apple HFS/HFS+
19+
AF0A = Apple APFS
20+
```
21+
22+
## Partitioning
23+
24+
You should have ran `resize_apfs` to resize the apfs filesystem already.
25+
After resizing the filesystem, the partition table needs to be updated.
26+
27+
Start by running gdisk against the main disk.
28+
```
29+
# ./gdisk /dev/disk0
30+
```
31+
32+
You should get:
33+
```
34+
GPT fdisk (gdisk) version 1.0.10
35+
36+
Warning: Devices opened with shared lock will not have their
37+
partition table automatically reloaded!
38+
Partition table scan:
39+
MBR: protective
40+
BSD: not present
41+
APM: not present
42+
GPT: present
43+
44+
Found valid GPT with protective MBR; using GPT.
45+
46+
```
47+
48+
Type `p` and enter to print the current partition table:
49+
50+
```
51+
Command (? for help): p
52+
Disk /dev/disk0: 62500000 sectors, 238.4 GiB
53+
Sector size (logical): 4096 bytes
54+
Disk identifier (GUID): 37FE5887-699F-463D-A34F-98CA0D99FBA3
55+
Partition table holds up to 128 entries
56+
Main partition table begins at sector 2 and ends at sector 5
57+
First usable sector is 6, last usable sector is 62499994
58+
Partitions will be aligned on 2-sector boundaries
59+
Total free space is 1 sectors (4.0 KiB)
60+
61+
Number Start (sector) End (sector) Size Code Name
62+
1 6 62499993 238.4 GiB AF0A Apple APFS
63+
64+
```
65+
66+
Then we will actually delete this partition since there's no such
67+
thing as resizing partition in gdisk. The changes are not written
68+
out until a `w` command is issued.
69+
70+
Type `d` and enter to delete a partition. Since there is only one
71+
partition, the partition will be automatically selected and
72+
deelted.
73+
74+
```
75+
Command (? for help): d
76+
Using 1
77+
78+
```
79+
80+
Then we need to create a new partition that exactly matches the size
81+
of the resized filesystem. Start and end are inclusive and each
82+
sector is 4096 bytes long.
83+
84+
Type `n`, enter, and `1`, enter. For start, keep it at `6` like it
85+
originally is. For end, suppose the filesystem is resized to be
86+
`192000000000` bytes (this size must be sector-aligned), then the
87+
last sector is `(6 + (192000000000) / 4096) - 1 = 46875005` In
88+
general for a 4096-byte aligned filesystem size `n`, the last sector
89+
is `(start + (size) / 4096) - 1`.
90+
91+
Type start and end sector. As for type code, use `AF0A` for `Apple APFS`:
92+
93+
```
94+
Command (? for help): n
95+
Partition number (1-128, default 1): 1
96+
First sector (6-62499994, default = 6) or {+-}size{KMGTP}: 6
97+
Last sector (6-62499994, default = 62499993) or {+-}size{KMGTP}: 46875005
98+
Current type is AF00 (Apple HFS/HFS+)
99+
Hex code or GUID (L to show codes, Enter = AF00): AF0A
100+
Changed type of partition to 'Apple APFS'
101+
```
102+
103+
Now the APFS partition is restored. Custom partitions can now be created,
104+
suppose we want a partition to hold the rootfs:
105+
106+
```
107+
Command (? for help): n
108+
Partition number (2-128, default 2): 2
109+
First sector (46875006-62499994, default = 46875006) or {+-}size{KMGTP}: 46875006
110+
Last sector (46875006-62499994, default = 62499993) or {+-}size{KMGTP}: 61035156
111+
Current type is AF00 (Apple HFS/HFS+)
112+
Hex code or GUID (L to show codes, Enter = AF00): 8300
113+
Changed type of partition to 'Linux filesystem'
114+
```
115+
116+
where 8300 = `Linux filesystem`
117+
118+
And a partition to hold the boot files:
119+
120+
```
121+
Command (? for help): n
122+
Partition number (3-128, default 3): 3
123+
First sector (61035157-62499994, default = 61035158) or {+-}size{KMGTP}: 61035264
124+
Last sector (61035264-62499994, default = 62499993) or {+-}size{KMGTP}: 61157119
125+
Current type is AF00 (Apple HFS/HFS+)
126+
Hex code or GUID (L to show codes, Enter = AF00): 8300
127+
Changed type of partition to 'Linux filesystem'
128+
```
129+
130+
where 8300 = `Linux filesystem`
131+
132+
A FAT32 partition to hold earlier boot files:
133+
134+
```
135+
Command (? for help): n
136+
Partition number (4-128, default 4): 4
137+
First sector (61035157-62499994, default = 61157120) or {+-}size{KMGTP}: 61157120
138+
Last sector (61157120-62499994, default = 62499993) or {+-}size{KMGTP}: 61222655
139+
Current type is AF00 (Apple HFS/HFS+)
140+
Hex code or GUID (L to show codes, Enter = af00): 0700
141+
Changed type of partition to 'Microsoft basic data'
142+
```
143+
144+
where 0700 = `Microsoft basic data`
145+
146+
A swap partition:
147+
148+
```
149+
Command (? for help): n
150+
Partition number (5-128, default 5): 5
151+
First sector (61035157-62499994, default = 61222656) or {+-}size{KMGTP}: 61222656
152+
Last sector (61222656-62499994, default = 62499993) or {+-}size{KMGTP}: 62499839
153+
Current type is af00 (Apple HFS/HFS+)
154+
Hex code or GUID (L to show codes, Enter = af00): 8200
155+
Changed type of partition to 'Linux swap'
156+
```
157+
158+
In this example, 4 new partitions are created and the existing APFS partition is
159+
shrunk. Type `p` to print the new partition table and CHECK CAREFULLY to avoid
160+
data loss:
161+
162+
```
163+
Command (? for help): p
164+
Disk /dev/disk0: 62500000 sectors, 238.4 GiB
165+
Sector size (logical): 4096 bytes
166+
Disk identifier (GUID): 37FE5887-699F-463D-A34F-98CA0D99FBA3
167+
Partition table holds up to 128 entries
168+
Main partition table begins at sector 2 and ends at sector 5
169+
First usable sector is 6, last usable sector is 62499994
170+
Partitions will be aligned on 2-sector boundaries
171+
Total free space is 262 sectors (1.0 MiB)
172+
173+
Number Start (sector) End (sector) Size Code Name
174+
1 6 46875005 178.8 GiB AF0A Apple APFS
175+
2 46875006 61035156 54.0 GiB 8300 Linux filesystem
176+
3 61035264 61157119 476.0 MiB 8300 Linux filesystem
177+
4 61157120 61222655 256.0 MiB 0700 Microsoft basic data
178+
5 61222656 62499839 4.9 GiB 8200 Linux swap
179+
```
180+
181+
When everything is good, type `w`, enter, confirm with `y` to actually
182+
write the partition table:
183+
184+
```
185+
Command (? for help): w
186+
187+
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
188+
PARTITIONS!!
189+
190+
Do you want to proceed? (Y/N): y
191+
OK; writing new GUID partition table (GPT) to /dev/disk0.
192+
Warning: Devices opened with shared lock will not have their
193+
partition table automatically reloaded!
194+
Warning: The kernel may continue to use old or deleted partitions.
195+
You should reboot or remove the drive.
196+
The operation has completed successfully.
197+
```
198+
199+
Now, check `/dev` to ensure the partitions `/dev/disk0s2`,
200+
`/dev/disk0s3`, ... are created.
201+
202+
Now the partitions has been created. However, there are no filesystem
203+
on them. You will need to flash prebuilt filesystem images with `dd`,
204+
and for some other partitions, format them once booted into Linux.
205+
The filesystem images likely has to have a block size of 4096.
206+
207+
For example, to flash a filesystem image, `root.img` into the second
208+
partition:
209+
210+
```
211+
# dd if=root.img of=/dev/disk0s2
212+
```
213+
214+
For Apple A11, the partition will show up as `/dev/nvme0n1p...` in Linux.
215+
For example `/dev/disk0s2` is `/dev/nvme0n1p2` in Linux.

0 commit comments

Comments
 (0)