Skip to content

Commit

Permalink
Improved readme
Browse files Browse the repository at this point in the history
  • Loading branch information
adbancroft committed Sep 23, 2024
1 parent effb06d commit 8e7fdbe
Showing 1 changed file with 14 additions and 3 deletions.
17 changes: 14 additions & 3 deletions readme.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
![Build](https://github.com/adbancroft/avr-fast-div/actions/workflows/build.yml/badge.svg)
![Build](https://github.com/adbancroft/avr-fast-div/actions/workflows/unit-tests.yml/badge.svg)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=adbancroft_avr-fast-div&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=adbancroft_avr-fast-div) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=adbancroft_avr-fast-div&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=adbancroft_avr-fast-div)
[![Build](https://github.com/adbancroft/avr-fast-div/actions/workflows/build.yml/badge.svg)](https://github.com/adbancroft/avr-fast-div/actions/workflows/build.yml)
[![Unit Tests](https://github.com/adbancroft/avr-fast-div/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/adbancroft/avr-fast-div/actions/workflows/unit-tests.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=adbancroft_avr-fast-div&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=adbancroft_avr-fast-div)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=adbancroft_avr-fast-div&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=adbancroft_avr-fast-div)

# avr-fast-div: optimized integer division for AVR hardware

This library provides *up to* 60% improvement in run time division speed on AVR hardware. Exact speedup varies depending on data types & number ranges - see below for details (also see the [unit tests](https://github.com/adbancroft/avr-fast-div/actions/workflows/unit-tests.yml)).

As a general guideline, avr-fast-div is applicable to these operations:
Expand All @@ -20,12 +23,18 @@ int16_t/int8_t
### Constraints
1. division using a signed type and unsigned type is not supported. E.g. `int16_t/uint16_t` (it's also a recipe for confusion, since C++ converts the signed integer to an unsigned one before doing the division).
2. There is no 64-bit support
## Using the library
### Installation
The library is available in both the [Arduino Library](https://www.arduino.cc/reference/en/libraries/avr-fast-div/) and [PlatformIO Library](https://registry.platformio.org/libraries/adbancroft/avr-fast-div) registries.
The library can also be cloned & included locally or included directly from GitHub (if your tooling supports it).
### Code
1. `#include <avr-fast-div.h>`
2. Replace divide operations with a call to fast_div. I.e.
* `a / b` -> `fast_div(a, b)`
Expand All @@ -35,7 +44,9 @@ The code base is compatible with all platforms: non-AVR builds compile down to t
**Note:** if the divisor (`b`) is a [compile time constant greater than 8-bits](https://stackoverflow.com/questions/47994933/why-doesnt-gcc-or-clang-on-arm-use-division-by-invariant-integers-using-multip), you probably want to use [libdivide](https://libdivide.com/) instead.
You can reduce the amount of flash (.text segment) the library uses by defining `AFD_SMALL_TEXT`: this will reduce performance by up to 5% in some cases.
## Details
Since the AVR architecture has no hardware divider, all run time division is done in software by the compiler emitting a call to one of the division functions (E.g. [__udivmodsi4](https://github.com/gcc-mirror/gcc/blob/cdd5dd2125ca850aa8599f76bed02509590541ef/libgcc/config/avr/lib1funcs.S#L1615)) contained in a [runtime support library](https://gcc.gnu.org/wiki/avr-gcc#Exceptions_to_the_Calling_Convention).
By neccesity, the division functions are optimised for the general case. Combined with integer type promotion, this can result in sub-optimal division speed. E.g.
Expand Down

0 comments on commit 8e7fdbe

Please sign in to comment.