## File: README.md

[](https://github.com/acidanthera/OpenCorePkg/actions) [](https://scan.coverity.com/projects/18169)
-----

OpenCore bootloader with development SDK.

## Libraries

This repository also contains additional UEFI support common libraries shared by other projects in [Acidanthera](https://github.com/acidanthera). The primary purpose of the library set is to provide supplemental functionality for Apple-specific UEFI drivers. Key features:

- Apple disk image loading support
- Apple keyboard input aggregation
- Apple PE image signature verification
- Apple UEFI secure boot supplemental code
- Audio management with screen reading support
- Basic ACPI and SMBIOS manipulation
- CPU information gathering with timer support
- Cryptographic primitives (SHA-256, RSA, etc.)
- Decompression primitives (zlib, lzss, lzvn, etc.)
- Helper code for ACPI reads and modifications
- Higher level abstractions for files, strings, UEFI variables
- Overflow checking arithmetics
- PE image loading with no UEFI Secure Boot conflict
- Plist configuration format parsing
- PNG image manipulation
- Text output and graphics output implementations
- XNU kernel driver injection and patch engine

Early history of the codebase could be found in [AppleSupportPkg](https://github.com/acidanthera/AppleSupportPkg) and PicoLib library set by The HermitCrabs Lab.

#### OcGuardLib

This library implements basic safety features recommended for the use within the project. It implements fast
safe integral arithmetics mapping on compiler builtins, type alignment checking, and UBSan runtime,
based on [NetBSD implementation](https://blog.netbsd.org/tnf/entry/introduction_to_µubsan_a_clean).

The use of UBSan runtime requires the use of Clang compiler and `-fsanitize=undefined` argument. Refer to
[Clang documentation](https://releases.llvm.org/7.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html) for more
details.

#### Credits

- The HermitCrabs Lab
- All projects providing third-party code (refer to file headers)
- [AppleLife](https://applelife.ru) team and user-contributed resources
- Chameleon and Clover teams for hints and legacy
- [al3xtjames](https://github.com/al3xtjames)
- [Andrey1970AppleLife](https://github.com/Andrey1970AppleLife)
- [mhaeuser (ex Download-Fritz)](https://github.com/mhaeuser)
- [Goldfish64](https://github.com/Goldfish64)
- [MikeBeaton](https://github.com/MikeBeaton)
- [nms42](https://github.com/nms42)
- [PMheart](https://github.com/PMheart)
- [savvamitrofanov](https://github.com/savvamitrofanov)
- [usr-sse2](https://github.com/usr-sse2)
- [vit9696](https://github.com/vit9696)

#### Discussion

Please refer to the following [list of OpenCore discussion forums](/Docs/FORUMS.md).

---

## File: AppleModels/README.md

Apple Models
===========

Various information about Apple hardware
([current database status](https://github.com/acidanthera/OpenCorePkg/blob/master/AppleModels/DataBase.md)).

## Improving database

To add a new hardware board, please create a file in DataBase
directory, and then run `./update_generated.py`. It should not
output anything and return zero code.

To install PyYAML on macOS use the following commands:

```
sudo -H python3 -m pip install pyyaml
```

## Unpacking firmware

To update the database you can either get the information from firmware images or from
running hardware. There currently are two places for firmware images: `FirmwareUpdate.pkg`
for generic models and `BridgeOSUpdateCustomer.pkg` for T2 models (the entire restore list
is available at [mesu.apple.com](https://mesu.apple.com/assets/bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml))
To use them do as follows:

1. Visit suitable update catalogue by filling the OS versions (e.g. [this](https://swscan.apple.com/content/catalogs/others/index-16seed-16-15-14-13-12-10.16-10.15-10.14-10.13-10.12-10.11-10.10-10.9-mountainlion-lion-snowleopard-leopard.merged-1.sucatalog.gz) one for macOS 26 beta).  
Note: This catalogue does not include `FirmwareUpdate.pkg` for macOS 11+. You can extract firmware images for generic models from `Install macOS Big Sur.app` (or newer).
2. Download most recent `FirmwareUpdate.pkg` and `BridgeOSUpdateCustomer.pkg`.
3. Extract `scap` and `fd` files from `FirmwareUpdate.pkg` and use them as is.
4. Extract `/usr/standalone/firmware/bridgeOSCustomer.bundle/Contents/Resources/UpdateBundle.zip`
   file from `BridgeOSUpdateCustomer.pkg` and unpack it.
5. After unpacking `UpdateBundle.zip` go to `boot/Firmware/MacEFI` directory and unpack im4p files.
   You can use [img4](https://github.com/xerub/img4lib), [img4tool](https://github.com/tihmstar/img4tool), or our dedicated [MacEfiUnpack](https://github.com/acidanthera/OpenCorePkg/blob/master/Utilities/MacEfiUnpack/MacEfiUnpack.py). For example, `for i in *.im4p ; do ./MacEfiUnpack.py "$i" ; done`

---

## File: Application/GopStop/README.md

GOP Testing Tool
================

1. Disable watchdog timer.
2. Gather all N available GOP protocols.
3. Allocate N buffer for GOP reports (`EFI_PAGE_SIZE`).
4. Get GOP reports for every GOP and set maximum resolution.
5. Save GOP reports to file to any writable fs (`gop-{date}.txt`)
6. Run tests in every GOP with non-zero resolution.

### GOP Report

```
GOP #(%u+1) of total %u, console/auxiliary
Current mode %u, max mode %u, FB: %p, FBS: %X
Current: W x H, pixel %u (%X %X %X %X), scan: %u
0: W x H, pixel %u (%X %X %X %X), scan: %u
1: Invalid parameter
New mode %u, max mode %u, FB: %p, FBS: %X
New: W x H, pixel %u (%X %X %X %X), scan: %u
```

### GOP Test

1. Fill screen with Red (#FF0000) in direct mode.
1. Wait 5 seconds.
1. Fill screen with 4 rectangles. From left to right top to bottom they should contain the following colours: Red (#FF0000) / Green (#00FF00) / Blue (#0000FF) / White (#FFFFFF). The user should visually ensure that the colours match and that rectangles equally split the screen in 4 parts.
1. Wait 5 seconds.
1. **UNIMPLEMENTED** Fill screen with white text on black screen in normal mode. The screen should effectively be filled with 9 equal rectangles. From left to right top to bottom they should contain the following symbols: A B C D # F G H I. Instead of # there should be current GOP number. The user should visually ensure text and background colour, rectangle sizes, rectangle data.
1. **UNIMPLEMENTED** Wait 5 seconds.
1. **UNIMPLEMENTED** Fill screen with white text on black screen in HiDPI mode. This should repeat the previous test but the text should be twice bigger. The user should ensure all previous requirements and the fact that the text got bigger.
1. **UNIMPLEMENTED** Wait 5 seconds.
1. **UNIMPLEMENTED** Print all GOP reports one by one (on separate screens) with white text in black screen in normal mode. Wait 5 seconds after each. The user should screenshot these and later compare to the file if available.
1. Fill screen with 9 rectangles of different colours. From left to right top to bottom they should contain the following colours: Red (#FF0000), Green (#00FF00), Blue (#0000FF), White (#FFFFFF), Light Grey (#989898), Black (#000000), Cyan (#00FFFF), Magenta (#FF00FF), Yellow (#FFFF00). visually ensure that the colours match and that rectangles equally split the screen in 9 parts.
1. Wait 5 seconds.

### Hints

- Due to not all resolutions being divisible by 2 and 3, right and bottom pixel rows may be unused in corresponding tests.
- Depending on rendering performance and amount of GOPs the test may take up to several minutes.
- Reference images for some tests are availale in `Examples` directory.

---

## File: Debug/README.md

UEFI Debugging with GDB/LLDB
============================

These scripts provide support for easier UEFI code debugging on virtual machines like VMware Fusion
or QEMU. The code is based on [Andrei Warkentin](https://github.com/andreiw)'s
[DebugPkg](https://github.com/andreiw/andreiw-wip/tree/master/uefi/DebugPkg) with improvements
in macOS support, pretty printing, and bug fixing.

The general approach is as follows:

1. Build GdbSyms binary with EDK II type info in DWARF
1. Locate `EFI_SYSTEM_TABLE` in memory by its magic
1. Locate `EFI_DEBUG_IMAGE_INFO_TABLE` by its GUID
1. Map relocated images within GDB
1. Provide handy functions and pretty printers

#### Preparing Source Code

To get started, the compilation environment should be set up. Such commands can be found in `Docs/Configuration.pdf`, section `3.3 Contribution`.

By default EDK II optimises produced binaries, so to build a "real" debug binary one should target
`NOOPT`. Do be aware that it strongly affects resulting binary size:

```
build -a X64 -t XCODE5   -b NOOPT -p OpenCorePkg/OpenCorePkg.dsc # for macOS
build -a X64 -t CLANGPDB -b NOOPT -p OpenCorePkg/OpenCorePkg.dsc # for other systems
```

`GdbSyms.dll` is built as a part of OpenCorePkg, yet prebuilt binaries are also available:

- `GdbSyms/Bin/X64_XCODE5/GdbSyms.dll` is built with XCODE5

To wait for debugger connection on startup `WaitForKeyPress` functions from `OcMiscLib.h` can be
utilised. Do be aware that this function additionally calls `DebugBreak` function, which may
be broken at during GDB/LLDB init.

#### VMware Configuration

VMware Fusion contains a dedicated debugStub, which can be enabled by adding the following
lines to .vmx file. Afterwards vmware-vmx will listen on TCP ports 8832 and 8864 (on the host)
for 32-bit and 64-bit gdb connections respectively, similarly to QEMU:
```
debugStub.listen.guest32 = "TRUE"
debugStub.listen.guest64 = "TRUE"
```

In case the debugging session is remote the following lines should be appended:
```
debugStub.listen.guest32.remote = "TRUE"
debugStub.listen.guest64.remote = "TRUE"
```

To halt the virtual machine upon executing the first instruction the following line code be added.
Note, that it does not seem to work on VMware Fusion 11 and results in freezes:
```
monitor.debugOnStartGuest32 = "TRUE"
```

To force hardware breakpoints use the following line:
```
debugStub.hideBreakpoints = "TRUE"
```

Alternatively to force software INT 3 breakpoints use the following line:
```
debugStub.hideBreakpoints = "FALSE"
```

Depending on the version of VMware Fusion and the host macOS version, only one or other of the
above may work to successfully single step and hit breakpoints, so you may need to try both.

When setting up a virtual machine for debugging, it is useful to be able to enter UEFI firmware
settings easily. To stall during POST for 3 seconds add the following line. Pressing any key
during this pause will boot into firmware settings:
```
bios.bootDelay = "3000"
```

In order to test `AudioDxe.efi` in VMware Fusion, the `.vmx` file must contain the line:
```
sound.virtualDev = "hdaudio"
```

This is present by default in a VM set up as macOS guest, and may be added manually to a Linux guest.
Current `AudioDxe.efi` UEFI sound quality in VMware Fusion is not representative of the quality available on real hardware.

#### QEMU configuration

In addition to VMware it is also possible to use [QEMU](https://www.qemu.org). QEMU debugging
on macOS host is generally rather limited and slow, but it is enough for generic troubleshooting
when no macOS guest booting is required.

1. Build OVMF firmware in NOOPT mode to be able to debug it:

    ```
    git submodule init
    git submodule update     # to clone OpenSSL
    build -a X64 -t XCODE5   -b NOOPT -p OvmfPkg/OvmfPkgX64.dsc # for macOS
    build -a X64 -t CLANGPDB -b NOOPT -p OvmfPkg/OvmfPkgX64.dsc # for other systems
    ```

    To build OVMF with SMM support add `-D SMM_REQUIRE=1`. To build OVMF with serial debugging
    add `-D DEBUG_ON_SERIAL_PORT=1`.

    _Note_: Optionally, you may build OvmfPkg with its own build script, which is located within the OvmfPkg directory.
    Use e.g. `./build.sh -a X64` or  `./build.sh -a X64 -b NOOPT`; additional build arguments such as for serial debugging
    or SMM support may be appended to this.

2. Prepare launch directory with OpenCore as usual. For example, make a directory named
    `QemuRun` and `cd` to it. You should have a similar directory structure:

    ```
    .
    └── ESP
        └── EFI
            ├── BOOT
            │   └── BOOTx64.efi
            └── OC
                ├── OpenCore.efi
                └── config.plist
    ```

3. Run QEMU
    
    The OvmfPkg build script can also start the virtual machine which it has just built, e.g.
    `./build.sh -a X64 qemu -drive format=raw,file=fat:rw:ESP` should be sufficient to start OpenCore;
    all options after `qemu` are passed directly to QEMU. Starting QEMU this way uses file `OVMF.fd`
    from the OVMF build directory, which is `OVMF_CODE.fd` and `OVMF_VARS.fd` combined; you may prefer
    to follow the second example below which specifies these files separately.

    In the remaining examples `OVMF_BUILD` should point to the OVMF build directory, e.g.
    `$HOME/UefiWorkspace/Build/OvmfX64/NOOPT_XCODE5/FV`.

    To start QEMU directly, and with a more realistic machine architecture:

    ```
    qemu-system-x86_64 -L . -bios "$OVMF_BUILD/OVMF.fd" -drive format=raw,file=fat:rw:ESP \
      -machine q35 -m 2048 -cpu Penryn -smp 4,cores=2 -usb -device usb-mouse -gdb tcp::8864
    ```

    To run QEMU with SMM support; also specifying CODE and VARS separately; also specifying the port required to connect a debugger (next section):

    ```
    qemu-system-x86_64 -L . -global driver=cfi.pflash01,property=secure,value=on \
      -drive if=pflash,format=raw,unit=0,file="$OVMF_BUILD"/OVMF_CODE.fd,readonly=on \
      -drive if=pflash,format=raw,unit=1,file="$OVMF_BUILD"/OVMF_VARS.fd \
      -drive format=raw,file=fat:rw:ESP \
      -global ICH9-LPC.disable_s3=1 -machine q35,smm=on,accel=tcg -m 2048 -cpu Penryn \
      -smp 4,cores=2 -usb -device usb-mouse -gdb tcp::8864
    ```

    You may additionally pass `-S` flag to QEMU to stop at first instruction
    and wait for GDB connection. To use serial debugging add `-serial stdio`
    (this causes OpenCore console log output to go to the shell which started QEMU).

4. Key and mouse support when running OpenCore in QEMU:

    Enabling keyboard and mouse support is effectively the same as on a normal machine, however some typical options are:

    For keyboard support either, a) use `KeySupport=true`, or b) use `KeySupport=false`, in which case pass `-usb -device usb-kbd` to QEMU, and use `OpenUsbKbDxe.efi` driver.

    For mouse support either, a) use `Ps2MouseDxe.efi` driver, or b) pass `-usb -device usb-mouse` to QEMU and use `UsbMouseDxe.efi` driver.

5. Audio support in QEMU:

    QEMU flags to enable audio support in QEMU running on macOS host are `-audiodev coreaudio,id=audio0 -device ich9-intel-hda -device hda-output,audiodev=audio0`.
      - `coreaudio` is the macOS specific hardware audio driver
      - `intel-hda` may be used instead of `ich9-intel-hda` in order to use the QEMU Intel HDA ICH6 software driver instead of ICH9
      - Note that current `AudioDxe.efi` UEFI sound quality in QEMU is not representative of the quality available on real hardware

#### Debugger Configuration

For simplicitly `efidebug.tool` performs all the necessary GDB or LLDB scripting.
Note, this adds the `reload-uefi` command within the debugger, which you need to run after any new binary loads.

The script will run and attempt to connect with reasonable defaults without additional configuration, but check
`efidebug.tool` header for environment variables to configure your setup. For example, you can use `EFI_DEBUGGER`
variable to force LLDB (`LLDB`) or GDB (`GDB`).

#### GDB Configuration

It is a good idea to use GDB Multiarch in case different debugging architectures are planned to be
used. This can be done in several ways:

- https://www.gnu.org/software/gdb/ — from source
- https://macports.org/ — via MacPorts (`sudo port install gdb +multiarch`)
- Your preferred method here

Once GDB is installed you can use `efidebug.tool` for debugging. In case you do not
want to use `efidebug.tool`, the following set of commands can be used as a reference:

```
$ ggdb /opt/UDK/Build/OpenCorePkg/NOOPT_XCODE5/X64/OpenCorePkg/Debug/GdbSyms/GdbSyms/DEBUG/GdbSyms.dll.dSYM/Contents/Resources/DWARF/GdbSyms.dll

target remote localhost:8864
source /opt/UDK/OpenCorePkg/Debug/Scripts/gdb_uefi.py
set pagination off
reload-uefi
b DebugBreak
```

#### CLANGDWARF

CLANGDWARF toolchain is an LLVM-based toolchain that directly generates
PE/COFF images with DWARF debug information via LLD linker. LLVM 9.0 or
newer with working dead code stripping in LLD is required for this to work
([LLD patches](https://bugs.llvm.org/show_bug.cgi?id=45273)).

For debugging support it may be necessary to set `EFI_SYMBOL_PATH`
environment variable to `:`-separated list of paths with `.debug` files,
for example:

```
export EFI_SYMBOL_PATH="$WORKSPACE/Build/OvmfX64/NOOPT_CLANGPDB/X64:$WORKSPACE/Build/OpenCorePkg/NOOPT_CLANGPDB/X64"
```

The reason for this requirement is fragile `--add-gnudebug-link` option
[implementation in llvm-objcopy](https://bugs.llvm.org/show_bug.cgi?id=45277).
It strips path from the debug file preserving only filename and also does not
update DataDirectory debug entry.

#### IDE Source Level Debugging

Once you have got command line GDB or LLDB source level debugging working, setting up IDE source level debugging (if you prefer to use it)
is a matter of choosing an IDE which already knows about whichever of GDB or LLDB you will be using, and then extracting the relevant config
setup which `efidebug.tool` would have applied for you.

For example, this is a working `launch.json` file for both LLDB and GDB debugging in VS Code:

```
/* Detailed source-code truncated for AI context efficiency. */
```

_Note 1_: Debug type `cppdbg` is part of the standard VSCode cpp tools - you do not need to install any other marketplace LLDB tools.

_Note 2_: Step `b DebugBreak` from `efidebug.tool` is ommitted from `customLaunchSetupCommands`, you need to add the breakpoint by
hand in VSCode before launching your first debug session, otherwise VSCode will complain about hitting a breakpoint which it did not set.

#### References

1. https://communities.vmware.com/thread/390128
1. https://wiki.osdev.org/VMware
1. https://github.com/andreiw/andreiw-wip/tree/master/uefi/DebugPkg

---

## File: Docs/Logos/README.md

OpenCore Logo
=============

This directory contains OpenCore project official logo. The following
formats are supported:

- Sketch source file
- Portable Document Format (PDF)
- Portable Network Graphics (PNG)
- Scalable Vector Graphics (SVG)

SVG format is currently not recommended, as it contains an approximated
version of the logo, which has slightly wrong colourspace due to missing
conic gradient support in SVG.

You may use this logo free of charge to refer to OpenCore project for
informational purposes. You have no right to modify logo. 
The use of this logo in your own projects which
are related to OpenCore is also permitted free of charge, yet requires
OpenCore maintainer approval. Please
[contact us](https://github.com/acidanthera/bugtracker/issues/new)
for more details.

We would like to express our deep gratitude to
[Anadea Inc.](http://anadea.info) designing team for their brilliant work
and extreme patience!

---

## File: Docs/Flavours.md

# OpenCore Content Flavours

See [Configuration.pdf](Configuration.pdf) for a technical description of the OpenCore content flavour system.

This document provides a list of recommended flavours, so that icon pack artists understand what they must and can do, and so that different icon packs can use consistent names for optional icons.

***Please follow this guide when providing non-default icons in icon packs.***

Please raise a Pull Request or create an Issue to request additional flavours added to the lists below.


## Recommended Icon Flavours

In general, users are recommended to apply the full specified flavour names from the lists below (in **bold**), and icon pack authors are strongly encouraged to create icons with file names from the lists below (in `monotype`)

Icon pack authors are encouraged to provide only those icons for which there is real demand. The complete lists below are provided for consistency of naming, and not because there is a requirement to provide all (or even most, or any - except for the required system icons listed last) of the icons listed here in a given icon pack.

> Note that for all boot entry icon files `<Flavour>.icns` specified below, an `Ext<Flavour>.icns` version may be provided as well. If the selected flavour is specified for an external drive then, if present, `Ext<Flavour>.icns` will be used, otherwise for security reasons OpenCore will use `ExtHardDrive.icns` instead (not `<Flavour>.icns`). Providing `Ext<Flavour>.icns` is optional for icon providers, the fallback behaviour will be perfectly acceptable anyway, in most cases.

## macOS

In the case of macOS only, a flavour based on the detected OS version is applied automatically (as shown below), and the user does not normally need to override this.

For icon pack authors, the **Apple** icon is recommended, **AppleRecv** and **AppleTM** are suggested, all others are entirely optional.

 - **Apple12:Apple** - Monterey (`Apple12.icns`)
 - **Apple11:Apple** - Big Sur (`Apple11.icns`)
 - **Apple10_15:Apple** - Catalina (`Apple10_15.icns`, etc.)
 - **Apple10_14:Apple** - Mojave
 - **Apple10_13:Apple** - High Sierra
 - **Apple10_12:Apple** - Sierra
 - **Apple10_11:Apple** - El Capitan
 - **Apple10_10:Apple** - Yosemite
 - **Apple10_9:Apple** - Mavericks
 - **Apple10_8:Apple** - Mountain Lion
 - **Apple10_7:Apple** - Lion
 - **Apple10_6:Apple** - Snow Leopard
 - **Apple10_5:Apple** - Leopard
 - **Apple10_4:Apple** - Tiger

In addition, per-OS Recovery variants and Time Machine variants may be supported by adding `Recv` and `TM` to each element of the flavour as shown below.

Recovery flavours also automatically add the OS version:

 - **AppleRecv11:AppleRecv:Apple11:Apple** - macOS Big Sur Recovery (`AppleRecv11.icns`, etc.)
 - ...
 - **AppleRecv10_4:AppleRecv:Apple10_4:Apple** - macOS Tiger Recovery

 Time machine icons _do not_ automatically add the OS version, so per-OS versions would require manual specification by the user (e.g. in `.contentFlavour`) as follows, in order to be found and used:

 - **AppleTM:Apple** - macOS Time Machine, default flavour, not version specific
 - **AppleTM11:AppleTM:Apple11:Apple** - macOS Big Sur Time Machine (`AppleTM11.icns`, etc.)
 - ...
 - **AppleTM10_4:AppleTm:Apple10_4:Apple** - macOS Tiger Time Machine

## Windows

Windows is automatically detected by OpenCore, so the basic `Windows` flavour will be applied automatically. Unlike macOS, Windows versions are not detected automatically, so per-version icons will require manual specification by the user (e.g. in `.contentFlavour`) as follows, in order to be found and used.

**Windows** icon is recommended, all others are optional.

 - **Windows** - Microsoft Windows (auto-detected by OC; fallback: **HardDrive**)
 - **Windows11:Windows** - Microsoft Windows 11 (`Windows11.icns`)
 - **Windows10:Windows** - Microsoft Windows 10 (`Windows10.icns`)
 - **Windows8_1:Windows** - Microsoft Windows 8.1 (`Windows8_1.icns`, etc.)
 - **Windows8:Windows** - Microsoft Windows 8
 - **Windows7:Windows** - Microsoft Windows 7


## Linux

Icon support for Linux is optional. It is not required to provide all flavours even if some are provided; icon pack authors are encouraged to respond to real user demand.

> Note: Media pack authors should understand that it is not required, but optional, to provide `Linux.icns` even if, for example, `Debian.icns` or `Ubuntu.icns` are provided. Provided icons will be used (if selected in flavours specified by the user); icons which are not present will always fall back eventually to OC defaults. (In the case of an OS this will fall back to `HardDrive.icns`.) Similar rules apply in all sections.

Please open an Issue or Pull Request if an additional Linux flavour is required. (Please base this on actual need, e.g. it will affect at least several users.)

 - **Linux** - Base icon for Linux (`Linux.icns`)
 - **Arch:Linux** - Arch Linux (`Arch.icns`, etc.)
 - **Astra:Linux** - Astra Linux
 - **CentOS:Linux** - CentOS
 - **Debian:Linux** - Debian
 - **Deepin:Linux** - Deepin
 - **elementaryOS:Linux** - elementary OS
 - **Endless:Linux** - Endless OS
 - **Gentoo:Linux** - Gentoo Linux
 - **Fedora:Linux** - Fedora
 - **KDEneon:Linux** - KDE neon
 - **Kali:Linux** - Kali Linux
 - **MX:Linux** - MX Linux
 - **Mageia:Linux** - Mageia (fork of former Mandriva)
 - **Manjaro:Linux** - Manjaro
 - **Mint:Linux** - Linux Mint
 - **openSUSE:Linux** - openSUSE
 - **Oracle:Linux** - Oracle Linux
 - **PopOS:Linux** - Pop!_OS
 - **RHEL:Linux** - Red Hat Enterprise Linux
 - **Rocky:Linux** - Rocky Linux
 - **Solus:Linux** - Solus
 - **Ubuntu:Linux** - Ubuntu
 - **Lubuntu:Ubuntu:Linux** - Lubuntu (`Lubuntu.icns`, etc.)
 - **UbuntuMATE:Ubuntu:Linux** - Ubuntu MATE
 - **Void:Linux** - Void Linux
 - **Xubuntu:Ubuntu:Linux** - Xubuntu
 - **Zorin:Linux** - Zorin OS

## Other Operating Systems

All optional.

Additional sub-flavours are obviously possible for Android, but none are currently defined in this list. Create a Pull Request or Issue if you believe there is a genuine need - e.g. affecting at least several users - to include these.

 - **Android** - Android OS
   - It is down to user preference whether to specify the flavour as **Android:Linux** or just **Android** - depending on whether the user wishes to use `Linux.icns` as a fallback where available, or to fallback directly to **HardDrive** if no `Android.icns` is available
 - **BSD** - Base icon for BSD
 - **FreeBSD:BSD** - FreeBSD
   - Typically at most one of the above two icon files will be provided
 - **ReactOS** - ReactOS (alpha version open-source Windows Server binary compatible OS; not currently UEFI bootable, but reserved here anyway) (`ReactOS.icns`)
   - It is user preference whether to specify **ReactOS:Windows** or just **ReactOS** - depending on whether the user wishes to use `Windows.icns` as a fallback, or to fallback directly to `HardDrive.icns` if no `ReactOS.icns` is available.

## Tools

Create an Issue or Pull Request to request additional tool icons. If doing so please provide a clear case, e.g. showing that it affects at least several users.

### Generic Tool Icon

It is recommended to provide this icon.

 - **Tool** - Any tool entry
   - If provided, is used as fallback for non-OS entries in OpenCore; if not provided falls back again to **HardDrive** (which is required)

### Shell Tools

It is recommended to provide _one_ of these files (more is optional, and not normally required).

If providing just one file, name it `Shell.icns` if the theming of the icon is generic to any shell tool (as in the examples in OcBinaryData). Name it `OpenShell.icns` or `UEFIShell.icns` if the theming is more specific (e.g. includes specific text on the icon).

 - **Shell** - Any shell-style tool
 - **UEFIShell:Shell** - EDK II UEFI Shell
   - As an example of how flavours work: **UEFIShell:Shell** will try `UEFIShell.icns`, then `Shell.icns` (and then, by OC default behaviour, `Tool.icns`, then `HardDrive.icns`)
   - _**Note**: Including **UEFIShell** anywhere in the flavour triggers picker audio-assist for "UEFI Shell"_
 - **OpenShell:UEFIShell:Shell** - Themed specifically for OpenCore OpenShell (which is a variant of the EDK II UEFI Shell)
   - This is the recommended flavour to use for `OpenShell.efi`, as is done in the sample config files
   - Although this is the recommended *flavour*, icon artists are not required to provide this icon file, since this flavour will automatically find and use `Shell.icns` or `UEFIShell.icns` anyway
   - Because **UEFIShell** is included in this flavour, it will also trigger picker audio-assist for "UEFI Shell"
 - **GRUBShell:Shell** - GRUB Shell themed icon

### NVRAM Tools

It is recommended to either i) only provide `NVRAMTool.icns`, as this will be applied to the Reset NVRAM tool and the Toogle SIP tool, or else ii) provide `ResetNVRAM.icns` and `ToggleSip.icns` separately (in which case `NVRAMTool.icns` is not normally required).

If providing `NVRAMTool.icns`, it should be themed so that it could be applied to any generic NVRAM tool.

 - **NVRAMTool** - Any NVRAM-related tool (`NVRAMTool.icns`)
 - **ResetNVRAM:NVRAMTool** - Reset NVRAM tool  (`ResetNVRAM.icns`)
   - This is the recommended flavour, used for the entry created by the `ResetNvramEntry.efi` driver.
   - As another example of how flavours work: **ResetNVRAM:NVRAMTool** will look for `ResetNVRAM.icns`, then `NVRAMTool.icns` (and then, by OC default behaviour, `Tool.icns` then `HardDrive.icns`)
   - **Note**: Including **ResetNVRAM** anywhere in a flavour triggers picker audio-assist and builtin label support for "Reset NVRAM"
 - **ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool  (`ToggleSIP.icns`)
 - **ToggleSIP_Enabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is enabled (system is protected)
 - **ToggleSIP_Disabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is disabled (system is unprotected)
   - **Note**: Including **ToggleSIP_Enabled** or **ToggleSIP_Disabled** anywhere in a flavour triggers picker audio-assist and builtin label support for the two states of the Toggle SIP menu entry

### Network Boot

`OpenNetworkBoot.efi` uses the following flavours:

 - **HttpBoot4:HttpBoot:NetworkBoot** - IPv4 HTTP(S) Boot
 - **HttpBoot6:HttpBoot:NetworkBoot** - IPv6 HTTP(S) Boot
 - **PxeBoot4:PxeBoot:NetworkBoot** - IPv4 PXE Boot
 - **PxeBoot6:PxeBoot:NetworkBoot** - IPv6 PXE Boot

If none of these icons are available, network boot is treated like an external OS, so the fallbacks are **Other** followed by **HardDrive**.

 - **Note**: Including **NetworkBoot** anywhere in a flavour triggers picker audio-assist and builtin label support for "Network Boot"

### Other Tools

A list of other known tools which are common enough that some icon pack artists may wish to provide a standard icon for them:

 - **FirmwareSettings** - A boot menu entry for accessing firmware settings, such as generated by `FirmwareSettingsEntry.efi` (`FirmwareSettings.icns`)
   - **Note**: Including **FirmwareSettings** anywhere in a flavour triggers picker audio-assist and builtin label support for "Firmware Settings"
 - **MemTest** - A system memory testing tool such as that available from [memtest86.com](https://www.memtest86.com/) (`MemTest.icns`)

## Bootloaders

Certain well-known bootloaders have also been assigned a flavour:

 - **Boatloader** - Generic bootloader icon (`Bootloader.icns`)
 - **Grub:Bootloader** - Icon for the GRUB2 bootloader (`Grub.icns`)
 - **OpenCore:Bootloader** - OpenCore intentionally does not offer to start instances of itself which have had the OC binary signature applied (i.e. standard release versions), however a) it will show non-signed versions and b) we need to have our own flavour (`OpenCore.icns`)

---

## System Boot Entry Icons

### Required

OpenCanopy will not start if these are not present.

 - **ExtHardDrive** - Bootable OS (on external drive)
 - **HardDrive** - Bootable OS

### Optional

Provided by OcBinaryData. Used automatically by OC in some circumstances, if provided in an icon pack.

 - **AppleRecv** - Apple Recovery (fallback: **HardDrive**)
 - **AppleTM** - Apple Time Machine (fallback: **HardDrive**)
 - **ExtAppleRecv** - Apple Recovery (on external drive) (fallback: **ExtHardDrive**)
 - **ExtAppleTM** - Apple Time Machine (on external drive) (fallback: **ExtHardDrive**)
 - **Shell** - Shell tool (fallback: **Tool**)
 - **Tool** - Generic tool (fallback: **HardDrive**)
 - **Other** - Other OS (fallback: **HardDrive**)
 - **Windows** - Microsoft Windows (fallback: **HardDrive**)

### Additional Optional

NOT provided by OcBinaryData. Are used automatically by OC in some circumstances, if provided.

 - **Apple** - macOS (fallback: **HardDrive**)
 - **ExtApple** - macOS (on external drive) (fallback: **ExtHardDrive**)
 - **ExtWindows** - Microsoft Windows (on external drive) (fallback: **ExtHardDrive**)
 - **ResetNVRAM** - Reset NVRAM tool (fallback: **Tool**)

---

## System Icons

Required. OpenCanopy will not start if these are not present.

These icons are not directly related to boot entry flavours, but they are included here to provide all relevant icon pack info in one place.

 - **BtnFocus** - show focus on additional (shutdown and restart) buttons (`BtnFocus.icns`)
 - **Cursor** - mouse cursor (`Cursor.icns`, etc.)
 - **Dot** - password entry hidden character dot
 - **Enter** - password entry enter symbol
 - **Left** - additional picker entries to left
 - **Lock** - password lock
 - **Password** - password entry text area
 - **Restart** - additional button: restart
 - **Right** - additional picker entries to right
 - **Selected** - selected entry background
 - **Selector** - show selected entry
 - **SetDefault** - show selected entry in 'set default' mode
 - **ShutDown** - additional button: shut down

In addition, **Background** (`Background.icns`) is used as the background image for the OpenCanopy boot picker if provided.

---

## File: Docs/FORUMS.md

## OpenCore Discussion Forums

- AppleLife.ru in Russian:
  - [Development](https://applelife.ru/threads/razrabotka-opencore.2943955)
  - [Discussion](https://applelife.ru/threads/opencore-obsuzhdenie-i-ustanovka.2944066/)
  - [Icon sets](https://applelife.ru/threads/kastomizacija-opencanopy.2945020/)
- [Hackintosh-Forum.de](https://www.hackintosh-forum.de/forum/thread/42353-opencore-bootloader) in German
- MacRumors.com in English:
  - [Big Sur on Unsupported Macs](https://forums.macrumors.com/threads/macos-11-big-sur-on-unsupported-macs-thread.2242172/)
  - [Monterey on Unsupported Macs](https://forums.macrumors.com/threads/macos-12-monterey-on-unsupported-macs-thread.2299557/)
  - [OpenCore on the MacPro](https://forums.macrumors.com/threads/opencore-on-the-mac-pro.2207814/)
- [macOS86.it](https://macos86.it/topic/1187-opencore-aka-oc-nuovo-bootloader/) in Italian
- [KVM-OpenCore](https://github.com/Leoyzen/KVM-Opencore) in English, KVM configuration
- [Reddit](https://www.reddit.com/r/hackintosh) in English

---

## File: Docs/Kexts.md

Kexts
=====

| Ethernet | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|----------|-----------------------|-----------------------|------|
| [AppleRTL8169Ethernet](https://www.realtek.com/en/directly-download) | — | — | — |
| [AtherosE2200Ethernet.kext](https://github.com/Mieze/AtherosE2200Ethernet) | — | — | — |
| [AtherosL1cEthernet.kext](https://github.com/al3xtjames/AtherosL1cEthernet) | — | — | — |
| [IntelMausi.kext](https://github.com/acidanthera/IntelMausi) | 13.0.0 (10.9) | — | — |
| [IntelSnowMausi.kext](https://github.com/acidanthera/IntelMausi) | 10.0.0 (10.6) | 12.0.0 (10.8) | Not tested |
| [IntelMausiEthernet.kext](https://github.com/Mieze/IntelMausiEthernet) | — | — | — |
| [NullEthernetInjector.kext](https://github.com/RehabMan/OS-X-Null-Ethernet) | — | — | — |
| [RealtekR1000SL.kext](https://github.com/SergeySlice/RealtekLANv3) | — | — | — |
| [RealtekRTL8100.kext](https://github.com/Mieze/RealtekRTL8100) | — | — | — |
| [RealtekRTL8111.kext](https://github.com/Mieze/RTL8111_driver_for_OS_X) | — | — | — |

| Wi-Fi and bluetooth | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|---------------------|-----------------------|-----------------------|------|
| [AirPortAtheros40.kext](https://i.applelife.ru/2018/12/442854_AirPortAtheros40.kext.zip) | 18.0.0 (10.14) | — | From 10.13 |
| [AirportBrcmFixup.kext](https://github.com/acidanthera/AirportBrcmFixup) | 12.0.0 (10.8) | 25.9.9 (26) | — |
| [ATH9KFixup.kext](https://github.com/chunnann/ATH9KFixup) | — | — | — |
| [BrcmPatchRAM](https://github.com/acidanthera/BrcmPatchRAM) | 14.0.0 (10.10) | 25.9.9 (26) | — |
| [IntelBluetoothFirmware](https://github.com/zxystd/IntelBluetoothFirmware) | — | — | — |
| [MT7610](https://d86o2zu8ugzlg.cloudfront.net/mediatek-craft/drivers/MT7612_7610U_D5.0.1.25_SDK1.0.2.18_UI5.0.0.27_20151209.zip) | — | — | — |
| [RT5370](https://d86o2zu8ugzlg.cloudfront.net/mediatek-craft/drivers/RTUSB_D2870-4.2.9.2_UI-4.0.9.6_2013_11_29.zip) | — | — | — |
| [RTL8192CU](https://drive.google.com/file/d/1ZtdMqlvKBbHULJhl1u9omuLOy6j0vx48/view?usp=sharing) | — | — | — |

| Keyboard, trackpad and mouse | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|------------------------------|-----------------------|-----------------------|------|
| [BrightnessKeys.kext](https://github.com/acidanthera/BrightnessKeys) | — | — | — |
| [GK701HIDDevice.kext](https://github.com/osy86/GK701HIDDevice) | — | — | — |
| [NoTouchID.kext](https://github.com/al3xtjames/NoTouchID) | 17.0.0 (10.13) | — | — |
| [SerialMouse.kext](https://github.com/Goldfish64/SerialMouse) | — | — | — |
| [VoodooI2C.kext](https://github.com/VoodooI2C/VoodooI2C) | 16.0.0 (10.12) | — | — |
| [VoodooPS2Controller.kext](https://github.com/acidanthera/VoodooPS2) | 14.0.0 (10.10) | — | — |
| [VoodooPS2Keyboard.kext](https://github.com/acidanthera/VoodooPS2) | 14.0.0 (10.10) | — | — |
| [VoodooPS2Mouse.kext](https://github.com/acidanthera/VoodooPS2) | 14.0.0 (10.10) | — | — |
| [VoodooPS2Trackpad.kext](https://github.com/acidanthera/VoodooPS2) | 14.0.0 (10.10) | — | — |
| [VoodooInput.kext](https://github.com/acidanthera/VoodooInput) | 14.0.0 (10.10) | — | — |
| [VoodooSMBus.kext](https://github.com/leo-labs/VoodooSMBus) | 18.0.0 (10.14) | — | — |
| [VoodooRMI.kext](https://github.com/VoodooSMBus/VoodooRMI) | 15.0.0 (10.11) | — | — |
| [AlpsHID.kext](https://github.com/blankmac/AlpsHID) | — | — | — |

| Video and audio | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|-----------------|-----------------------|-----------------------|------|
| [AppleALC.kext](https://github.com/acidanthera/AppleALC) | 8.0.0 (10.4) | 25.9.9 (26) | — |
| [AppleALCU.kext](https://github.com/acidanthera/AppleALC) | 8.0.0 (10.4) | 25.9.9 (26) | — |
| [EMUUSBAudio.kext](https://github.com/Wouter1/EMU-driver) | — | — | — |
| [kXAudioDriver.kext](https://github.com/kxproject/kx-audio-driver) | — | — | — |
| [Nvidia CUDA drivers](https://www.nvidia.com/object/mac-driver-archive.html) | 10.0.0 (10.6) | 17.9.9 (10.13) | — |
| [Nvidia Web-drivers](https://gfe.nvidia.com/mac-update) | 12.0.0 (10.8) | 17.9.9 (10.13) | — |
| [VoodooHDA.kext](https://sourceforge.net/projects/voodoohda/) | — | — | — |
| [WhateverGreen.kext](https://github.com/acidanthera/WhateverGreen) | 10.0.0 (10.6) | 25.9.9 (26) | — |
| [Polaris22Fixup.kext](https://github.com/osy86/Polaris22Fixup) | 18.0.0 (10.14) | — | — |

| CPU and SMC | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|-------------|-----------------------|-----------------------|------|
| [AAAMouSSE.kext](https://forums.macrumors.com/threads/mp3-1-others-sse-4-2-emulation-to-enable-amd-metal-driver.2206682/) | 16.0.0 (10.12) | — | — |
| [AppleMCEReporterDisabler.kext](https://github.com/acidanthera/bugtracker/issues/424#issuecomment-535624313) | — | — | — |
| [AsusSMC.kext](https://github.com/hieplpvip/AsusSMC) | — | — | — |
| [CPUFriend.kext](https://github.com/acidanthera/CPUFriend) | 10.0.0 (10.6) | 25.9.9 (26) | — |
| [HWPEnabler.kext](https://github.com/headkaze/HWPEnable) | — | — | — |
| [OpcodeEmulator.kext](https://www.insanelymac.com/forum/topic/329704-opcode-emulator-opemu-plug-in-project/) | — | — | — |
| [telemetrap.kext](https://forums.macrumors.com/posts/28447707) | 18.0.0 (10.14) | — | — |
| [TSCAdjustReset.kext](https://github.com/interferenc/TSCAdjustReset) | — | — | — |
| [VoodooTSCSync.kext](https://github.com/RehabMan/VoodooTSCSync) | — | — | — |
| [CpuTscSync.kext](https://github.com/acidanthera/CpuTscSync) | 12.0.0 (10.8) | 25.9.9 (26) | — |
| [VirtualSMC.kext](https://github.com/acidanthera/VirtualSMC) | 8.0.0 (10.4) | 25.9.9 (26) | — |
| [SMCLightSensor.kext](https://github.com/acidanthera/VirtualSMC) | 10.0.0 (10.6) | — | Not tested 10.6 and 10.7 |
| [SMCSuperIO.kext](https://github.com/acidanthera/VirtualSMC) | 10.0.0 (10.6) | — | Not tested 10.6 and 10.7 |
| [SMCBatteryManager.kext](https://github.com/acidanthera/VirtualSMC) | 8.0.0 (10.4) | — | — |
| [SMCProcessor.kext](https://github.com/acidanthera/VirtualSMC) | 11.0.0 (10.7) | — | Not tested 10.7 |
| [SMCDellSensor.kext](https://github.com/acidanthera/VirtualSMC) | 11.0.0 (10.7) | — | Not tested 10.7 |

| USB and other ports | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|---------------------|-----------------------|-----------------------|------|
| [IOElectrify.kext](https://github.com/the-darkvoid/macOS-IOElectrify) | — | — | — |
| [Legacy_InternalHub-EHCx.kext](https://applelife.ru/posts/537459) | 15.0.0 (10.11) | — | — |
| [Legacy_USB3.kext](https://applelife.ru/posts/537459) | 15.0.0 (10.11) | — | — |
| [NVMeFix.kext](https://github.com/acidanthera/NVMeFix) | 18.0.0 (10.14) | 25.9.9 (26) | — |
| [USBWakeFixup.kext](https://github.com/osy86/USBWakeFixup) | — | — | — |
| [SASMegaRAID.kext](https://github.com/dukzcry/osx-goodies) | — | — | — |
| [Sinetek-rtsx.kext](https://www.insanelymac.com/forum/topic/321080-sineteks-driver-for-realtek-rtsx-sdhc-card-readers/?do=findComment&comment=2376387) | — | — | — |
| [VoodooSDHC.kext](https://github.com/lvs1974/VoodooSDHCMod) | — | — | — |
| [RealtekCardReader.kext](https://github.com/0xFireWolf/RealtekCardReader) | — | — | — |
| [EmeraldSDHC.kext](https://github.com/acidanthera/EmeraldSDHC) | — | — | — |

| Other kexts | MinKernel (Min macOS) | MaxKernel (Max macOS) | Note |
|-------------|-----------------------|-----------------------|------|
| [AppleIntelInfo.kext](https://github.com/headkaze/AppleIntelInfo) | — | — | — |
| [DebugEnhancer.kext](https://github.com/acidanthera/DebugEnhancer) | 12.0.0 (10.8) | 25.9.9 (26) | — |
| [HibernationFixup.kext](https://github.com/acidanthera/HibernationFixup) | 12.0.0 (10.8) | 25.9.9 (26) | — |
| [Lilu.kext](https://github.com/acidanthera/Lilu) | 8.0.0 (10.4) | 25.9.9 (26) | — |
| [RestrictEvents.kext](https://github.com/acidanthera/RestrictEvents) | 12.0.0 (10.8) | 25.9.9 (26) | — |
| [RTCMemoryFixup.kext](https://github.com/lvs1974/RTCMemoryFixup) | 12.0.0 (10.8) | — | — |
| [WebCamera.kext](https://www.applelife.ru/threads/asus-x550vc-i-asus-x550cc.41752/page-130#post-593586) | — | — | — |
| [TOSMotionSensor.kext](https://github.com/jslegendre/TOSMotionSensor) | — | — | — |
| [FeatureUnlock.kext](https://github.com/acidanthera/FeatureUnlock) | 16.0.0 (10.12) | 25.9.9 (26) | — |
| [MacHyperVSupport.kext](https://github.com/acidanthera/MacHyperVSupport) | 8.0.0 (10.4) | 25.9.9 (26) | — |
| [CryptexFixup.kext](https://github.com/acidanthera/CryptexFixup) | 20.0.0 (11) | 25.9.9 (26) | — |

More complete list with legacy kexts is hosted [here](https://docs.google.com/spreadsheets/d/15S-ocrkm_VTUJpKxNII-YUyQFd5VYdjbe0DHlZVCQyM). Full Lilu plugin list with legacy kexts is hosted [here](https://github.com/acidanthera/Lilu/blob/master/KnownPlugins.md). For developers only.   
Acidanthera members are not affiliated with the authors of any kernel extensions but ones hosted at https://github.com/acidanthera. This list is provided for information purposes without warranty of any kind.

---

## File: Docs/Libraries.md

#### Library Descriptions

* OcAcpiLib — ACPI injector and patcher
* OcAppleBootPolicyLib — Apple bless protocol implementation
* OcAppleKernelLib — Apple kernelspace injector and patcher
* OcCompressionLib — Misc compression and decompression (LZSS, LZVN, ZLIB)
* OcAppleChunklistLib — Apple chunklist (e.g. for dmg hashes) handling library
* OcBootManagementLib — Simple blessed-based boot management with UI
* OcCpuLib — CPU feature scanning
* OcCryptoLib — Misc cryptographic primitives (AES, RSA, MD5, SHA-1, SHA-256)
* OcDataHubLib — Apple-specific DataHub data configuration
* OcAppleDiskImageLib — Expose DMG as a UEFI RAM disk
* OcConfigurationLib — Deserialize OpenCore configuration
* OcDebugLogLib — Debug output redirection through OC Log protocol
* OcDevicePathLib — Device path management and transformation
* OcDevicePropertyLib — Apple device property protocol implementation
* OcFileLib — Supplemental file I/O
* OcFirmwarePasswordLib — Apple firmware password protocol implementation
* OcGuardLib — Basic sanity checking (static assertions, overflow maths)
* OcMachoLib — Mach-O image handling and transformation
* OcMiscLib — Miscellaneous stuff not fitting elsewhere
* OcPeCoffExtLib — EFI image management extras for Apple
* OcPngLib — PNG image decoding
* OcRtcLib — CMOS memory access
* OcSerializeLib — PLIST document deserialization
* OcSmbiosLib — Apple-specific SMBIOS data configuration
* OcStorageLib — Resource storage abstraction (from e.g. FS I/O)
* OcStringLib — String handling and management
* OcTemplateLib — Data description and resource management
* OcTimerLib — EDK II timer library based on TSC
* OcVirtualFsLib — UEFI file system interception
* OcXmlLib — XML and PLIST reading and transformation