Skip to content

♻️ (minor) v6: Make hal::duration_from_cycles the reverse of cycles_per - #128

Merged
kammce merged 1 commit into
mainfrom
v6-duration-from-cycles
Nov 13, 2026
Merged

kammce merged 1 commit into
mainfrom
v6-duration-from-cycles

Conversation

@kammce

@kammce kammce commented Nov 12, 2026

Copy link
Copy Markdown
Member

Makes hal::duration_from_cycles() the reverse of hal::cycles_per(): the time a number of cycles of a frequency takes, in whole integers and rounded up. It's for code that counts in ticks of a clock and needs the time left as a duration, such as sleeping on a waiter until a steady-clock deadline. libhal/libhal-arm-mcu#242's dma_i2c is the first caller, in place of its own hand-written conversion.

auto const left = deadline - clock.uptime();
waiter.block_for(hal::duration_from_cycles(clock.frequency(), left));

Changes

Before After
Signature std::optional<hal::time_duration> duration_from_cycles(hertz, std::uint32_t) constexpr hal::time_duration duration_from_cycles(hertz, hal::u64)
Arithmetic float, so long counts lose precision integers: whole seconds, then the cycles left over, so nothing overflows
Rounding down, so a sleep until a deadline could end early up, like cycles_per(): the duration is never shorter than the cycles take
Too long to represent std::nullopt hal::time_duration::max() (about 292 years), from its last whole second on
0 Hz std::nullopt hal::time_duration::max(), since such a clock never completes a cycle. 0 cycles still take 0.

Changing the return type breaks callers that call .value(), but nothing outside libhal-util calls it.

Size

The function is constexpr and inlines into its caller. On the stm32f103c8 (LLVM 23, MinSizeRel), using it in dma_i2c's DMA wait in place of the hand-written version grows wait_for_transfer() by 46 B (392 to 438 B). The difference is the 0 Hz case and the saturation at max(), which the hand-written version handled by forcing the frequency to at least 1 Hz and capping each sleep at 2^32 seconds. Both versions make the same two 64-bit divisions.

Testing

All 17 host test suites pass, with clang-tidy on. The duration_from_cycles tests now cover:

  • exact durations;
  • rounding up of the cycles left over;
  • cycles_per() of the result giving back the cycles, or one more from rounding both ways;
  • no cycles, and 0 Hz;
  • saturating at the last whole second;
  • the largest frequency with the most cycles left over.

The release this PR cuts ((minor)) is what libhal/libhal-arm-mcu#242 needs as its minimum libhal-util version.

duration_from_cycles() computed in float, so long counts lost precision,
took 32-bit cycles, and rounded down, so a sleep until a deadline could
end early. It now works in integers: 64-bit cycles, rounded up like
cycles_per(), so the duration is never shorter than the cycles take.

It returns the duration instead of an optional:
hal::time_duration::max() from its last second on, and at 0 Hz, which
never completes a cycle. Nothing outside libhal-util calls it.
@kammce
kammce merged commit 2aee675 into main Nov 13, 2026
10 checks passed
@kammce
kammce deleted the v6-duration-from-cycles branch November 13, 2026 13:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant