Skip to content

Commit 0180a0b

Browse files
Merge pull request #597 from ianrrees/delay-docs
Document asm::delay() behaviour more thoroughly
2 parents c04e4db + 0d6da44 commit 0180a0b

File tree

1 file changed

+13
-8
lines changed

1 file changed

+13
-8
lines changed

cortex-m/src/asm.rs

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,18 @@ pub fn bkpt() {
1616

1717
/// Blocks the program for *at least* `cycles` CPU cycles.
1818
///
19-
/// This is implemented in assembly so its execution time is independent of the optimization
20-
/// level, however it is dependent on the specific architecture and core configuration.
19+
/// This is implemented in assembly as a fixed number of iterations of a loop, so that execution
20+
/// time is independent of the optimization level.
2121
///
22-
/// NOTE that the delay can take much longer if interrupts are serviced during its execution
23-
/// and the execution time may vary with other factors. This delay is mainly useful for simple
24-
/// timer-less initialization of peripherals if and only if accurate timing is not essential. In
25-
/// any other case please use a more accurate method to produce a delay.
22+
/// The loop code is the same for all architectures, however the number of CPU cycles required for
23+
/// one iteration varies substantially between architectures. This means that with a 48MHz CPU
24+
/// clock, a call to `delay(48_000_000)` is guaranteed to take at least 1 second, but for example
25+
/// could take 2 seconds.
26+
///
27+
/// NOTE that the delay can take much longer if interrupts are serviced during its execution and the
28+
/// execution time may vary with other factors. This delay is mainly useful for simple timer-less
29+
/// initialization of peripherals if and only if accurate timing is not essential. In any other case
30+
/// please use a more accurate method to produce a delay.
2631
#[cfg(cortex_m)]
2732
#[inline]
2833
pub fn delay(cycles: u32) {
@@ -33,9 +38,9 @@ pub fn delay(cycles: u32) {
3338
let real_cycles = 1 + cycles / 2;
3439
unsafe {
3540
asm!(
36-
// The `bne` on some cores (eg Cortex-M4) will take a different number of instructions
41+
// The `bne` on some cores (eg Cortex-M4) will take a different number of cycles
3742
// depending on the alignment of the branch target. Set the alignment of the top of the
38-
// loop to prevent surprising timing changes when the alignment of the delay() changes.
43+
// loop to prevent surprising timing changes when the alignment of `fn delay()` changes.
3944
".p2align 3",
4045
// Use local labels to avoid R_ARM_THM_JUMP8 relocations which fail on thumbv6m.
4146
"1:",

0 commit comments

Comments
 (0)