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