Date: Tue, 27 Aug 2019 11:46:23 +0000 (UTC) From: Edward Tomasz Napierala <trasz@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r351544 - in head: lib/msun/man share/man/man3 sys/sys tests/sys/sys Message-ID: <201908271146.x7RBkNAu079456@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@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@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@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@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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201908271146.x7RBkNAu079456>