diff options
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 4 | ||||
| -rw-r--r-- | include/libmpu.h.in | 2 | ||||
| -rw-r--r-- | man/Makefile.am | 9 | ||||
| -rw-r--r-- | man/iadc.3mpu | 64 | ||||
| -rw-r--r-- | man/iadd.3mpu | 61 | ||||
| -rw-r--r-- | man/isbb.3mpu | 65 | ||||
| -rw-r--r-- | man/isub.3mpu | 61 | ||||
| -rw-r--r-- | man/libmpu.7 | 404 | ||||
| -rw-r--r-- | man/ru/Makefile.am | 11 | ||||
| -rw-r--r-- | man/ru/iadc.3mpu | 64 | ||||
| -rw-r--r-- | man/ru/iadd.3mpu | 61 | ||||
| -rw-r--r-- | man/ru/isbb.3mpu | 65 | ||||
| -rw-r--r-- | man/ru/isub.3mpu | 61 | ||||
| -rw-r--r-- | man/ru/libmpu.7 | 410 |
15 files changed, 1341 insertions, 3 deletions
diff --git a/Makefile.am b/Makefile.am index dab8856..c5e80ec 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,7 @@ ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = po mpu +SUBDIRS = po mpu man EXTRA_DIST = config.rpath m4/ChangeLog \ config/patches bootstrap \ diff --git a/configure.ac b/configure.ac index 16f7938..c5f20da 100644 --- a/configure.ac +++ b/configure.ac @@ -280,7 +280,9 @@ AC_CONFIG_FILES([ po/Makefile.in mpu/Makefile include/libmpu.h mpu-config - mpu.pc]) + mpu.pc + man/Makefile + man/ru/Makefile]) AC_OUTPUT if test -f "config.h"; then diff --git a/include/libmpu.h.in b/include/libmpu.h.in index 5057481..f8f9dee 100644 --- a/include/libmpu.h.in +++ b/include/libmpu.h.in @@ -459,7 +459,7 @@ extern void ior ( mpu_int *c, mpu_int *a, mpu_int *b, int nb ); extern void ixor ( mpu_int *c, mpu_int *a, mpu_int *b, int nb ); extern void iinc ( mpu_int *c, mpu_int *a, int nb ); -extern void idec ( mpu_int *c, mpu_int *a, int nb ); +extern void idec ( mpu_int *c, mpu_int *a, int nb ); extern void ixchg ( mpu_int *a, mpu_int *b, int nb ); diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..53688a4 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,9 @@ + +SUBDIRS = ru + +MAN3 = iadc.3mpu iadd.3mpu \ + isbb.3mpu isub.3mpu + +MAN7 = libmpu.7 + +dist_man_MANS = $(MAN3) $(MAN7) diff --git a/man/iadc.3mpu b/man/iadc.3mpu new file mode 100644 index 0000000..871ab35 --- /dev/null +++ b/man/iadc.3mpu @@ -0,0 +1,64 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH iadc 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBiadc\fP \- signed and unsigned addition with carryover +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void iadс( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +The \fBiadc()\fP function performs the operation of adding integers located at addresses \fBa\fP and \fBb\fP, +adds the value of the carry flag \fBC\fP to the obtained sum and places the result at address \fBc\fP. The +operands can be numbers with or without a sign. The memory contents at addresses \fBa\fP, \fBb\fP are not +changed, the previous memory contents at address \fBc\fP are lost. The \fBnb\fP parameter defines the size, +in bytes, of the operands located at addresses \fBc\fP, \fBa\fP, \fBb\fP. Since the \fBiadc()\fP function +uses the \fBC\fP carry flag, it can be used to add numbers whose length exceeds the maximum allowed size +of integers. +.PP +The function affects the flags \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP, and \fBV\fP. +.PP +Flags \fBА\fP and \fBP\fP are set only when the size of operands \fBa\fP, \fBb\fP is one or +two bytes (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + __mpu_stc(); /* Set Carry Flag */ + + iadc( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 275; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.SH SEE ALSO +.BR iadd(3), +.BR isub(3), +.BR isbb(3). + diff --git a/man/iadd.3mpu b/man/iadd.3mpu new file mode 100644 index 0000000..d89694b --- /dev/null +++ b/man/iadd.3mpu @@ -0,0 +1,61 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH iadd 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBiadd\fP \- signed and unsigned addition +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void iadd( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +The \fBiadd()\fP function performs the operation of addition of integers located at addresses \fBa\fP and +\fBb\fP, with the result placed at address \fBc\fP. The operands can be numbers with or without a sign. +The memory contents at addresses \fBa\fP, \fBb\fP are not changed, the previous memory contents at address +\fBc\fP are lost. The \fBnb\fP parameter defines the size in bytes of the operands located at addresses +\fBc\fP, \fBa\fP, \fBb\fP. +.PP +The function affects the flags \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP, and \fBV\fP. +.PP +Flags \fBА\fP and \fBP\fP are set only when the size of operands \fBa\fP, \fBb\fP is one or +two bytes (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + iadd( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\\n", s ); /* c = 274; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadc (3), +.BR isub (3), +.BR isbb (3). + diff --git a/man/isbb.3mpu b/man/isbb.3mpu new file mode 100644 index 0000000..b2ff263 --- /dev/null +++ b/man/isbb.3mpu @@ -0,0 +1,65 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH isbb 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBisbb\fP \- subtraction signed and unsigned with carryover +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void isbb( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +The \fBisbb()\fP function performs the operation of subtraction of integers located at addresses \fBa\fP +and \fBb\fP, subtracts the value of the carry flag \fBC\fP from the obtained difference and places the +result at address \fBc\fP. The operands can be numbers with or without a sign. The memory contents at +addresses \fBa\fP, \fBb\fP are not changed, the previous memory contents at address \fBc\fP are lost. +The \fBnb\fP parameter determines the size, in bytes, of the operands located at addresses +\fBc\fP, \fBa\fP, \fBb\fP. Since the \fBisbb()\fP function uses the \fBC\fP carry flag, +it can be used to subtract numbers whose length exceeds the maximum allowed size of integers. +.PP +The function affects the flags \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP, and \fBV\fP. +.PP +Flags \fBА\fP and \fBP\fP are set only when the size of operands \fBa\fP, \fBb\fP is one or +two bytes (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + __mpu_stc(); /* Set Carry Flag */ + + isbb( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 199; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadd(3), +.BR iadc(3), +.BR isub(3). + diff --git a/man/isub.3mpu b/man/isub.3mpu new file mode 100644 index 0000000..f82ee89 --- /dev/null +++ b/man/isub.3mpu @@ -0,0 +1,61 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH isub 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBisub\fP \- subtraction signed and unsigned +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void isub( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +The \fBisub()\fP function performs the operation of subtraction of integers located at addresses \fBa\fP +and \fBb\fP, with the result placed at address \fBc\fP. The operands can be numbers with or without a sign. +The memory contents at addresses \fBa\fP, \fBb\fP are not changed, the previous memory contents at address +\fBc\fP are lost. The \fBnb\fP parameter defines the size in bytes of the operands located at addresses +\fBc\fP, \fBa\fP, \fBb\fP. +.PP +The function affects the flags \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP, and \fBV\fP. +.PP +Flags \fBА\fP and \fBP\fP are set only when the size of operands \fBa\fP, \fBb\fP is one or +two bytes (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + isub( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 200; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadd(3), +.BR iadc(3), +.BR isbb(3). + diff --git a/man/libmpu.7 b/man/libmpu.7 new file mode 100644 index 0000000..7005059 --- /dev/null +++ b/man/libmpu.7 @@ -0,0 +1,404 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH LIBMPU 7 "December 27, 2024" "libmpu" "libmpu Programmer's Manual" +.SH NAME +libmpu \- Math Processor Unit Library (libmpu). +.SH DESCRIPTION +The library is designed as a processor emulator with a set of registers and flags that are set according +to the results of the operations performed. The set of integer functions contains arithmetic and logical +operations, as well as all types of shift operations. Basic trigonometric functions are implemented for +real and complex numbers. +.PP +Bit capacity is limited to \fB65536\fP bits for arithmetic operations and \fB16384\fP bits +for trigonometry. The limitations are due to the order of the approximation series. +.SH Data formats +The library supports integer, real and complex types. Variables are stored in byte arrays. +.sp +.SS Integer numbers +The \fBlibmpu.h\fP header file defines constants that represent the number of bytes +to store integer variables: +.nf +.sp +#define NB_I8 1 +#define NB_I16 2 +#define NB_I32 4 +#define NB_I64 8 +#define NB_I128 16 +#define NB_I256 32 +#define NB_I512 64 +#define NB_I1024 128 +#define NB_I2048 256 +#define NB_I4096 512 +#define NB_I8192 1024 +#define NB_I16384 2048 +#define NB_I32768 4096 +#define NB_I65536 8192 +#define NB_I_MAX 8192 +.fi +.PP +These constants can be used as the value of the \fBnb\fP argument for integer operations. +.PP +In systems with \fBbig\-endian\fP byte order, the high byte of a number is stored at the +lowest memory address and the low byte at the highest memory address. In a system with +\fBlittle\-endian\fP byte order, on the contrary, the smallest byte is stored at the +smallest address. +.PP +The following diagram shows the placement of the integer depending on the machine +architecture: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB-1], . . . , [0]; + ┌─────────────────────────── . . . ───────────────────────────┐ + │ high low │ + └─────────────────────────── . . . ───────────────────────────┘ + ^Sign bit + size: NB. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [NB-1]; + ┌─────────────────────────── . . . ───────────────────────────┐ + │ high low │ + └─────────────────────────── . . . ───────────────────────────┘ + ^Sign bit + size: NB. +} +.fi +.PP +Here, the symbol \fBNB\fP — denotes the number of bytes of the number. +.PP +To represent integer variables, the user can independently create byte arrays in any +of the following ways: +.nf +.sp + __mpu_byte_t a[NB_I65536]; + mpu_int a[NB_I65536]; + + mpu_int *a = (mpu_int *)malloc( NB_I65536 * sizeof(__mpu_byte_t) ); +.fi +.PP +and also use, predefined in \fBlibmpu.h\fP, data types that explicitly talk +about dimensionality: +.nf +.sp + mpu_int4096_t a; +.fi +.PP +Integers can be considered both signed and unsigned. Signed variables are represented in two’s +complement form for convenience of operations with them. Below is a table of some values of an +8\-bit variable in two’s complement form. +.nf +.sp + ┌────────────────┬─────────────────┐ + │ Decimal │ Binary │ + │ representation │ representation │ + ├────────────────┼─────────────────┤ + │ 127 │ 0111 1111 │ + │ 3 │ 0000 0011 │ + │ 2 │ 0000 0010 │ + │ 1 │ 0000 0001 │ + │ 0 │ 0000 0000 │ + │ -1 │ 1111 1111 │ + │ -2 │ 1111 1110 │ + │ -3 │ 1111 1101 │ + │ -127 │ 1000 0001 │ + │ -128 │ 1000 0000 │ + └────────────────┴─────────────────┘ +.fi +.sp +.SS Real numbers +Real variables, just like integer variables, are stored as byte arrays. The \fBlibmpu.h\fP +header file defines constants that represent the number of bytes for storing real variables: +.nf +.sp +#define NB_R32 4 +#define NB_R64 8 +#define NB_R128 16 +#define NB_R256 32 +#define NB_R512 64 +#define NB_R1024 128 +#define NB_R2048 256 +#define NB_R4096 512 +#define NB_R8192 1024 +#define NB_R16384 2048 +#define NB_R32768 4096 +#define NB_R65536 8192 +#define NB_R_MAX 8192 +.fi +.PP +These constants can be used as the value of the \fBnb\fP argument for operations +with real numbers. +.PP +Real numbers have two fields: the shifted exponent and the mantissa. The integer +unit bit is implicit. The sign is located in the high bit of the number. +.PP +The following diagram shows the placement of a real number depending on the +architecture of the machine: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB-1], . . . , [nS] │ [nS-1], . . . , [0]; + ┌────── . . . ───────┬─────────────── . . . ──────────────────┐ + │ Sign + Exponent │ Significand │ + └────── . . . ───────┴─────────────── . . . ──────────────────┘ + ^Sign bit ^(1. - implicit) + size: nE nS. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [nE-1] │ [nE], . . . , [NB-1]; + ┌────── . . . ───────┬─────────────── . . . ──────────────────┐ + │ Sign + Exponent │ Significand │ + └────── . . . ───────┴─────────────── . . . ──────────────────┘ + ^Sign bit ^(1. - implicit) + size: nE nS. +} +.fi +.PP +Here, the symbols \fBnE\fP and \fBnS\fP denote the number of bytes of the exponent and the +number of bytes of the mantissa, respectively. +.PP +The number of bits allocated to represent the sign, exponent and mantissa is distributed +as follows: +.nf +.sp + ┌───────────────────────┬───────────────────┬─────────────┐ + │ Total number of bits │ (Sign + Exponent) │ Significand │ + ├───────────────────────┼───────────────────┼─────────────┤ + │ 32 │ 1 + 8 + │ 23 │ + │ 64 │ 1 + 11 + │ 52 │ + │ 128 │ 1 + 31 + │ 96 │ + │ 256 │ 1 + 31 + │ 224 │ + │ 512 │ 1 + 63 + │ 448 │ + │ 1024 │ 1 + 63 + │ 960 │ + │ 2048 │ 1 + 127 + │ 1920 │ + │ 4096 │ 1 + 127 + │ 3968 │ + │ 8192 │ 1 + 255 + │ 7936 │ + │ 16384 │ 1 + 255 + │ 16128 │ + │ 32768 │ 1 + 511 + │ 32256 │ + │ 65536 │ 1 + 511 + │ 65024 │ + └───────────────────────┴───────────────────┴─────────────┘ +.fi +.PP +The 32\- and 64\-bit number formats are fully consistent with the \fBIEEE\fP (Institute +of Electrical and Electronics Engineers) format. +.PP +For convenience in declaring real\-type variables, the \fBlibmpu.h\fP header file +defines the corresponding data types, the application of which may look, for example, +as follows: +.nf +.sp + mpu_real16384_t a, b; +.fi +.sp +.SS Not\-a\-Numbers +To enhance computational capabilities, the floating\-point number format provides +several special values along with the usual real numbers. These have some meaning +and provide important information about the algorithms and operations in which these +values appear. Special values include real numbers with normalization violations, +indeterminacy, zeros, infinities, and non\-numbers, shown in the following table. +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 1111 . . . 1111 │ 0000 . . . 0000 │ +/- inf │ + │ S │ 0000 . . . 0000 │ 0000 . . . 0000 │ +/- 0 │ + │ 1 │ 1111 . . . 1111 │ 1000 . . . 0000 │ - ind │ + │ S │ 1111 . . . 1111 │ 0000 . . . 0001 │ +/- NaN (min) │ + │ S │ 1111 . . . 1111 │ 1111 . . . 1111 │ +/- NaN (max) │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ + + Здесь: + +/- inf - +/- infinity; + +/- 0 - +/- signed zero; + - ind - indeterminacy; + +/- NaN (min) - +/- minimal Not-a-Number; + +/- NaN (max) - +/- maximal Not-a-Number. +.fi +.PP +Denormalized numbers: +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 0000 . . . 0000 │ 0000 . . . 0001 │ +/- min │ + │ S │ 0000 . . . 0000 │ 1111 . . . 1111 │ +/- max │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ +.fi +.PP +Maximum and minimum real numbers: +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 0000 . . . 0001 │ 0000 . . . 0000 │ +/- MIN │ + │ S │ 1111 . . . 1110 │ 1111 . . . 1111 │ +/- MAX │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ +.fi +.sp +.SS Complex numbers +Complex numbers are stored in the machine's memory as a structure consisting +of two real numbers. +.PP +The constants that define the size of complex numbers in bytes are set so +that they represent half the size of the complex number: +.nf +.sp +#define NB_C32 4 +#define NB_C64 8 +#define NB_C128 16 +#define NB_C256 32 +#define NB_C512 64 +#define NB_C1024 128 +#define NB_C2048 256 +#define NB_C4096 512 +#define NB_C8192 1024 +#define NB_C16384 2048 +#define NB_C32768 4096 +#define NB_C65536 8192 +#define NB_C_MAX 8192 +.fi +.PP +It is important to note here that functions working with complex variables accept these very +values as a parameter determining the operand size. Thus, for example, to work with a variable +of the \fBmpu_complex256_t\fP type, \fBnb\fP = 32 == \fBNB_C256\fP must be supplied to the +function input, while \fBsizeof\fP(\fBmpu_complex256_t\fP) == 64 == \fBNB_C256\fP * 2. +.PP +The representation of complex numbers in memory is shown in the following diagram: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB*2-1], . . . , [NB] │ [NB-1], . . . , [0]; + ┌──────────── . . . ───────────┬──────────── . . . ───────────┐ + │ Real part │ Imaginary │ + └──────────── . . . ───────────┴──────────── . . . ───────────┘ + size: NB_Real == NB_CXXX NB_Imag == NB_CXXX. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [NB-1] │ [NB], . . . , [NB*2-1]; + ┌──────────── . . . ───────────┬──────────── . . . ───────────┐ + │ Real part │ Imaginary │ + └──────────── . . . ───────────┴──────────── . . . ───────────┘ + size: NB_Real == NB_CXXX NB_Imag == NB_CXXX. +} +.fi +.PP +The Imaginary and Real part formats of complex variables are the same as those of real numbers. +.sp +.SH Flags +Most operations on integers and real numbers expose flags. The flags of operations are +placed in an integer 32\-bit variable. The lower 8 bits [7 ... 0] are given for flags +of integer operations. Bits 8 through 15 are occupied by flags set by operations with +real numbers. +.sp +.SS Flags of integer operations: +.nf +.sp + 7 6 5 4 3 2 1 0 + . . . ─┬────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐ + │ V │ R │ Z │ P │ S │ O │ C │ A │ + . . . ─┴────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘ +.sp + A - Auxiliary Carry Flag (carry from lowest 4-bit word) + C - Carry Flag + O - Overflow Flag + S - Sign Flag + P - Parity Flag (of lowest significant byte) + Z - Zero Flag + R - major || remainder + V - Invalid operation +.fi +.PP +NOTE: The \fBA\fP and \fBP\fP flags are exposed only by operations on 8\-bit +and 16\-bit variables. +.sp +.SS Flags of operations with real variables: +.nf +.sp + 15 14 13 12 11 10 9 8 + . . . ─┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬ . . . + │ INX │ IND │ PLS │ TLS │ UDF │ OVF │ SNG │ DOM │ + . . . ─┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴ . . . +.sp + DOM - Domain Flag + SNG - Singularity Flag + OVF - Overflow Flag + UDF - Underflow Flag + TLS - TLOSS Flag + PLS - PLOSS Flag + IND - ind-produsing operation Flag + INX - Inexact Flag +.fi +.PP +The \fBlibmpu.h\fP header file defines flag handling functions such as clearing flags, +resetting, setting, and checking operation flags. +.sp +.SH Exceptions and error codes +Besides flagging operations with integers and real numbers, the \fBLibMPU\fP library supports +the standard \fBerrno\fP variable and, in addition, its own variables \fB__mpu_integer_error_no\fP, +\fB__mpu_real_error_no\fP, \fB__mpu_complex_error_no\fP, \fB__mpu_math_error_no\fP. +.PP +Error codes are defined in the \fBlibmpu.h\fP header file. +.PP +The \fBLibMPU\fP library supports error handling through the \fB__mpu_math_error()\fP function, +which can be overridden by the user at the object code linking stage in the same way that it is +possible to override the \fBmatherr()\fP function when linking programs with a standard \fBC\fP +language library (e.g., \fBGNU Libc\fP). +.PP +In addition, the user can override the \fB__mpu_warning()\fP function, which +can output additional error information. +.PP +As in the case of the \fBmatherr()\fP function of the \fBC\fP standard library, +the parameter of the \fB__mpu_math_error()\fP and \fB__mpu_warning()\fP functions +is a pointer to the \fB__exception\fP structure: +.nf +.sp +struct __exception +{ + int who; /* _COMPLEX_, _REAL_, _INTEGER_, _MATH_ */ + + int type; + __mpu_char8_t *name; + __mpu_char8_t *msg; + int msg_type; /* >= 1 - error, 0 - warning */ + + int nb_a1; /* number of bytes in arg_1 */ + int nb_a2; /* number of bytes in arg_2 */ + int nb_rv; /* number of bytes in return_value */ + + unsigned char *arg_1; + unsigned char *arg_2; + unsigned char *return_value; +}; +.fi +.PP +where the error source, error type, the name of the function whose execution caused +the error, as well as pointers to the function arguments and the received return +value are defined. +.PP +Using \fB__mpu_utf8mpu_error()\fP function you can get a pointer to a string constant +containing a text description of the error corresponding to the error code (see +\fB__mpu_integer_error_no\fP, \fB__mpu_real_error_no\fP, \fB__mpu_complex_error_no\fP, +\fB__mpu_math_error_no\fP variables). +.PP +For simple calculations, we usually do not have to override the functions \fBmatherr()\fP, +\fB__mpu_math_error()\fP and \fB__mpu_warning()\fP, but we have kept this possibility as one +of the standard features provided by the \fBC\fP language library. +.sp +.SH SEE ALSO +.BR iadd (3), +.BR iadc (3), +.BR isub (3), +.BR isbb (3). diff --git a/man/ru/Makefile.am b/man/ru/Makefile.am new file mode 100644 index 0000000..eedea05 --- /dev/null +++ b/man/ru/Makefile.am @@ -0,0 +1,11 @@ + +LANG = ru + +mandir = @mandir@/$(LANG) + +MAN3 = iadc.3mpu iadd.3mpu \ + isbb.3mpu isub.3mpu + +MAN7 = libmpu.7 + +dist_man_MANS = $(MAN3) $(MAN7) diff --git a/man/ru/iadc.3mpu b/man/ru/iadc.3mpu new file mode 100644 index 0000000..320a7a6 --- /dev/null +++ b/man/ru/iadc.3mpu @@ -0,0 +1,64 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH iadc 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBiadc\fP \- сложение знаковое и беззнаковое с переносом +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void iadс( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +Функция \fBiadc()\fP выполняет операцию сложения целых чисел, расположенных по адресам \fBa\fP и \fBb\fP, +к полученной сумме добавляет значение флага переноса \fBC\fP и размещает результат по адресу \fBc\fP. +Операнды могут быть числами со знаком или без него. Содержимое памяти по адресам \fBa\fP, \fBb\fP +не изменяется, предыдущее содержимое памяти по адресу \fBc\fP теряется. Параметр \fBnb\fP определяет +размер в байтах, операндов расположенных по адресам \fBc\fP, \fBa\fP, \fBb\fP. Поскольку функция \fBiadc()\fP +использует флаг переноса \fBC\fP, то она может применяться для сложения чисел, длина которых +превышает максимально допустимые размеры целых чисел. +.PP +Функция воздействует на флаги \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP и \fBV\fP. +.PP +Флаги \fBА\fP и \fBP\fP выставляются только в том случае, когда размер операндов \fBa\fP, \fBb\fP равен одному или +двум байтам (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + __mpu_stc(); /* Set Carry Flag */ + + iadc( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 275; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.SH SEE ALSO +.BR iadd(3), +.BR isub(3), +.BR isbb(3). + diff --git a/man/ru/iadd.3mpu b/man/ru/iadd.3mpu new file mode 100644 index 0000000..939fe2a --- /dev/null +++ b/man/ru/iadd.3mpu @@ -0,0 +1,61 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH iadd 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBiadd\fP \- сложение знаковое и беззнаковое +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void iadd( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +Функция \fBiadd()\fP выполняет операцию сложения целых чисел, расположенных по адресам \fBa\fP и \fBb\fP, +c размещением результата по адресу \fBc\fP. Операнды могут быть числами со знаком или без него. +Содержимое памяти по адресам \fBa\fP, \fBb\fP не изменяется, предыдущее содержимое памяти по адресу +\fBc\fP теряется. Параметр \fBnb\fP определяет размер в байтах, операндов расположенных по адресам +\fBc\fP, \fBa\fP, \fBb\fP. +.PP +Функция воздействует на флаги \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP и \fBV\fP. +.PP +Флаги \fBА\fP и \fBP\fP выставляются только в том случае, когда размер операндов \fBa\fP, \fBb\fP равен одному или +двум байтам (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + iadd( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\\n", s ); /* c = 274; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadc (3), +.BR isub (3), +.BR isbb (3). + diff --git a/man/ru/isbb.3mpu b/man/ru/isbb.3mpu new file mode 100644 index 0000000..6770000 --- /dev/null +++ b/man/ru/isbb.3mpu @@ -0,0 +1,65 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH isbb 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBisbb\fP \- вычитание знаковое и беззнаковое с переносом +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void isbb( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +Функция \fBisbb()\fP выполняет операцию вычитания целых чисел, расположенных по адресам \fBa\fP и \fBb\fP, +из полученной разности вычитает значение флага переноса \fBC\fP и размещает результат по адресу \fBc\fP. +Операнды могут быть числами со знаком или без него. Содержимое памяти по адресам \fBa\fP, \fBb\fP +не изменяется, предыдущее содержимое памяти по адресу \fBc\fP теряется. Параметр \fBnb\fP определяет +размер в байтах, операндов расположенных по адресам \fBc\fP, \fBa\fP, \fBb\fP. Поскольку функция \fBisbb()\fP +использует флаг переноса \fBC\fP, то она может применяться для вычитания чисел, длина которых +превышает максимально допустимые размеры целых чисел. +.PP +Функция воздействует на флаги \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP и \fBV\fP. +.PP +Флаги \fBА\fP и \fBP\fP выставляются только в том случае, когда размер операндов \fBa\fP, \fBb\fP равен одному или +двум байтам (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + __mpu_stc(); /* Set Carry Flag */ + + isbb( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 199; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadd(3), +.BR iadc(3), +.BR isub(3). + diff --git a/man/ru/isub.3mpu b/man/ru/isub.3mpu new file mode 100644 index 0000000..7a3624a --- /dev/null +++ b/man/ru/isub.3mpu @@ -0,0 +1,61 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH isub 3 "December 27, 2024" "libmpu" "LibMPU Programmer's Manual" +.SH NAME +\fBisub\fP \- вычитание знаковое и беззнаковое +.SH SYNOPSIS +.nf +.B #include <libmpu.h> +.PP +.BI "void isub( mpu_int *" c ", mpu_int *" a ", mpu_int *" b ", int " nb " ); +.fi +.SH DESCRIPTION +Функция \fBisub()\fP выполняет операцию вычитания целых чисел, расположенных по адресам \fBa\fP и \fBb\fP, +c размещением результата по адресу \fBc\fP. Операнды могут быть числами со знаком или без него. +Содержимое памяти по адресам \fBa\fP, \fBb\fP не изменяется, предыдущее содержимое памяти по адресу +\fBc\fP теряется. Параметр \fBnb\fP определяет размер в байтах, операндов расположенных по адресам +\fBc\fP, \fBa\fP, \fBb\fP. +.PP +Функция воздействует на флаги \fBA\fP, \fBC\fP, \fBO\fP, \fBP\fP, \fBS\fP, \fBZ\fP и \fBV\fP. +.PP +Флаги \fBА\fP и \fBP\fP выставляются только в том случае, когда размер операндов \fBa\fP, \fBb\fP равен одному или +двум байтам (\fBnb\fP == 1 || \fBnb\fP == 2). +.sp +.SH EXAMPLES +.nf +.sp +#include <libmpu.h> +#include <stdio.h> + +int main( void ) +{ + int rc = 0; + + __mpu_init(); + __mpu_extra_warnings = 1; + + { + mpu_int128_t c, a, b; + int nb = NB_I128; + __mpu_char8_t s[256]; + + iatoi( a, "237", nb ); /* evaluate the A variable */ + iatoi( b, "37", nb ); /* evaluate the B variable */ + + isub( c, a, b, nb ); + iitoa( s, c, RADIX_DEC, LOWERCASE, nb ); /* convert C value to ASCII string S */ + printf( "c = %s;\n", s ); /* c = 200; */ + } + + __mpu_free_context(); + + return( rc ); +} +.fi +.sp +.SH SEE ALSO +.BR iadd(3), +.BR iadc(3), +.BR isbb(3). + diff --git a/man/ru/libmpu.7 b/man/ru/libmpu.7 new file mode 100644 index 0000000..4fb129f --- /dev/null +++ b/man/ru/libmpu.7 @@ -0,0 +1,410 @@ +.\" Copyright 2024 Andrew V.Kosteltsev (kx@radix-linux.su) +.\" +.\" +.TH LIBMPU 7 "December 27, 2024" "libmpu" "libmpu Programmer's Manual" +.SH NAME +libmpu \- Math Processor Unit Library (libmpu). +.SH DESCRIPTION +Библиотека выполнена как эмулятор процессора с набором регистров и флагов, устанавливаемых +по результатам проведенных операций. Набор целочисленных функций содержит арифметические, +логические операции, а также всевозможные операции сдвига. Для вещественных и комплексных +чисел реализованы основные тригонометрические функции. +.PP +Разрядность ограничена \fB65536\fP бит для арифметических операций и \fB16384\fP бит для +тригонометрии. Ограничения обусловлены порядком рядов аппроксимации. +.SH Форматы данных +Библиотека поддерживает целые, вещественные и комплексные типы. Переменные хранятся +в массивах байтов. +.sp +.SS Целые числа +В заголовочном файле \fBlibmpu.h\fP определены константы, которые представляют количество +байтов для хранения целых переменных: +.nf +.sp +#define NB_I8 1 +#define NB_I16 2 +#define NB_I32 4 +#define NB_I64 8 +#define NB_I128 16 +#define NB_I256 32 +#define NB_I512 64 +#define NB_I1024 128 +#define NB_I2048 256 +#define NB_I4096 512 +#define NB_I8192 1024 +#define NB_I16384 2048 +#define NB_I32768 4096 +#define NB_I65536 8192 +#define NB_I_MAX 8192 +.fi +.PP +Данные константы можно использовать в качестве значения аргумента \fBnb\fP для операций +с целыми числами. +.PP +В системах с \fBbig\-endian\fP порядком байтов старший байт числа хранится по наименьшему +адресу памяти, а младший байт — по наибольшему. В системе с \fBlittle\-endian\fP порядком +байтов, напротив, младший байт хранится по наименьшему адресу. +.PP +На следующей схеме представлено размещение целого числа в зависимости от архитектуры +машины: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB-1], . . . , [0]; + ┌─────────────────────────── . . . ───────────────────────────┐ + │ high low │ + └─────────────────────────── . . . ───────────────────────────┘ + ^Sign bit + size: NB. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [NB-1]; + ┌─────────────────────────── . . . ───────────────────────────┐ + │ high low │ + └─────────────────────────── . . . ───────────────────────────┘ + ^Sign bit + size: NB. +} +.fi +.PP +Здесь, символ \fBNB\fP — обозначает количество байтов числа. +.PP +Для представления целых переменных, пользователь может самостоятельно создавать массивы +байтов любым из перечисленных ниже способов: +.nf +.sp + __mpu_byte_t a[NB_I65536]; + mpu_int a[NB_I65536]; + + mpu_int *a = (mpu_int *)malloc( NB_I65536 * sizeof(__mpu_byte_t) ); +.fi +.PP +а также использовать, предопределенные в \fBlibmpu.h\fP, типы данных, которые прямо +говорят о размерности: +.nf +.sp + mpu_int4096_t a; +.fi +.PP +Целые числа могут рассматриваться как знаковые (\fIsigned\fP), так и беззнаковые (\fIunsigned\fP). +Знаковые переменные, для удобства операций с ними, представляются в дополнительном коде. +Ниже приведена таблица некоторых значений 8\-разрядной переменной в дополнительном коде. +.nf +.sp + ┌────────────────┬─────────────────┐ + │ Десятичное │ Двоичное │ + │ представление │ представление │ + ├────────────────┼─────────────────┤ + │ 127 │ 0111 1111 │ + │ 3 │ 0000 0011 │ + │ 2 │ 0000 0010 │ + │ 1 │ 0000 0001 │ + │ 0 │ 0000 0000 │ + │ -1 │ 1111 1111 │ + │ -2 │ 1111 1110 │ + │ -3 │ 1111 1101 │ + │ -127 │ 1000 0001 │ + │ -128 │ 1000 0000 │ + └────────────────┴─────────────────┘ +.fi +.sp +.SS Вещественные числа +Вещественные переменные, также как и целые, хранятся в виде массивов байтов. +В заголовочном файле \fBlibmpu.h\fP определены константы, которые представляют +количество байтов для хранения вещественных переменных: +.nf +.sp +#define NB_R32 4 +#define NB_R64 8 +#define NB_R128 16 +#define NB_R256 32 +#define NB_R512 64 +#define NB_R1024 128 +#define NB_R2048 256 +#define NB_R4096 512 +#define NB_R8192 1024 +#define NB_R16384 2048 +#define NB_R32768 4096 +#define NB_R65536 8192 +#define NB_R_MAX 8192 +.fi +.PP +Данные константы можно использовать в качестве значения аргумента \fBnb\fP для +операций с вещественными числами. +.PP +Вещественные числа имеют в своем составе два поля: смещенной экспоненты и мантиссы. +Бит целой единицы неявный. Знак расположен в старшем бите числа. +.PP +На следующей схеме представлено размещение вещественного числа в зависимости +от архитектуры машины: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB-1], . . . , [nS] │ [nS-1], . . . , [0]; + ┌────── . . . ───────┬─────────────── . . . ──────────────────┐ + │ Sign + Exponent │ Significand │ + └────── . . . ───────┴─────────────── . . . ──────────────────┘ + ^Sign bit ^(1. - implicit) + size: nE nS. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [nE-1] │ [nE], . . . , [NB-1]; + ┌────── . . . ───────┬─────────────── . . . ──────────────────┐ + │ Sign + Exponent │ Significand │ + └────── . . . ───────┴─────────────── . . . ──────────────────┘ + ^Sign bit ^(1. - implicit) + size: nE nS. +} +.fi +.PP +Здесь, символы \fBnE\fP и \fBnS\fP — обозначают количество байтов экспоненты и количество +байтов мантиссы, соответственно. +.PP +Количество бит выделяемое для представления знака, экспоненты и мантиссы распределено +следующим образом: +.nf +.sp + ┌───────────────────────┬───────────────────┬─────────────┐ + │ Общее количество бит │ (Sign + Exponent) │ Significand │ + ├───────────────────────┼───────────────────┼─────────────┤ + │ 32 │ 1 + 8 + │ 23 │ + │ 64 │ 1 + 11 + │ 52 │ + │ 128 │ 1 + 31 + │ 96 │ + │ 256 │ 1 + 31 + │ 224 │ + │ 512 │ 1 + 63 + │ 448 │ + │ 1024 │ 1 + 63 + │ 960 │ + │ 2048 │ 1 + 127 + │ 1920 │ + │ 4096 │ 1 + 127 + │ 3968 │ + │ 8192 │ 1 + 255 + │ 7936 │ + │ 16384 │ 1 + 255 + │ 16128 │ + │ 32768 │ 1 + 511 + │ 32256 │ + │ 65536 │ 1 + 511 + │ 65024 │ + └───────────────────────┴───────────────────┴─────────────┘ +.fi +.PP +Форматы 32\- и 64\-битных чисел полностью совпадают с \fBIEEE\fP (Institute of Electrical +and Electronics Engineers) форматом. +.PP +Для удобства декларирования переменных вещественного типа в заголовочном файле +\fBlibmpu.h\fP определены соответствующие типы данных, применение которых может +выглядеть, например, следующим образом: +.nf +.sp + mpu_real16384_t a, b; +.fi +.sp +.SS Не числа +Для расширения вычислительных возможностей в формате чисел с плавающей точкой наряду +с обычными вещественными числами предусмотрено несколько специальных значений. Они +имеют определенный смысл и дают важную информацию об алгоритмах и операциях, в которых +появляются эти значения. К специальным значениям относятся вещественные числа +с нарушением нормализации, неопределенность, нули, бесконечности и не числа, +представленные в следующей таблице. +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 1111 . . . 1111 │ 0000 . . . 0000 │ +/- inf │ + │ S │ 0000 . . . 0000 │ 0000 . . . 0000 │ +/- 0 │ + │ 1 │ 1111 . . . 1111 │ 1000 . . . 0000 │ - ind │ + │ S │ 1111 . . . 1111 │ 0000 . . . 0001 │ +/- NaN (min) │ + │ S │ 1111 . . . 1111 │ 1111 . . . 1111 │ +/- NaN (max) │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ + + Здесь: + +/- inf - +/- бесконечность; + +/- 0 - +/- знаковый нуль; + - ind - неопределенность; + +/- NaN (min) - +/- минимальное не число; + +/- NaN (max) - +/- максимальное не число. +.fi +.PP +Числа с нарушением нормализации: +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 0000 . . . 0000 │ 0000 . . . 0001 │ +/- min │ + │ S │ 0000 . . . 0000 │ 1111 . . . 1111 │ +/- max │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ +.fi +.PP +Кодировка максимального и минимального вещественных чисел: +.nf +.sp + ┌──────┬───────────────────┬───────────────────┬──────────────────┐ + │ Sign │ Exponent │ Significand │ comments │ + ├──────┼───────────────────┼───────────────────┼──────────────────┤ + │ S │ 0000 . . . 0001 │ 0000 . . . 0000 │ +/- MIN │ + │ S │ 1111 . . . 1110 │ 1111 . . . 1111 │ +/- MAX │ + └──────┴───────────────────┴───────────────────┴──────────────────┘ +.fi +.sp +.SS Комплексные числа +Комплексные числа хранятся в памяти машины как структура, состоящая из двух +вещественных чисел. +.PP +Константы, определяющие размер комплексных чисел в байтах, заданы так, что +они представляют половину размера комплексного числа: +.nf +.sp +#define NB_C32 4 +#define NB_C64 8 +#define NB_C128 16 +#define NB_C256 32 +#define NB_C512 64 +#define NB_C1024 128 +#define NB_C2048 256 +#define NB_C4096 512 +#define NB_C8192 1024 +#define NB_C16384 2048 +#define NB_C32768 4096 +#define NB_C65536 8192 +#define NB_C_MAX 8192 +.fi +.PP +Здесь важно отметить, что функции, работающие с комплексными переменными в качестве параметра, +определяющего размер операндов принимают именно эти величины. Таким образом, например, для работы +с переменной типа \fBmpu_complex256_t\fP, на вход функций надо подавать \fBnb\fP = 32 == +\fBNB_C256\fP, в то время, как \fBsizeof\fP(\fBmpu_complex256_t\fP) == 64 == \fBNB_C256\fP * 2. +.PP +Представление комплексных чисел в памяти показано на следующей схеме: +.nf +.sp +if( MPU_BYTE_ORDER_BIG_ENDIAN == 0 ) +{ + [NB*2-1], . . . , [NB] │ [NB-1], . . . , [0]; + ┌──────────── . . . ───────────┬──────────── . . . ───────────┐ + │ Real part │ Imaginary │ + └──────────── . . . ───────────┴──────────── . . . ───────────┘ + size: NB_Real == NB_CXXX NB_Imag == NB_CXXX. +} + +if( MPU_BYTE_ORDER_BIG_ENDIAN == 1 ) +{ + [0], . . . , [NB-1] │ [NB], . . . , [NB*2-1]; + ┌──────────── . . . ───────────┬──────────── . . . ───────────┐ + │ Real part │ Imaginary │ + └──────────── . . . ───────────┴──────────── . . . ───────────┘ + size: NB_Real == NB_CXXX NB_Imag == NB_CXXX. +} +.fi +.PP +Форматы вещественной и мнимой частей комплексных переменных совпадают с форматами вещественных чисел. +.sp +.SH Флаги +Большинство операций с целыми и вещественными числами выставляют флаги. Флаги операций +размещены в целой 32\-битной переменной. Младшие 8 битов [7 ... 0] отданы под флаги +целочисленных операций. Биты с 8\-го по 15\-й занимают флаги, выставляемые операциями +с вещественными числами. +.sp +.SS Флаги целочисленных операций: +.nf +.sp + 7 6 5 4 3 2 1 0 + . . . ─┬────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐ + │ V │ R │ Z │ P │ S │ O │ C │ A │ + . . . ─┴────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘ +.sp + A - Auxiliary Carry Flag (carry from lowest 4-bit word) + C - Carry Flag + O - Overflow Flag + S - Sign Flag + P - Parity Flag (of lowest significant byte) + Z - Zero Flag + R - major || remainder + V - Invalid operation +.fi +.PP +NOTE: Флаги \fBA\fP и \fBP\fP выставляются только операциями над 8\-разрядными +и 16\-разрядными переменными. +.sp +.SS Флаги операций с вещественными переменными: +.nf +.sp + 15 14 13 12 11 10 9 8 + . . . ─┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬ . . . + │ INX │ IND │ PLS │ TLS │ UDF │ OVF │ SNG │ DOM │ + . . . ─┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴ . . . +.sp + DOM - Domain Flag + SNG - Singularity Flag + OVF - Overflow Flag + UDF - Underflow Flag + TLS - TLOSS Flag + PLS - PLOSS Flag + IND - ind-produsing operation Flag + INX - Inexact Flag +.fi +.PP +В заголовочном файле \fBlibmpu.h\fP определены функции работы с флагами, такие как +очистка флагов, сброс, выставление флагов, а также проверки флагов операций. +.sp +.SH Исключения и коды ошибок +Помимо выставления флагов операциями с целыми и вещественными числами, библиотека \fBLibMPU\fP +поддерживает стандартную переменную \fBerrno\fP и, ктоме того, собственные переменные +\fB__mpu_integer_error_no\fP, \fB__mpu_real_error_no\fP, \fB__mpu_complex_error_no\fP, +\fB__mpu_math_error_no\fP. +.PP +Коды ошибок определены в заголовочном файле \fBlibmpu.h\fP. +.PP +Библиотека \fBLibMPU\fP поддерживает обработку ошибок посредством функции +\fB__mpu_math_error()\fP, которая может быть переопределена пользователем +на этапе компоновки объектного кода так, как это возможно при переопределении +функции \fBmatherr()\fP во время компоновки программ со стандартной библиотекой языка \fBC\fP +(например, \fBGNU Libc\fP). +.PP +Кроме того, пользователь может переопределить функцию \fB__mpu_warning()\fP, +которая может выводить дополнительную информацию об ошибках. +.PP +Как и в случае функции \fBmatherr()\fP стандартной библиотеки языка \fBC\fP, +параметром функций \fB__mpu_math_error()\fP, \fB__mpu_warning()\fP является +указатель на структуру \fB__exception\fP: +.nf +.sp +struct __exception +{ + int who; /* _COMPLEX_, _REAL_, _INTEGER_, _MATH_ */ + + int type; + __mpu_char8_t *name; + __mpu_char8_t *msg; + int msg_type; /* >= 1 - error, 0 - warning */ + + int nb_a1; /* number of bytes in arg_1 */ + int nb_a2; /* number of bytes in arg_2 */ + int nb_rv; /* number of bytes in return_value */ + + unsigned char *arg_1; + unsigned char *arg_2; + unsigned char *return_value; +}; +.fi +.PP +в которой определены: источник ошибки, тип ошибки, имя функции выполнение которой +привело к ошибке, а также указатели на аргументы функции и полученное возвращаемое +значение. +.PP +С помощью функции \fB__mpu_utf8mpu_error()\fP можно получить указатель на строковую +константу, содержащую текстовое описание ошибки, соответствующее коду ошибки (см. +переменные \fB__mpu_integer_error_no\fP, \fB__mpu_real_error_no\fP, +\fB__mpu_complex_error_no\fP, \fB__mpu_math_error_no\fP). +.PP +Для простых вычислений, как правило, не приходится переопределять функции +\fBmatherr()\fP, \fB__mpu_math_error()\fP и \fB__mpu_warning()\fP, однако +мы сохранили такую возможность как одну из стандартных возможностей, +предоставляемых библиотекой языка \fBC\fP. +.sp +.SH SEE ALSO +.BR iadd (3), +.BR iadc (3), +.BR isub (3), +.BR isbb (3). |