Go back to main page

ATV1sm

Bypass for the original Apple TV's EFI verification, allowing it to boot and run any EFI-capable OS. View on GitHub

READ THIS FIRST!

Every Apple device with IA32 EFI, including the original Apple TV, has a bug, likely in their memory map output, that results in possible soft-bricking when running Linux. If you expereince a soft-brick (LED blinking, no signal) when using ATV1sm, don't panic. Instead, follow these steps:

Remove the CMOS battery
Plug the Apple TV in and perform a PRAM/NVRAM reset (hold Command-Option-P-R on the keyboard at power-on)
Reinstall the CMOS battery

A PRAM reset before ever running ATV1sm should also work. This also happens when using ATV1sm/UEFI FreeLoader to boot Windows XP, which is why I'd still recommend NTATV for this purpose despite its lack of USB input/boot support.

Contents:

Features
Installation
Tested OSes and Loaders
How this works
Known issues
Components used
Compiling
Special Thanks
Name

Features

Virtually every 32-bit and Class-3 EFI-capable OS can now work on the original Apple TV
Can be run from a USB flash drive and installed onto the internal hard drive
USB flash drive bundled with rEFInd to allow for chainloading other EFI loaders
Automatically loads GopShim to allow for working basic video on EFI OSes such as Windows

Installation

Note: This process is easiest to do on Linux due to its handling of GPT disks. Instructions for USB disk partitioning are for Linux only.

Getting Apple Service Diagnostics

This process involves a copy of the internal Apple Service Diagnostic (ASD) tool that Apple stores and AASPs used back in the day to diagnose problems with the original Apple TV. I heard you could get one from here: https://www.mediafire.com/file/zb8gsnh2ef820dk/693-6420-A.9999.dmg

Once you've downloaded this file, you must extract it. To do so using 7-zip CLI:

7z e 693-6420-A.9999.dmg "Apple TV Diag Installer App/Apple TV Diagnostics Installer.app/Contents/Resources/AppleTVDiags01.dmg" 7z x AppleTVDiags01.dmg "FieldDiags/System"

Patching ASD with ATV1sm and GopShim

Download and unzip ATV1sm_0.1.2.zip from the GitHub releases page
Copy ASD to /System/Library/CoreServices/ASD.acm/Contents/MacOS/ASD, replacing the existing file
Copy GopShimDxe.efi to /System/Library/CoreServices/Runtime_Files/EFI/Drivers/GopShimDxe.efi

Creating a USB flash drive with ATV1sm and rEFInd

Format a USB drive as GPT. In GParted:

Select the drive
Go to Device -> Create Partition Table...

Create a FAT32 partition

Partition -> New
File system: fat32

Change partition flags

Partition -> Manage Flags
Check atvrecv

Copy the System folder we extracted and modified earlier to the root of this drive
Copy the EFI folder from ATV1sm_0.1.2.zip (contains rEFInd) to the root of this drive

In the end, your drive's layout should look like this:

Root of USB -> EFI -> boot -> bootia32.efi (and other rEFInd files)
                   -> tools -> shellia32.efi
            -> System -> Library -> CoreServices -> ASD.acm -> Contents -> MacOS -> ASD (replaced)
                                 -> Runtime_Files -> EFI -> Drivers -> GopShimDxe.efi (added)

If you did everything right, you should now be able to plug the USB flash drive into the Apple TV, turn it on, and, after a few seconds and some lines scrolling down the screen, get to the rEFInd menu!

Installing onto an ESP on the internal hard disk

Unlike with USB booting, the ESP does not have to be a special partition type in order to work. Simply mount the ESP on the installed system, copy the System folder to it (you might need to copy the files off a secondary USB flash drive, as most non-Linux OSes do not want to mount an Apple TV recovery partition), and reboot!

Note: Some OSes (notably Debian) don't install their bootloader to /EFI/BOOT by default. To resolve this, run grub-install --removable /dev/<internal hard drive ID, probably sda>.

Tested OSes and Loaders

OS name	Status
rEFInd	Works perfectly
Alpine Linux	Boots, installs, runs. May result in a "soft-brick", see above. Only 194MB RAM is accessible to the system (compared to 212MB when booting with atv-bootloader).
NetBSD 10.1	Boots, installs, runs. 32-bit installer USB must be patched to add EFI bootloader from 64-bit NetBSD. RCA audio is quiet, optical and HDMI audio works. NVIDIA drivers do not load and must be disabled by typing `userconf disable nouveau` before `boot` at the boot shell.
9front (Plan9)	Boots to desktop from USB. Input works fine. Part of the screen is cut off due to
Windows 8/8.1/10 (Windows Boot Manager)	Installation must be done on a second machine/VM due to low RAM. Boots, but virtually unusable on 256MB RAM even when debloated. NVIDIA drivers install and work. HDMI audio does not work. RCA audio is quiet.
UEFI FreeLoader (ReactOS)	GCC builds hang infinitely and display corrupted characters to the screen. MSVC builds successfully boot Windows but soft-brick (see above) the Apple TV.
Haiku R1/beta5 and Nightly	Hangs infinitely at startup, something is hanging in `calculate_cpu_conversion_factor`. Even when this is commented out, Haiku hangs due to some incompatibility with the way it handles the Block I/O protocol.
Windows Longhorn/Vista/7 EFI	Requires CSM in order to work or work properly. May not work at all for booting 32-bit Windows.
CSMWrap	Apple TV is missing PCI I/O protocol, which results in broken VGA arbitration and therefore any number of issues once SeaBIOS loads. Specifying the Apple TV's VGA BIOS also does not work.

