Crate lpc82x_hal[−][src]
LPC82x Hardware Abstraction Layer
Hardware Abstraction Layer (HAL) for the NXP LPC82x series of ARM Cortex-M0+ microcontrollers.
Using LPC82x HAL in a Library
Writing a library on top of LPC82x HAL is pretty simple. All you need to do
is include it via Cargo, by adding the following to your Cargo.toml
:
[dependencies]
lpc82x-hal = "0.2"
With that in place, you can just reference the crate in your Rust code, like this:
// lib.rs extern crate lpc82x_hal;
That's it! Now you can start using the LPC82x HAL APIs. Take a look at
Peripherals
, which is the entry point to the whole API.
Please note that LPC82x HAL is an implementation of embedded-hal. If your library is not specific to LPC82x, please consider depending on embedded-hal instead. Doing so means that your library should work on top of all embedded-hal implementations.
Using LPC82x HAL in an Application
To use LPC82x HAL in your application, you need to go through a bit of additional trouble. This section tries to walk you through some of the basics, but it's not a complete tutorial. Please refer to cortex-m-quickstart for additional details.
Runtime Support
Including LPC82x HAL in your application via Cargo is mostly the same as it
is for libraries, but with one addition. You need to enable runtime support
when including the crate in your Cargo.toml
:
[dependencies.lpc82x-hal]
version = "0.2"
features = ["rt"]
The runtime support will provide you with some basics that are required for your program to run correctly. However, it needs to know how the memory on your microcontroller is set up.
You can get that information from the user manual. To provide it to LPC82x
HAL, create a file called memory.x
in your project root (the directory
where Cargo.toml
is located). memory.x
should look something like this:
MEMORY { FLASH : ORIGIN = 0x00000000, LENGTH = 16K RAM : ORIGIN = 0x10000000, LENGTH = 4K }
Runtime support is provided by the cortex-m-rt crate. Please refer to the cortex-m-rt documentation for additional details.
Build System
The LPC82x is a Cortex-M0+ microcontroller, which means it has an ARMv6-M core. In order to compile and link a binary for that architecture, we need to install a precompiled Rust core library.
The following example assumes you installed Rust using rustup.
$ rustup target add thumbv6m-none-eabi
This will install the precompiled core library we need, enabling us to cross-compile binaries for the LPC82x.
Additionally, we need to tell Cargo how to link your project. Create the
file .cargo/config
in your project directory, and add the following
contents:
[build]
target = "thumbv6m-none-eabi"
[target.thumbv6m-none-eabi]
rustflags = [
"-C", "link-arg=-Tlink.x",
"-C", "linker=arm-none-eabi-ld",
"-Z", "linker-flavor=ld"
]
This tells Cargo to use the arm-none-eabi-gcc toolchain for linking. You need to install this separately. How to do so is dependent on your platform and is left as an exercise to the reader.
If everything is set up correctly, you can build your project with the following command:
$ cargo build --release
Uploading the Binary
There are many ways to upload the binary to the microcontroller. How to do this is currently beyond the scope of this documentation, but this fork of lpc21isp is known to work.
Examples
There are a number of examples in the repository. A good place to start is the GPIO example.
References
Various places in this crate's documentation reference the LPC82x User manual, which is available from NXP.
Re-exports
pub extern crate lpc82x as raw; |
pub use self::gpio::GPIO; |
pub use self::i2c::I2C; |
pub use self::pmu::PMU; |
pub use self::swm::SWM; |
pub use self::syscon::SYSCON; |
pub use self::usart::USART; |
pub use self::wkt::WKT; |
Modules
clock |
Common types for system clocks |
gpio |
API for General Purpose I/O (GPIO) |
i2c |
API for the I2C peripherals |
init_state |
Contains types that encode the state of hardware initialization |
pmu |
API for the Power Management Unit (PMU) |
prelude |
Re-exports various traits that are required to use lpc82x-hal |
sleep |
Higher-level sleep API |
swm |
APIs for the switch matrix (SWM) |
syscon |
API for system configuration (SYSCON) |
usart |
API for USART |
wkt |
API for the self-wake-up timer (WKT) |
Structs
CPUID |
CPUID |
DCB |
Debug Control Block |
DWT |
Data Watchpoint and Trace unit |
MPU |
Memory Protection Unit |
NVIC |
Nested Vector Interrupt Controller |
Peripherals |
Provides access to all peripherals |
SCB |
System Control Block |
SYST |
SysTick: System Timer |
Enums
Interrupt |
Enumeration of all the interrupts |