src/lib/ffl/README.md

# 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

```rust
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`:
```rust
use ffl::{from_ratio, to_resolution, Fixed};

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