ladybird/Base/usr/share/man/man7/boot_device_addressing.md

## Name

Boot Device Addressing - addressing the correct boot device to use.

## Synopsis

Serenity's kernel can select the boot device at boot time, based on the `root` boot parameter.
This functionality is used to control which boot device is selected to be used for all further boot process operations.

## Description

The kernel `root` boot parameter takes the form of **`root={value}`**, where the **`={value}`**
trailer can be set to specific prefixes to indicate the boot device preference.

### Addressing options

The user can choose to use addressing based on synthetic unix concepts:

```
block0:0
```

This is especially useful in static hardware setups, so the user can choose to use
either a raw `StorageDevice` or partition block device. The `0,0` selection is the `MAJOR,MINOR`
numbers of the device.

However, when there's knowledge of the hardware arrangement of raw `StorageDevice`s,
it could be valuable to use addressing based on hardware-relative interface-specific "location"
to address raw `StorageDevice`s:

```
ata0:0:0 [First ATA controller, ATA first primary channel, master device]
nvme0:0 [First NVMe Controller, First NVMe Namespace]
ramdisk0 [First Ramdisk]
```

When the logical arrangement is known, using (absolute) LUNs is the easiest option as it doesn't rely on
using unix device numbers or hardware-relative location:

```
lun0:0:0 - first device on the first channel of the first controller to be enumerated
```

### Note on selecting partitions from raw `StorageDevice`s

All the addressing options above support selecting a partition device, given that
the selected device is a `StorageDevice` and not a `DiskPartition` device:

```
nvme0;part0
lun0:0:0;part0
```

The only exception to this is when choosing a `BlockDevice`. As such,
trying to specify `block0:0;part0`, for example, will lead to a kernel panic,
as an invalid boot device parameter.

### Selecting a specific partition based on known GUID

For GPT partitions, passing `PARTUUID:` and the GUID of the partition can be used
to select a GPT partition. Although it could be slower to find the corresponding
partition, it is the safest option available for persistent storage.
Kernel/Storage: Introduce new boot device addressing modes Before of this patch, we supported two methods to address a boot device: 1. Specifying root=/dev/hdXY, where X is a-z letter which corresponds to a boot device, and Y as number from 1 to 16, to indicate the partition number, which can be omitted to instruct the kernel to use a raw device rather than a partition on a raw device. 2. Specifying root=PARTUUID: with a GUID string of a GUID partition. In case of existing storage device with GPT partitions, this is most likely the safest option to ensure booting from persistent storage. While option 2 is more advanced and reliable, the first option has 2 caveats: 1. The string prefix "/dev/hd" doesn't mean anything beside a convention on Linux installations, that was taken into use in Serenity. In Serenity we don't mount DevTmpFS before we mount the boot device on /, so the kernel doesn't really access /dev anyway, so this convention is only a big misleading relic that can easily make the user to assume we access /dev early on boot. 2. This convention although resemble the simple linux convention, is quite limited in specifying a correct boot device across hardware setup changes, so option 2 was recommended to ensure the system is always bootable. With these caveats in mind, this commit tries to fix the problem with adding more addressing options as well as to remove the first option being mentioned above of addressing. To sum it up, there are 4 addressing options: 1. Hardware relative address - Each instance of StorageController is assigned with a index number relative to the type of hardware it handles which makes it possible to address storage devices with a prefix of the commandset ("ata" for ATA, "nvme" for NVMe, "ramdisk" for Plain memory), and then the number for the parent controller relative hardware index, another number LUN target_id, and a third number for LUN disk_id. 2. LUN address - Similar to the previous option, but instead we rely on the parent controller absolute index for the first number. 3. Block device major and minor numbers - by specifying the major and minor numbers, the kernel can simply try to get the corresponding block device and use it as the boot device. 4. GUID string, in the same fashion like before, so the user use the "PARTUUID:" string prefix and add the GUID of the GPT partition. For the new address modes 1 and 2, the user can choose to also specify a partition out of the selected boot device. To do that, the user needs to append the semicolon character and then add the string "partX" where X is to be changed for the partition number. We start counting from 0, and therefore the first partition number is 0 and not 1 in the kernel boot argument. 2022-08-05 20:32:26 +03:00			`## Name`

			`Boot Device Addressing - addressing the correct boot device to use.`

			`## Synopsis`

			Serenity's kernel can select the boot device at boot time, based on the `root` boot parameter.
			`This functionality is used to control which boot device is selected to be used for all further boot process operations.`

			`## Description`

			The kernel `root` boot parameter takes the form of `root={value}`, where the `={value}`
			`trailer can be set to specific prefixes to indicate the boot device preference.`

			`### Addressing options`

			`The user can choose to use addressing based on synthetic unix concepts:`

			```
			`block0:0`
			```

			`This is especially useful in static hardware setups, so the user can choose to use`
			either a raw `StorageDevice` or partition block device. The `0,0` selection is the `MAJOR,MINOR`
			`numbers of the device.`

			However, when there's knowledge of the hardware arrangement of raw `StorageDevice`s,
			`it could be valuable to use addressing based on hardware-relative interface-specific "location"`
			to address raw `StorageDevice`s:

			```
			`ata0:0:0 [First ATA controller, ATA first primary channel, master device]`
			`nvme0:0 [First NVMe Controller, First NVMe Namespace]`
			`ramdisk0 [First Ramdisk]`
			```

			`When the logical arrangement is known, using (absolute) LUNs is the easiest option as it doesn't rely on`
			`using unix device numbers or hardware-relative location:`

			```
			`lun0:0:0 - first device on the first channel of the first controller to be enumerated`
			```

			### Note on selecting partitions from raw `StorageDevice`s

			`All the addressing options above support selecting a partition device, given that`
			the selected device is a `StorageDevice` and not a `DiskPartition` device:

			```
			`nvme0;part0`
			`lun0:0:0;part0`
			```

			The only exception to this is when choosing a `BlockDevice`. As such,
			trying to specify `block0:0;part0`, for example, will lead to a kernel panic,
			`as an invalid boot device parameter.`

			`### Selecting a specific partition based on known GUID`

			For GPT partitions, passing `PARTUUID:` and the GUID of the partition can be used
			`to select a GPT partition. Although it could be slower to find the corresponding`
			`partition, it is the safest option available for persistent storage.`