mirror of
https://github.com/italicsjenga/rp-hal-boards.git
synced 2024-12-23 12:41:31 +11:00
Added documentation to #[entry] and to the readme
While the project does have examples, even a simple example such as blinky doesn't really cover how to get started if you don't want to use a template.
This commit is contained in:
parent
e24d9b9ee9
commit
7a65556bc7
|
@ -8,16 +8,19 @@ pub use rp2040_hal::entry;
|
||||||
/// The linker will place this boot block at the start of our program image. We
|
/// The linker will place this boot block at the start of our program image. We
|
||||||
/// need this to help the ROM bootloader get our code up and running.
|
/// need this to help the ROM bootloader get our code up and running.
|
||||||
///
|
///
|
||||||
/// According to
|
/// According to [the Arduino store]
|
||||||
/// https://store.arduino.cc/products/arduino-nano-rp2040-connect
|
|
||||||
/// the board should contain a AT25SF128A flash chip. But
|
/// the board should contain a AT25SF128A flash chip. But
|
||||||
/// there are reports of board with different flash chips,
|
/// there are [reports] of board with different flash chips,
|
||||||
/// where the boot loader BOOT_LOADER_AT25SF128A does not
|
/// where the boot loader BOOT_LOADER_AT25SF128A does not
|
||||||
/// work. (https://github.com/rp-rs/rp-hal/issues/503)
|
/// work.
|
||||||
///
|
///
|
||||||
/// Therefore, the generic boot loader is used by default. For a specific
|
/// Therefore, the generic boot loader is used by default. For a specific
|
||||||
/// board, the flash performance can be increased by switching to the
|
/// board, the flash performance can be increased by switching to the
|
||||||
/// matching boot loader.
|
/// matching boot loader.
|
||||||
|
///
|
||||||
|
/// [the Arduino store]: https://store.arduino.cc/products/arduino-nano-rp2040-connect
|
||||||
|
/// [reports]: https://github.com/rp-rs/rp-hal/issues/503
|
||||||
|
///
|
||||||
#[cfg(feature = "boot2")]
|
#[cfg(feature = "boot2")]
|
||||||
#[link_section = ".boot2"]
|
#[link_section = ".boot2"]
|
||||||
#[no_mangle]
|
#[no_mangle]
|
||||||
|
|
|
@ -54,6 +54,32 @@ $ cargo install elf2uf2-rs
|
||||||
```
|
```
|
||||||
then try repeating the `cargo run` command above.
|
then try repeating the `cargo run` command above.
|
||||||
|
|
||||||
|
### From Scratch
|
||||||
|
|
||||||
|
To start a basic project from scratch, create a project using `cargo new project-name`. Within the
|
||||||
|
project directory, run `cargo add rp-pico`, `cargo add cortex-m-rt`, and `cargo add panic-halt`. The
|
||||||
|
first command will this HAL (Hardware Abstraction Layer), the second is required for the `#[entry]` macro, and _panic-halt_ creates a simple panic function, which just halts.
|
||||||
|
|
||||||
|
You'll also need to copy the cargo config file from the [repo](https://github.com/rp-rs/rp-hal-boards/blob/main/.cargo/config). It specifies the target and optimizing flags to the linker. You'll also need to copy [_memory.x_](https://github.com/rp-rs/rp-hal-boards/blob/main/memory.x) to your project root. This file tells the linker the flash and RAM layout, so it won't clobber the bootloader or write to an out of bounds memory address.
|
||||||
|
|
||||||
|
The simplest working example, which does nothing except loop forever, is:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
#![no_std]
|
||||||
|
#![no_main]
|
||||||
|
use rp_pico::entry;
|
||||||
|
use panic_halt as _;
|
||||||
|
#[entry]
|
||||||
|
fn see_doesnt_have_to_be_called_main() -> ! {
|
||||||
|
loop {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
It can be placed in _/src/main.rs_.
|
||||||
|
|
||||||
|
You can use `cargo run` to compile and install it.
|
||||||
|
**Note**: You won't see any activity since this program does nothing. You can use the examples provided
|
||||||
|
to add more functionality.
|
||||||
### [pico_blinky](./examples/pico_blinky.rs)
|
### [pico_blinky](./examples/pico_blinky.rs)
|
||||||
|
|
||||||
Flashes the Pico's on-board LED on and off.
|
Flashes the Pico's on-board LED on and off.
|
||||||
|
|
|
@ -1,9 +1,61 @@
|
||||||
#![no_std]
|
#![no_std]
|
||||||
|
|
||||||
|
//! A Hardware Abstraction Layer for the Raspberry Pi Pico.
|
||||||
|
//!
|
||||||
|
//! This crate serves as a HAL (Hardware Abstraction Layer) for the Raspberry Pi Pico. Since the Raspberry Pi Pico
|
||||||
|
//! is based on the RP2040 chip, it re-exports the [rp2040_hal] crate which contains the tooling to work with the
|
||||||
|
//! rp2040 chip.
|
||||||
|
//!
|
||||||
|
//! # Examples:
|
||||||
|
//!
|
||||||
|
//! The following example turns on the onboard LED. Note that most of the logic works through the [rp2040_hal] crate.
|
||||||
|
//! ```
|
||||||
|
//! #![no_main]
|
||||||
|
//! use rp_pico::entry;
|
||||||
|
//! use panic_halt as _;
|
||||||
|
//! use embedded_hal::digital::v2::OutputPin;
|
||||||
|
//! use rp_pico::hal::pac;
|
||||||
|
//! use rp_pico::hal;
|
||||||
|
|
||||||
|
//! #[entry]
|
||||||
|
//! fn does_not_have_to_be_main() -> ! {
|
||||||
|
//! let mut pac = pac::Peripherals::take().unwrap();
|
||||||
|
//! let sio = hal::Sio::new(pac.SIO);
|
||||||
|
//! let pins = rp_pico::Pins::new(
|
||||||
|
//! pac.IO_BANK0,
|
||||||
|
//! pac.PADS_BANK0,
|
||||||
|
//! sio.gpio_bank0,
|
||||||
|
//! &mut pac.RESETS,
|
||||||
|
//! );
|
||||||
|
//! let mut led_pin = pins.led.into_push_pull_output();
|
||||||
|
//! led_pin.set_high().unwrap();
|
||||||
|
//! loop {
|
||||||
|
//! }
|
||||||
|
//! }
|
||||||
|
//! ```
|
||||||
|
|
||||||
|
|
||||||
pub extern crate rp2040_hal as hal;
|
pub extern crate rp2040_hal as hal;
|
||||||
|
|
||||||
#[cfg(feature = "rt")]
|
#[cfg(feature = "rt")]
|
||||||
extern crate cortex_m_rt;
|
extern crate cortex_m_rt;
|
||||||
|
|
||||||
|
/// The `entry` macro declares the starting function to the linker.
|
||||||
|
/// This is similar to the `main` function in console applications.
|
||||||
|
///
|
||||||
|
/// It is based on the [cortex_m_rt](https://docs.rs/cortex-m-rt/latest/cortex_m_rt/attr.entry.html) crate.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
/// ```
|
||||||
|
/// #![no_std]
|
||||||
|
/// #![no_main]
|
||||||
|
/// use rp_pico::entry;
|
||||||
|
/// #[entry]
|
||||||
|
/// fn you_can_use_a_custom_main_name_here() -> ! {
|
||||||
|
/// loop {}
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
|
||||||
#[cfg(feature = "rt")]
|
#[cfg(feature = "rt")]
|
||||||
pub use hal::entry;
|
pub use hal::entry;
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue