发布时间 : 星期六 文章MIRACL用户手册（译）更新完毕开始阅读d542f2ed0975f46527d3e1dc
MIRACL用户手册
译：叶道全 yedaoq@126.com
摘要
Miracl库包含100余个例程，涉及多倍精度运算（multiprecision arithmetic）的各个方面。定义了两种新的数据类型——表示大整数的big类型和表示有理数的flash（short for floating-slash）类型。大整数例程基于Knuth算法（在他的著作“The Art of Computer Programming”第四章中提出）。floating-slash（不固定斜杠？）算法基于圆整小数，最初由D.Matula和P.Kornerup提出。所有例程都针对速度和效率进行了全面的优化，同时也是标准的，可移植的C程序。另外，对于某些时间要求非常严格的算法，Miracl也针对流行的Intel 80x86系列处理器提供了汇编语言实现。Miracl还提供了C++接口。
Miracl的所有源代码都包含于此。
第二章 安装
通过Microsft C/C++、Borlands Turbo C/C++、Watcom C以及DJGPP GNU编译器，MIRACL库已经成功安装到VAX11/780，各种UNIX工作站（Sun，SPARC、Next以及IBM RS/6000），IBM PC等机器上。还有ARM机器和Apple Macintosh。最近MIRACL也已经在Itanium和AMD 64位处理器上运行过了。
MIRACL分发包中包含了库中所有模块的完整源代码以及各自的示例程序。大部分是用标准的ANSI C编写的，可用任意规范的ANSI C编译器进行编译。一些模块包含大量的内联汇编代码，用于优化在某些特定编译器/处理器组合上的性能。通过条件编译，它们可以透明地调用，并且不会影响到其它编译器。批处理文件xxdoit.xxx包含在多种编译器上生成库文件和示例程序的命令。请打开并检查与你的配置相关的文件。
分发包包含了部分流行的编译器的预编译库文件：ready-to-run版本，它们可立即使用，为了节省空间，其中并没有包含所有的示例程序。
要生成一个库，必须使用编译器，文本编译器，链接器，库管理实用程序（librarian utility）以及汇编器（assembler，可选），请阅读编译器文档以获取更多细节。mrmuldv.any文件包含了时间关键（time-critical）
的例程muldiv，muldvd，muldvd2和muldvm的汇编语言版本，它们可能需要根据配置作一些改动。当编译器不支持一个可用于保存两个单字长整数乘积的双倍长度类型时，这些模块尤为必要。许多现代编译器支持这一点（通常称为long long），在这种情况下，一般使用这些模块的C版本mrmuldv.ccc（直接拷贝到mrmuldv.c）就足够了。更多细节请仔细阅读手册以及mrmuldv.any的注释。
必须指定硬件/编译器规格文件mirdef.h。为了协助此过程，提供了此头文件的五个示例：mirdef.h16（16位处理器）、mirdef.h32（32位处理器）、mirdef.haf（工作在16位模式的32位处理器）以及mirdef.hpc（工作在16位环境中的伪32位）。
请注意完整的32位版本是最快的，但只是在使用一个32位处理器及一个32位编译器的时候如此。在Unix环境中使用gcc和g++时尽量用mirdef.gcc。
config.c用于协助配置过程。在目标处理器上编译和运行它，它会自动生成mirdef.h文件，并给出常规的配置建议。它还生成一个miracl.lst文件，其中包含建立相关库时应包含的MIRACL模块列表。强烈建议尝试此程序。编译它时请务必关掉所有编译器优化选项。
mirdef.h文件包含一些可选定义：当无法满足muldvd，muldvd2和muldvm在mrmuldv.c中的版本时，定义MR NOFULLWIDTH；若要在程序中使用flash变量，定义MR_FLASH；MR_LITTLE_ENDIAN 与 MR_BIG_ENDIAN，必须定义其中之一，config.c会自动决定哪一个适用于你的处理器。
省略MR_FLASH时，big变量可以更大，并且生成的库也更小。定义MR_STRIPPED_DOWN将忽略错误消息，可以进一步节约生成的代码空间，请小心使用！
如果不想要任何汇编器，请定义MR_NOASM。这将以内联的方式生成四个时间关键例程的标准C代码。这稍快一些——节省了函数调用的开销——这也是最优编译器得考虑的一点（原文：and also gives an optimising compiler something to chew on）。
使用Microsoft Visual C++时，msvisual.txt中提供了一些有用的建议。Linux操作系统对应的是linux.txt，Borland编译器用户则可以查看borland.txt。
预生成库或.txt文件中提供的建议不可用的时候，通过下列步骤多半能成功地生成MIRACL库： 1. 在目标处理器上编译并运行config.c。
2. 将生成的mirdef.tst重命名为mirdef.h。
3. 根据config程序的建议，从mrmuldv.any中提取一个合适的mrmuldv.c或将标准C版本的mrmuldv.ccc拷贝到mrmuldv.c）。如果是纯汇编，则可以命名为mrmuldv.s或mrmuldv.asm。
4. 如果选择了快速KCM或Comba模乘算法，则编译并运行mex.c实用程序（在任意工作站上）。使用它自动生成mrcomba.c或mrkcm.c，其中需要一个处理器/编译器规格文件xxx.mcs，同时编译器必须支持内联汇编。
5. 确保编译器能访问所有MIRACL头文件。通常标志-I或/I允许访问当前目录中的所有头文件。 6. 编译miracl.lst文件中列出的MIRACL模块并创建库文件，通常是miracl.a或miracl.lib。这可以通过将miracl.lst编译为一个合适的批处理文件或make文件来实现。在UNIX上可以像这样简单：
gcc -I. -c -O2 mr*.c ar rc miracl.a mr*.o
7. 若要使用MIRACL的C++包装，编译所需的模块，例如zzn.cpp和（或）big.cpp等。
8. 将MIRACL库和所需的任意C++模块编译并链接到你的应用程序（原文：Compile and link your application code to any C++ modules it requires and to the MIRACL library）。
记住MIRACL是可移植软件，它可以移植到任意支持某个ANSI C编译器的计算机上。
请注意MIRACL是一个C库，而不是C++。它总是应该作为一个C库来生成，否则你可能得到编译器错误。为在C程序中包含MIRACL例程，请在程序的开始处include头文件miracl.h（在stdio.h之后）。虽然大部分情况下使用C++包装更为可取，你也还是可以通过以下方式在C++程序中直接调用MIRACL例程：
extern \{
#include \}
2.1 优化
在MIRACL的上下文中，这意味着更快的速度。配置MIRACL时需要作的一个关键决策就是确定要使用的底层类型（经常是int类型）。如config所要求的，通常应定义尽可能大的底层类型。如果你有一个64位处理器，你就应该可以指定一个64位的底层类型。在某些场合，使用一个双精度浮点型的底层类型可能更快。
显然纯C的MIRACL产品是最慢的（当然它依然相当地快），它也是最容易入门的。这需要一种宽度是底层类型的两倍的整数类型。在这样的背景下，请注意目前大多数的编译都支持一种long long（有时称为__int64）类型，其尺寸是int的两倍。
如果你的处理器是低端的RISC类型并且不支持整数乘除指令，或需要使用非常大的模数，则
Karatsuba-Montgomery-Comba快速模乘技术可以使乘幂加密系统（exponentiation cryptosystems）更快。config程序将同样针对此点为你提供引导。
有时用汇编语言实现mrmuldv模块会更快。这不需要双倍尺寸的数据类型。如果够幸运你的编译器也支持自动调用内联汇编，则将更变更快。可以在miracl.h中查看哪些编译器支持这种方法。
为获得终极速度，可以使用mrkcm.c，mrcomba.c中实现的非常（extreme，极品）技术，kcmcomba.txt中有关于如何用mex实用程序自动生成这些文件的操作指南。
2.2 从版本3升级
版本4引入了MIRACL实例指针（MIRACL Instance Pointer，mip）。之前的版本使用一些全局和静态变量存储内部状态信息。这主要有两个问题。首先是为了避免冲突，这些全局变量取了一些令人费解的名字；其次是它使得开发多线程应用程序变得更困难。所以从版本4开始，这些变量声明到一个miracl结构中，作为实例变量来引用，必须通过指向miracl结构的指针来访问它们。现在全局指针是MIRACL维护的唯一全局/静态变量。它的值由负责初始化MIRACL库的mirsys例程返回。
C++程序员应注意miracl与Miracl命名上的区别，mip可以通过对Miracl实例取址来获得： Miracl precision = 50; ...