Skip to content

Commit ccebf8a

Browse files
thejpsterthejpster
authored
Merge pull request #78 from Neotron-Compute/update-docs
Update README.
2 parents 0fea0b8 + a806655 commit ccebf8a

File tree

1 file changed

+114
-75
lines changed

1 file changed

+114
-75
lines changed

‎README.md‎

Lines changed: 114 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -5,95 +5,133 @@ Pico] board.
55

66
[Neotron Pico]: (https://github.com/neotron-compute/neotron-pico)
77

8-
![Build Status](https://github.com/neotron-compute/neotron-pico-bios/workflows/Build/badge.svg "Github Action Build Status")
8+
![Build Status](https://github.com/neotron-compute/neotron-pico-bios/actions/workflows/build.yml/badge.svg?branch=develop)
99

10-
![Format Status](https://github.com/neotron-compute/neotron-pico-bios/workflows/Format/badge.svg "Github Action Format Check Status")
10+
![Format Status](https://github.com/neotron-compute/neotron-pico-bios/actions/workflows/format.yml/badge.svg?branch=develop)
1111

1212
## Compatibility
1313

14-
This BIOS will run on the [Neotron Pico] v0.5.0. Other boards based around the
15-
Raspberry Pi Pico could be supported with just a minor change to the pin
16-
configurations.
14+
This BIOS will run on the [Neotron Pico] v1.0.0 and v1.1.0. Other boards based
15+
around the Raspberry Pi Pico could be supported with just a minor change to the
16+
pin configurations.
1717

18-
## Features
18+
## Hardware Features
1919

20-
The Neotron Pico offers:
20+
The Neotron Pico PCB offers:
2121

22-
* Dual Cortex-M0+ clocked at 133 MHz
22+
* Dual Cortex-M0+ clocked at ~~133 MHz~~ 151.2 MHz
2323
* 256 KiB RAM
2424
* 2048 KiB Flash
2525
* SD/MMC Slot
26-
* 4096-colour VGA output
27-
* Stereo 16-bit 48kHz audio
26+
* 640x480 VGA output
27+
* Stereo 16-bit 48 kHz audio
2828
* Four Neotron expansion slots
2929
* A dedicated Board Management Controller, offering:
3030
* Dual PS/2 ports
31-
* 5-wire TTL UART
31+
* 5-wire 3.3V TTL UART
3232
* Power/reset control
3333

34-
Currently the BIOS only uses a single core, and starts the OS on the same core.
35-
Later versions may move some functionality onto the second core (e.g. screen
36-
updates) for performance reasons.
34+
## Software Features
35+
36+
Currently the BIOS uses Core 0 for running the Neotron OS (and application code), and Core 1 for updating the video display and performing 80-column colour text rendering in real-time.
37+
38+
* [x] 640x480 @ 60 Hz text mode
39+
* [x] 80 columns, 60 rows, 8x8 font
40+
* [x] 80 columns, 30 rows, 8x16 font
41+
* [x] 16 foreground and 8 background colours
42+
* [x] Fixed font
43+
* [ ] Loadable soft-font
44+
* [x] 640x400 @ 70 Hz text mode
45+
* [x] 80 columns, 50 rows, 8x8 font
46+
* [x] 80 columns, 25 rows, 8x16 font
47+
* [x] 16 foreground and 8 background colours
48+
* [x] Fixed font
49+
* [ ] Loadable soft-font
50+
* [ ] 640x480 @ 60 Hz graphics mode
51+
* [ ] 1-bpp mode (2 colours) in 38 KiB
52+
* [ ] 2-bpp mode (4 colours) in 75 KiB
53+
* [ ] 4-bpp mode (4 colours) in 150 KiB
54+
* [ ] 320x240 @ 60 Hz grapics mode
55+
* [ ] 1-bpp mode (2 colours) in 10 KiB
56+
* [ ] 2-bpp mode (4 colours) in 19 KiB
57+
* [ ] 4-bpp mode (4 colours) in 38 KiB
58+
* [ ] 8-bpp mode (8 colours) in 75 KiB
59+
* [x] SPI Bus
60+
* [x] I2C Bus
61+
* [x] SPI I/O Expander for Chip Selects and LEDs
62+
* [x] External Interrupts
63+
* [x] SD Card support
64+
* [x] Read/write 512 byte blocks
65+
* [x] Insert/remove detection
66+
* [x] Communications with the BMC
67+
* [x] Reading from a PS/2 keyboard
68+
* [x] Sending beeps/boops to the PC Speaker
69+
* [ ] Writing to the PS/2 keyboard
70+
* [ ] Reading/writing to/from the PS/2 mouse
71+
* [ ] UART support
72+
* [ ] Second I2C Bus support
73+
* [ ] Volatage monitoring
74+
* [ ] Soft-power
75+
* [ ] Soft-reset
76+
* [x] Dallas or Microchip RTC support
77+
* [ ] Audio CODEC mixer programming
78+
* [ ] I2S Audio Output
79+
* [ ] I2S Audio Input
3780

3881
## Programming
3982

40-
The Neotron BIOS uses the [defmt](https://crates.io/crates/defmt) crate to provide structured logging over the SWD interface. The easiest way to flash and debug your Neotron Pico BIOS is with a second Raspberry Pi Pico.
83+
The Neotron BIOS uses the [defmt](https://crates.io/crates/defmt) crate to provide structured logging over the SWD interface. The easiest way to flash and debug your Neotron Pico BIOS is with a second Raspberry Pi Pico, or the official Raspberry Pi Debug Probe.
4184

42-
1. Connect your *Debugger* Pico to the *Neotron* Pico:
43-
* connect Pin 3 on the *Debugger* Pico to GND on the *Neotron* Pico
44-
* connect Pin 4 on the *Debugger* Pico to SWCLK on the *Neotron* Pico
45-
* connect Pin 5 on the *Debugger* Pico to SWDIO on the *Neotron* Pico
46-
* connect USB on the *Debugger* Pico to your PC
85+
1. If your BMC has not been programmed, do that first.
4786

48-
2. Flash your *Debugger* Pico with https://github.com/raspberrypi/picoprobe or https://github.com/majbthrd/DapperMime firmware (e.g. by copying the UF2 file to the USB Mass Storage device)
87+
2. Connect your *Debugger* Pico to the three *DEBUG* pins on the *Neotron* Pico, following the instructions for your particular debugging device or firmware.
4988

50-
3. On your PC, install [*probe-run*](https://github.com/knurling-rs/probe-run), the programming tool from [Ferrous System's](https://www.ferrous-systems.com) [Knurling Project](https://github.com/knurling).
89+
3. If your *Debugger* Pico was a bare Pi Pico (and not a Debug Probe) then flash it with <https://github.com/raspberrypi/picoprobe> or <https://github.com/majbthrd/DapperMime> firmware (e.g. by copying the UF2 file to the USB Mass Storage device)
5190

52-
We are temporarily stuck at 0.3.6 as 0.3.7 is broken and 0.3.8 doesn't support the RP2040. A 0.3.9 should be along shortly, but the logging binary format has changed, and we currently pin ourselves to a 0.3.6 compatible version.
91+
4. On your PC, install [*probe-run*](https://github.com/knurling-rs/probe-run), the programming tool from [Ferrous System's](https://www.ferrous-systems.com) [Knurling Project](https://github.com/knurling).
5392

54-
```sh
55-
cargo install probe-run --version=0.3.6
56-
```
93+
```sh
94+
cargo install probe-run
95+
```
5796

58-
4. Power on your Neotron Pico.
97+
5. Power on your Neotron Pico by applying 12V and pressing the On/Off button.
5998

60-
5. Build the Neotron OS
99+
6. Build the Neotron OS:
100+
We use the "neotron-flash-1002.ld" linker script to link it at `0x1002_0000`.
61101

62-
We use the "neotron-flash-1002.ld" linker script to link it at `0x1002_0000`.
102+
```console
103+
user@host ~/neotron-os $ cargo build --bin=flash1002 --release --target=thumbv6m-none-eabi
104+
user@host ~/neotron-os $ arm-none-eabi-objcopy -O binary ./target/thumbv6m-none-eabi/release/flash1002 ../neotron-pico-bios/src/thumbv6m-none-eabi-flash1002-libneotron_os.bin
105+
```
63106

64-
```console
65-
user@host ~/neotron-os $ cargo build --bin=flash1002 --release --target=thumbv6m-none-eabi
66-
user@host ~/neotron-os $ arm-none-eabi-objcopy -O binary ./target/thumbv6m-none-eabi/release/flash1002 ../neotron-pico-bios/src/thumbv6m-none-eabi-flash1002-libneotron_os.bin
67-
```
107+
7. Build and load the Neotron BIOS, and view the debug output stream, with `cargo run --release`:
68108

69-
6. Build and load the Neotron BIOS, and view the debug output stream, with `cargo run --release`:
109+
```console
110+
user@host ~/neotron-pico-bios $ DEFMT_LOG=debug cargo run --release
111+
Compiling neotron-pico-bios v0.1.0 (/home/jonathan/Documents/neotron/neotron-pico-bios)
112+
Finished release [optimized + debuginfo] target(s) in 0.76s
113+
Running `probe-run-rp --chip RP2040 target/thumbv6m-none-eabi/release/neotron-pico-bios`
114+
(HOST) INFO flashing program (7.30 KiB)
115+
(HOST) INFO success!
116+
────────────────────────────────────────────────────────────────────────────────
117+
INFO Neotron BIOS starting...
118+
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:79
119+
INFO Clocks OK
120+
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:102
121+
INFO Pins OK
122+
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:121
123+
DEBUG Loop...
124+
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:128
125+
```
70126

71-
```console
72-
user@host ~/neotron-pico-bios $ DEFMT_LOG=debug cargo run --release
73-
Compiling neotron-pico-bios v0.1.0 (/home/jonathan/Documents/neotron/neotron-pico-bios)
74-
Finished release [optimized + debuginfo] target(s) in 0.76s
75-
Running `probe-run-rp --chip RP2040 target/thumbv6m-none-eabi/release/neotron-pico-bios`
76-
(HOST) INFO flashing program (7.30 KiB)
77-
(HOST) INFO success!
78-
────────────────────────────────────────────────────────────────────────────────
79-
INFO Neotron BIOS starting...
80-
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:79
81-
INFO Clocks OK
82-
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:102
83-
INFO Pins OK
84-
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:121
85-
DEBUG Loop...
86-
└─ neotron_pico_bios::__cortex_m_rt_main @ src/main.rs:128
87-
```
88-
89-
You should see your Neotron Pico boot, both over RTT in the `probe-run` output, and also on the VGA output.
90-
91-
6a. Multiple probes
92-
93-
If you have multiple probe-rs compatible probes attached to your computer,
127+
You should see your Neotron Pico boot, both over RTT in the `probe-run` output, and also on the VGA output.
128+
129+
## Multiple Probes
130+
131+
If you have multiple `probe-rs` compatible probes attached to your computer,
94132
you will receive an error message.
95133

96-
You can set the PROBE_RUN_PROBE environment variable to select one of the
134+
You can set the PROBE_RUN_PROBE environment variable to select one of the
97135
available probes, like so:
98136

99137
```console
@@ -104,10 +142,10 @@ the following probes were found:
104142
user@host ~/neotron-pico-bios $ PROBE_RUN_PROBE='0483:3748' DEFMT_LOG=debug cargo run --release
105143
```
106144

107-
You can also just provide the probe Serial, for example if you have multiple
145+
You can also just provide the probe Serial number, for example if you have multiple
108146
identical probes.
109147

110-
The documentation for this feature can be found at
148+
The documentation for this feature can be found at
111149
<https://github.com/knurling-rs/probe-run#12-multiple-probes>
112150

113151
## Changelog
@@ -116,27 +154,29 @@ See [CHANGELOG.md](./CHANGELOG.md)
116154

117155
## Licence
118156

119-
Neotron-Pico-BIOS Copyright (c) Jonathan 'theJPster' Pallant and the Neotron Developers, 2023
157+
```text
158+
Neotron-Pico-BIOS Copyright (c) Jonathan 'theJPster' Pallant and the Neotron Developers, 2023
120159
121-
This program is free software: you can redistribute it and/or modify
122-
it under the terms of the GNU General Public License as published by
123-
the Free Software Foundation, either version 3 of the License, or
124-
(at your option) any later version.
160+
This program is free software: you can redistribute it and/or modify
161+
it under the terms of the GNU General Public License as published by
162+
the Free Software Foundation, either version 3 of the License, or
163+
(at your option) any later version.
125164
126-
This program is distributed in the hope that it will be useful,
127-
but WITHOUT ANY WARRANTY; without even the implied warranty of
128-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
129-
GNU General Public License for more details.
165+
This program is distributed in the hope that it will be useful,
166+
but WITHOUT ANY WARRANTY; without even the implied warranty of
167+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
168+
GNU General Public License for more details.
130169
131-
You should have received a copy of the GNU General Public License
132-
along with this program. If not, see <https://www.gnu.org/licenses/>.
170+
You should have received a copy of the GNU General Public License
171+
along with this program. If not, see <https://www.gnu.org/licenses/>.
172+
```
133173

134174
See the full text in [LICENSE.txt](./LICENSE.txt). Broadly, we (the developers)
135175
interpret this to mean (and note that we are not lawyers and this is not
136176
legal advice) that if you give someone a Neotron Pico, you must also give them
137177
one of:
138178

139-
* Complete and corresponding source code (e.g. as a link to your own on-line
179+
* Complete and corresponding source code (e.g. as a link to your **own** on-line
140180
Git repo) for any GPL components (e.g. the BIOS and the OS), as supplied on
141181
the Neotron Pico.
142182
* A written offer to provide complete and corresponding source code on
@@ -147,8 +187,8 @@ the board for commercial gain), and you are using an unmodified upstream
147187
version of the source code, then the third option is to give them:
148188

149189
* A link to the tag/commit-hash on the relevant official Neotron Github
150-
repositories - https://github.com/Neotron-Compute/Neotron-Pico-BIOS and
151-
https://github.com/Neotron-Compute/Neotron-OS.
190+
repositories - <https://github.com/Neotron-Compute/Neotron-Pico-BIOS> and
191+
<https://github.com/Neotron-Compute/Neotron-OS>.
152192

153193
This is to ensure everyone always has the freedom to access the source code in
154194
their Neotron Pico.
@@ -158,4 +198,3 @@ their Neotron Pico.
158198
Unless you explicitly state otherwise, any contribution intentionally
159199
submitted for inclusion in the work by you shall be licensed as above,
160200
without any additional terms or conditions.
161-

0 commit comments

Comments
 (0)