Manual Pages  — QMATH

typedef int8_t          s8q_t;
typedef uint8_t         u8q_t;
typedef int16_t         s16q_t;
typedef uint16_t        u16q_t;
typedef int32_t         s32q_t;
typedef uint32_t        u32q_t;
typedef int64_t         s64q_t;
typedef uint64_t        u64q_t;

These types are referred to generically in the earlier API definitions as QTYPE, while ITYPE refers to the stdint(7) integer types the Q data types are derived from. NTYPE is used to refer to any numeric type and is therefore a superset of QTYPE and ITYPE.

The 3 least significant bits (LSBs) of all q_t data types are reserved for embedded control data:

	bits 1-2 specify the binary radix point shift index operand, with 00,01,10,11 == 1,2,3,4.
	bit 3 specifies the radix point shift index operand multiplier as 2 (0) or 16 (1).

This scheme can therefore represent Q numbers with [2,4,6,8,16,32,48,64] bits of precision after the binary radix point. The number of bits available for the integral component is not explicitly specified, and implicitly consumes the remaining available bits of the chosen Q data type.

Additionally, the most significant bit (MSB) of signed Q types stores the sign bit, with bit value 0 representing a positive number and bit value 1 representing a negative number. Negative numbers are stored as absolute values with the sign bit set, rather than the more typical two's complement representation. This avoids having to bit shift negative numbers, which can result in undefined behaviour from some compilers.

This binary representation used for Q numbers therefore comprises a set of distinct data bit types and associated bit counts. Data bit types/labels, listed in LSB to MSB order, are: control 'C', fractional 'F', integer 'I' and sign 'S'. The following example illustrates the binary representation of a Q20.8 number represented using a s32q_t variable:

M                                                             L
S                                                             S
B                                                             B

3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

S I I I I I I I I I I I I I I I I I I I I F F F F F F F F C C C

Important bit counts are: total, control, control-encoded fractional, maximum fractional, effective fractional and integer bits.

The count of total bits is derived from the size of the q_t data type. For example, a s32q_t has 32 total bits.

The count of control-encoded fractional bits is derived from calculating the number of fractional bits per the control bit encoding scheme. For example, the control bits binary value of 101 encodes a fractional bit count of 2 x 16 = 32 fractional bits.

The count of maximum fractional bits is derived from the difference between the counts of total bits and control/sign bits. For example, a s32q_t has a maximum of 32 - 3 - 1 = 28 fractional bits.

The count of effective fractional bits is derived from the minimum of the control-encoded fractional bits and the maximum fractional bits. For example, a s32q_t with 32 control-encoded fractional bits is effectively limited to 28 fractional bits.

The count of integer bits is derived from the difference between the counts of total bits and all other non-integer data bits (the sum of control, fractional and sign bits.) For example, a s32q_t with 8 effective fractional bits has 32 - 3 - 8 - 1 = 20 integer bits. The count of integer bits can be zero if all available numeric data bits have been reserved for fractional data, e.g., when the number of control-encoded fractional bits is greater than or equal to the underlying Q data type's maximum fractional bits.