limine/README.md

222 lines
7.6 KiB
Markdown
Raw Normal View History

2020-08-29 21:02:16 +03:00
# Limine
2020-09-18 21:08:19 +03:00
2020-09-21 15:08:45 +03:00
### What is Limine?
Limine is a modern, advanced, portable, multiprotocol bootloader, also used
2022-03-22 06:48:24 +03:00
as the reference implementation for the [Limine boot protocol](/PROTOCOL.md).
2020-09-21 15:08:45 +03:00
2020-09-25 23:39:14 +03:00
### Limine's boot menu
2020-04-07 08:24:19 +03:00
2020-08-05 01:08:40 +03:00
![Reference screenshot](/screenshot.png?raw=true "Reference screenshot")
2022-03-11 06:57:47 +03:00
[Photo by Martin Damboldt from Pexels](https://www.pexels.com/photo/gray-bridge-and-trees-814499/)
2020-11-09 16:29:53 +03:00
### Supported architectures
* IA-32 (32-bit x86)
* x86_64
* aarch64 (arm64)
2020-04-20 13:39:24 +03:00
### Supported boot protocols
* Linux
2022-03-22 06:48:24 +03:00
* [Limine](/PROTOCOL.md)
* Multiboot 1
* Multiboot 2
2021-07-06 04:17:28 +03:00
* Chainloading
2020-04-20 13:39:24 +03:00
### Supported filesystems
2020-09-21 15:08:45 +03:00
* ext2/3/4
2021-05-11 07:46:42 +03:00
* FAT12/16/32
2022-01-22 06:10:48 +03:00
* NTFS
2021-02-25 08:44:41 +03:00
* ISO9660 (CDs/DVDs)
2020-04-20 13:39:24 +03:00
### Supported partitioning schemes
* MBR
* GPT
2021-02-25 08:44:41 +03:00
* Unpartitioned media
2020-04-20 13:39:24 +03:00
2022-03-02 20:08:06 +03:00
### Minimum system requirements
For 32-bit x86 systems, support is only ensured starting with those with
Pentium Pro (i686) class CPUs.
All x86_64 and aarch64 (UEFI) systems are supported.
2022-03-02 20:08:06 +03:00
2021-03-21 11:16:06 +03:00
## Binary releases
For convenience, for point releases, binaries are distributed. These binaries
are shipped in the `-binary` branches and tags of this repository
(see [branches](https://github.com/limine-bootloader/limine/branches/all) and
[tags](https://github.com/limine-bootloader/limine/tags)).
For example, to clone the latest binary release of the `v4.x` branch one can do
```bash
git clone https://github.com/limine-bootloader/limine.git --branch=v4.x-branch-binary --depth=1
```
or, to clone a specific binary point release (for example `v4.0`)
```bash
git clone https://github.com/limine-bootloader/limine.git --branch=v4.0-binary --depth=1
```
2021-03-21 11:16:06 +03:00
2022-04-02 10:31:19 +03:00
In order to rebuild `limine-deploy`, simply run `make` in the binary
2022-01-22 06:10:48 +03:00
release directory.
2021-03-21 11:16:06 +03:00
2022-07-05 17:19:00 +03:00
`limine-deploy.exe` binaries are provided for Windows.
2021-03-21 11:16:06 +03:00
## Building the bootloader
2022-01-22 06:10:48 +03:00
*The following steps are not necessary if cloning a binary release. If so, skip to*
*"Installing Limine binaries".*
### Prerequisites
2022-03-02 20:08:06 +03:00
In order to build Limine, the following programs have to be installed:
common UNIX tools (also known as `coreutils`),
2022-03-02 20:08:06 +03:00
`GNU make`, `grep`, `sed`, `find`, `awk`, `gzip`, `nasm`, `mtools`
(optional, necessary to build `limine-cd-efi.bin`).
Furthermore, `gcc` or `llvm/clang` must also be installed, alongside
the respective binutils.
### Configure
2022-01-22 06:10:48 +03:00
If using a release tarball (recommended, see https://github.com/limine-bootloader/limine/releases),
run `./configure` directly.
2022-06-15 01:35:16 +03:00
If checking out from the repository, run `./bootstrap` first in order to download the
necessary dependencies and generate the configure script (`GNU autoconf` and `GNU automake` required).
2022-06-15 01:35:16 +03:00
`./configure` takes arguments and environment variables; for more information on
these, run `./configure --help`.
**`./configure` by default does not build any Limine port. Make sure to read the**
**output of `./configure --help` and enable any or all ports!**
2022-07-05 17:19:00 +03:00
To build using the LLVM toolchain, pass `CROSS_TOOLCHAIN=llvm` to `./configure`.
2022-01-22 06:10:48 +03:00
Limine supports both in-tree and out-of-tree builds. Simply run the `configure`
script from the directory you wish to execute the build in. The following `make`
commands are supposed to be ran inside the build directory.
### Building Limine
To build Limine, run:
2020-09-13 16:47:43 +03:00
```bash
make # (or gmake where applicable)
2020-09-13 16:47:43 +03:00
```
The generated bootloader files are going to be in `./bin`.
2021-03-21 11:16:06 +03:00
## Installing Limine binaries
This step is optional as the bootloader binaries can be used from the `./bin` or
2022-07-05 22:04:18 +03:00
release directory just fine. This step will only install them to `share`, `include`, and
2022-01-16 08:09:36 +03:00
`bin` directories in the specified prefix (default is `/usr/local`, see
2022-07-05 22:04:18 +03:00
`./configure --help`, or the `PREFIX` variable if installing from a binary release).
2021-02-25 10:18:43 +03:00
2022-01-16 08:09:36 +03:00
To install Limine, run:
```bash
2022-01-22 05:10:25 +03:00
make install # (or gmake where applicable)
2022-01-16 08:09:36 +03:00
```
## How to use
### UEFI
The `BOOT{IA32,X64,AA64}.EFI` files are vaild EFI applications that can be simply copied to
the `/EFI/BOOT` directory of a FAT formatted EFI system partition. These files can
be installed there and coexist with a BIOS installation of Limine (see below) so
that the disk will be bootable on both BIOS and UEFI systems.
The boot device must to contain the `limine.cfg` file in
either the root or the `boot` directory of one of the partitions, formatted
with a supported file system (the ESP partition is recommended).
### BIOS/MBR
In order to install Limine on a MBR device (which can just be a raw image file),
2022-04-02 10:31:19 +03:00
run `limine-deploy` as such:
2020-04-07 08:24:19 +03:00
```bash
2022-04-02 10:31:19 +03:00
limine-deploy <path to device/image>
2020-04-07 08:24:19 +03:00
```
2021-02-26 02:32:02 +03:00
The boot device must to contain the `limine.sys` and `limine.cfg` files in
either the root or the `boot` directory of one of the partitions, formatted
with a supported file system.
2021-02-25 10:18:43 +03:00
### BIOS/GPT
If using a GPT formatted device, there are 2 options one can follow for
installation:
* Specifying a dedicated stage 2 partition.
2022-04-02 10:31:19 +03:00
* Letting `limine-deploy` attempt to embed stage 2 within GPT structures.
In case one wants to specify a stage 2 partition, create a partition on the GPT
device of at least 32KiB in size, and pass the 1-based number of the partition
2022-04-02 10:31:19 +03:00
to `limine-deploy` as a second argument; such as:
2020-04-20 13:39:24 +03:00
```bash
2022-04-02 10:31:19 +03:00
limine-deploy <path to device/image> <1-based stage 2 partition number>
2020-04-20 13:39:24 +03:00
```
2022-04-02 10:31:19 +03:00
In case one wants to let `limine-deploy` embed stage 2 within GPT's structures,
simply omit the partition number, and invoke `limine-deploy` the same as one
would do for an MBR partitioned device.
2021-02-26 02:32:02 +03:00
The boot device must to contain the `limine.sys` and `limine.cfg` files in
either the root or the `boot` directory of one of the partitions, formatted
with a supported file system.
2021-02-25 10:18:43 +03:00
### BIOS/UEFI hybrid ISO creation
In order to create a hybrid ISO with Limine, place the
`limine-cd-efi.bin`, `limine-cd.bin`, `limine.sys`, and `limine.cfg` files
into a directory which will serve as the root of the created ISO.
2021-02-26 02:32:02 +03:00
(`limine.sys` and `limine.cfg` must either be in the root or inside a `boot`
subdirectory; `limine-cd-efi.bin` and `limine-cd.bin` can reside
anywhere).
2021-02-25 08:44:41 +03:00
Place any other file you want to be on the final ISO in said directory, then
run:
2021-02-25 08:44:41 +03:00
```
xorriso -as mkisofs -b <relative path of limine-cd.bin> \
-no-emul-boot -boot-load-size 4 -boot-info-table \
--efi-boot <relative path of limine-cd-efi.bin> \
-efi-boot-part --efi-boot-image --protective-msdos-label \
<root directory> -o image.iso
2021-02-25 08:44:41 +03:00
```
*Note: `xorriso` is required.*
2021-02-25 08:44:41 +03:00
2022-04-02 10:31:19 +03:00
And do not forget to also run `limine-deploy` on the generated image:
```
2022-04-02 10:31:19 +03:00
limine-deploy image.iso
```
`<relative path of limine-cd.bin>` is the relative path of
`limine-cd.bin` inside the root directory.
For example, if it was copied in `<root directory>/boot/limine-cd.bin`,
it would be `boot/limine-cd.bin`.
`<relative path of limine-cd-efi.bin>` is the relative path of
`limine-cd-efi.bin` inside the root directory.
For example, if it was copied in
`<root directory>/boot/limine-cd-efi.bin`, it would be
`boot/limine-cd-efi.bin`.
### BIOS/PXE boot
2021-02-26 02:32:02 +03:00
The `limine-pxe.bin` binary is a valid PXE boot image.
In order to boot Limine from PXE it is necessary to setup a DHCP server with
support for PXE booting. This can either be accomplished using a single DHCP
server or your existing DHCP server and a proxy DHCP server such as dnsmasq.
2021-02-26 02:32:02 +03:00
`limine.cfg` and `limine.sys` are expected to be on the server used for boot.
### Configuration
2021-02-26 02:32:02 +03:00
The `limine.cfg` file contains Limine's configuration.
2020-04-07 08:24:19 +03:00
2021-08-26 04:16:54 +03:00
An example `limine.cfg` file can be found in [`test/limine.cfg`](https://github.com/limine-bootloader/limine/blob/trunk/test/limine.cfg).
2020-04-07 08:24:19 +03:00
2021-08-26 04:11:52 +03:00
More info on the format of `limine.cfg` can be found in [`CONFIG.md`](https://github.com/limine-bootloader/limine/blob/trunk/CONFIG.md).
2020-04-21 20:18:13 +03:00
2020-09-13 16:47:43 +03:00
## Acknowledgments
Limine uses a stripped-down version of [tinf](https://github.com/jibsen/tinf).
2020-05-02 18:02:05 +03:00
## Discord server
We have a [Discord server](https://discord.gg/QEeZMz4) if you need support,
info, or you just want to hang out with us.