limine/README.md

218 lines
8.1 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 an advanced x86/x86_64 BIOS/UEFI Bootloader which supports *modern* PC features
2020-09-21 15:08:45 +03:00
such as Long Mode, 5-level paging, and SMP (multicore), to name a few.
2021-05-05 15:40:32 +03:00
### Support Limine
Like Limine and want to support it? Donate Bitcoin to `bc1q00d59y75crpapw7qp8sea5j5sx6l4k2ssjylf9` :)
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")
[Photo by Chris Kane from Pexels](https://www.pexels.com/photo/reflection-of-building-on-body-of-water-at-daytime-166360/)
2020-11-09 16:29:53 +03:00
2020-04-20 13:39:24 +03:00
### Supported boot protocols
* Linux
2021-04-10 05:21:51 +03:00
* stivale and stivale2 (Limine's native boot protocols, see [their specifications](https://github.com/stivale/stivale) for details)
* Multiboot 1
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
2020-04-22 18:49:19 +03:00
* echfs
2021-05-11 07:46:42 +03:00
* FAT12/16/32
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
2021-03-21 11:16:06 +03:00
## Binary releases
2021-03-21 11:16:06 +03:00
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 `v2.x` branch one can do
```bash
2021-03-21 11:16:06 +03:00
git clone https://github.com/limine-bootloader/limine.git --branch=v2.0-branch-binary --depth=1
```
2021-07-07 11:08:17 +03:00
or, to clone a specific binary point release (for example v2.29)
```bash
2021-07-07 11:08:17 +03:00
git clone https://github.com/limine-bootloader/limine.git --branch=v2.29-binary --depth=1
```
2021-03-21 11:16:06 +03:00
2021-03-29 20:08:36 +03:00
Additionally, the absolute latest Limine binary release can be obtained by fetching
the `latest-binary` branch:
```bash
git clone https://github.com/limine-bootloader/limine.git --branch=latest-binary --depth=1
```
2021-03-21 11:16:06 +03:00
`limine-install` binaries are provided for Linux and Windows. In case one wants to
rebuild `limine-install`, simply use `make` in the binary release.
## Building the bootloader
*These steps are not necessary if cloning a binary release. If so, skip to*
*"Installing Limine binaries".*
2021-04-11 10:56:48 +03:00
**Note that the build system does not support building from a directory whose**
**full path contains spaces.**
### Building the toolchain
2020-09-13 16:47:43 +03:00
This step can take a long time, but it will ensure that the compiler will work with
Limine. If on an x86_64 host, with GCC or Clang installed, you can also skip to the next paragraph.
The toolchain building process depends on the following packages: `bash`, `make`,
2021-07-06 01:02:28 +03:00
`curl`, `gcc`, `g++`, `GNU binutils`.
Building the toolchain can be accomplished by running:
2020-09-13 16:47:43 +03:00
```bash
make toolchain
```
*The above step may take a while*
2020-09-13 16:47:43 +03:00
### Building Limine
In order to build Limine, the following packages have to be installed: `bash`, `make`,
2021-06-30 19:22:50 +03:00
`git`, `nasm`, `mtools` (optional, necessary to build `limine-eltorito-efi.bin`).
Furthermore, either the toolchain must have been built in the previous paragraph,
or `gcc` or `llvm/clang` must also be installed.
`GNU binutils` is necessary in order to build the UEFI port of Limine. A full
LLVM toolchain without `GNU binutils` can be used to build the BIOS port instead.
2021-06-01 21:39:43 +03:00
Both the UEFI and BIOS ports of the bootloader can be built, using `GCC/GNU binutils`, with:
2020-09-13 16:47:43 +03:00
```bash
make
2020-09-13 16:47:43 +03:00
```
It is possible to pass `make` additional flags, most relevantly, `TOOLCHAIN=` which
allows one to specify an alternative toolchain for the build system to use
(the default is `x86_64-elf`, falling back to no-triple, or host, toolchain).
2021-02-25 08:44:41 +03:00
The generated bootloader files are going to be in `bin`.
2020-09-13 16:47:43 +03:00
#### Using clang/LLVM
In order to build the BIOS port fully using clang/LLVM, run `make` as such:
```bash
make limine-bios bin/limine-install CC="clang" TOOLCHAIN="llvm" TOOLCHAIN_CC="clang" TOOLCHAIN_LD="ld.lld"
```
And in order to build the UEFI port using clang/LLVM + `GNU binutils`, run `make` as such:
```bash
make limine-uefi TOOLCHAIN="llvm" TOOLCHAIN_CC="clang" TOOLCHAIN_LD="ld" TOOLCHAIN_OBJCOPY="objcopy"
```
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
release directory just fine. This step will only install them in a `share` and `bin`
2021-02-26 02:32:02 +03:00
directories in the specified `PREFIX` (default is `/usr/local`).
2021-02-25 10:18:43 +03:00
2021-02-26 02:32:02 +03:00
Use `make install` to install Limine binaries, optionally specifying a prefix with a
`PREFIX=...` option.
## How to use
### UEFI
The `BOOTX64.EFI` file is a vaild EFI application that can be simply copied to the
`/EFI/BOOT` directory of a FAT formatted EFI system partition. This file can be
installed there and coexist with a BIOS installation of Limine (see below) so that
the disk will be bootable by both BIOS and UEFI.
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),
2021-02-25 08:44:41 +03:00
run `limine-install` as such:
2020-04-07 08:24:19 +03:00
```bash
2020-12-31 08:13:30 +03:00
limine-install <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.
* Letting `limine-install` 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
2020-12-31 08:13:30 +03:00
to `limine-install` as a second argument; such as:
2020-04-20 13:39:24 +03:00
```bash
2020-12-31 08:13:30 +03:00
limine-install <path to device/image> <1-based stage 2 partition number>
2020-04-20 13:39:24 +03:00
```
In case one wants to let `limine-install` embed stage 2 within GPT's structures,
simply omit the partition number, and invoke `limine-install` 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-eltorito-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-eltorito-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:
```
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-eltorito-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
And do not forget to also run `limine-install` on the generated image:
```
limine-install 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-eltorito-efi.bin>` is the relative path of
`limine-eltorito-efi.bin` inside the root directory.
For example, if it was copied in `<root directory>/boot/limine-eltorito-efi.bin`,
it would be `boot/limine-eltorito-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.
`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
2020-08-29 21:02:16 +03:00
An example `limine.cfg` file can be found in `test/limine.cfg`.
2020-04-07 08:24:19 +03:00
2020-08-29 21:02:16 +03:00
More info on the format of `limine.cfg` can be found in `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.