share/man/man3/qmath.3

   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
  35 number format
  36 .Sh SYNOPSIS
  37 .In sys/qmath.h
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 data types and APIs support fixed-point math based on the
  42 .Dq Q
  43 number format.
  44 The 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 ,
  52 and
  53 .Vt u64q_t ,
  54 which are referred to generically in the earlier API definitions as
  55 .Fa QTYPE .
  56 The
  57 .Fa ITYPE
  58 refers to the
  59 .Xr stdint 7
  60 integer types.
  61 .Fa NTYPE
  62 is used to refer to any numeric type and is therefore a superset of
  63 .Fa QTYPE
  64 and
  65 .Fa ITYPE .
  66 .Pp
  67 This scheme can represent Q numbers with
  68 .Bq 2, 4, 6, 8, 16, 32, 48
  69 bits of precision after the binary radix point,
  70 depending on the
  71 .Fa rpshft
  72 argument to
  73 .Fn Q_INI .
  74 The number of bits available for the integral component is not explicitly
  75 specified, and implicitly consumes the remaining available bits of the chosen Q
  76 data type.
  77 .Pp
  78 Operations on Q numbers maintain the precision of their arguments.
  79 The fractional component is truncated to fit into the destination,
  80 with no rounding.
  81 None of the operations is affected by the floating-point environment.
  82 .Pp
  83 For more details, see the
  84 .Sx IMPLEMENTATION DETAILS
  85 below.
  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
 193 The
 194 .Nm
 195 data types and APIs support fixed-point math based on the
 196 .Dq Q
 197 number format.
 198 This implementation uses the Q notation
 199 .Em Qm.n ,
 200 where
 201 .Em m
 202 specifies the number of bits for integral data
 203 .Pq excluding the sign bit for signed types ,
 204 and
 205 .Em n
 206 specifies the number of bits for fractional data.
 207 .Pp
 208 The APIs have been built around the following q_t derived data types:
 209 .Bd -literal -offset indent
 210 typedef int8_t          s8q_t;
 211 typedef uint8_t         u8q_t;
 212 typedef int16_t         s16q_t;
 213 typedef uint16_t        u16q_t;
 214 typedef int32_t         s32q_t;
 215 typedef uint32_t        u32q_t;
 216 typedef int64_t         s64q_t;
 217 typedef uint64_t        u64q_t;
 218 .Ed
 219 .Pp
 220 These types are referred to generically in the earlier API definitions as
 221 .Fa QTYPE ,
 222 while
 223 .Fa ITYPE
 224 refers to the
 225 .Xr stdint 7
 226 integer types the Q data types are derived from.
 227 .Fa NTYPE
 228 is used to refer to any numeric type and is therefore a superset of
 229 .Fa QTYPE
 230 and
 231 .Fa ITYPE .
 232 .Pp
 233 The 3 least significant bits
 234 .Pq LSBs
 235 of all q_t data types are reserved for embedded control data:
 236 .Bl -dash
 237 .It
 238 bits 1-2 specify the binary radix point shift index operand, with 00,01,10,11 ==
 239 1,2,3,4.
 240 .It
 241 bit 3 specifies the radix point shift index operand multiplier as 2
 242 .Pq 0
 243 or 16
 244 .Pq 1 .
 245 .El
 246 .Pp
 247 This scheme can therefore represent Q numbers with
 248 .Bq 2,4,6,8,16,32,48,64
 249 bits of precision after the binary radix point.
 250 The number of bits available for the integral component is not explicitly
 251 specified, and implicitly consumes the remaining available bits of the chosen Q
 252 data type.
 253 .Pp
 254 Additionally, the most significant bit
 255 .Pq MSB
 256 of signed Q types stores the sign bit, with bit value 0 representing a positive
 257 number and bit value 1 representing a negative number.
 258 Negative numbers are stored as absolute values with the sign bit set, rather
 259 than the more typical two's complement representation.
 260 This avoids having to bit shift negative numbers, which can result in undefined
 261 behaviour from some compilers.
 262 .Pp
 263 This binary representation used for Q numbers therefore comprises a set of
 264 distinct data bit types and associated bit counts.
 265 Data bit types/labels, listed in LSB to MSB order, are: control
 266 .Sq C ,
 267 fractional
 268 .Sq F ,
 269 integer
 270 .Sq I
 271 and sign
 272 .Sq S .
 273 The following example illustrates the binary representation of a Q20.8 number
 274 represented using a s32q_t variable:
 275 .Bd -literal -offset indent
 276 M                                                             L
 277 S                                                             S
 278 B                                                             B
 279
 280 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
 281 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
 282
 283 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
 284 .Ed
 285 .Pp
 286 Important bit counts are: total, control, control-encoded fractional, maximum
 287 fractional, effective fractional and integer bits.
 288 .Pp
 289 The count of total bits is derived from the size of the q_t data type.
 290 For example, a s32q_t has 32 total bits.
 291 .Pp
 292 The count of control-encoded fractional bits is derived from calculating the
 293 number of fractional bits per the control bit encoding scheme.
 294 For example, the control bits binary value of 101 encodes a fractional bit
 295 count of 2 x 16 = 32 fractional bits.
 296 .Pp
 297 The count of maximum fractional bits is derived from the difference between the
 298 counts of total bits and control/sign bits.
 299 For example, a s32q_t has a maximum of 32 - 3 - 1 = 28 fractional bits.
 300 .Pp
 301 The count of effective fractional bits is derived from the minimum of the
 302 control-encoded fractional bits and the maximum fractional bits.
 303 For example, a s32q_t with 32 control-encoded fractional bits is effectively
 304 limited to 28 fractional bits.
 305 .Pp
 306 The count of integer bits is derived from the difference between the counts of
 307 total bits and all other non-integer data bits
 308 .Pq the sum of control, fractional and sign bits.
 309 For example, a s32q_t with 8 effective fractional bits has 32 - 3 - 8 - 1 = 20 integer
 310 bits.
 311 The count of integer bits can be zero if all available numeric data bits have
 312 been reserved for fractional data, e.g., when the number of control-encoded
 313 fractional bits is greater than or equal to the underlying Q data type's maximum
 314 fractional bits.
 315 .Sh EXAMPLES
 316 .Ss Calculating area of a circle with r=4.2 and rpshft=16
 317 .Bd -literal -offset indent
 318 u64q_t a, pi, r;
 319 char buf[32]
 320
 321 Q_INI(&a, 0, 0, 16);
 322 Q_INI(&pi, 3, 14159, 16);
 323 Q_INI(&r, 4, 2, 16);
 324
 325 Q_QCLONEQ(&a, r);
 326 Q_QMULQ(&a, r);
 327 Q_QMULQ(&a, pi);
 328
 329 Q_TOSTR(a, -1, 10, buf, sizeof(buf));
 330 printf("%s\\n", buf);
 331 .Ed
 332 .Ss Debugging
 333 Declare a Q20.8 s32q_t number
 334 .Fa s32 ,
 335 initialise it with the fixed-point value for 5/3, and render a debugging
 336 representation of the variable
 337 .Pq including its full precision decimal C-string representation ,
 338 to the console:
 339 .Bd -literal -offset indent
 340 s32q_t s32;
 341 Q_INI(&s32, 0, 0, 8);
 342 Q_QFRACI(&s32, 5, 3);
 343 char buf[Q_MAXSTRLEN(s32, 10)];
 344 Q_TOSTR(s32, -1, 10, buf, sizeof(buf));
 345 printf(Q_DEBUG(s32, "", "\\n\\ttostr=%s\\n\\n", 0), buf);
 346 .Ed
 347 .Pp
 348 The 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, \\
 352 imax=0xfffff
 353         qraw=0x00000d53
 354         imask=0x7ffff800, fmask=0x000007f8, cmask=0x00000007, \\
 355 ifmask=0x7ffffff8
 356         iraw=0x00000800, iabsval=0x1, ival=0x1
 357         fraw=0x00000550, fabsval=0xaa, fval=0xaa
 358         tostr=1.664
 359 .Ed
 360 .Pp
 361 Note: The
 362 .Qq \e
 363 present in the rendered output above indicates a manual line break inserted to
 364 keep 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
 379 The
 380 .Nm
 381 functions first appeared in
 382 .Fx 13.0 .
 383 .Sh AUTHORS
 384 .An -nosplit
 385 The
 386 .Nm
 387 functions and this manual page were written by
 388 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
 389 and sponsored by Netflix, Inc.