07a2b481 (kx 2024-12-28 08:20:38 +0300 1) .\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su)
07a2b481 (kx 2024-12-28 08:20:38 +0300 2) .\"
07a2b481 (kx 2024-12-28 08:20:38 +0300 3) .\"
07a2b481 (kx 2024-12-28 08:20:38 +0300 4) .TH LIBMPU 7 "December 27, 2024" "libmpu" "libmpu Programmer's Manual"
07a2b481 (kx 2024-12-28 08:20:38 +0300 5) .SH NAME
07a2b481 (kx 2024-12-28 08:20:38 +0300 6) libmpu \- Math Processor Unit Library (libmpu).
07a2b481 (kx 2024-12-28 08:20:38 +0300 7) .SH DESCRIPTION
07a2b481 (kx 2024-12-28 08:20:38 +0300 8) The library is designed as a processor emulator with a set of registers and flags that are set according
07a2b481 (kx 2024-12-28 08:20:38 +0300 9) to the results of the operations performed. The set of integer functions contains arithmetic and logical
07a2b481 (kx 2024-12-28 08:20:38 +0300 10) operations, as well as all types of shift operations. Basic trigonometric functions are implemented for
07a2b481 (kx 2024-12-28 08:20:38 +0300 11) real and complex numbers.
07a2b481 (kx 2024-12-28 08:20:38 +0300 12) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 13) Bit capacity is limited to \fB65536\fP bits for arithmetic operations and \fB16384\fP bits
07a2b481 (kx 2024-12-28 08:20:38 +0300 14) for trigonometry. The limitations are due to the order of the approximation series.
07a2b481 (kx 2024-12-28 08:20:38 +0300 15) .SH Data formats
07a2b481 (kx 2024-12-28 08:20:38 +0300 16) The library supports integer, real and complex types. Variables are stored in byte arrays.
07a2b481 (kx 2024-12-28 08:20:38 +0300 17) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 18) .SS Integer numbers
07a2b481 (kx 2024-12-28 08:20:38 +0300 19) The \fBlibmpu.h\fP header file defines constants that represent the number of bytes
07a2b481 (kx 2024-12-28 08:20:38 +0300 20) to store integer variables:
07a2b481 (kx 2024-12-28 08:20:38 +0300 21) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 22) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 23) #define NB_I8 1
07a2b481 (kx 2024-12-28 08:20:38 +0300 24) #define NB_I16 2
07a2b481 (kx 2024-12-28 08:20:38 +0300 25) #define NB_I32 4
07a2b481 (kx 2024-12-28 08:20:38 +0300 26) #define NB_I64 8
07a2b481 (kx 2024-12-28 08:20:38 +0300 27) #define NB_I128 16
07a2b481 (kx 2024-12-28 08:20:38 +0300 28) #define NB_I256 32
07a2b481 (kx 2024-12-28 08:20:38 +0300 29) #define NB_I512 64
07a2b481 (kx 2024-12-28 08:20:38 +0300 30) #define NB_I1024 128
07a2b481 (kx 2024-12-28 08:20:38 +0300 31) #define NB_I2048 256
07a2b481 (kx 2024-12-28 08:20:38 +0300 32) #define NB_I4096 512
07a2b481 (kx 2024-12-28 08:20:38 +0300 33) #define NB_I8192 1024
07a2b481 (kx 2024-12-28 08:20:38 +0300 34) #define NB_I16384 2048
07a2b481 (kx 2024-12-28 08:20:38 +0300 35) #define NB_I32768 4096
07a2b481 (kx 2024-12-28 08:20:38 +0300 36) #define NB_I65536 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 37) #define NB_I_MAX 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 38) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 39) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 40) These constants can be used as the value of the \fBnb\fP argument for integer operations.
07a2b481 (kx 2024-12-28 08:20:38 +0300 41) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 42) In systems with \fBbig\-endian\fP byte order, the high byte of a number is stored at the
07a2b481 (kx 2024-12-28 08:20:38 +0300 43) lowest memory address and the low byte at the highest memory address. In a system with
07a2b481 (kx 2024-12-28 08:20:38 +0300 44) \fBlittle\-endian\fP byte order, on the contrary, the smallest byte is stored at the
07a2b481 (kx 2024-12-28 08:20:38 +0300 45) smallest address.
07a2b481 (kx 2024-12-28 08:20:38 +0300 46) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 47) The following diagram shows the placement of the integer depending on the machine
07a2b481 (kx 2024-12-28 08:20:38 +0300 48) architecture:
07a2b481 (kx 2024-12-28 08:20:38 +0300 49) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 50) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 51) if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 52) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 53) [NB-1], . . . , [0];
07a2b481 (kx 2024-12-28 08:20:38 +0300 54) ┌─────────────────────────── . . . ───────────────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 55) │ high low │
07a2b481 (kx 2024-12-28 08:20:38 +0300 56) └─────────────────────────── . . . ───────────────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 57) ^Sign bit
07a2b481 (kx 2024-12-28 08:20:38 +0300 58) size: NB.
07a2b481 (kx 2024-12-28 08:20:38 +0300 59) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 60)
07a2b481 (kx 2024-12-28 08:20:38 +0300 61) if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 62) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 63) [0], . . . , [NB-1];
07a2b481 (kx 2024-12-28 08:20:38 +0300 64) ┌─────────────────────────── . . . ───────────────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 65) │ high low │
07a2b481 (kx 2024-12-28 08:20:38 +0300 66) └─────────────────────────── . . . ───────────────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 67) ^Sign bit
07a2b481 (kx 2024-12-28 08:20:38 +0300 68) size: NB.
07a2b481 (kx 2024-12-28 08:20:38 +0300 69) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 70) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 71) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 72) Here, the symbol \fBNB\fP — denotes the number of bytes of the number.
07a2b481 (kx 2024-12-28 08:20:38 +0300 73) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 74) To represent integer variables, the user can independently create byte arrays in any
07a2b481 (kx 2024-12-28 08:20:38 +0300 75) of the following ways:
07a2b481 (kx 2024-12-28 08:20:38 +0300 76) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 77) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 78) __mpu_byte_t a[NB_I65536];
07a2b481 (kx 2024-12-28 08:20:38 +0300 79) mpu_int a[NB_I65536];
07a2b481 (kx 2024-12-28 08:20:38 +0300 80)
07a2b481 (kx 2024-12-28 08:20:38 +0300 81) mpu_int *a = (mpu_int *)malloc( NB_I65536 * sizeof(__mpu_byte_t) );
07a2b481 (kx 2024-12-28 08:20:38 +0300 82) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 83) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 84) and also use, predefined in \fBlibmpu.h\fP, data types that explicitly talk
07a2b481 (kx 2024-12-28 08:20:38 +0300 85) about dimensionality:
07a2b481 (kx 2024-12-28 08:20:38 +0300 86) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 87) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 88) mpu_int4096_t a;
07a2b481 (kx 2024-12-28 08:20:38 +0300 89) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 90) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 91) Integers can be considered both signed and unsigned. Signed variables are represented in two’s
07a2b481 (kx 2024-12-28 08:20:38 +0300 92) complement form for convenience of operations with them. Below is a table of some values of an
07a2b481 (kx 2024-12-28 08:20:38 +0300 93) 8\-bit variable in two’s complement form.
07a2b481 (kx 2024-12-28 08:20:38 +0300 94) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 95) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 96) ┌────────────────┬─────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 97) │ Decimal │ Binary │
07a2b481 (kx 2024-12-28 08:20:38 +0300 98) │ representation │ representation │
07a2b481 (kx 2024-12-28 08:20:38 +0300 99) ├────────────────┼─────────────────┤
07a2b481 (kx 2024-12-28 08:20:38 +0300 100) │ 127 │ 0111 1111 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 101) │ 3 │ 0000 0011 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 102) │ 2 │ 0000 0010 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 103) │ 1 │ 0000 0001 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 104) │ 0 │ 0000 0000 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 105) │ -1 │ 1111 1111 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 106) │ -2 │ 1111 1110 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 107) │ -3 │ 1111 1101 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 108) │ -127 │ 1000 0001 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 109) │ -128 │ 1000 0000 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 110) └────────────────┴─────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 111) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 112) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 113) .SS Real numbers
07a2b481 (kx 2024-12-28 08:20:38 +0300 114) Real variables, just like integer variables, are stored as byte arrays. The \fBlibmpu.h\fP
07a2b481 (kx 2024-12-28 08:20:38 +0300 115) header file defines constants that represent the number of bytes for storing real variables:
07a2b481 (kx 2024-12-28 08:20:38 +0300 116) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 117) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 118) #define NB_R32 4
07a2b481 (kx 2024-12-28 08:20:38 +0300 119) #define NB_R64 8
07a2b481 (kx 2024-12-28 08:20:38 +0300 120) #define NB_R128 16
07a2b481 (kx 2024-12-28 08:20:38 +0300 121) #define NB_R256 32
07a2b481 (kx 2024-12-28 08:20:38 +0300 122) #define NB_R512 64
07a2b481 (kx 2024-12-28 08:20:38 +0300 123) #define NB_R1024 128
07a2b481 (kx 2024-12-28 08:20:38 +0300 124) #define NB_R2048 256
07a2b481 (kx 2024-12-28 08:20:38 +0300 125) #define NB_R4096 512
07a2b481 (kx 2024-12-28 08:20:38 +0300 126) #define NB_R8192 1024
07a2b481 (kx 2024-12-28 08:20:38 +0300 127) #define NB_R16384 2048
07a2b481 (kx 2024-12-28 08:20:38 +0300 128) #define NB_R32768 4096
07a2b481 (kx 2024-12-28 08:20:38 +0300 129) #define NB_R65536 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 130) #define NB_R_MAX 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 131) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 132) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 133) These constants can be used as the value of the \fBnb\fP argument for operations
07a2b481 (kx 2024-12-28 08:20:38 +0300 134) with real numbers.
07a2b481 (kx 2024-12-28 08:20:38 +0300 135) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 136) Real numbers have two fields: the shifted exponent and the mantissa. The integer
07a2b481 (kx 2024-12-28 08:20:38 +0300 137) unit bit is implicit. The sign is located in the high bit of the number.
07a2b481 (kx 2024-12-28 08:20:38 +0300 138) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 139) The following diagram shows the placement of a real number depending on the
07a2b481 (kx 2024-12-28 08:20:38 +0300 140) architecture of the machine:
07a2b481 (kx 2024-12-28 08:20:38 +0300 141) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 142) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 143) if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 144) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 145) [NB-1], . . . , [nS] │ [nS-1], . . . , [0];
07a2b481 (kx 2024-12-28 08:20:38 +0300 146) ┌────── . . . ───────┬─────────────── . . . ──────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 147) │ Sign + Exponent │ Significand │
07a2b481 (kx 2024-12-28 08:20:38 +0300 148) └────── . . . ───────┴─────────────── . . . ──────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 149) ^Sign bit ^(1. - implicit)
07a2b481 (kx 2024-12-28 08:20:38 +0300 150) size: nE nS.
07a2b481 (kx 2024-12-28 08:20:38 +0300 151) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 152)
07a2b481 (kx 2024-12-28 08:20:38 +0300 153) if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 154) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 155) [0], . . . , [nE-1] │ [nE], . . . , [NB-1];
07a2b481 (kx 2024-12-28 08:20:38 +0300 156) ┌────── . . . ───────┬─────────────── . . . ──────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 157) │ Sign + Exponent │ Significand │
07a2b481 (kx 2024-12-28 08:20:38 +0300 158) └────── . . . ───────┴─────────────── . . . ──────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 159) ^Sign bit ^(1. - implicit)
07a2b481 (kx 2024-12-28 08:20:38 +0300 160) size: nE nS.
07a2b481 (kx 2024-12-28 08:20:38 +0300 161) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 162) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 163) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 164) Here, the symbols \fBnE\fP and \fBnS\fP denote the number of bytes of the exponent and the
07a2b481 (kx 2024-12-28 08:20:38 +0300 165) number of bytes of the mantissa, respectively.
07a2b481 (kx 2024-12-28 08:20:38 +0300 166) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 167) The number of bits allocated to represent the sign, exponent and mantissa is distributed
07a2b481 (kx 2024-12-28 08:20:38 +0300 168) as follows:
07a2b481 (kx 2024-12-28 08:20:38 +0300 169) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 170) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 171) ┌───────────────────────┬───────────────────┬─────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 172) │ Total number of bits │ (Sign + Exponent) │ Significand │
07a2b481 (kx 2024-12-28 08:20:38 +0300 173) ├───────────────────────┼───────────────────┼─────────────┤
07a2b481 (kx 2024-12-28 08:20:38 +0300 174) │ 32 │ 1 + 8 + │ 23 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 175) │ 64 │ 1 + 11 + │ 52 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 176) │ 128 │ 1 + 31 + │ 96 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 177) │ 256 │ 1 + 31 + │ 224 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 178) │ 512 │ 1 + 63 + │ 448 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 179) │ 1024 │ 1 + 63 + │ 960 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 180) │ 2048 │ 1 + 127 + │ 1920 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 181) │ 4096 │ 1 + 127 + │ 3968 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 182) │ 8192 │ 1 + 255 + │ 7936 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 183) │ 16384 │ 1 + 255 + │ 16128 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 184) │ 32768 │ 1 + 511 + │ 32256 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 185) │ 65536 │ 1 + 511 + │ 65024 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 186) └───────────────────────┴───────────────────┴─────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 187) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 188) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 189) The 32\- and 64\-bit number formats are fully consistent with the \fBIEEE\fP (Institute
07a2b481 (kx 2024-12-28 08:20:38 +0300 190) of Electrical and Electronics Engineers) format.
07a2b481 (kx 2024-12-28 08:20:38 +0300 191) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 192) For convenience in declaring real\-type variables, the \fBlibmpu.h\fP header file
07a2b481 (kx 2024-12-28 08:20:38 +0300 193) defines the corresponding data types, the application of which may look, for example,
07a2b481 (kx 2024-12-28 08:20:38 +0300 194) as follows:
07a2b481 (kx 2024-12-28 08:20:38 +0300 195) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 196) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 197) mpu_real16384_t a, b;
07a2b481 (kx 2024-12-28 08:20:38 +0300 198) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 199) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 200) .SS Not\-a\-Numbers
07a2b481 (kx 2024-12-28 08:20:38 +0300 201) To enhance computational capabilities, the floating\-point number format provides
07a2b481 (kx 2024-12-28 08:20:38 +0300 202) several special values along with the usual real numbers. These have some meaning
07a2b481 (kx 2024-12-28 08:20:38 +0300 203) and provide important information about the algorithms and operations in which these
07a2b481 (kx 2024-12-28 08:20:38 +0300 204) values appear. Special values include real numbers with normalization violations,
07a2b481 (kx 2024-12-28 08:20:38 +0300 205) indeterminacy, zeros, infinities, and non\-numbers, shown in the following table.
07a2b481 (kx 2024-12-28 08:20:38 +0300 206) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 207) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 208) ┌──────┬───────────────────┬───────────────────┬──────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 209) │ Sign │ Exponent │ Significand │ comments │
07a2b481 (kx 2024-12-28 08:20:38 +0300 210) ├──────┼───────────────────┼───────────────────┼──────────────────┤
07a2b481 (kx 2024-12-28 08:20:38 +0300 211) │ S │ 1111 . . . 1111 │ 0000 . . . 0000 │ +/- inf │
07a2b481 (kx 2024-12-28 08:20:38 +0300 212) │ S │ 0000 . . . 0000 │ 0000 . . . 0000 │ +/- 0 │
07a2b481 (kx 2024-12-28 08:20:38 +0300 213) │ 1 │ 1111 . . . 1111 │ 1000 . . . 0000 │ - ind │
07a2b481 (kx 2024-12-28 08:20:38 +0300 214) │ S │ 1111 . . . 1111 │ 0000 . . . 0001 │ +/- NaN (min) │
07a2b481 (kx 2024-12-28 08:20:38 +0300 215) │ S │ 1111 . . . 1111 │ 1111 . . . 1111 │ +/- NaN (max) │
07a2b481 (kx 2024-12-28 08:20:38 +0300 216) └──────┴───────────────────┴───────────────────┴──────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 217)
07a2b481 (kx 2024-12-28 08:20:38 +0300 218) Здесь:
07a2b481 (kx 2024-12-28 08:20:38 +0300 219) +/- inf - +/- infinity;
07a2b481 (kx 2024-12-28 08:20:38 +0300 220) +/- 0 - +/- signed zero;
07a2b481 (kx 2024-12-28 08:20:38 +0300 221) - ind - indeterminacy;
07a2b481 (kx 2024-12-28 08:20:38 +0300 222) +/- NaN (min) - +/- minimal Not-a-Number;
07a2b481 (kx 2024-12-28 08:20:38 +0300 223) +/- NaN (max) - +/- maximal Not-a-Number.
07a2b481 (kx 2024-12-28 08:20:38 +0300 224) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 225) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 226) Denormalized numbers:
07a2b481 (kx 2024-12-28 08:20:38 +0300 227) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 228) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 229) ┌──────┬───────────────────┬───────────────────┬──────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 230) │ Sign │ Exponent │ Significand │ comments │
07a2b481 (kx 2024-12-28 08:20:38 +0300 231) ├──────┼───────────────────┼───────────────────┼──────────────────┤
07a2b481 (kx 2024-12-28 08:20:38 +0300 232) │ S │ 0000 . . . 0000 │ 0000 . . . 0001 │ +/- min │
07a2b481 (kx 2024-12-28 08:20:38 +0300 233) │ S │ 0000 . . . 0000 │ 1111 . . . 1111 │ +/- max │
07a2b481 (kx 2024-12-28 08:20:38 +0300 234) └──────┴───────────────────┴───────────────────┴──────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 235) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 236) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 237) Maximum and minimum real numbers:
07a2b481 (kx 2024-12-28 08:20:38 +0300 238) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 239) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 240) ┌──────┬───────────────────┬───────────────────┬──────────────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 241) │ Sign │ Exponent │ Significand │ comments │
07a2b481 (kx 2024-12-28 08:20:38 +0300 242) ├──────┼───────────────────┼───────────────────┼──────────────────┤
07a2b481 (kx 2024-12-28 08:20:38 +0300 243) │ S │ 0000 . . . 0001 │ 0000 . . . 0000 │ +/- MIN │
07a2b481 (kx 2024-12-28 08:20:38 +0300 244) │ S │ 1111 . . . 1110 │ 1111 . . . 1111 │ +/- MAX │
07a2b481 (kx 2024-12-28 08:20:38 +0300 245) └──────┴───────────────────┴───────────────────┴──────────────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 246) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 247) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 248) .SS Complex numbers
07a2b481 (kx 2024-12-28 08:20:38 +0300 249) Complex numbers are stored in the machine's memory as a structure consisting
07a2b481 (kx 2024-12-28 08:20:38 +0300 250) of two real numbers.
07a2b481 (kx 2024-12-28 08:20:38 +0300 251) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 252) The constants that define the size of complex numbers in bytes are set so
07a2b481 (kx 2024-12-28 08:20:38 +0300 253) that they represent half the size of the complex number:
07a2b481 (kx 2024-12-28 08:20:38 +0300 254) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 255) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 256) #define NB_C32 4
07a2b481 (kx 2024-12-28 08:20:38 +0300 257) #define NB_C64 8
07a2b481 (kx 2024-12-28 08:20:38 +0300 258) #define NB_C128 16
07a2b481 (kx 2024-12-28 08:20:38 +0300 259) #define NB_C256 32
07a2b481 (kx 2024-12-28 08:20:38 +0300 260) #define NB_C512 64
07a2b481 (kx 2024-12-28 08:20:38 +0300 261) #define NB_C1024 128
07a2b481 (kx 2024-12-28 08:20:38 +0300 262) #define NB_C2048 256
07a2b481 (kx 2024-12-28 08:20:38 +0300 263) #define NB_C4096 512
07a2b481 (kx 2024-12-28 08:20:38 +0300 264) #define NB_C8192 1024
07a2b481 (kx 2024-12-28 08:20:38 +0300 265) #define NB_C16384 2048
07a2b481 (kx 2024-12-28 08:20:38 +0300 266) #define NB_C32768 4096
07a2b481 (kx 2024-12-28 08:20:38 +0300 267) #define NB_C65536 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 268) #define NB_C_MAX 8192
07a2b481 (kx 2024-12-28 08:20:38 +0300 269) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 270) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 271) It is important to note here that functions working with complex variables accept these very
07a2b481 (kx 2024-12-28 08:20:38 +0300 272) values as a parameter determining the operand size. Thus, for example, to work with a variable
07a2b481 (kx 2024-12-28 08:20:38 +0300 273) of the \fBmpu_complex256_t\fP type, \fBnb\fP = 32 == \fBNB_C256\fP must be supplied to the
07a2b481 (kx 2024-12-28 08:20:38 +0300 274) function input, while \fBsizeof\fP(\fBmpu_complex256_t\fP) == 64 == \fBNB_C256\fP * 2.
07a2b481 (kx 2024-12-28 08:20:38 +0300 275) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 276) The representation of complex numbers in memory is shown in the following diagram:
07a2b481 (kx 2024-12-28 08:20:38 +0300 277) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 278) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 279) if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 280) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 281) [NB*2-1], . . . , [NB] │ [NB-1], . . . , [0];
07a2b481 (kx 2024-12-28 08:20:38 +0300 282) ┌──────────── . . . ───────────┬──────────── . . . ───────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 283) │ Real part │ Imaginary │
07a2b481 (kx 2024-12-28 08:20:38 +0300 284) └──────────── . . . ───────────┴──────────── . . . ───────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 285) size: NB_Real == NB_CXXX NB_Imag == NB_CXXX.
07a2b481 (kx 2024-12-28 08:20:38 +0300 286) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 287)
07a2b481 (kx 2024-12-28 08:20:38 +0300 288) if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 )
07a2b481 (kx 2024-12-28 08:20:38 +0300 289) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 290) [0], . . . , [NB-1] │ [NB], . . . , [NB*2-1];
07a2b481 (kx 2024-12-28 08:20:38 +0300 291) ┌──────────── . . . ───────────┬──────────── . . . ───────────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 292) │ Real part │ Imaginary │
07a2b481 (kx 2024-12-28 08:20:38 +0300 293) └──────────── . . . ───────────┴──────────── . . . ───────────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 294) size: NB_Real == NB_CXXX NB_Imag == NB_CXXX.
07a2b481 (kx 2024-12-28 08:20:38 +0300 295) }
07a2b481 (kx 2024-12-28 08:20:38 +0300 296) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 297) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 298) The Imaginary and Real part formats of complex variables are the same as those of real numbers.
07a2b481 (kx 2024-12-28 08:20:38 +0300 299) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 300) .SH Flags
07a2b481 (kx 2024-12-28 08:20:38 +0300 301) Most operations on integers and real numbers expose flags. The flags of operations are
07a2b481 (kx 2024-12-28 08:20:38 +0300 302) placed in an integer 32\-bit variable. The lower 8 bits [7 ... 0] are given for flags
07a2b481 (kx 2024-12-28 08:20:38 +0300 303) of integer operations. Bits 8 through 15 are occupied by flags set by operations with
07a2b481 (kx 2024-12-28 08:20:38 +0300 304) real numbers.
07a2b481 (kx 2024-12-28 08:20:38 +0300 305) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 306) .SS Flags of integer operations:
07a2b481 (kx 2024-12-28 08:20:38 +0300 307) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 308) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 309) 7 6 5 4 3 2 1 0
07a2b481 (kx 2024-12-28 08:20:38 +0300 310) . . . ─┬────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
07a2b481 (kx 2024-12-28 08:20:38 +0300 311) │ V │ R │ Z │ P │ S │ O │ C │ A │
07a2b481 (kx 2024-12-28 08:20:38 +0300 312) . . . ─┴────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
07a2b481 (kx 2024-12-28 08:20:38 +0300 313) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 314) A - Auxiliary Carry Flag (carry from lowest 4-bit word)
07a2b481 (kx 2024-12-28 08:20:38 +0300 315) C - Carry Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 316) O - Overflow Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 317) S - Sign Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 318) P - Parity Flag (of lowest significant byte)
07a2b481 (kx 2024-12-28 08:20:38 +0300 319) Z - Zero Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 320) R - major || remainder
07a2b481 (kx 2024-12-28 08:20:38 +0300 321) V - Invalid operation
07a2b481 (kx 2024-12-28 08:20:38 +0300 322) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 323) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 324) NOTE: The \fBA\fP and \fBP\fP flags are exposed only by operations on 8\-bit
07a2b481 (kx 2024-12-28 08:20:38 +0300 325) and 16\-bit variables.
07a2b481 (kx 2024-12-28 08:20:38 +0300 326) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 327) .SS Flags of operations with real variables:
07a2b481 (kx 2024-12-28 08:20:38 +0300 328) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 329) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 330) 15 14 13 12 11 10 9 8
07a2b481 (kx 2024-12-28 08:20:38 +0300 331) . . . ─┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬ . . .
07a2b481 (kx 2024-12-28 08:20:38 +0300 332) │ INX │ IND │ PLS │ TLS │ UDF │ OVF │ SNG │ DOM │
07a2b481 (kx 2024-12-28 08:20:38 +0300 333) . . . ─┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴ . . .
07a2b481 (kx 2024-12-28 08:20:38 +0300 334) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 335) DOM - Domain Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 336) SNG - Singularity Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 337) OVF - Overflow Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 338) UDF - Underflow Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 339) TLS - TLOSS Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 340) PLS - PLOSS Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 341) IND - ind-produsing operation Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 342) INX - Inexact Flag
07a2b481 (kx 2024-12-28 08:20:38 +0300 343) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 344) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 345) The \fBlibmpu.h\fP header file defines flag handling functions such as clearing flags,
07a2b481 (kx 2024-12-28 08:20:38 +0300 346) resetting, setting, and checking operation flags.
07a2b481 (kx 2024-12-28 08:20:38 +0300 347) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 348) .SH Exceptions and error codes
07a2b481 (kx 2024-12-28 08:20:38 +0300 349) Besides flagging operations with integers and real numbers, the \fBLibMPU\fP library supports
07a2b481 (kx 2024-12-28 08:20:38 +0300 350) the standard \fBerrno\fP variable and, in addition, its own variables \fB__mpu_integer_error_no\fP,
07a2b481 (kx 2024-12-28 08:20:38 +0300 351) \fB__mpu_real_error_no\fP, \fB__mpu_complex_error_no\fP, \fB__mpu_math_error_no\fP.
07a2b481 (kx 2024-12-28 08:20:38 +0300 352) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 353) Error codes are defined in the \fBlibmpu.h\fP header file.
07a2b481 (kx 2024-12-28 08:20:38 +0300 354) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 355) The \fBLibMPU\fP library supports error handling through the \fB__mpu_math_error()\fP function,
07a2b481 (kx 2024-12-28 08:20:38 +0300 356) which can be overridden by the user at the object code linking stage in the same way that it is
07a2b481 (kx 2024-12-28 08:20:38 +0300 357) possible to override the \fBmatherr()\fP function when linking programs with a standard \fBC\fP
07a2b481 (kx 2024-12-28 08:20:38 +0300 358) language library (e.g., \fBGNU Libc\fP).
07a2b481 (kx 2024-12-28 08:20:38 +0300 359) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 360) In addition, the user can override the \fB__mpu_warning()\fP function, which
07a2b481 (kx 2024-12-28 08:20:38 +0300 361) can output additional error information.
07a2b481 (kx 2024-12-28 08:20:38 +0300 362) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 363) As in the case of the \fBmatherr()\fP function of the \fBC\fP standard library,
07a2b481 (kx 2024-12-28 08:20:38 +0300 364) the parameter of the \fB__mpu_math_error()\fP and \fB__mpu_warning()\fP functions
07a2b481 (kx 2024-12-28 08:20:38 +0300 365) is a pointer to the \fB__exception\fP structure:
07a2b481 (kx 2024-12-28 08:20:38 +0300 366) .nf
07a2b481 (kx 2024-12-28 08:20:38 +0300 367) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 368) struct __exception
07a2b481 (kx 2024-12-28 08:20:38 +0300 369) {
07a2b481 (kx 2024-12-28 08:20:38 +0300 370) int who; /* _COMPLEX_, _REAL_, _INTEGER_, _MATH_ */
07a2b481 (kx 2024-12-28 08:20:38 +0300 371)
07a2b481 (kx 2024-12-28 08:20:38 +0300 372) int type;
07a2b481 (kx 2024-12-28 08:20:38 +0300 373) __mpu_char8_t *name;
07a2b481 (kx 2024-12-28 08:20:38 +0300 374) __mpu_char8_t *msg;
07a2b481 (kx 2024-12-28 08:20:38 +0300 375) int msg_type; /* >= 1 - error, 0 - warning */
07a2b481 (kx 2024-12-28 08:20:38 +0300 376)
07a2b481 (kx 2024-12-28 08:20:38 +0300 377) int nb_a1; /* number of bytes in arg_1 */
07a2b481 (kx 2024-12-28 08:20:38 +0300 378) int nb_a2; /* number of bytes in arg_2 */
07a2b481 (kx 2024-12-28 08:20:38 +0300 379) int nb_rv; /* number of bytes in return_value */
07a2b481 (kx 2024-12-28 08:20:38 +0300 380)
07a2b481 (kx 2024-12-28 08:20:38 +0300 381) unsigned char *arg_1;
07a2b481 (kx 2024-12-28 08:20:38 +0300 382) unsigned char *arg_2;
07a2b481 (kx 2024-12-28 08:20:38 +0300 383) unsigned char *return_value;
07a2b481 (kx 2024-12-28 08:20:38 +0300 384) };
07a2b481 (kx 2024-12-28 08:20:38 +0300 385) .fi
07a2b481 (kx 2024-12-28 08:20:38 +0300 386) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 387) where the error source, error type, the name of the function whose execution caused
07a2b481 (kx 2024-12-28 08:20:38 +0300 388) the error, as well as pointers to the function arguments and the received return
07a2b481 (kx 2024-12-28 08:20:38 +0300 389) value are defined.
07a2b481 (kx 2024-12-28 08:20:38 +0300 390) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 391) Using \fB__mpu_utf8mpu_error()\fP function you can get a pointer to a string constant
07a2b481 (kx 2024-12-28 08:20:38 +0300 392) containing a text description of the error corresponding to the error code (see
07a2b481 (kx 2024-12-28 08:20:38 +0300 393) \fB__mpu_integer_error_no\fP, \fB__mpu_real_error_no\fP, \fB__mpu_complex_error_no\fP,
07a2b481 (kx 2024-12-28 08:20:38 +0300 394) \fB__mpu_math_error_no\fP variables).
07a2b481 (kx 2024-12-28 08:20:38 +0300 395) .PP
07a2b481 (kx 2024-12-28 08:20:38 +0300 396) For simple calculations, we usually do not have to override the functions \fBmatherr()\fP,
07a2b481 (kx 2024-12-28 08:20:38 +0300 397) \fB__mpu_math_error()\fP and \fB__mpu_warning()\fP, but we have kept this possibility as one
07a2b481 (kx 2024-12-28 08:20:38 +0300 398) of the standard features provided by the \fBC\fP language library.
07a2b481 (kx 2024-12-28 08:20:38 +0300 399) .sp
07a2b481 (kx 2024-12-28 08:20:38 +0300 400) .SH SEE ALSO
41c271da (kx 2025-01-05 15:42:39 +0300 401) .BR iadd(3),
41c271da (kx 2025-01-05 15:42:39 +0300 402) .BR isub(3),
41c271da (kx 2025-01-05 15:42:39 +0300 403) .BR iadc(3),
41c271da (kx 2025-01-05 15:42:39 +0300 404) .BR isbb(3),
41c271da (kx 2025-01-05 15:42:39 +0300 405) .BR ishl(3),
41c271da (kx 2025-01-05 15:42:39 +0300 406) .BR ishr(3),
41c271da (kx 2025-01-05 15:42:39 +0300 407) .BR isal(3),
41c271da (kx 2025-01-05 15:42:39 +0300 408) .BR isar(3),
41c271da (kx 2025-01-05 15:42:39 +0300 409) .BR irol(3),
41c271da (kx 2025-01-05 15:42:39 +0300 410) .BR iror(3),
41c271da (kx 2025-01-05 15:42:39 +0300 411) .BR ircl(3),
41c271da (kx 2025-01-05 15:42:39 +0300 412) .BR ircr(3),
41c271da (kx 2025-01-05 15:42:39 +0300 413) .BR ishln(3),
41c271da (kx 2025-01-05 15:42:39 +0300 414) .BR ishrn(3),
41c271da (kx 2025-01-05 15:42:39 +0300 415) .BR isaln(3),
41c271da (kx 2025-01-05 15:42:39 +0300 416) .BR isarn(3),
41c271da (kx 2025-01-05 15:42:39 +0300 417) .BR iroln(3),
41c271da (kx 2025-01-05 15:42:39 +0300 418) .BR irorn(3),
41c271da (kx 2025-01-05 15:42:39 +0300 419) .BR ircln(3),
41c271da (kx 2025-01-05 15:42:39 +0300 420) .BR ircrn(3),
41c271da (kx 2025-01-05 15:42:39 +0300 421) .BR ineg(3),
41c271da (kx 2025-01-05 15:42:39 +0300 422) .BR inot(3),
41c271da (kx 2025-01-05 15:42:39 +0300 423) .BR iand(3),
41c271da (kx 2025-01-05 15:42:39 +0300 424) .BR itest(3),
41c271da (kx 2025-01-05 15:42:39 +0300 425) .BR icmp(3),
41c271da (kx 2025-01-05 15:42:39 +0300 426) .BR ior(3),
41c271da (kx 2025-01-05 15:42:39 +0300 427) .BR ixor(3),
41c271da (kx 2025-01-05 15:42:39 +0300 428) .BR iinc(3),
41c271da (kx 2025-01-05 15:42:39 +0300 429) .BR idec(3),
41c271da (kx 2025-01-05 15:42:39 +0300 430) .BR ixchg(3),
41c271da (kx 2025-01-05 15:42:39 +0300 431) .BR icpy(3),
41c271da (kx 2025-01-05 15:42:39 +0300 432) .BR icvt(3),
41c271da (kx 2025-01-05 15:42:39 +0300 433) .BR imul(3),
41c271da (kx 2025-01-05 15:42:39 +0300 434) .BR ismul(3),
41c271da (kx 2025-01-05 15:42:39 +0300 435) .BR idiv(3),
41c271da (kx 2025-01-05 15:42:39 +0300 436) .BR isdiv(3),
41c271da (kx 2025-01-05 15:42:39 +0300 437) .BR iatoi(3),
41c271da (kx 2025-01-05 15:42:39 +0300 438) .BR iatoui(3),
41c271da (kx 2025-01-05 15:42:39 +0300 439) .BR iitoa(3),
41c271da (kx 2025-01-05 15:42:39 +0300 440) .BR iuitoa(3).
Math Processor Unit Library
libmpu – library of arithmetic functions for integer, real, and complex numbers of increased digit capacity
16 Commits
0 Branches
2 Tags