Fuchsia Fixed-Point Library (FFL) for Rust

A Rust port of the Fuchsia Fixed-Point Library (originally //zircon/system/ulib/ffl).

Introduction

FFL is a fixed-point arithmetic library. In Rust, it is designed as a type-safe library to support kernel scheduler development and other performance-sensitive code where floating-point math is unavailable or undesirable, and well-defined saturating arithmetic and convergent rounding (round-half-to-even) are required.

Key Types

  1. Fixed<I, const FRAC: usize>: The primary fixed-point type. It uses the integer type I as the underlying representation, and reserves FRAC bits for the fractional component. Supports standard arithmetic operators (addition, subtraction, multiplication, division, negation), relational operators, and formatting/display.

  2. FastFixed<I, const FRAC: usize>: A wrapper around Fixed that forces intermediate calculations to be performed in 64-bit saturating space for maximum execution efficiency on 64-bit targets. For performance-sensitive code paths (like scheduler tick math), FastFixed can be used to avoid 128-bit intermediates where 64-bit intermediates are known not to overflow or where saturation to 64-bit limits is acceptable.

General Usage

use ffl::Fixed;

// Construct Fixed values
let a = Fixed::<i32, 16>::from_integer(5);
let b = Fixed::<i32, 16>::from_raw(12345);

// Arithmetic
let sum = a + b;
let diff = a - b;

// Division produces a DivExpression, which is evaluated on conversion back to
// Fixed
let ratio = Fixed::<i32, 16>::from(a / b);

Expression Trees and Precision

To preserve precision during intermediate calculation (especially division), arithmetic operators return intermediate types:

  • Division returns a DivExpression, which evaluates only when converted back to a Fixed type or coerced to a target resolution via to_resolution.
  • Mixed-precision arithmetic uses PromoteAddSub and PromoteMul traits to automatically select wider intermediate integer types, preventing premature overflow/underflow.

Resolution Coercion

You can coerce intermediate expression results to a specific target resolution using to_resolution:

use ffl::{from_ratio, to_resolution, Fixed};

let val = to_resolution::<2, i32, _, _>(from_ratio(123, 456));