# Neotron OS
This is the Neotron OS. It will run on any system which has an implementation
of the [Neotron BIOS](https://github.com/neotron-compute/Neotron-Common-BIOS).
## Status
This OS is a work in progress. We intend to support:
* [x] Calling BIOS APIs
* [x] Text mode VGA console
* [x] Serial console
* [x] Running built-in commands from a shell
* [x] Executing applications from RAM
* [x] Applications can print to stdout
* [x] Applications can read from stdin
* [x] Applications can open/close/read files
* [ ] Applications can write to files
* [x] MBR/FAT32 formatted block devices
* [x] Read blocks
* [x] Directory listing of /
* [ ] Write to files
* [ ] Delete files
* [ ] Change directory
* [x] Load ELF binaries from disk
* [x] Load ELF binaries from ROM
* [x] Changing text modes
* [ ] Basic networking
* [x] Music playback
* [ ] Various keyboard layouts
* [ ] Ethernet / WiFi networking
* [ ] Built-in scripting language
## Build instructions
Your board will need an appropriate Neotron BIOS installed, and you need to have
OpenOCD or some other programming tool running for your particular board. See
your BIOS instructions for more details.
Building Neotron OS is handled by the `nbuild` tool, in this repository. Run `cargo nbuild help` for more information.
To make an image for a board like the Neotron Pico, you want to run `cargo nbuild binary`. By default this will produce a `thumbv6m-none-eabi` image linked to run at address `0x1002_0000`, with a ROMFS containing various utilities, which is what you need on a Neotron Pico. Your BIOS should tell you if you need to change these options, and how to load the resulting image onto your system.
```console
$ cargo nbuild binary
...
$ ls ./target/thumbv6m-none-eabi/release
build/ examples/ flames.d libflames.d libneotron_os.d neotron-os neotron-os.d
deps/ flames incremental/ libflames.rlib libneotron_os.rlib neotron-os.bin romfs.bin
```
Here:
* `romfs.bin` is the raw ROMFS image
* `neotron-os` is an ELF file containing the OS and the ROMFS image
* `neotron-os.bin` is an raw binary copy of the contents of the ELF file
When the OS is running, programs in the ROMFS can be loaded with:
```text
> rom
flames (14212 bytes)
> rom flames
Loading 4256 bytes to 0x20001000
Loading 532 bytes to 0x200020a0
Loading 4908 bytes to 0x200022b4
> run
*Program starts running**
```
A better UI for loading files from ROM is being planned (maybe we should have drive letters, and the ROM can be `R:`).
You can also build a *shared object* to load into a Windows/Linux/macOS application, like [Neotron Desktop BIOS](https://github.com/neotron-compute/neotron-desktop-bios):
```console
$ cargo nbuild library
...
$ ls ./target/debug/*.so
./target/debug/libneotron_os.so
```
## Changelog
See [`CHANGELOG.md`](./CHANGELOG.md)
## Licence
```text
Copyright (c) 2019-2024 Jonathan 'theJPster' Pallant and The Neotron Developers
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see