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