diff options
Diffstat (limited to 'tools/README.md')
| -rw-r--r-- | tools/README.md | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..30299ac --- /dev/null +++ b/tools/README.md @@ -0,0 +1,138 @@ +# m1n1: an experimentation playground for Apple Silicon + +(And to some extent a Linux bootloader) + +## Building + +You need an `aarch64-linux-gnu-gcc` cross-compiler toolchain (or a native one, if running on ARM64). + +```shell +$ git clone --recursive https://github.com/AsahiLinux/m1n1.git +$ cd m1n1 +$ make +``` + +The output will be in build/m1n1.macho. + +To build on a native arm64 machine, use `make ARCH=`. + +Building on ARM64 macOS is supported with clang and LLVM; you need to use Homebrew to +install the required dependencies: + +```shell +$ brew install llvm +``` + +After that, just type `make`. + +### Building using the container setup + +If you have a container runtime installed, like Podman or Docker, you can make use of the compose setup, which contains all build dependencies. + +```shell +$ git clone --recursive https://github.com/AsahiLinux/m1n1.git +$ cd m1n1 +$ podman-compose run m1n1 make +$ # or +$ docker-compose run m1n1 make +``` + +## Usage + +Our [wiki](https://github.com/AsahiLinux/docs/wiki/m1n1%3AUser-Guide) has more information on how to +use m1n1. + +To install on an OS container based on macOS <12.1, use `m1n1.macho`: + +```shell +kmutil configure-boot -c m1n1.macho -v <path to your OS volume> +``` + +To install on an OS container based on macOS >=12.1, use `m1n1.bin`: + +```shell +kmutil configure-boot -c m1n1.bin --raw --entry-point 2048 --lowest-virtual-address 0 -v <path to your OS volume> +``` + +## Payloads + +m1n1 supports running payloads by simple concatenation: + +```shell +$ cat build/m1n1.macho Image.gz build/dtb/apple-j274.dtb initramfs.cpio.gz > m1n1-payload.macho +$ cat build/m1n1.bin Image.gz build/dtb/apple-j274.dtb initramfs.cpio.gz > m1n1-payload.bin +``` + +Supported payload file formats: + +* Kernel images (or compatible). Must be compressed or last payload. +* Devicetree blobs (FDT). May be uncompressed or compressed. +* Initramfs cpio images. Must be compressed. + +Supported compression formats: + +* gzip +* xz + +## License + +m1n1 is licensed under the MIT license, as included in the [LICENSE](LICENSE) file. + +* Copyright The Asahi Linux Contributors + +Please see the Git history for authorship information. + +Portions of m1n1 are based on mini: + +* Copyright (C) 2008-2010 Hector Martin "marcan" <marcan@marcan.st> +* Copyright (C) 2008-2010 Sven Peter <sven@svenpeter.dev> +* Copyright (C) 2008-2010 Andre Heider <a.heider@gmail.com> + +m1n1 embeds libfdt, which is dual [BSD](3rdparty_licenses/LICENSE.BSD-2.libfdt) and +[GPL-2](3rdparty_licenses/LICENSE.GPL-2) licensed and copyright: + +* Copyright (C) 2014 David Gibson <david@gibson.dropbear.id.au> +* Copyright (C) 2018 embedded brains GmbH +* Copyright (C) 2006-2012 David Gibson, IBM Corporation. +* Copyright (C) 2012 David Gibson, IBM Corporation. +* Copyright 2012 Kim Phillips, Freescale Semiconductor. +* Copyright (C) 2016 Free Electrons +* Copyright (C) 2016 NextThing Co. + +The ADT code in mini is also based on libfdt and subject to the same license. + +m1n1 embeds [minlzma](https://github.com/ionescu007/minlzma), which is +[MIT](3rdparty_licenses/LICENSE.minlzma) licensed and copyright: + +* Copyright (c) 2020 Alex Ionescu + +m1n1 embeds a slightly modified version of [tinf](https://github.com/jibsen/tinf), which is +[ZLIB](3rdparty_licenses/LICENSE.tinf) licensed and copyright: + +* Copyright (c) 2003-2019 Joergen Ibsen + +m1n1 embeds portions taken from +[arm-trusted-firmware](https://github.com/ARM-software/arm-trusted-firmware), which is +[BSD](3rdparty_licenses/LICENSE.BSD-3.arm) licensed and copyright: + +* Copyright (c) 2013-2020, ARM Limited and Contributors. All rights reserved. + +m1n1 embeds [Doug Lea's malloc](ftp://gee.cs.oswego.edu/pub/misc/malloc.c) (dlmalloc), which is in +the public domain ([CC0](3rdparty_licenses/LICENSE.CC0)). + +m1n1 embeds portions of [PDCLib](https://github.com/DevSolar/pdclib), which is in the public +domain ([CC0](3rdparty_licenses/LICENSE.CC0)). + +m1n1 embeds the [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) font, which is +licensed under the [OFL-1.1](3rdparty_licenses/LICENSE.OFL-1.1) license and copyright: + +* Copyright 2010-2019 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries. +* This Font Software is licensed under the SIL Open Font License, Version 1.1. + +m1n1 embeds portions of the [dwc3 usb linux driver](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/usb/dwc3/core.h?id=7bc5a6ba369217e0137833f5955cf0b0f08b0712), which was [BSD-or-GPLv2 dual-licensed](3rdparty_licenses/LICENSE.BSD-3.dwc3) and copyright +* Copyright (C) 2010-2011 Texas Instruments Incorporated - http://www.ti.com + +m1n1 embeds portions of [musl-libc](https://musl.libc.org/)'s floating point library, which are MIT licensed and copyright +* Copyright (c) 2017-2018, Arm Limited. + +m1n1 embeds some rust crates. Licenses can be found in the vendor directory for every crate. |