diff --git a/README.md b/README.md index 8ac44ae..499550b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,128 @@ -# NesUEFI -A bootable NES Emulator running on UEFI + +# NesUEFI - A bootable NES Emulator running on UEFI +**NesUEFI** is a **NES Emulator running without an operating system** directly on **Unified Extensible Firmware Interface (UEFI).** Simply place **NesUEFI** and nes roms in a pendrive and play. **NesUEFI file browser** will show the available roms. The core drivers (Graphics, File System, Keyboard, Timer) are written in c using **GNU-EFI** and the emulator part is a port of [LiteNES](https://github.com/NJU-ProjectN/LiteNES). Adafruit GFX Graphics Library is ported for GNU-EFI ecosystem in C for high level graphics operations and text rendering. + +# Compile NesUEFI +## Requirements + +- **GNU-EFI** Library. Download it from [here](https://sourceforge.net/projects/gnu-efi/). +- **gcc-3.0 or newer** +- A version of **objcopy** that supports EFI applications +- **qemu** (To run without real hardware) +- **mtools** : Utilities to access MS-DOS disks from Linux (to run on qemu) +- **OVMF** (To run on qemu) + + +## Compile and install GNU-EFI Library +Go to gnu-efi source folder +```bash + make + make install +``` +Here is a guide you can follow for more details on how to compile and install gnu-efi applications. + +## Compile NesUEFI +Change the following macros in makefile to locate GNU-EFI **libraries** and **headers** installed on the previous step. + +```makefile + INCDIR = /usr/local/include + LIBDIR = /usr/local/lib + EFILIB = /usr/local/lib +``` + +# NesUEFI on qemu : + +### Locate OVMF in Makefile: +To run the compiled application in qemu we need OVMF for UEFI emulation. OVMF is a port of Intel's tianocore firmware to the qemu virtual machine. +```makefile + OVMF_DIR = ../OVMF +``` +Change **OVMF_DIR** directory in the makefile. + +### Create Image +Add your roms here in the makefile to write it to your image. For example : test_1.nes, test_2.nes +```makefile + mcopy -i $(IMAGE).img splash.bmp :: + # Add your roms here + mcopy -i $(IMAGE).img test_1.nes :: + mcopy -i $(IMAGE).img test_2.nes :: +``` +```bash + make img +``` + +### Run +```bash + make run +``` +# NesUEFI on real hardware +**Do at your own risk. Under no circumstances shall the author be liable for any damage.** +Technically NesUEFI should not mess with your system. But you should at least know what you are doing. + +- Format a pendrive with **FAT32** file system. +- Create **/efi/boot/** folders in the pendrive +- Rename **main.efi** to **bootx64.efi** for **64 bit** and **bootia32.efi** for **32 bit** application. +- Copy **bootx64.efi** or **bootia32.efi** to boot folder. +- For **64 bit** application the pendrive should look like this : **/efi/boot/bootx64.efi** +- For **32 bit** application the pendrive should look like this : **/efi/boot/bootia32.efi** +- Simply place your roms in the pendrive. **NesUEFI file browser** will show the available roms. + +# Demo on Real Hardware + +## Controls +| NesUEFI Key | Keyboard Key | +| ----------- | ----------- | +| Up | W | +| Down | S | +| Left | A | +| Right | D | +| Select | U | +| Start | I | +| A | K | +| B | J | +| Reload | R | +## Known Issues +- Mappers are not implemented yet. +- It does not support Audio emulation yet. +- EFI only have a simple text input protocol. So it only recognizes input character but not keystroke. So key press and release events are emulated by holding down a key until a new key is pressed. Otherwise we can not emulate multi key press events. +- Only single player is supported. + +## Tested Games +Below games are currently tested on real hardware. But NesUEFI is not only limited to these games. It should technically run all the classic roms that use mapper 0. [Here](https://nesdir.github.io/mapper0.html) is a list of mapper 0 games. +- [x] Super Mario Bros +- [x] Popeye +- [x] Yie Ar Kung-Fu +- [x] Battle City +- [x] Super Arabian +- [x] Road Fighters +- [x] 1942 +- [x] F1 Race + +## Screenshots +## TODO +- [x] Graphics +- [x] Timer +- [x] Keyboard +- [x] File System +- [x] File Browser +- [x] Graphics Library +- [ ] APU +- [ ] Mappers +- [ ] USB Keyboard Driver + +## Acknowledgements +- https://wiki.osdev.org +- https://wiki.osdev.org/Tutorials +- https://wiki.osdev.org/UEFI +- https://wiki.osdev.org/GNU-EFI +- https://wiki.osdev.org/UEFI_App_Bare_Bones +- https://wiki.osdev.org/Loading_files_under_UEFI +- https://github.com/NJU-ProjectN/LiteNES +- https://learn.adafruit.com/adafruit-gfx-graphics-library +- https://edk2-devel.narkive.com/WhxSiG6I/edk2-directory-file-system-traversal-example +- https://www.youtube.com/watch?v=mpPbKEeWIHU&list=PLxN4E629pPnJxCQCLy7E0SQY_zuumOVyZ +- https://blog.fpmurphy.com/2015/08/display-bmp-details-and-image-in-uefi-shell.html#ixzz7SHLiufWS +- https://unsplash.com/photos/UqRnUzV5pjQ + +# License +Licensed under the [MIT](https://github.com/shadlyd15/NesUEFI/blob/master/LICENSE) License. diff --git a/screenshots/0.png b/screenshots/0.png new file mode 100644 index 0000000..ad22ad3 Binary files /dev/null and b/screenshots/0.png differ diff --git a/screenshots/1.png b/screenshots/1.png new file mode 100644 index 0000000..ab7327a Binary files /dev/null and b/screenshots/1.png differ diff --git a/screenshots/2.png b/screenshots/2.png new file mode 100644 index 0000000..f08ad0e Binary files /dev/null and b/screenshots/2.png differ diff --git a/screenshots/3.png b/screenshots/3.png new file mode 100644 index 0000000..a2c9cb5 Binary files /dev/null and b/screenshots/3.png differ diff --git a/splash.bmp b/splash.bmp new file mode 100644 index 0000000..1a2a9b4 Binary files /dev/null and b/splash.bmp differ