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