Copyright 2008, William Hart This file is part of the MPIR Library. The MPIR Library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. The MPIR Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with the MPIR Library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. MACROS in gmp_impl.h =========================================== LIKELY(cond) - branch hint (likely), e.g. if LIKELY(x > 0).... UNLIKELY(cond) - branch hint (unlikely) ABS(x) - absolute value of x MIN(x, y) - minimum of x and y (operands may be signed or unsigned) MAX(x, y) - maximum of x and y numberof(x) - assumes x is a pointer to an array, returns the number of elements of the array that fit into a type the same size as a pointer (??) SIZ(z) - _mp_size field of z ABSIZ(z) - abs val of SIZ(z) PTR(z) - _mp_d field of z LIMBS(z) - same as PTR(z) EXP(z) - _mp_exp field of x PREC(x) - _mp_prec field of x ALLOC(x) - _mp_alloc field of x MP_LIMB_T_SWAP(x, y) - swap two mp_limb_t's MP_SIZE_T_SWAP(x, y) - swap two mp_size_t's MP_PTR_SWAP(x, y) - swap two mp_ptr's MP_SRCPTR_SWAP(x, y) - swap two mp_srcptr's MPN_PTR_SWAP(xp, xs, yp, ys) - swap {xp, xs} and {yp, ys} MPN_SRCPTR_SWAP(xp, xs, yp, ys) - swap {xp, xs} and {yp, ys} MPZ_PTR_SWAP(x, y) - swap two mpz_ptr's MPZ_SRCPTR_SWAP(x, y) - swap two mpz_srcptr's MPN_CMP(result, xp, yp, size) - compare {xp, size} with {yp, size} and set result to -1, 0, 1, size may be zero MPN_COPY_INCR(dst, src, size) - copy size limbs from src to dst incrementing memory locations throughout copy (i.e. src must come after dst if they overlap) size == 0 is allowed MPN_COPY_DECR(dst, src, size) - as for MPN_COPY_INCR except ptrs are decremented (i.e. src must come before dst if they overlap) MPN_COPY(dst, src, size) - copy size limbs from src to dst which must be same or separate MPN_REVERSE(dst, src, size) - set {dst, size} to the limbs of {src, size} in reverse order MPN_ZERO(dst, n) - set n limbs at dst to zero mpn_com_n(dst, src, size) - set {dst, size} to the complement of {src, size} mpn_and_n(dst, src1, src2, n) - set {dst, n} to {src1, n} & {src2, n} mpn_andn_n(dst, src1, src2, n) - set {dst, n} to {src1, n} & ~{src2, n} mpn_nand_n(dst, src1, src2, n) - set {dst, n} to {src1, n} nand {src2, n} mpn_ior_n(dst, src1, src2, n) - set {dst, n} to {src1, n} | {src2, n} mpn_iorn_n(dst, src1, src2, n) - set {dst, n} to {src1, n} | ~{src2, n} mpn_nior_n(dst, src1, src2, n) - set {dst, n} to {src1, n} nor {src2, n} mpn_xor_n(dst, src1, src2, n) - set {dst, n} to {src1, n} xor {src2, n} mpn_xnor_n(dst, src1, src2, n) - set {dst, n} to {src1, n} xnor {src2, n} MPN_NORMALIZE(dst, nlimbs) - normalise the mpn at dst, i.e. set nlimbs to number of non-zero limbs MPN_NORMALIZE_NOT_ZERO(dst, nlimbs) - normalise the mpn at dst, i.e. set nlimbs to number of non-zero limbs, assuming it isn't zero MPN_STRIP_LOW_ZEROS_NOT_ZERO(ptr, size, low) - strip least sig zero limbs from {ptr, size} by incr ptr and decr size, low should be ptr[0] and will be set to new ptr[0] upon return, function assumes {ptr, size} is not zero MPN_OVERLAP_P(xp, xsize, yp, ysize) - nonzero if the given mpns overlap MPN_SAME_OR_INCR2_P(dst, dsize, src, ssize) - nonzero if ok for incr algorithm MPN_SAME_OR_INCR_P(dst, src, size) - as for INCR2 variant, but same sizes MPN_SAME_OR_DECR2_P(dst, dsize, src, ssize) - nonzero if ok for decr algorithm MPN_SAME_OR_DECR_P(dst, src, size) - as for DECR2 variant, but same sizes MPN_LOGOPS_N_INLINE(dst, src1, src2, n, operation) - do n operations involving any of src1, src2, dst MPN_INCR_U(ptr, size, incr) - {ptr, size} += n expect no carry MPN_DECR_U(ptr, size, incr) - {ptr, size} -= n expect no carry mpn_incr_u(ptr, incr) - {ptr, size} += n carry possible mpn_decr_u(ptr, incr) - {ptr, size} -= n carry possible MPN_SIZEINBASE(result, ptr, size, base) - set result to number of numerals {ptr, size} has, in the given base. For power of 2 bases it is exact, otherwise it may sometimes be one too big - this is done for efficiency so not all limbs have to be checked MPN_SIZEINBASE_16(result, ptr, size, base) - special optimisation for base 16 MPN_SET_UI(zp, zn, u) - set {zp, zn} to the given ui, where zn must be big enough to accomodate a ulong MPN_DIVREM_OR_PREINV_DIVREM_1(qp,xsize,ap,size,d,dinv,shift) - set {qp, xsize} to {ap, size} divided by d with dinv an inverse of d and shift the number of bits d has to be shifted, only uses the preinv if this will be better on this arch MPN_MOD_OR_PREINV_MOD_1(ap,size,d,dinv) - return {ap, size} mod d with d an inverse of d - using preinv only if better on this arch MPN_DIVREM_OR_DIVEXACT_1(dst, src, size, divisor) - divide {src, size} by divisor assuming no remainder if this will be faster MPN_DIVREM_OR_DIVEXACT_1(dst, src, size, divisor) - mpn_modexact_1_odd or mpn_mod_1 depending on which is faster on this arch MPN_BSWAP(dst, src, size) - byte swap limbs from {src,size} and store at {dst,size} MPN_BSWAP_REVERSE(dst, src, size) - byte swap limbs from {dst,size} and store in reverse order at {src,size} ADDC_LIMB(cout, w, x, y) - w = x + y with cout set to 1 for carry from add ADDC_LIMB(cout, w, x, y) - w = x - y with cout set to 1 for borrow from sub BITS_TO_LIMBS(n) - number of limbs required to store the given number of bits LIMB_HIGHBIT_TO_MASK(n) - platform independently set a mask to 0 or 0xFF..FF depending on whether high bit of n is 0 or 1 LOW_ZEROS_MASK(n) - bit mask of all the least significant zero bits of n ULONG_PARITY(p, n) - sets p to 1 if the number of 1 bits in n is odd NEG_MOD(r, a, d) - r = -a mod d (a >= d is allowed) may return r > d (all limbs) BSWAP_LIMB(dst, src) - reverse bytes in a limb BSWAP_LIMB_FETCH(dst, src) - set dst to the reverse of the bytes in the limb pointed to by src BSWAP_LIMB_STORE(dst, src) - set limb pointed to by dst to the reverse of the bytes in src popc_limb(result, input) - population count of a limb (fast!!) POW2_P(n) - return 1 if n is a power of 2 (or 0) CNST_LIMB(C) - platform independent way of writing e.g. 1L if C was 1 say MEM_OVERLAP_P(xp, xsize, yp, ysize) - nonzero if given arrays of bytes overlap invert_limb(invxl, xl) - set invxl to the "inverse" of the limb xl for functions that take a precomputed "inverse" limb technically this isn't an inverse, but it sets invxl to the largest limb not larger than (2^(2*BITS_PER_MP_LIMB))/xl - (2^BITS_PER_MP_LIMB) and all 1's if this would give an overflow udiv_qrnnd_preinv1(q, r, nh, nl, d, di) - nh, nl divided by d with di an "inverse" of d. The most significant bit of d has to be set udiv_qrnnd_preinv2(q, r, nh, nl, d, di) - as for preinv1 but branch free udiv_qrnnd_preinv2gen(q, r, nh, nl, d, di, dnorm, lgup) - as for preinv2 but for any d. dnorm is d shifted left so its msb is set, lgup is ceil_log2(d) modlimb_invert(inv, n) - true limb invert, i.e. inv*n == 1 mod 2^GMP_NUMB_BITS MODLIMB_INVERSE_3 - special case of modlimb_invert for n == 3 MPZ_TMP_INIT(X, NLIMBS) - Allocates a temporary mpz_t with space for NLIMBS, space will automatically be cleared out upon calling function's return MPZ_REALLOC(z, n) - reallocate mpz_t to n limbs if it doesn't have enough MPZ_EQUAL_1_P(z) - returns 1 if z is 1, otherwise 0 MPZ_FAKE_UI(z, zp, u) - creates a fake mpz_t z from an ui. zp must have space for an unsigned long ABOVE_THRESHOLD(size, thresh) - decide whether to use algorithm A or B depending whether size >= thresh. thresh == MP_SIZE_T_MAX means only ever use A, thresh == 0 means only ever use B BELOW_THRESHOLD(size, thresh) - !ABOVE_THRESHOLD Macro constants defined in gmp_impl.h =========================================== BYTES_PER_MP_LIMB - bytes per limb BITS_PER_MP_LIMB - bits per limb BITS_PER_ULONG - bits in an unsigned long LIMBS_PER_ULONG - number of limbs per unsigned long ULONG_MAX - unsigned long ~0 UINT_MAX - unsigned in ~0 USHRT_MAX - unsigned short ~0 MP_LIMB_T_MAX - mp_limb_t ~0 ULONG_HIGHBIT - unsigned long high bit set UINT_HIGHBIT - unsigned int high bit set USHRT_HIGHBIT - unsigned short high bit set GMP_LIMB_HIGHBIT - mp_limb_t high bit set LONG_MIN - smallest negative long LONG_MAX - largest positive long LONG_HIGHBIT - LONG_MIN INT_MIN - smallest negative int INT_MAX - largest positive int INT_HIGHBIT - INT_MIN SHRT_MIN - smallest negative short SHRT_MAX - largest positive short SHRT_HIGHBIT - SHRT_MIN MP_SIZE_T_MIN - smallest negative mp_size_t MP_SIZE_T_MAX - largest positive mp_size_t MP_EXP_T_MIN - smallest negative mp_exp_t MP_EXP_T_MAX - largest positive mp_exp_t GMP_NUMB_HIGHBIT - highest bit of a limb (not including nail bits) GMP_NUMB_CEIL_MAX_DIV3 - ceil(GMP_NUMB_MAX/3) GMP_NUMB_CEIL_2MAX_DIV3 - ceil(2*GMP_NUMB_MAX/3) PP - product of odd primes that will fit in a limb 3x5x... PP_FIRST_OMITTED - first odd prime omitted PP_INVERTED - inverse of PP Exception macros =========================================== GMP_ERROR(code) - raise exception with given code DIVIDE_BY_ZERO - raise divide by zero exception SQRT_OF_NEGATIVE - raise square root of negative exception Some types defined in gmp_impl.h =========================================== gmp_uint_least32_t - unsigned integer type with at least 32 bits Macros used in prototypes =========================================== ATTRIBUTE_CONST - function examines its arguments and returns a value but no memory is read or written to and function has no side effects ATTRIBUTE_NORETURN - signifies a function that won't ever return (supresses "code unreachable" compile time errors) ATTRIBUTE_MALLOC - function returns a pointer that can't alias anything, just as malloc does REGPARM_2_1(a,b,x) - reorder parameters to x,a,b so that x can be put in a reg REGPARM_3_1(a,b,c,x) - reorder parameters to x,a,b,c so that x can be put in a reg REGPARM_ATTR(n) - make parameter a register parameter Stack based memory manager ========================== Usage: TMP_DECL; TMP_MARK; ptr = TMP_ALLOC(bytes); TMP_FREE; This pushes handling of the stack allocation onto the calling function, which is what Pari does. It is faster than malloc and other stack based methods (!) A reentrant version is available by doing #define WANT_TMP_REENTRANT 1 Variants: TMP_SDECL, TMP_SMARK, TMP_SALLOC, TMP_SFREE - for small allocations (uses alloca if available) TMP_SDECL, TMP_SMARK, TMP_SALLOC, TMP_SFREE - for large allocations Note: TEMP_ALLOC calls TMP_SALLOC if bytes < 65536, otherwise TMP_BALLOC TMP_B/S/ALLOC_TYPE(n, type) - alloc space for n variables of the given type TMP_B/S/ALLOC_LIMBS(n) - alloc space for n limbs TMP_B/S/ALLOC_MP_PTRS(n) - alloc space for n mp_ptr's TMP_ALLOC_LIMBS_2(xp, xsize, yp, ysize) - makes two allocations at once (faster) Memory manager ========================== alloca(size) - allocate size bytes of space in the stack frame of the calling function. Space is automatically freed when the calling function returns __gmp_default_allocate(bytes) - alloc bytes using GMP default memory manager __gmp_default_reallocate(ptr,bytes) - realloc bytes using default memory manager __gmp_default_free(ptr, size) - free the size bytes allocated at ptr __GMP_ALLOCATE_FUNC_TYPE(n, type) - allocate space for n vars of given type using user defined memory management function __GMP_ALLOCATE_FUNC_LIMBS(n) - allocate n limbs, user defined mem man __GMP_REALLOCATE_FUNC_TYPE(p, old, new, type) - reallocate from old to new size user defined memory management function __GMP_REALLOCATE_FUNC_LIMBS(p, old, new) - realloc from old to new limbs, user defined mem man __GMP_FREE_FUNC_TYPE(n, type) - free space for n vars of given type using user defined memory management function __GMP_FREE_FUNC_LIMBS(n) - free n limbs, user defined mem man __GMP_REALLOCATE_FUNC_MAYBE(p, old, new) - reallocate, oldsize can equal newsize, user defined memory management function __GMP_REALLOCATE_FUNC_MAYBE_TYPE(p, old, new, type) - reallocate type, oldsize can equal newsize, user defined memory management function Assembly macros ==================================== ASM_L(name) - local label for a gcc asm block Debugging ==================================== MPZ_CHECK_FORMAT(z) - tries to check an mpz_t to see if it is broken MPZ_PROVOKE_REALLOC(z) - cause z to be realloc'd just because ou feel like it Misc ==================================== - Macros to do with the random generators - Lot's of undocumented mpn functions presumably defined in mpn/generic - macros for temp space required by kara and toom3 mul and sqr - space for fibonnacci functions, fn for n-th fib num from table and biggest n such that L_n fits in a long - default values for mullow, kara, toom, fft params and thresholds, div divide and conquer thresholds - piles of different assert macros - defines for longlong.h - stuff for handling doubles - lots of macros for v. fast computation of jacobi symbols - stuff for mpf's - stuff for formatted printing, reading