Загрузка ядра с помощью Easyboot
================================

[Easyboot](https://gitlab.com/bztsrc/easyboot) — это универсальный менеджер загрузки и создатель образа загрузочного диска, который
может загружать различные ядра ОС и ядра, совместимые с Multiboot2, в различных форматах.

[[_TOC_]]

Установка
---------

```
 easyboot [-v|-vv] [-s <mb>] [-b <mb>] [-u <guid>] [-p <t> <u> <i>] [-e] [-c] <indir> <outfile|device>

  -v, -vv         увеличить многословность/проверку
  -s <mb>         установите размер образа диска в мегабайтах (по умолчанию 35 МБ)
  -b <mb>         установите размер загрузочного раздела в мегабайтах (по умолчанию 33 МБ)
  -u <guid>       установить уникальный идентификатор загрузочного раздела (по умолчанию случайный)
  -p <t> <u> <i>  добавить дополнительный раздел (введите guid, уникальный guid, файл изображения)
  -e              добавить El Torito Boot Catalog (поддержка загрузки BIOS / EFI CDROM)
  -c              всегда создавайте новый файл изображения, даже если он существует
  <indir>         используйте содержимое этого каталога для загрузочного раздела
  <outfile>       выходное изображение или имя файла устройства
```

Инструмент **Easyboot** создает образ загрузочного диска с именем `(outfile)`, используя таблицу разделов GUID с одним разделом,
отформатированным как FAT32 и названным «EFI System Partition» (сокращенно ESP). Содержимое этого раздела берется из
предоставленного вами `(indir)`. Вы должны поместить простой текстовый файл конфигурации в этот каталог с именем
`easyboot/menu.cfg`. Имея окончания строк NL или CRLF, вы можете легко редактировать их в любом текстовом редакторе. В зависимости
от вашей конфигурации вам также могут понадобиться некоторые [плагины](plugins.md) в этом каталоге под названием `easyboot/*.plg`.

Образ можно загрузить и на Raspberry Pi, и он будет работать в qemu; но для загрузки на реальной машине вам потребуются
дополнительные файлы прошивки `bootcode.bin`, `fixup.dat`, `start.elf` и файл .dtb в каталоге `(indir)`, их можно скачать из
[официального репозитория](https://github.com/raspberrypi/firmware/tree/master/boot) Raspberry Pi.

Инструмент также имеет несколько дополнительных флагов командной строки: `-s (mb)` устанавливает общий размер сгенерированного
образа диска в мегабайтах, а `-b (mb)` устанавливает размер загрузочного раздела в мегабайтах. Очевидно, что первое должно быть
больше, чем второе. Если не указано, то размер раздела рассчитывается на основе размера данного каталога (минимум 33 МБ, самая
маленькая FAT32, которая может быть), а размер диска по умолчанию на 2 МБ больше (из-за выравнивания и пространства, необходимого
для разбиения разделов). стол). Если между этими двумя значениями размера разница более 2 МБ, вы можете использовать сторонние
инструменты, такие как `fdisk`, чтобы добавить в образ дополнительные разделы по своему вкусу (или см. `-p` ниже). Если вам нужен
предсказуемый макет, вы также можете указать уникальный идентификатор загрузочного раздела (UniquePartitionGUID) с помощью флага
`-u <guid>`.

При желании вы также можете добавить дополнительные разделы с флагом `-p`. Для этого требуются три аргумента: (PartitionTypeGUID),
(UniquePartitionGUID) и имя файла изображения, содержащего содержимое раздела. Этот флаг может повторяться несколько раз.

Флаг `-e` добавляет El Torito Boot Catalog к сгенерированному образу, чтобы его можно было загружать не только как USB-накопитель,
но и как BIOS / EFI CDROM.

Если `(outfile)` является файлом устройства (например, `/dev/sda` в Linux, `/dev/disk0` в BSD и `\\.\PhysicalDrive0` в Windows),
то он не создает ни GPT, ни ESP вместо этого находит уже существующие на устройстве. Он по-прежнему копирует все файлы из `(indir)`
в загрузочный раздел и устанавливает загрузчики. Это также работает, если `(outfile)` является уже существующим файлом изображения
(в этом случае используйте флаг `-c`, чтобы всегда сначала создавать новый пустой файл изображения).

Конфигурация
------------

Файл `easyboot/menu.cfg` может содержать следующие строки (очень похоже на синтаксис grub.cfg, пример файла конфигурации вы можете
найти [здесь](menu.cfg)):

### Комментарии

Все строки, начинающиеся с `#`, считаются комментариями и пропускаются до конца строки.

### Уровень детализации

Вы можете установить уровень детализации, используя строку, начинающуюся с `verbose`.

```
verbose (0-3)
```

Это сообщает загрузчику, какой объем информации следует вывести на загрузочную консоль. Verbose 0 означает абсолютно тихий режим
(по умолчанию), а verbose 3 выгрузит загруженные сегменты ядра и машинный код в точке входа.

### Фреймбуфер

Вы можете запросить определенное разрешение экрана, указав строку, начинающуюся с `framebuffer`. Формат следующий:

```
framebuffer (ширина) (высота) (бит на пиксель) [#(цвет переднего плана)] [#(цвет фона)] [#(полоса выполнения)]
```

**Easyboot** настроит для вас фреймбуфер, даже если эта строка не существует (по умолчанию 800 x 600 x 32 бита на пиксель). Но если
эта строка существует, то она попытается установить указанное разрешение. Режимы с палитрами не поддерживаются, поэтому количество
бит на пиксель должно быть не менее 15.

Если задан четвертый необязательный параметр цвета, он должен быть в формате HTML, начинающимся с хеш-метки, за которой следуют 6
шестнадцатеричных цифр, RRGGBB. Например, #ff0000 — ярко-красный, а #007f7f — тёмно-голубой. Он устанавливает передний план или,
другими словами, цвет шрифта. Аналогично, если указан пятый необязательный параметр цвета, он также должен быть в нотации HTML и
задает цвет фона. Последний необязательный параметр цвета аналогичен и устанавливает цвет фона индикатора выполнения.

Если цвета не заданы, по умолчанию используются белые буквы на черном фоне, а фон индикатора выполнения темно-серый.

### Вариант загрузки по умолчанию

Строка, начинающаяся с `default`, устанавливает, какой пункт меню должен загружаться без взаимодействия с пользователем после
указанного таймаута.


```
default (индекс menuentry) (таймаут мс)
```

Индекс menuentry представляет собой число от 1 до 9. Тайм-аут указывается в миллисекундах (одна тысячная секунды), поэтому 1000
соответствует одной секунде.

### Выравнивание меню

Строки, начинающиеся с «menualign», изменяют способ отображения параметров загрузки.

```
menualign ("vertical"|"horizontal")
```

По умолчанию меню `horizontal` (горизонтальное), которое вы можете изменить на `vertical` (вертикальное).

### Параметры загрузки

Вы можете указать до 9 пунктов меню, строки которых начинаются с «menuentry». Формат следующий:

```
menuentry (значок) [метка]
```

Для каждого значка в загрузочном разделе должен существовать файл `easyboot/(значок).tga`. Изображение должно быть закодировано по
длине и отображено по цветам [формат Targa](../en/TGA.txt), поскольку это наиболее сжатый вариант (первые три байта файла должны
быть `0`, `1` и `9` в этом порядке, см. Тип данных 9 в спецификации). Его размеры должны составлять ровно 64 пикселя в высоту и 64
пикселя в ширину.

Чтобы сохранить в этом формате из GIMP, сначала выберите «Image > Mode > Indexed...», во всплывающем окне установите «Maximum
number of colors» на 256. Затем выберите «File > Export As...», введите имя файла, оканчивающееся на `.tga`, и во всплывающем окне
отметьте «RLE compression». В качестве инструмента преобразования командной строки вы можете использовать ImageMagick,
`convert (любой файл изображения) -colors 256 -compress RLE значок.tga`.

Необязательный параметр метки предназначен для отображения информации о версии или выпуске ASCII в меню, а не для произвольных
строк, поэтому для экономии места UTF-8 не поддерживается, если вы также не предоставите `easyboot/font.sfn`. (Шрифт UNICODE
требует большого объема памяти, хотя [Scalable Screen Font](https://gitlab.com/bztsrc/scalable-font2) очень эффективен, его размер
все равно составляет около 820 КБ. Напротив, файл unicode.pf2 GRUB намного больше, около 2392 КБ, хотя оба шрифта содержат около
55 600 символов в растровых изображениях 8x16 и 16x16. Встроенный шрифт ASCII содержит только растровые изображения 8x16 и 96
символов.)

Все строки, которые идут после строки `menuentry`, будут принадлежать этому пункту меню, за исключением случаев, когда эта строка
является другой строкой menuentry. Для удобства можно использовать блоки как в GRUB, но это всего лишь синтаксический сахар.
Фигурные скобки обрабатываются как пробелы. Вы можете опустить их и вместо этого использовать вкладки, как в скрипте Python или
Makefile, если вы этого предпочитаете.

Например
```
menuentry FreeBSD backup
{
    kernel bsd.old/boot
}
```

### Перегородка подбор

Строка, начинающаяся с `partition`, выбирает раздел GPT. Должна предшествовать строка `menuentry`.

```
partition (уникальный UUID раздела)
```

Этот раздел будет использоваться в качестве корневой файловой системы для варианта загрузки. Ядро и модули будут загружены из этого
раздела и в зависимости от протокола загрузки также будут переданы ядру. Указанный раздел может находиться на другом диске, чем
загрузочный. **Easyboot** во время загрузки будет перебирать все диски с разделами GPT, чтобы найти его.

Для удобства раздел ищется также по строке `kernel` (см. ниже). Если данная командная строка загрузки содержит строку `root=(UUID)`
или `root=*=(UUID)`, то нет необходимости в отдельной строке `partition`.

Если раздел не указан явно, ядро и модули загружаются из загрузочного раздела.

### Указываем ядро

Строка, начинающаяся с `kernel`, сообщает, какой файл следует загрузить и с какими параметрами. Должна предшествовать строка
`menuentry`.

```
kernel (путь к файлу вашего ядра) (необязательные аргументы командной строки загрузки)
```

Путь должен указывать на существующий файл, исполняемый двоичный файл ядра, и это должен быть абсолютный путь UTF-8 в корневом
(или загрузочном) разделе. Если ядро находится не в корневом каталоге раздела, то разделителем каталогов всегда будет `/`, даже в
системах UEFI. Если имя содержит пробел, его необходимо экранировать с помощью `\`. За путем могут следовать аргументы командной
строки, разделенные пробелом. Для ядер, совместимых с Multiboot2, эти аргументы командной строки будут переданы в теге *Командная
строка загрузки* (тип 1). Они не будут изменены с помощью **Easyboot** и не будут анализироваться, за исключением поиска
спецификатора раздела.

По умолчанию **Easyboot** может загружать ядра, совместимые с Multiboot2, в форматах ELF64 и PE32+/COFF (а в системах UEFI — и
приложения UEFI). Обычно этот протокол не допускает использование ядер с более высокой половиной, но **Easyboot** немного нарушает
протокол, не нарушая нормальные ядра без более высокой половины. Если вы хотите загрузить любое другое ядро, вам понадобится
загрузчик ядра [плагин](plugins.md).

ПРИМЕЧАНИЕ: В отличие от GRUB, где вам нужно использовать специальные команды, такие как «linux» или «multiboot», для выбора
протокола загрузки, здесь есть только одна команда, и протокол автоматически определяется вашим ядром во время выполнения.

### Загрузка дополнительных модулей

Вы можете загружать произвольные файлы (начальные рамдиски, драйверы ядра и т. д.) вместе с ядром, используя строки, начинающиеся
с `module`. Должна предшествовать строка `menuentry`. Обратите внимание, что эта строка может повторяться несколько раз в каждом
пункте меню. Если протокол загрузки поддерживает initrd, то самая первая строка модуля считается initrd.

```
module (путь к файлу) (дополнительные аргументы командной строки модуля)
```

Путь должен указывать на существующий файл и должен быть абсолютным путем UTF-8 в корневом (или загрузочном) разделе. За ним могут
следовать аргументы командной строки, разделенные пробелом. Если файл сжат и для него существует [плагин](plugins.md) распаковки,
то модуль будет прозрачно распакован. Информация об этих загруженных (и несжатых) модулях будет передана ядру, совместимому с
Multiboot2, в тегах *Модули* (тип 3).

Особый случай — если модуль начинается с байтов `DSDT`, `GUDT` или `0xD00DFEED`. В этих случаях файл не будет добавлен в теги
*Модули*, а будет исправлена таблица ACPI, чтобы ее указатели DSDT указывали на содержимое этого файла. Благодаря этому вы можете
легко заменить ошибочную таблицу ACPI BIOS на таблицу, предоставленную пользователем.

### Логотип загрузки загрузки

Вы также можете отобразить логотип в центре экрана, когда выбран вариант загрузки, если поместите строку, начинающуюся с
`bootsplash`. Должна предшествовать строка `menuentry`.

```
bootsplash [#(цвет фона)] (путь к файлу tga)
```

Цвет фона не является обязательным и должен быть указан в формате HTML, начиная с хеш-метки, за которой следуют 6 шестнадцатеричных
цифр, RRGGBB. Если первый аргумент не начинается с `#`, то предполагается аргумент пути.

Путь должен указывать на существующий файл и должен быть абсолютным путем UTF-8 в загрузочном (НЕ корневом) разделе. Изображение
должно быть в формате Targa с цветовой кодировкой и цветовой маркировкой, как и значки меню. Размеры могут быть любыми, подходящими
для экрана.

### Поддержка многоядерности

Чтобы запустить ядро на всех ядрах процессора одновременно, укажите директиву `multicore` (только 64-битные ядра). Должна
предшествовать строка `menuentry`.

```
multicore
```

Поиск неисправностей
--------------------

Если у вас возникнут какие-либо проблемы, просто запустите с флагом `easyboot -vv`. Это выполнит проверку и выведет результаты во
время создания изображения. В противном случае добавьте `verbose 3` в `easyboot/menu.cfg`, чтобы получить подробные сообщения о
времени загрузки.

Если вы видите строку `PMBR-ERR` в верхнем левом углу на красном фоне, это означает, что ваш процессор очень старый и не
поддерживает 64-битный длинный режим, или загрузочный сектор не смог загрузить загрузчик. Это может произойти только на компьютерах
с BIOS, этого никогда не произойдет с UEFI или RaspberryPi.

| Сообщение                           | Описание                                                                          |
|-------------------------------------|-----------------------------------------------------------------------------------|
| `Booting [X]...`                    | указывает, что был выбран вариант загрузки X (индекс menuentry)                   |
| `Loading 'X' (Y bytes)...`          | загружается файл X длины Y                                                        |
| `Parsing kernel...`                 | ядро было найдено, теперь определяется его формат                                 |
| `Starting X boot...`                | показывает, что был обнаружен загрузчик системы X                                 |
| `Starting X kernel...`              | показывает, что ядро системы X было обнаружено                                    |
| `Transfering X control to Y`        | указывает, что скоро будет вызвана точка входа в режим X по адресу Y              |

Если после появления последнего сообщения у вас возникли какие-либо проблемы, это означает, что проблема возникла в процедуре
загрузки операционной системы, а не в загрузчике **Easyboot**, поэтому вам необходимо обратиться к документации данной операционной
системы для получения информации. Ответ. В противном случае, пожалуйста, смело открывайте [проблему](https://gitlab.com/bztsrc/easyboot/-/issues)
на gitlab.

### Multiboot1

Необходимые плагины: [grubmb1](../../src/plugins/grubmb1.c)

### Multiboot2

Это наиболее гибкий вариант, поддерживающий множество вариантов с помощью плагинов:

- ELF64 или PE32+ с упрощенной Multiboot2: плагины не требуются.
- ELF32 с упрощенным Multiboot2 и 32-битной точкой входа: [elf32](../../src/plugins/elf32.c)
- a.out (struct exec) с упрощенным Multiboot2 и 32-битной точкой входа: [aout](../../src/plugins/aout.c)
- GRUB-совместимый Multiboot2 с 32-битной точкой входа: [grumb2](../../src/plugins/grubmb2.c)

Обратите внимание на разницу: [упрощенный Multiboot2](ABI.md) не требует встроенных тегов, поддерживает ядра старшей половины,
чистую 64-битную точку входа с параметрами, передаваемыми в соответствии с Multiboot2, SysV и fastcall ABI.

С другой стороны, [GRUB-совместимый Multiboot2](https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html) требует
встроенных тегов, не поддерживает ядра старшей половины и 64-битные ядра, Точка входа всегда 32-битная, а параметры передаются
только в `eax`, `ebx`.

### Windows

Никаких плагинов не требуется, но вы должны настроить [Secure Boot](secureboot.md).

```
menuentry win {
  kernel EFI/Microsoft/BOOT/BOOTMGRW.EFI
}
```

### Linux

Необходимые плагины: [linux](../../src/plugins/linux.c), [ext234](../../src/plugins/ext234.c)

Если ядро не размещено в загрузочном разделе, вы можете использовать командную строку для указания корневого раздела.

```
menuentry linux {
  kernel vmlinuz-linux root=PARTUUID=01020304-0506-0708-0a0b0c0d0e0f1011
}
```

### OpenBSD

Необходимые плагины: [obsdboot](../../src/plugins/obsdboot.c), [ufs44](../../src/plugins/ufs44.c)

```
menuentry openbsd {
  partition 01020304-0506-0708-0a0b0c0d0e0f1011
  kernel boot
}
```

ПРЕДУПРЕЖДЕНИЕ! Не используйте плагин [elf32](../../src/plugins/elf32.c), если вы загружаете OpenBSD! Его «загрузка» ошибочно
утверждает, что это ELF с 32-битной точкой входа SysV ABI, но на самом деле у нее есть 16-битная запись реального режима.

### FreeBSD

Необходимые плагины: [fbsdboot](../../src/plugins/fbsdboot.c), [ufs2](../../src/plugins/ufs2.c)

В устаревших системах BIOS укажите загрузчик `boot`.

```
menuentry freebsd {
  partition 01020304-0506-0708-0a0b0c0d0e0f1011
  kernel boot/boot
}
```

На машинах с UEFI используйте `loader.efi` в загрузочном разделе (плагины не требуются).

```
menuentry freebsd {
  kernel boot/loader.efi
}
```

Если ваша корневая файловая система ZFS, скопируйте этот файл (`boot` в BIOS, `loader.efi` в UEFI) в `(indir)` и НЕ указывайте
корневой раздел.

### FreeDOS

Необходимые плагины: [fdos](../../src/plugins/fdos.c)

Переместите файлы FreeDOS в `(indir)` (FreeDOS будет использовать загрузочный раздел в качестве корневого раздела).

```
menuentry freedos {
  kernel KERNEL.SYS
}
```

Если загрузка прекращается после печати копирайта и `-InitDisk`, значит, ядро FreeDOS было скомпилировано без поддержки FAT32.
Загрузите другое ядро с `f32` в названии.

### ReactOS

Необходимые плагины: [reactos](../../src/plugins/reactos.c)

```
menuentry reactos {
  kernel FREELDR.SYS
}
```

### MenuetOS

Необходимые плагины: [menuet](../../src/plugins/menuet.c)

```
menuentry menuetos {
  kernel KERNEL.MNT
  module CONFIG.MNT
  module RAMDISK.MNT
}
```

Чтобы отключить автоматическую настройку, добавьте `noauto` в командную строку.

### KolibriOS

Необходимые плагины: [kolibri](../../src/plugins/kolibri.c)

```
menuentry kolibrios {
  kernel KERNEL.MNT syspath=/rd/1/ launcher_start=1
  module KOLIBRI.IMG
  module DEVICES.DAT
}
```

Плагин работает и на машинах с UEFI, но вы также можете использовать `uefi4kos.efi` в загрузочном разделе (при этом плагин не
требуется).

### SerenityOS

Необходимые плагины: [grubmb1](../../src/plugins/grubmb1.c)

```
menuentry serenityos {
  kernel boot/Prekernel
  module boot/Kernel
}
```

### Haiku

Необходимые плагины: [grubmb1](../../src/plugins/grubmb1.c), [befs](../../src/plugins/befs.c)

```
menuentry haiku {
  partition 01020304-0506-0708-0a0b0c0d0e0f1011
  kernel system/packages/haiku_loader-r1~beta4_hrev56578_59-1-x86_64.hpkg
}
```

На машинах с UEFI используйте `haiku_loader.efi` в загрузочном разделе (плагины не требуются).

### OS/Z

```
menuentry osz {
  kernel ibmpc/core
  module ibmpc/initrd
}
```

Пплагины не требуются.
