1.\" 2.\" Copyright (c) 2018 Netflix, Inc. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions, and the following disclaimer, 10.\" without modification, immediately at the beginning of the file. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 18.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd July 4, 2019 29.Dt QMATH 3 30.Os 31.Sh NAME 32.Nm qmath 33.Nd fixed-point math library based on the 34.Dq Q 35number format 36.Sh SYNOPSIS 37.In sys/qmath.h 38.Sh DESCRIPTION 39The 40.Nm 41data types and APIs support fixed-point math based on the 42.Dq Q 43number format. 44The APIs have been built around the following data types: 45.Vt s8q_t , 46.Vt u8q_t , 47.Vt s16q_t , 48.Vt u16q_t , 49.Vt s32q_t , 50.Vt u32q_t , 51.Vt s64q_t , 52and 53.Vt u64q_t , 54which are referred to generically in the earlier API definitions as 55.Fa QTYPE . 56The 57.Fa ITYPE 58refers to the 59.Xr stdint 7 60integer types. 61.Fa NTYPE 62is used to refer to any numeric type and is therefore a superset of 63.Fa QTYPE 64and 65.Fa ITYPE . 66.Pp 67This scheme can represent Q numbers with 68.Bq 2, 4, 6, 8, 16, 32, 48 69bits of precision after the binary radix point, 70depending on the 71.Fa rpshft 72argument to 73.Fn Q_INI . 74The number of bits available for the integral component is not explicitly 75specified, and implicitly consumes the remaining available bits of the chosen Q 76data type. 77.Pp 78Operations on Q numbers maintain the precision of their arguments. 79The fractional component is truncated to fit into the destination, 80with no rounding. 81None of the operations is affected by the floating-point environment. 82.Pp 83For more details, see the 84.Sx IMPLEMENTATION DETAILS 85below. 86.Sh LIST OF FUNCTIONS 87.de Cl 88.Bl -column "isgreaterequal" "bessel function of the second kind of the order 0" 89.Em "Name Description" 90.. 91.Ss Functions which create/initialise a Q number 92.Cl 93.Xr Q_INI 3 initialise a Q number 94.El 95.Ss Numeric functions which operate on two Q numbers 96.Cl 97.Xr Q_QADDQ 3 addition 98.Xr Q_QDIVQ 3 division 99.Xr Q_QMULQ 3 multiplication 100.Xr Q_QSUBQ 3 subtraction 101.Xr Q_NORMPREC 3 normalisation 102.Xr Q_QMAXQ 3 maximum function 103.Xr Q_QMINQ 3 minimum function 104.Xr Q_QCLONEQ 3 identical copy 105.Xr Q_QCPYVALQ 3 representational copy 106.El 107.Ss Numeric functions which apply integers to a Q number 108.Cl 109.Xr Q_QADDI 3 addition 110.Xr Q_QDIVI 3 division 111.Xr Q_QMULI 3 multiplication 112.Xr Q_QSUBI 3 subtraction 113.Xr Q_QFRACI 3 fraction 114.Xr Q_QCPYVALI 3 overwrite 115.El 116.Ss Numeric functions which operate on a single Q number 117.Cl 118.Xr Q_QABS 3 absolute value 119.Xr Q_Q2D 3 double representation 120.Xr Q_Q2F 3 float representation 121.El 122.Ss Comparison and logic functions 123.Cl 124.Xr Q_SIGNED 3 determine sign 125.Xr Q_LTZ 3 less than zero 126.Xr Q_PRECEQ 3 compare bits 127.Xr Q_QLTQ 3 less than 128.Xr Q_QLEQ 3 less or equal 129.Xr Q_QGTQ 3 greater than 130.Xr Q_QGEQ 3 greater or equal 131.Xr Q_QEQ 3 equal 132.Xr Q_QNEQ 3 not equal 133.Xr Q_OFLOW 3 would overflow 134.Xr Q_RELPREC 3 relative precision 135.El 136.Ss Functions which manipulate the control/sign data bits 137.Cl 138.Xr Q_SIGNSHFT 3 sign bit position 139.Xr Q_SSIGN 3 sign bit 140.Xr Q_CRAWMASK 3 control bitmask 141.Xr Q_SRAWMASK 3 sign bitmask 142.Xr Q_GCRAW 3 raw control bits 143.Xr Q_GCVAL 3 value of control bits 144.Xr Q_SCVAL 3 set control bits 145.El 146.Ss Functions which manipulate the combined integer/fractional data bits 147.Cl 148.Xr Q_IFRAWMASK 3 integer/fractional bitmask 149.Xr Q_IFVALIMASK 3 value of integer bits 150.Xr Q_IFVALFMASK 3 value of fractional bits 151.Xr Q_GIFRAW 3 raw integer/fractional bits 152.Xr Q_GIFABSVAL 3 absolute value of fractional bits 153.Xr Q_GIFVAL 3 real value of fractional bits 154.Xr Q_SIFVAL 3 set integer/fractional bits 155.Xr Q_SIFVALS 3 set separate integer/fractional values 156.El 157.Ss Functions which manipulate the integer data bits 158.Cl 159.Xr Q_IRAWMASK 3 integer bitmask 160.Xr Q_GIRAW 3 raw integer bits 161.Xr Q_GIABSVAL 3 absolute value of integer bits 162.Xr Q_GIVAL 3 real value of integer bits 163.Xr Q_SIVAL 3 set integer bits 164.El 165.Ss Functions which manipulate the fractional data bits 166.Cl 167.Xr Q_FRAWMASK 3 fractional bitmask 168.Xr Q_GFRAW 3 raw fractional bits 169.Xr Q_GFABSVAL 3 absolute value of fractional bits 170.Xr Q_GFVAL 3 real value of fractional bits 171.Xr Q_SFVAL 3 set fractional bits 172.El 173.Ss Miscellaneous functions/variables 174.Cl 175.Xr Q_NCBITS 3 number of reserved control bits 176.Xr Q_BT 3 C data type 177.Xr Q_TC 3 casted data type 178.Xr Q_NTBITS 3 number of total bits 179.Xr Q_NFCBITS 3 number of control-encoded fractional bits 180.Xr Q_MAXNFBITS 3 number of maximum fractional bits 181.Xr Q_NFBITS 3 number of effective fractional bits 182.Xr Q_NIBITS 3 number of integer bits 183.Xr Q_RPSHFT 3 bit position of radix point 184.Xr Q_ABS 3 absolute value 185.Xr Q_MAXSTRLEN 3 number of characters to render string 186.Xr Q_TOSTR 3 render string 187.Xr Q_SHL 3 left-shifted value 188.Xr Q_SHR 3 right-shifted value 189.Xr Q_DEBUG 3 render debugging information 190.Xr Q_DFV2BFV 3 convert decimal fractional value 191.El 192.Sh IMPLEMENTATION DETAILS 193The 194.Nm 195data types and APIs support fixed-point math based on the 196.Dq Q 197number format. 198This implementation uses the Q notation 199.Em Qm.n , 200where 201.Em m 202specifies the number of bits for integral data 203.Pq excluding the sign bit for signed types , 204and 205.Em n 206specifies the number of bits for fractional data. 207.Pp 208The APIs have been built around the following q_t derived data types: 209.Bd -literal -offset indent 210typedef int8_t s8q_t; 211typedef uint8_t u8q_t; 212typedef int16_t s16q_t; 213typedef uint16_t u16q_t; 214typedef int32_t s32q_t; 215typedef uint32_t u32q_t; 216typedef int64_t s64q_t; 217typedef uint64_t u64q_t; 218.Ed 219.Pp 220These types are referred to generically in the earlier API definitions as 221.Fa QTYPE , 222while 223.Fa ITYPE 224refers to the 225.Xr stdint 7 226integer types the Q data types are derived from. 227.Fa NTYPE 228is used to refer to any numeric type and is therefore a superset of 229.Fa QTYPE 230and 231.Fa ITYPE . 232.Pp 233The 3 least significant bits 234.Pq LSBs 235of all q_t data types are reserved for embedded control data: 236.Bl -dash 237.It 238bits 1-2 specify the binary radix point shift index operand, with 00,01,10,11 == 2391,2,3,4. 240.It 241bit 3 specifies the radix point shift index operand multiplier as 2 242.Pq 0 243or 16 244.Pq 1 . 245.El 246.Pp 247This scheme can therefore represent Q numbers with 248.Bq 2,4,6,8,16,32,48,64 249bits of precision after the binary radix point. 250The number of bits available for the integral component is not explicitly 251specified, and implicitly consumes the remaining available bits of the chosen Q 252data type. 253.Pp 254Additionally, the most significant bit 255.Pq MSB 256of signed Q types stores the sign bit, with bit value 0 representing a positive 257number and bit value 1 representing a negative number. 258Negative numbers are stored as absolute values with the sign bit set, rather 259than the more typical two's complement representation. 260This avoids having to bit shift negative numbers, which can result in undefined 261behaviour from some compilers. 262.Pp 263This binary representation used for Q numbers therefore comprises a set of 264distinct data bit types and associated bit counts. 265Data bit types/labels, listed in LSB to MSB order, are: control 266.Sq C , 267fractional 268.Sq F , 269integer 270.Sq I 271and sign 272.Sq S . 273The following example illustrates the binary representation of a Q20.8 number 274represented using a s32q_t variable: 275.Bd -literal -offset indent 276M L 277S S 278B B 279 2803 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 2811 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 282 283S 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 284.Ed 285.Pp 286Important bit counts are: total, control, control-encoded fractional, maximum 287fractional, effective fractional and integer bits. 288.Pp 289The count of total bits is derived from the size of the q_t data type. 290For example, a s32q_t has 32 total bits. 291.Pp 292The count of control-encoded fractional bits is derived from calculating the 293number of fractional bits per the control bit encoding scheme. 294For example, the control bits binary value of 101 encodes a fractional bit 295count of 2 x 16 = 32 fractional bits. 296.Pp 297The count of maximum fractional bits is derived from the difference between the 298counts of total bits and control/sign bits. 299For example, a s32q_t has a maximum of 32 - 3 - 1 = 28 fractional bits. 300.Pp 301The count of effective fractional bits is derived from the minimum of the 302control-encoded fractional bits and the maximum fractional bits. 303For example, a s32q_t with 32 control-encoded fractional bits is effectively 304limited to 28 fractional bits. 305.Pp 306The count of integer bits is derived from the difference between the counts of 307total bits and all other non-integer data bits 308.Pq the sum of control, fractional and sign bits. 309For example, a s32q_t with 8 effective fractional bits has 32 - 3 - 8 - 1 = 20 integer 310bits. 311The count of integer bits can be zero if all available numeric data bits have 312been reserved for fractional data, e.g., when the number of control-encoded 313fractional bits is greater than or equal to the underlying Q data type's maximum 314fractional bits. 315.Sh EXAMPLES 316.Ss Calculating area of a circle with r=4.2 and rpshft=16 317.Bd -literal -offset indent 318u64q_t a, pi, r; 319char buf[32] 320 321Q_INI(&a, 0, 0, 16); 322Q_INI(&pi, 3, 14159, 16); 323Q_INI(&r, 4, 2, 16); 324 325Q_QCLONEQ(&a, r); 326Q_QMULQ(&a, r); 327Q_QMULQ(&a, pi); 328 329Q_TOSTR(a, -1, 10, buf, sizeof(buf)); 330printf("%s\\n", buf); 331.Ed 332.Ss Debugging 333Declare a Q20.8 s32q_t number 334.Fa s32 , 335initialise it with the fixed-point value for 5/3, and render a debugging 336representation of the variable 337.Pq including its full precision decimal C-string representation , 338to the console: 339.Bd -literal -offset indent 340s32q_t s32; 341Q_INI(&s32, 0, 0, 8); 342Q_QFRACI(&s32, 5, 3); 343char buf[Q_MAXSTRLEN(s32, 10)]; 344Q_TOSTR(s32, -1, 10, buf, sizeof(buf)); 345printf(Q_DEBUG(s32, "", "\\n\\ttostr=%s\\n\\n", 0), buf); 346.Ed 347.Pp 348The above code outputs the following to the console: 349.Bd -literal -offset indent 350"s32"@0x7fffffffe7d4 351 type=s32q_t, Qm.n=Q20.8, rpshft=11, imin=0xfff00001, \\ 352imax=0xfffff 353 qraw=0x00000d53 354 imask=0x7ffff800, fmask=0x000007f8, cmask=0x00000007, \\ 355ifmask=0x7ffffff8 356 iraw=0x00000800, iabsval=0x1, ival=0x1 357 fraw=0x00000550, fabsval=0xaa, fval=0xaa 358 tostr=1.664 359.Ed 360.Pp 361Note: The 362.Qq \e 363present in the rendered output above indicates a manual line break inserted to 364keep the man page within 80 columns and is not part of the actual output. 365.Sh SEE ALSO 366.Xr errno 2 , 367.Xr math 3 , 368.Xr Q_FRAWMASK 3 , 369.Xr Q_IFRAWMASK 3 , 370.Xr Q_INI 3 , 371.Xr Q_IRAWMASK 3 , 372.Xr Q_QABS 3 , 373.Xr Q_QADDI 3 , 374.Xr Q_QADDQ 3 , 375.Xr Q_SIGNED 3 , 376.Xr Q_SIGNSHFT 3 , 377.Xr stdint 7 378.Sh HISTORY 379The 380.Nm 381functions first appeared in 382.Fx 13.0 . 383.Sh AUTHORS 384.An -nosplit 385The 386.Nm 387functions and this manual page were written by 388.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 389and sponsored by Netflix, Inc. 390