How this works

The original Apple TV has EFI firmware, just like every Intel Mac ever sold. Unlike all non-T2 models, though, the Apple TV's EFI firmware is locked to only Apple-signed executables. Previously, the only known useful executable to be signed was the boot.efi executable that came with the Apple TV's version of 10.4.7, and a few bootloaders for other Mac OS X versions. Previously, code execution has been achieved by replacing the mach_kernel that boot.efi loads with our own. This is what every other contemporary Apple TV hack (NTATV FreeLoader, atv-bootloader) does. However, it has a major drawback: we don't have access to EFI boot services. This means that things like disk access, printing to the screen, reading from input devices (keyboards, mice), and memory allocation must be done manually like we are in a real OS. Because of the lack of boot services, conventional bootloaders, like GRUB2 and Windows Boot Manager, never worked on the original Apple TV.

One of the other signed executables is the version of Apple Service Diagnostic (Apple Store/AASP version of Apple Hardware Test) for the Apple TV. Thanks to research by Rairii/WackO, it was determined that ASD loads and executes a Mach-O bundle file while still in an EFI boot services environment and, importantly for us, without any signature checks. The Mach-O file, located at /System/Library/CoreServices/ASD.acm/Contents/MacOS/ASD (which, contrary to its location, is not run under Mac OS), is the main runtime of Apple Software Diagnostic, and is loaded quickly at the beginning of ASD's initialization. It can be replaced with our own file of the same format to get code execution under EFI boot services!

In order to actually do anything useful with our newfound code execution, however, we need the pointers (memory addresses) to the EFI image handle and system table. Thankfully, ASD (specifically the TestSupport.efi driver) sets the value of the symbol gCoreFunction inside of the Mach-O executable to the address of a global variable inside itself. TestSupport.efi, like most EFI applications, also stores the image handle and system table as global variables, so all that has to be done is to deterimine where these are stored relative to gCoreFunction. Rairii figured these offsets out, which allowed me to gain access to EFI boot services!

With access to EFI boot services, I could run whatever code I wanted to in this phase of Apple TV initialization, but there was still a problem: I couldn't load any conventional bootloaders (at least not without recompiling them from source and modifying them to work with my weird build system). This is because the LoadImage and StartImage EFI boot services are responsible for enforcing the EFI lock on the Apple TV, much like they are with UEFI secure boot (which the Apple TV's implementation is not identical to, though it is conceptually similar). Since I have full control over the memory space at this stage, I can just replace those functions, along with UnloadImage and Exit, with my own implementations (or, more accurately, implementations based on OpenCore's OcBootManagementLib). With that done, I now have full, persistent, EFI access on the original Apple TV! I can chainload anything, including Windows Boot Manager, GRUB2, FreeLoader, and the NetBSD bootloader, to run virtually any modern-ish OS on the Apple TV.

Known Issues

This is NOT to be taken as a reference implementation of, well, anything lol. The code for Load/Start/UnloadImage/Exit is haphazardly copy-pasted from OpenCore, resulting in some bootloaders (notable MinGW-compiled UEFI FreeLoader) not working.
Fat binaries (like those used in Mac OS X) do not work and will fall back to the locked original Load/StartImage for now.
ATV1sm freezes when attempting to open a file when compiled with optimizations enabled or with Apple clang. I'd assume it has something to do with the fact that I'm targeting the wrong ABI and there is no valid reason on the face of the earth to ever do what I am doing. Or maybe it's the Apple gods personally smiting me down for sinning. I'm not sure.

Components used

Portions of OpenCore's OcBootManagementLib
GNU-EFI (hard fork for Clang/Mach-O support, the build process is also completely different)
Baselibc string/memory functions
rEFInd bundled, along with an EFI 1.x shell from rEFIt

Compiling

Linux

Install LLVM/Clang, autoconf, automake, libtool, git, and nasm
Compile and install version 986 of cctools-port (newer versions work but are more complicated to set up):


                    git clone https://github.com/tpoechtrager/cctools-port.git -b 986-ld64-711
                    

                    cd cctools-port/cctools
                    

                    ./configure --prefix=/opt/cross --target=i386-apple-darwin8
                    

                    make -j$(nproc)
                    

                    sudo make install

Clone this repo and cd into it
Type export PATH=/opt/cross/bin:$PATH
Type make

macOS

Install the Xcode command line tools
Install nasm and llvm from Homebrew (or MacPorts, or somewhere else)
Clone this repo and cd into it
Type make

Windows

Use WSL or a Linux VM or something. I don't develop on Windows.

Special Thanks

Rairii/Wack0 for determining the offsets of the system table and image handle

Name

ATV1sm is a combination of the words Apple TV 1 (ATV1) and autism (since Apple Software Diagnostic and Autism Spectrum Disorder have the same acronym, and also because it took an immense amount of autism to put this thing together). Let me know if you can think of anything better.