svn commit: r351544 - in head: lib/msun/man share/man/man3 sys/sys tests/sys/sys
Edward Tomasz Napierala
trasz at FreeBSD.org
Tue Aug 27 11:46:25 UTC 2019
Author: trasz
Date: Tue Aug 27 11:46:22 2019
New Revision: 351544
URL: https://svnweb.freebsd.org/changeset/base/351544
Log:
Introduce <sys/qmath.h>, a fixed-point math library from Netflix.
This makes it possible to perform mathematical operations
on
fractional values without using floating point. It operates on Q
numbers, which are integer-sized, opaque structures initialized
to hold a chosen number of integer and fractional
bits.
For a general description of the Q number system, see the "Fixed Point
Representation & Fractional Math" whitepaper[1]; for the actual
API see the qmath(3) man page.
This is one of dependencies for the upcoming stats(3) framework[2]
that will be applied to the TCP stack in a later commit.
1. https://www.superkits.net/whitepapers/Fixed%20Point%20Representation%20&%20Fractional%20Math.pdf
2. https://reviews.freebsd.org/D20477
Reviewed by: bcr (man pages, earlier version), sef (earlier version)
Discussed with: cem, dteske, imp, lstewart
Sponsored By: Klara Inc, Netflix
Obtained from: Netflix
Differential Revision: https://reviews.freebsd.org/D20116
Added:
head/share/man/man3/Q_FRAWMASK.3 (contents, props changed)
head/share/man/man3/Q_IFRAWMASK.3 (contents, props changed)
head/share/man/man3/Q_INI.3 (contents, props changed)
head/share/man/man3/Q_IRAWMASK.3 (contents, props changed)
head/share/man/man3/Q_QABS.3 (contents, props changed)
head/share/man/man3/Q_QADDI.3 (contents, props changed)
head/share/man/man3/Q_QADDQ.3 (contents, props changed)
head/share/man/man3/Q_SIGNED.3 (contents, props changed)
head/share/man/man3/Q_SIGNSHFT.3 (contents, props changed)
head/share/man/man3/qmath.3 (contents, props changed)
head/sys/sys/qmath.h (contents, props changed)
head/tests/sys/sys/qmath_test.c (contents, props changed)
Modified:
head/lib/msun/man/math.3
head/share/man/man3/Makefile
head/tests/sys/sys/Makefile
Modified: head/lib/msun/man/math.3
==============================================================================
--- head/lib/msun/man/math.3 Tue Aug 27 09:20:01 2019 (r351543)
+++ head/lib/msun/man/math.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -217,6 +217,7 @@ rarely, and then only in very-close-to-halfway cases.
.Xr complex 3 ,
.Xr fenv 3 ,
.Xr ieee 3 ,
+.Xr qmath 3 ,
.Xr tgmath 3
.Sh HISTORY
A math library with many of the present functions appeared in
Modified: head/share/man/man3/Makefile
==============================================================================
--- head/share/man/man3/Makefile Tue Aug 27 09:20:01 2019 (r351543)
+++ head/share/man/man3/Makefile Tue Aug 27 11:46:22 2019 (r351544)
@@ -13,6 +13,16 @@ MAN= assert.3 \
makedev.3 \
offsetof.3 \
${PTHREAD_MAN} \
+ Q_FRAWMASK.3 \
+ Q_IFRAWMASK.3 \
+ Q_INI.3 \
+ Q_IRAWMASK.3 \
+ Q_QABS.3 \
+ Q_QADDI.3 \
+ Q_QADDQ.3 \
+ Q_SIGNED.3 \
+ Q_SIGNSHFT.3 \
+ qmath.3 \
queue.3 \
sigevent.3 \
siginfo.3 \
@@ -72,6 +82,68 @@ MLINKS+= fpgetround.3 fpgetmask.3 \
MLINKS+= makedev.3 major.3 \
makedev.3 minor.3
MLINKS+= ${PTHREAD_MLINKS}
+MLINKS+= Q_FRAWMASK.3 Q_GFRAW.3 \
+ Q_FRAWMASK.3 Q_GFABSVAL.3 \
+ Q_FRAWMASK.3 Q_GFVAL.3 \
+ Q_FRAWMASK.3 Q_SFVAL.3
+MLINKS+= Q_IFRAWMASK.3 Q_IFVALIMASK.3 \
+ Q_IFRAWMASK.3 Q_IFVALFMASK.3 \
+ Q_IFRAWMASK.3 Q_GIFRAW.3 \
+ Q_IFRAWMASK.3 Q_GIFABSVAL.3 \
+ Q_IFRAWMASK.3 Q_GIFVAL.3 \
+ Q_IFRAWMASK.3 Q_SIFVAL.3 \
+ Q_IFRAWMASK.3 Q_SIFVALS.3
+MLINKS+= Q_INI.3 Q_NCBITS.3 \
+ Q_INI.3 Q_BT.3 \
+ Q_INI.3 Q_TC.3 \
+ Q_INI.3 Q_NTBITS.3 \
+ Q_INI.3 Q_NFCBITS.3 \
+ Q_INI.3 Q_MAXNFBITS.3 \
+ Q_INI.3 Q_NFBITS.3 \
+ Q_INI.3 Q_NIBITS.3 \
+ Q_INI.3 Q_RPSHFT.3 \
+ Q_INI.3 Q_ABS.3 \
+ Q_INI.3 Q_MAXSTRLEN.3 \
+ Q_INI.3 Q_TOSTR.3 \
+ Q_INI.3 Q_SHL.3 \
+ Q_INI.3 Q_SHR.3 \
+ Q_INI.3 Q_DEBUG.3 \
+ Q_INI.3 Q_DFV2BFV.3
+MLINKS+= Q_IRAWMASK.3 Q_GIRAW.3 \
+ Q_IRAWMASK.3 Q_GIABSVAL.3 \
+ Q_IRAWMASK.3 Q_GIVAL.3 \
+ Q_IRAWMASK.3 Q_SIVAL.3
+MLINKS+= Q_QABS.3 Q_Q2D.3 \
+ Q_QABS.3 Q_Q2F.3
+MLINKS+= Q_QADDI.3 Q_QDIVI.3 \
+ Q_QADDI.3 Q_QMULI.3 \
+ Q_QADDI.3 Q_QSUBI.3 \
+ Q_QADDI.3 Q_QFRACI.3 \
+ Q_QADDI.3 Q_QCPYVALI.3
+MLINKS+= Q_QADDQ.3 Q_QDIVQ.3 \
+ Q_QADDQ.3 Q_QMULQ.3 \
+ Q_QADDQ.3 Q_QSUBQ.3 \
+ Q_QADDQ.3 Q_NORMPREC.3 \
+ Q_QADDQ.3 Q_QMAXQ.3 \
+ Q_QADDQ.3 Q_QMINQ.3 \
+ Q_QADDQ.3 Q_QCLONEQ.3 \
+ Q_QADDQ.3 Q_QCPYVALQ.3
+MLINKS+= Q_SIGNED.3 Q_LTZ.3 \
+ Q_SIGNED.3 Q_PRECEQ.3 \
+ Q_SIGNED.3 Q_QLTQ.3 \
+ Q_SIGNED.3 Q_QLEQ.3 \
+ Q_SIGNED.3 Q_QGTQ.3 \
+ Q_SIGNED.3 Q_QGEQ.3 \
+ Q_SIGNED.3 Q_QEQ.3 \
+ Q_SIGNED.3 Q_QNEQ.3 \
+ Q_SIGNED.3 Q_OFLOW.3 \
+ Q_SIGNED.3 Q_RELPREC.3
+MLINKS+= Q_SIGNSHFT.3 Q_SSIGN.3 \
+ Q_SIGNSHFT.3 Q_CRAWMASK.3 \
+ Q_SIGNSHFT.3 Q_SRAWMASK.3 \
+ Q_SIGNSHFT.3 Q_GCRAW.3 \
+ Q_SIGNSHFT.3 Q_GCVAL.3 \
+ Q_SIGNSHFT.3 Q_SCVAL.3
MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \
queue.3 LIST_CLASS_HEAD.3 \
queue.3 LIST_EMPTY.3 \
Added: head/share/man/man3/Q_FRAWMASK.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_FRAWMASK.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,125 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_FRAWMASK 3
+.Os
+.Sh NAME
+.Nm Q_FRAWMASK ,
+.Nm Q_GFRAW ,
+.Nm Q_GFABSVAL ,
+.Nm Q_GFVAL ,
+.Nm Q_SFVAL
+.Nd fixed-point math functions which manipulate the fractional data bits
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft ITYPE
+.Fn Q_FRAWMASK "QTYPE q"
+.Ft ITYPE
+.Fn Q_GFRAW "QTYPE q"
+.Ft ITYPE
+.Fn Q_GFABSVAL "QTYPE q"
+.Ft ITYPE
+.Fn Q_GFVAL "QTYPE q"
+.Ft QTYPE
+.Fn Q_SFVAL "QTYPE q" "ITYPE fv"
+.Sh DESCRIPTION
+.Fn Q_FRAWMASK
+returns a
+.Fa q Ns -specific
+bit mask for
+.Fa q Ap s
+fractional data bits.
+.Pp
+.Fn Q_GFRAW
+returns
+.Fa q Ap s
+raw masked fractional data bits.
+.Pp
+.Fn Q_GFABSVAL
+and
+.Fn Q_GFVAL
+return the absolute and real values of
+.Fa q Ap s
+fractional data bits respectively.
+.Pp
+.Fn Q_SFVAL
+sets
+.Fa q Ap s
+fractional data bits to the value
+.Fa fv .
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+The
+.Fa ITYPE
+refers to the
+.Xr stdint 7
+integer types.
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_FRAWMASK ,
+.Fn Q_GFRAW ,
+.Fn Q_GFABSVAL
+and
+.Fn Q_GFVAL
+return their respective values as integers of the same underlying ITYPE as
+.Fa q .
+.Pp
+.Fn Q_SFVAL
+returns the value of
+.Fa q
+post set.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr qmath 3 ,
+.Xr stdint 7
+.Sh HISTORY
+The
+.Xr qmath 3
+functions first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr qmath 3
+functions and this manual page were written by
+.An Lawrence Stewart Aq Mt lstewart at FreeBSD.org
+and sponsored by Netflix, Inc.
Added: head/share/man/man3/Q_IFRAWMASK.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_IFRAWMASK.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,162 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_IFRAWMASK 3
+.Os
+.Sh NAME
+.Nm Q_IFRAWMASK ,
+.Nm Q_IFVALIMASK ,
+.Nm Q_IFVALFMASK ,
+.Nm Q_GIFRAW ,
+.Nm Q_GIFABSVAL ,
+.Nm Q_GIFVAL ,
+.Nm Q_SIFVAL ,
+.Nm Q_SIFVALS
+.Nd fixed-point math functions which manipulate the combined integer/fractional
+data bits
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft ITYPE
+.Fn Q_IFRAWMASK "QTYPE q"
+.Ft ITYPE
+.Fn Q_IFVALIMASK "QTYPE q"
+.Ft ITYPE
+.Fn Q_IFVALFMASK "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIFRAW "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIFABSVAL "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIFVAL "QTYPE q"
+.Ft QTYPE
+.Fn Q_SIFVAL "QTYPE q" "ITYPE ifv"
+.Ft QTYPE
+.Fn Q_SIFVALS "QTYPE q" "ITYPE iv" "ITYPE fv"
+.Sh DESCRIPTION
+.Fn Q_IFRAWMASK
+returns a
+.Fa q Ns -specific
+bit mask for
+.Fa q Ap s
+combined integer and fractional data bits.
+.Pp
+.Fn Q_IFVALIMASK
+and
+.Fn Q_IFVALFMASK
+return
+.Fa q Ns -specific
+bit masks for the integer and fractional bits of
+.Fa q Ap s
+combined integer and fractional data bits value, i.e., are applicable to the
+values returned by
+.Fn Q_GIFABSVAL
+and
+.Fn Q_GIFVAL .
+.Pp
+.Fn Q_GIFRAW
+returns
+.Fa q Ap s
+raw masked integer/fractional data bits.
+.Pp
+.Fn Q_GIFABSVAL
+and
+.Fn Q_GIFVAL
+return the absolute and real values of
+.Fa q Ap s
+integer/fractional data bits respectively.
+.Pp
+.Fn Q_SIFVAL
+sets
+.Fa q Ap s
+combined integer/fractional data bits to the value
+.Fa ifv ,
+whereas
+.Fn Q_SIFVALS
+independently sets
+.Fa q Ap s
+integer and fractional data bits to the separate values
+.Fa iv
+and
+.Fa fv .
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+The
+.Fa ITYPE
+refers to the
+.Xr stdint 7
+integer types.
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_IFRAWMASK ,
+.Fn Q_IFVALIMASK ,
+.Fn Q_IFVALFMASK ,
+.Fn Q_GIFABSVAL ,
+.Fn Q_GIFVAL ,
+.Fn Q_GIFRAW ,
+.Fn Q_GIFABSVAL
+and
+.Fn Q_GIFVAL
+return their respective values as integers of the same underlying ITYPE as
+.Fa q .
+.Pp
+.Fn Q_SIFVAL
+and
+.Fn Q_SIFVALS
+return the value of
+.Fa q
+post change.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr qmath 3 ,
+.Xr stdint 7
+.Sh HISTORY
+The
+.Xr qmath 3
+functions first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr qmath 3
+functions and this manual page were written by
+.An Lawrence Stewart Aq Mt lstewart at FreeBSD.org
+and sponsored by Netflix, Inc.
Added: head/share/man/man3/Q_INI.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_INI.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,261 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_INI 3
+.Os
+.Sh NAME
+.Nm Q_INI ,
+.Nm Q_NCBITS ,
+.Nm Q_BT ,
+.Nm Q_TC ,
+.Nm Q_NTBITS ,
+.Nm Q_NFCBITS ,
+.Nm Q_MAXNFBITS ,
+.Nm Q_NFBITS ,
+.Nm Q_NIBITS ,
+.Nm Q_RPSHFT ,
+.Nm Q_ABS ,
+.Nm Q_MAXSTRLEN ,
+.Nm Q_TOSTR ,
+.Nm Q_SHL ,
+.Nm Q_SHR ,
+.Nm Q_DEBUG
+.Nd fixed-point math miscellaneous functions/variables
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft QTYPE
+.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft"
+.Fd Q_NCBITS
+.Ft __typeof(q)
+.Fn Q_BT "QTYPE q"
+.Ft ITYPE
+.Fn Q_TC "QTYPE q" "ITYPE v"
+.Ft uint32_t
+.Fn Q_NTBITS "QTYPE q"
+.Ft uint32_t
+.Fn Q_NFCBITS "QTYPE q"
+.Ft uint32_t
+.Fn Q_MAXNFBITS "QTYPE q"
+.Ft uint32_t
+.Fn Q_NFBITS "QTYPE q"
+.Ft uint32_t
+.Fn Q_NIBITS "QTYPE q"
+.Ft uint32_t
+.Fn Q_RPSHFT "QTYPE q"
+.Ft NTYPE
+.Fn Q_ABS "NTYPE n"
+.Ft uint32_t
+.Fn Q_MAXSTRLEN "QTYPE q" "int base"
+.Ft char *
+.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen"
+.Ft ITYPE
+.Fn Q_SHL "QTYPE q" "ITYPE iv"
+.Ft ITYPE
+.Fn Q_SHR "QTYPE q" "ITYPE iv"
+.Ft char *, ...
+.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt"
+.Ft ITYPE
+.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits"
+.Sh DESCRIPTION
+.Fn Q_INI
+initialises a Q number with the supplied integral value
+.Fa iv
+and decimal fractional value
+.Fa dfv ,
+with appropriate control bits based on the requested radix shift point
+.Fa rpshft .
+.Fa dfv
+must be passed as a preprocessor literal to preserve leading zeroes.
+.Pp
+The
+.Dv Q_NCBITS
+defined constant specifies the number of reserved control bits, currently 3.
+.Pp
+.Fn Q_NTBITS ,
+.Fn Q_NFCBITS ,
+.Fn Q_MAXNFBITS ,
+.Fn Q_NFBITS
+and
+.Fn Q_NIBITS
+return the
+.Fa q Ns -specific
+count of total, control-encoded fractional, maximum fractional, effective
+fractional, and integer bits applicable to
+.Fa q
+respectively.
+.Pp
+.Fn Q_BT
+returns the C data type of
+.Fa q ,
+while
+.Fn Q_TC
+returns
+.Fa v
+type casted to the C data type of
+.Fa q .
+.Pp
+.Fn Q_RPSHFT
+returns the bit position of
+.Fa q Ap s
+binary radix point relative to bit zero.
+.Pp
+.Fn Q_ABS
+returns the absolute value of any standard numeric type
+.Pq that uses the MSB as a sign bit, but not Q numbers
+passed in as
+.Fa n .
+The function is signed/unsigned type safe.
+.Pp
+.Fn Q_SHL
+and
+.Fn Q_SHR
+return the integral value
+.Fa v
+left or right shifted by the appropriate amount for
+.Fa q .
+.Pp
+.Fn Q_MAXSTRLEN
+calculates the maximum number of characters that may be required to render the
+C-string representation of
+.Fa q
+with numeric base
+.Fa base .
+.Pp
+.Fn Q_TOSTR
+renders the C-string representation of
+.Fa q
+with numeric base
+.Fa base
+and fractional precision
+.Fa prec
+into
+.Fa s
+which has an available capacity of
+.Fa slen
+characters.
+.Fa base
+must be in range
+.Bq 2,16 .
+Specifying
+.Fa prec
+as -1 renders the number's fractional component with maximum precision.
+If
+.Fa slen
+is greater than zero but insufficient to hold the complete C-string, the '\\0'
+C-string terminator will be written to
+.Fa *s ,
+thereby returning a zero length C-string.
+.Pp
+.Fn Q_DEBUG
+returns a format string and associated data suitable for printf-like rendering
+of debugging information pertaining to
+.Fa q .
+If either
+.Fa prefmt
+and/or
+.Fa postfmt
+are specified, they are prepended and appended to the resulting format string
+respectively.
+The
+.Fa incfmt
+boolean specifies whether to include
+.Pq Vt true
+or exclude
+.Pq Vt false
+the raw format string itself in the debugging output.
+.Pp
+.Fn Q_DFV2BFV
+converts decimal fractional value
+.Fa dfv
+to its binary-encoded representation with
+.Fa nfbits
+of binary precision.
+.Fa dfv
+must be passed as a preprocessor literal to preserve leading zeroes.
+The returned value can be used to set a Q number's fractional bits, for example
+using
+.Fn Q_SFVAL .
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+The
+.Fa ITYPE
+refers to the
+.Xr stdint 7
+integer types.
+.Fa NTYPE
+is used to refer to any numeric type and is therefore a superset of
+.Fa QTYPE
+and
+.Fa ITYPE .
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_INI
+returns the initialised Q number which can be used to chain initialise
+additional Q numbers.
+.Pp
+.Fn Q_TOSTR
+returns a pointer to the '\\0' C-string terminator appended to
+.Fa s
+after the rendered numeric data, or NULL on buffer overflow.
+.Pp
+.Fn Q_DFV2BFV
+returns the binary-encoded representation of decimal fractional value
+.Fa dfv
+with
+.Fa nfbits
+of binary precision.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr qmath 3 ,
+.Xr stdint 7
+.Sh HISTORY
+The
+.Xr qmath 3
+functions first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr qmath 3
+functions and this manual page were written by
+.An Lawrence Stewart Aq Mt lstewart at FreeBSD.org
+and sponsored by Netflix, Inc.
Added: head/share/man/man3/Q_IRAWMASK.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_IRAWMASK.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,125 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_IRAWMASK 3
+.Os
+.Sh NAME
+.Nm Q_IRAWMASK ,
+.Nm Q_GIRAW ,
+.Nm Q_GIABSVAL ,
+.Nm Q_GIVAL ,
+.Nm Q_SIVAL
+.Nd fixed-point math functions which manipulate the integer data bits
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft ITYPE
+.Fn Q_IRAWMASK "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIRAW "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIABSVAL "QTYPE q"
+.Ft ITYPE
+.Fn Q_GIVAL "QTYPE q"
+.Ft QTYPE
+.Fn Q_SIVAL "QTYPE q" "ITYPE iv"
+.Sh DESCRIPTION
+.Fn Q_IRAWMASK
+returns a
+.Fa q Ns -specific
+bit mask for
+.Fa q Ap s
+integer data bits.
+.Pp
+.Fn Q_GIRAW
+returns
+.Fa q Ap s
+raw masked integer data bits.
+.Pp
+.Fn Q_GIABSVAL
+and
+.Fn Q_GIVAL
+return the absolute and real values of
+.Fa q Ap s
+integer data bits respectively.
+.Pp
+.Fn Q_SIVAL
+sets
+.Fa q Ap s
+integer data bits to the value
+.Fa iv .
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+The
+.Fa ITYPE
+refers to the
+.Xr stdint 7
+integer types.
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_IRAWMASK ,
+.Fn Q_GIRAW ,
+.Fn Q_GIABSVAL
+and
+.Fn Q_GIVAL
+return their respective values as integers of the same underlying ITYPE as
+.Fa q .
+.Pp
+.Fn Q_SIVAL
+returns the value of
+.Fa q
+post change.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr qmath 3 ,
+.Xr stdint 7
+.Sh HISTORY
+The
+.Xr qmath 3
+functions first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr qmath 3
+functions and this manual page were written by
+.An Lawrence Stewart Aq Mt lstewart at FreeBSD.org
+and sponsored by Netflix, Inc.
Added: head/share/man/man3/Q_QABS.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_QABS.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,101 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_QABS 3
+.Os
+.Sh NAME
+.Nm Q_QABS ,
+.Nm Q_Q2S ,
+.Nm Q_Q2F
+.Nd fixed-point math functions which operate on a single Q number
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft QTYPE
+.Fn Q_QABS "QTYPE q"
+.Ft double
+.Fn Q_Q2D "QTYPE q"
+.Ft float
+.Fn Q_Q2F "QTYPE q"
+.Sh DESCRIPTION
+The
+.Fn Q_QABS
+function returns an absolute value representation of
+.Fa q .
+.Pp
+The
+.Fn Q_Q2D
+and
+.Fn Q_Q2F
+functions return the double and float representations of
+.Fa q
+respectively.
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_QABS
+function returns a QTYPE that is identical to that of
+.Fa q .
+.Pp
+The
+.Fn Q_Q2D
+and
+.Fn Q_Q2F
+functions return the double and float representations of
+.Fa q
+respectively.
+.Sh SEE ALSO
+.Xr errno 2 ,
+.Xr qmath 3 ,
+.Xr stdint 7
+.Sh HISTORY
+The
+.Xr qmath 3
+functions first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr qmath 3
+functions and this manual page were written by
+.An Lawrence Stewart Aq Mt lstewart at FreeBSD.org
+and sponsored by Netflix, Inc.
Added: head/share/man/man3/Q_QADDI.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/Q_QADDI.3 Tue Aug 27 11:46:22 2019 (r351544)
@@ -0,0 +1,134 @@
+.\"
+.\" Copyright (c) 2018 Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions, and the following disclaimer,
+.\" without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 8, 2018
+.Dt Q_QADDI 3
+.Os
+.Sh NAME
+.Nm Q_QADDI ,
+.Nm Q_QDIVI ,
+.Nm Q_QMULI ,
+.Nm Q_QSUBI ,
+.Nm Q_QFRACI ,
+.Nm Q_QCPYVALI
+.Nd fixed-point math functions which apply integers to a Q number
+.Sh SYNOPSIS
+.In sys/qmath.h
+.Ft int
+.Fn Q_QADDI "QTYPE *a" "ITYPE b"
+.Ft int
+.Fn Q_QDIVI "QTYPE *a" "ITYPE b"
+.Ft int
+.Fn Q_QMULI "QTYPE *a" "ITYPE b"
+.Ft int
+.Fn Q_QSUBI "QTYPE *a" "ITYPE b"
+.Ft int
+.Fn Q_QFRACI "QTYPE *q" "ITYPE n" "ITYPE d"
+.Ft int
+.Fn Q_QCPYVALI "QTYPE *q" "ITYPE i"
+.Sh DESCRIPTION
+The
+.Fn Q_QADDI ,
+.Fn Q_QDIVI ,
+.Fn Q_QMULI
+and
+.Fn Q_QSUBI
+functions add, divide, multiply or subtract
+.Fa b
+to/by/from
+.Fa a
+respectively, storing the result in
+.Fa a .
+.Pp
+The
+.Fn Q_QFRACI
+function computes the fraction
+.Fa n
+divided by
+.Fa d
+and stores the fixed-point result in
+.Fa q .
+.Pp
+The
+.Fn Q_QCPYVALI
+function overwrites
+.Fa q Ap s
+integer and fractional bits with the Q representation of integer value
+.Fa i .
+.Pp
+All of those functions operate on
+the following data types:
+.Vt s8q_t ,
+.Vt u8q_t ,
+.Vt s16q_t ,
+.Vt u16q_t ,
+.Vt s32q_t ,
+.Vt u32q_t ,
+.Vt s64q_t ,
+and
+.Vt u64q_t ,
+which are referred to generically as
+.Fa QTYPE .
+The
+.Fa ITYPE
+refers to the
+.Xr stdint 7
+integer types.
+.Pp
+For more details, see
+.Xr qmath 3 .
+.Sh RETURN VALUES
+.Fn Q_QADDI ,
+.Fn Q_QDIVI ,
+.Fn Q_QMULI ,
+.Fn Q_QSUBI ,
+.Fn Q_QFRACI
+and
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-head
mailing list