home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / crypl200.zip / BNLIB / README.BN < prev    next >
Text File  |  1996-05-18  |  8KB  |  183 lines
  1. Welcome to my multiprecision math library!  I'm a little bit proud
  2. of it, particularly its speed.  If you have a machine for which
  3. assembly-language subroutines are available (you can probably guess
  4. from the filename), it will go even faster.  Instructions for
  5. building the library with assembly subroutines are included later.
  6.  
  7. Barring that, on many machines using GCC, the GNU C compiler, helps
  8. the speed significantly, because it not only supports "long long"
  9. 64-bit data types, but it can perform operations on them in line.
  10. Many compilers that support "long long" are rather inefficient when
  11. working with them.
  12.  
  13. For a description of what the library does, see bn.doc.  For a description
  14. of how it's organized, see bnintern.doc.  For the real nitty-gritty,
  15. read the code.  I'm very curious what you all think of it.  One thing I
  16. tried to do was to comment it better than most, although that is more
  17. apparent in the lower-level parts of the code (the lbn* files) that I
  18. wrote first rather than the higher levels, when I didn't need comments
  19. to explain what I was doing to myself.
  20.  
  21. I can't put a full number theory course in the comments, so there
  22. are some parts that are just going to be confusing unless you
  23. have background.  Here's how I suggest judging it: if you stare
  24. at the code for a while, and figure out what's going on, but think
  25. that it was harder than necessary, send me mail explaining how you
  26. think it could be made easier.  If you never manage to figure it out,
  27. then assume that it's something you never learned in school and
  28. it's not my job to teach you.
  29.  
  30. But really, I can't stop you from saying whatever you want.  If you'd
  31. like to send some comments, good or bad, send me some mail.
  32. -- 
  33.     -Colin <colin@nyx.net>
  34.  
  35.  
  36. ** How to build the library
  37.  
  38. For the full details of how all the bits go together, see bnintern.doc.
  39. If you're on a Unix machine, run the "configure" script (generated
  40. from configure.in using GHU autoconf) and it will set things up
  41. automatically.  If you're on another machine, you'll have to do
  42. things by hand, although it's still not hard.
  43.  
  44. This library works in three word sizes: 16, 32 and 64 bits.  The
  45. limiting factor is that it needs a double-word multiply, so even
  46. a 64-bit SPARC must use the 32-bit code, because it only produces
  47. a 64-bit multiply result.  The MIPS, PowerPC and Alpha, however,
  48. can use the 64-bit version, as they provide access to the high
  49. 64 bits of an integer multiply result.
  50.  
  51. If you're compiling a pure C version, or even a simple assembly-language
  52. version, there are some special auto-size-detecting files that will
  53. figure out (at compile time, using <limits.h> and the C preprocessor)
  54. what version to compile and #include it.  To compile that version,
  55. you need to put together the following files:
  56.  
  57. - bn.c
  58. - bn00.c
  59. - lbn00.c
  60. - lbnmem.c
  61.  
  62. The file "bntest00.c" (see README.bntest) is a low-level test program
  63. that will check the correct operation of the library.  It needs to be
  64. linked onl with lbn00.c and lbnmem.c.  The file "sizetest.c" will tell
  65. you what word size it is compiling.  (Or look at the symbols compiled
  66. in the object files.)
  67.  
  68. The file "germtest.c" is a simple program to generate Sophie Germain
  69. primes which demonstrates the library's use.
  70.  
  71. It is possible to include some assembly-language primitives in this.
  72. For example, for the DEC Alpha primitives, you need to compile
  73. everything with the -DBNINCLUDE=lbnalpha.h flag (or somehow get
  74. the effect of "#define BNINCLUDE lbnalpha.h" in all of the code),
  75. and assemble and link in "lbnalpha.s".
  76.  
  77. If you want to compile a specific version of the library, say the
  78. 32-bit version, you need to compile together the following files:
  79.  
  80. - bn.c
  81. - bn32.c
  82. - bninit32.c
  83. - lbn32.c
  84. - lbnmem.c
  85. - legal.c
  86.  
  87. Note the estra "bninit32.c" file.  This is included in "bn00.c",
  88. but is separated out here so that you can compile the library
  89. for two word sizes and select a version to initialize at run
  90. time!  It contains only the function "bnInit()" which does nothing
  91. but call "bnInit_32()".
  92.  
  93. The fun comes when you compile version of the library for two word sizes.
  94. This is currently only supported for the 680x0 and 80x86 processors,
  95. which come in 16- and 32-bit versions, but this also makes sense on
  96. MIPS and PowerPC processors that have 32- and 64-bit versions.
  97.  
  98. To do this, you need to compile 
  99.  
  100. - bn.c
  101. - bn16.c
  102. - bn32.c
  103. - lbn16.c
  104. - lbn32.c
  105. - lbnmem.c
  106. - legal.c
  107. - lbn8086.asm (or lbn68000.c and lbn68020.c for the 680x0)
  108. - bn8086.c (or bn68000.c for the 680x0)
  109.  
  110. Further, you need to compile all the .c files with -DBNINCLUDE=lbn8086.h
  111. (or -DBNINCLUDE=lbn68000.h), or somehow get the effect of
  112. #define BNINCLUDE lbn8086.h
  113. when compiling all the .c files.
  114.  
  115. The lbn8086.asm file contains teh assembly-language subroutines
  116. The lbn8086.h file contains declarations for them and the
  117. necessary information to call them instead of the C versions
  118. The bn8086.c file contains the single function bnInit(), which
  119. determines the word size of the processor when called and calls
  120. bnInit_16() or bnInit_32(), as appropriate.
  121.  
  122. To summarize:
  123. *  To build a 16/32-bit 80x86 version with 16-bit segmented addressing,
  124.    compile with -DBNINCLUDE=lbn8086.h:
  125. - bn.c, bn16.c, bn32.c, lbn16.c, lbn32.c, lbnmem.c, legal.c
  126.   bn8086.c, lbn8086.asm
  127.  
  128. *  To build a 32-bit-only 80x86 version (x >= 3) with 16-bit segmented
  129.    addressing, compile with -DBNINCLUDE=lbn8086.h:
  130. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  131.   lbnmem.c, legal.c, lbn8086.asm
  132.  
  133. *  To build a 32-bit flat-model DOS 80x86 (x >= 3) version,
  134.    compile with -DBNINCLUDE=lbn80386.h:
  135. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  136.   lbnmem.c, legal.c, lbn80386.asm
  137. lbn80386.asm uses Intel assembler mnemonics.
  138.  
  139. *  To build a 32-bit flat-model Unix 80x86 (x >= 3) version,
  140.    compile with -DBNINCLUDE=lbn80386.h:
  141. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  142.   lbnmem.c, legal.c, lbn80386.s
  143. lbn80386.s uses AT&T (Unix) assembler mnemonics.
  144.  
  145. *  To build a 16/32-bit 680x0 version, compile with -DBNINCLUDE=lbn68000.h:
  146. - bn.c, bn16.c, bn32.c, lbn16.c, lbn32.c, lbnmem.c, legal.c, bn68000.c,
  147.   lbn68000.c, lbn68020.c    
  148. lbn68000.c and lbn68020.c use Metrowerks CodeWarrior inline assembler.
  149.  
  150. *  To build a 32-bit 680x0 (x >= 2) version,
  151.    compile with -DBNINCLUDE=lbn68020.h:
  152. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  153.   lbnmem.c, legal.c, lbn68020.c
  154. lbn68020.c uses Metrowerks CodeWarrior inline assembler.
  155.  
  156. *  To build a 32-bit PowerPC version, compile with -DBNINCLUDE=lbnppc.h:
  157. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  158.   lbnmem.c, legal.c, lbnppc.c
  159. lbnppc.c uses Metrowerks CodeWarrior inline assembler.
  160.  
  161. The Intel i960 and DEC Alpha versions (the Alpha uses 64 bits!) operate
  162. similarly.
  163.  
  164. *  To build a 32-bit Intel i960 version, compile with -DBNINCLUDE=lbn960jx.h:
  165. - bn.c, bn00.c (or bn32.c and bninit32.c), lbn00.c (or lbn32.c),
  166.   lbnmem.c, legal.c, lbn960jx.s
  167.  
  168. *  To build a 64-bit DEC Alpha, compile with -DBNINCLUDE=lbnalpha.h:
  169. - bn.c, bn00.c (or bn64.c and bninit64.c), lbn00.c (or lbn64.c),
  170.   lbnmem.c, legal.c, lbnalpha.s
  171.  
  172.  
  173. Note that the 32- and 64-bit files are all generated automatically
  174. from the corresponding 16-bit files, according to the Unix makefile.
  175. If you make changes, it is best to change the 16-bit file and then
  176. generate the 32- and 64-bit files from that.  To generate the
  177. 32-bit file from the 16-bit,
  178. - Replace every "32" in the 16-bit file with "64", THEN
  179. - Replace every "16" in the 16-bit file with "32".
  180.   (If you do this in the other order it won't work!)
  181.  
  182. The 64-bit version is similar, except "32" -> "128" and "16" -> "64".
  183.