Skip to content

✨ (minor) v6: Add hal::divide_round_up and hal::divide_round_nearest - #131

Open
kammce wants to merge 1 commit into
mainfrom
v6-divide-round-up
Open

kammce wants to merge 1 commit into
mainfrom
v6-divide-round-up

Conversation

@kammce

@kammce kammce commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Adds hal::divide_round_up() and hal::divide_round_nearest() to v6, and fixes hal::rounding_division() by having it call the second. Closes #127.

Changes

  • hal::divide_round_up(numerator, denominator) takes unsigned operands and returns the quotient, plus 1 if there is a remainder: (a / b) + (a % b != 0). It can't overflow, which (a + b - 1) / b can for a numerator near the type's largest value. With Clang 23 at -Os, a 32-bit call on a Cortex-M3 is udiv, mls, a compare and a conditional add. On a Cortex-M0+ it is one call to __aeabi_uidiv, and a 64-bit call is one call to __aeabi_uldivmod.
  • hal::divide_round_nearest(numerator, denominator) takes any integral type and rounds to the nearest integer, with a half rounding away from zero (5 / 2 is 3, -5 / 2 is -3). It works on the magnitudes in the unsigned type, so the smallest signed value doesn't overflow.
  • hal::rounding_division() keeps its hal::division<T> signature and calls divide_round_nearest(). The old version gave wrong results:
Input Before Now
7 / 3 3 2
10 / 7 2 1
3 / 4 0 1
1 / 2 0 1
1 / 0 0 not allowed, as with /

Choices to review

These are my answers to the questions in #127, and each is easy to change:

  • One function per rounding mode, not one function taking a mode. Rounding down is /.
  • A plain quotient, not { quotient, remainder }. A caller that wants the rate it actually reaches can work it out from the quotient.
  • Two parameters. rounding_division() keeps the struct because it already exists, and nothing in the org calls it.
  • A zero denominator is a precondition violation, the same as for /. It is a compile error in a constant expression.

Not in this PR

The hand-written round-ups listed in #127 (cycles_per, the arm-mcu SPI prescaler, ADC wait, I2C timing and SysTick counts) still use their own code. They can switch to divide_round_up() once this is released.

Testing

tests/math.test.cpp covers exact and inexact division, a half in each sign combination, the inputs from the table above, and the largest and smallest values of 32-bit and 64-bit types. All 17 test suites pass with Clang 23, ASan and clang-tidy as warnings-as-errors.

Clock dividers, prescalers and tick counts need a quotient that rounds
up, and every caller wrote its own. hal::divide_round_up() is that, and
can't overflow the way adding the denominator before dividing can.

hal::rounding_division() was wrong for some inputs: 7 / 3 gave 3, 10 / 7
gave 2, 3 / 4 and 1 / 2 gave 0, and a zero denominator gave 0. It now
calls the new hal::divide_round_nearest(), which rounds to the nearest
integer and a half away from zero, for any integral type.

This branch has not been deployed

No deployments
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.

v6: Add integer division that rounds up

1 participant