sam3_hal/lib.rs
1#![no_std]
2#![allow(dead_code)]
3//! # SAM3
4//!
5//! This is a hardware abstraction layer (HAL) over each of the following families of Microchip
6//! MCUs (configurations listed in parenthesis):
7//! - **ATSAM3A**, **ATSAM3X** (ATSAM3A4C, ATSAM3A8C, ATSAM3X4C, ATSAM3X4E, ATSAM3X8C, ATSAM3X8E,
8//! ATSAM3X8H)
9//! - **ATSAM3N** (ATSAM3N00A, ATSAM3N00B, ATSAM3N0A, ATSAM3N0B, ATSAM3N0C, ATSAM3N1A, ATSAM3N1B,
10//! ATSAM3N1C, ATSAM3N2A, ATSAM3N2B, ATSAM3N2C, ATSAM3N4A, ATSAM3N4B, ATSAM3N4C)
11//! - **ATSAM3S1**, **ATSAM3S2**, **ATSAM3S4** (ATSAM3S1A, ATSAM3S1B, ATSAM3S1C, ATSAM3S2A,
12//! ATSAM3S2B, ATSAM3S2C, ATSAM3S4A, ATSAM3S4B, ATSAM3S4C)
13//! - **ATSAM3S8**, **ATSAM3SD8** (ATSAM3S8B, ATSAM3S8C, ATSAM3SD8B, ATSAM3SD8C)
14//! - **ATSAM3U** (ATSAM3U1C, ATSAM3U1E, ATSAM3U2C, ATSAM3U2E, ATSAM3U4C, ATSAM3U4E)
15//!
16//! This project relies on some outside information under a different license (Apache), retrieved
17//! from [the Atmel/Microchip pack repository][atmel-src]. The SVD files for each of the families
18//! listed above are depended on for generating the PAC (peripheral access control) crates, and the
19//! linker scripts are used to create the `memory.x` and `device.x` files that the
20//! [`cortex-m-rt`][cortex-m-rt] depends on to compile device binaries.
21//!
22//! Additionally, documentation for each peripheral, register, and on-chip function has been copied
23//! over (excluding diagrams) from the device manuals. Extra sections with per-family or per-chip
24//! information have been added as necessary. However, should you prefer to read the manuals rather
25//! than the transcriptions here, you can find them here:
26//! - **ATSAM3A**, **ATSAM3X**: [manual][atsam3ax-manual]
27//! - **ATSAM3N**: [manual][atsam3n-manual]
28//! - **ATSAM3S1**, **ATSAM3S2**, **ATSAM3S4**: [manual][atsam3s124-manual]
29//! - **ATSAM3S8**, **ATSAM3SD8**: [manual][atsam3sd8-manual]
30//! - **ATSAM3U**: [manual][atsam3u-manual]
31//!
32//! There are errata for each one towards the end of the manuals.
33//!
34//! [atmel-src]: http://packs.download.atmel.com/
35//! [cortex-m-rt]: https://crates.io/crates/cortex-m-rt
36//! [atsam3ax-manual]: https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf
37//! [atsam3n-manual]: https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11011-32-bit-Cortex-M3-Microcontroller-SAM3N_Datasheet.pdf
38//! [atsam3s124-manual]: https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6500-32-bit-Cortex-M3-Microcontroller-SAM3S4-SAM3S2-SAM3S1_Datasheet.pdf
39//! [atsam3sd8-manual]: https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11090-32-bit%20Cortex-M3-Microcontroller-SAM-3S8-SD8_Datasheet.pdf
40//! [atsam3u-manual]: https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6430-32-bit-Cortex-M3-Microcontroller-SAM3U4-SAM3U2-SAM3U1_Datasheet.pdf
41//!
42//! # Important notes!
43//!
44//! #### Doc feature flags
45//!
46//! The docs were generated with the feature flags `sam3x8e-rt` and `unproven`. However, parts of
47//! the HAL are conditionally compiled and can change depending on your chip version, e.g.
48//! ```ignore
49//! #[cfg(not(feature = "schmitt"))]
50//! /// Disable PIO control of the output.
51//! pub struct OutputDisabled;
52//!
53//! #[cfg(feature = "schmitt")]
54//! /// Disable PIO control of the output.
55//! pub struct OutputDisabled<Schm: SchmittTriggerCfg> {
56//! _schm: PhantomData<Schm>,
57//! }
58//! ```
59//! It's highly recommended that you build docs locally for your chip if you're not using a SAM3A,
60//! SAM3U, or SAM3X chip.
61//!
62//! #### Feature flags
63//!
64//! The only feature flags that crate users should specify are:
65//! - A device feature (such as `sam3a4c`)
66//! - A device feature with runtime (such as `sam3a4c-rt`)
67//! - The `unproven` flag
68//!
69//! All the other features are marker features used as shorthands throughout the rest of the crate
70//! so it wouldn't be necessary to have large, hard to document `#[cfg()]` blocks in far too many
71//! places. You may attempt to enable other features if you wish, however, no guarantees are made
72//! about whether this crate will compile, much less function correctly.
73
74#[cfg(not(feature = "device"))]
75compile_error! {
76 "The HAL must be built for a specific device or as a library."
77}
78
79#[cfg(feature = "atsam3a4c")]
80pub use atsam3a4c as pac;
81
82#[cfg(feature = "atsam3a8c")]
83pub use atsam3a8c as pac;
84
85#[cfg(feature = "atsam3n00a")]
86pub use atsam3n00a as pac;
87
88#[cfg(feature = "atsam3n00b")]
89pub use atsam3n00b as pac;
90
91#[cfg(feature = "atsam3n0a")]
92pub use atsam3n0a as pac;
93
94#[cfg(feature = "atsam3n0b")]
95pub use atsam3n0b as pac;
96
97#[cfg(feature = "atsam3n0c")]
98pub use atsam3n0c as pac;
99
100#[cfg(feature = "atsam3n1a")]
101pub use atsam3n1a as pac;
102
103#[cfg(feature = "atsam3n1b")]
104pub use atsam3n1b as pac;
105
106#[cfg(feature = "atsam3n1c")]
107pub use atsam3n1c as pac;
108
109#[cfg(feature = "atsam3n2a")]
110pub use atsam3n2a as pac;
111
112#[cfg(feature = "atsam3n2b")]
113pub use atsam3n2b as pac;
114
115#[cfg(feature = "atsam3n2c")]
116pub use atsam3n2c as pac;
117
118#[cfg(feature = "atsam3n4a")]
119pub use atsam3n4a as pac;
120
121#[cfg(feature = "atsam3n4b")]
122pub use atsam3n4b as pac;
123
124#[cfg(feature = "atsam3n4c")]
125pub use atsam3n4c as pac;
126
127#[cfg(feature = "atsam3s1a")]
128pub use atsam3s1a as pac;
129
130#[cfg(feature = "atsam3s1b")]
131pub use atsam3s1b as pac;
132
133#[cfg(feature = "atsam3s1c")]
134pub use atsam3s1c as pac;
135
136#[cfg(feature = "atsam3s2a")]
137pub use atsam3s2a as pac;
138
139#[cfg(feature = "atsam3s2b")]
140pub use atsam3s2b as pac;
141
142#[cfg(feature = "atsam3s2c")]
143pub use atsam3s2c as pac;
144
145#[cfg(feature = "atsam3s4a")]
146pub use atsam3s4a as pac;
147
148#[cfg(feature = "atsam3s4b")]
149pub use atsam3s4b as pac;
150
151#[cfg(feature = "atsam3s4c")]
152pub use atsam3s4c as pac;
153
154#[cfg(feature = "atsam3s8b")]
155pub use atsam3s8b as pac;
156
157#[cfg(feature = "atsam3s8c")]
158pub use atsam3s8c as pac;
159
160#[cfg(feature = "atsam3sd8b")]
161pub use atsam3sd8b as pac;
162
163#[cfg(feature = "atsam3sd8c")]
164pub use atsam3sd8c as pac;
165
166#[cfg(feature = "atsam3u1c")]
167pub use atsam3u1c as pac;
168
169#[cfg(feature = "atsam3u1e")]
170pub use atsam3u1e as pac;
171
172#[cfg(feature = "atsam3u2c")]
173pub use atsam3u2c as pac;
174
175#[cfg(feature = "atsam3u2e")]
176pub use atsam3u2e as pac;
177
178#[cfg(feature = "atsam3u4c")]
179pub use atsam3u4c as pac;
180
181#[cfg(feature = "atsam3u4e")]
182pub use atsam3u4e as pac;
183
184#[cfg(feature = "atsam3x4c")]
185pub use atsam3x4c as pac;
186
187#[cfg(feature = "atsam3x4e")]
188pub use atsam3x4e as pac;
189
190#[cfg(feature = "atsam3x8c")]
191pub use atsam3x8c as pac;
192
193#[cfg(feature = "atsam3x8e")]
194pub use atsam3x8e as pac;
195
196#[cfg(feature = "atsam3x8h")]
197pub use atsam3x8h as pac;
198
199#[cfg(all(feature = "device", any(feature = "sam3a", feature = "sam3x")))]
200pub mod dacc;
201#[cfg(feature = "device")]
202pub mod peripheral_id;
203#[cfg(feature = "device")]
204pub mod pio;
205#[cfg(all(feature = "device", any(feature = "sam3a", feature = "sam3x")))]
206mod pmc;
207#[cfg(feature = "device")]
208pub mod structure;
209#[cfg(feature = "device")]
210pub mod write_protect;
211
212#[cfg(all(feature = "device", feature = "unproven"))]
213/// Bias current control settings for DACCs and ADCs.
214///
215/// # Warning
216///
217/// None of the SAM3 chip families except for SAM3U have documentation that states what the values
218/// for `IBCTLCH0`, `IBCTLCH1`, or `IBCTLDACCORE` can be, or what they mean. However, the docs for
219/// the SAM3U chips have [something](https://github.com/arduino/ArduinoCore-sam/blob/master/system/CMSIS/Device/ATMEL/sam3u/html/ADC12B.html#L1629)
220/// for IBCTL, and it's just assumed that they mean the same thing on other chip families.
221#[derive(Clone, Copy, Debug)]
222#[repr(u8)]
223pub enum CurrentBias {
224 /// `typical - 20%`
225 M20 = 0b00,
226 /// No change
227 Typ = 0b01,
228 /// `typical + 20%`
229 P20 = 0b10,
230 /// `typical + 40%`
231 P40 = 0b11,
232}