cortex_a/lib.rs
1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//
3// Copyright (c) 2018-2022 by the author(s)
4//
5// Author(s):
6// - Andre Richter <andre.o.richter@gmail.com>
7
8//! Low level access to Cortex-A processors.
9//!
10//! ## Currently Supported Execution States
11//!
12//! - [x] AArch64
13//! - [ ] AArch32
14//!
15//! ## Minimum Supported Rust Version
16//!
17//! Requires a recent nightly of Rust.
18//!
19//! ## Usage
20//!
21//! Please note that for using this crate's [register definitions](src/registers) (as provided by
22//! `cortex_a::registers::*`), you need to also include
23//! [`tock-registers`](https://crates.io/crates/tock-registers) in your project. This is because the
24//! `interface` traits provided by `tock-registers` are implemented by this crate. You should
25//! include the same version of `tock-registers` as is being used by this crate to ensure sane
26//! interoperatbility.
27//!
28//! For example, in the following snippet, `X.Y.Z` should be the same version of `tock-registers`
29//! that is mentioned in `cortex-a`'s [`Cargo.toml`](Cargo.toml).
30//!
31//! ```toml
32//! [package]
33//! name = "Your embedded project"
34//!
35//! # Some parts omitted for brevity.
36//!
37//! [dependencies]
38//! tock-registers = "X.Y.Z"
39//! cortex-a = "A.B.C" # <-- Includes tock-registers itself.
40//! ```
41//!
42//! ### Example
43//!
44//! Check out
45//! [rust-raspberrypi-OS-tutorials](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)
46//! for usage examples. Listed below is a snippet of `rust-raspberrypi-OS-tutorials`'s early boot
47//! code.
48//!
49//! ```rust
50//! # #[cfg(feature = "nightly")]
51//! use cortex_a::{asm, registers::*};
52//! # #[cfg(feature = "nightly")]
53//! use tock_registers::interfaces::Writeable; // <-- Trait needed to use `write()` and `set()`.
54//!
55//! // Some parts omitted for brevity.
56//!
57//! # #[cfg(feature = "nightly")]
58//! unsafe fn prepare_el2_to_el1_transition(
59//! virt_boot_core_stack_end_exclusive_addr: u64,
60//! virt_kernel_init_addr: u64,
61//! ) {
62//! // Enable timer counter registers for EL1.
63//! CNTHCTL_EL2.write(CNTHCTL_EL2::EL1PCEN::SET + CNTHCTL_EL2::EL1PCTEN::SET);
64//!
65//! // No offset for reading the counters.
66//! CNTVOFF_EL2.set(0);
67//!
68//! // Set EL1 execution state to AArch64.
69//! HCR_EL2.write(HCR_EL2::RW::EL1IsAarch64);
70//!
71//! // Set up a simulated exception return.
72//! SPSR_EL2.write(
73//! SPSR_EL2::D::Masked
74//! + SPSR_EL2::A::Masked
75//! + SPSR_EL2::I::Masked
76//! + SPSR_EL2::F::Masked
77//! + SPSR_EL2::M::EL1h,
78//! );
79//! }
80//! ```
81//!
82//! ## Disclaimer
83//!
84//! Descriptive comments in the source files are taken from the [ARM Architecture Reference Manual
85//! ARMv8, for ARMv8-A architecture
86//! profile](https://static.docs.arm.com/ddi0487/ca/DDI0487C_a_armv8_arm.pdf?_ga=2.266626254.1122218691.1534883460-1326731866.1530967873).
87
88#![cfg_attr(feature = "nightly", feature(core_intrinsics))]
89#![cfg_attr(feature = "nightly", feature(custom_inner_attributes))]
90#![no_std]
91
92pub mod asm;
93#[cfg(feature = "nightly")]
94pub mod registers;