README

   1 MUIS:
   2
   3 ------------------------------------------------------------------------
   4
   5 The mailing list is at muis@foxserver.be. Please send requests to be
   6 added to the list there, as well as any other muis related mail.
   7
   8 Git source repository: http://repo.or.cz/r/muis.git/
   9 If you just want to hack around on your own. Go ahead.
  10
  11 ------------------------------------------------------------------------
  12
  13 Code in the 'benchmarks' folder are not original code.
  14 Code in the 'code' folder, is code adapted or copied from the
  15 'benchmarks' code.
  16 Code in the 'problems' folder is an adaption of code that poses (or
  17 posed) problems with muis.
  18 Code in the 'muis' folder is original code and the main project code.
  19 Code in the root folder is original code and should be organised more
  20 properly.
  21
  22 ------------------------------------------------------------------------
  23
  24 The comments written in the code, as well as the documentation that is
  25 derived from it (using pydoc) provide information about the code
  26 implementation and workings. This document gives an overview of the
  27 modules and what their responsibility is.
  28
  29 aliasdb                     Saves aliases used in the code. These
  30                         textual aliases can be used instead of addresses
  31                         in the code.
  32 convenience                 Convenience module. Contains helper
  33                         functions with no specific use. Mainly used for
  34                         debugging.
  35 muis                        The main module. It parses the command line
  36                         arguments and starts the optimisation process.
  37 options                     Registers options set. Mainly used for
  38                         command line arguments.
  39 regex_support               Contains functions and strings which aid the
  40                         creation of regular expressions.
  41 test_aliasdb                Tests the 'aliasdb'.
  42 test_optimize               Test the optimizer.
  43 test_writer                 Tests the writer.
  44 basic_block                 Contains the structure for a basic block and
  45                         integrity checks.
  46 instruction                 Implements the instruction set of the MIPS
  47                         processor. If the program needs to be used for
  48                         different processors; this, and the 'registers'
  49                         module, should be the only one to change.
  50 optimize                    Does the actual optimization.
  51 reader                      Parses the basic block structure from
  52                         assembler code.
  53 registers                   Contains information about registers,
  54                         including behaviour and  list of all registers
  55                         in of the architecture
  56 test_instruction            Test the instruction set.
  57 test_reader                 Rests the reader.
  58 writer                      Writes basic block structures to assembler
  59                         code.
  60
  61
  62 ETCETERA:
  63
  64 Floating point operations are done using python's built-in floating
  65 point system. On most systems this is Python floats to IEEE-754 "double
  66 precision". In order to correctly (in an assembly sense) compute the
  67 numbers, a floating point calculator has to be created.
  68
  69 Due to the flaws of floating point numbers in computers, it is unsafe to
  70 rely on exact result in programming. So it is relatively safe to use an
  71 alternate floating point algorithm in the optimisation for the single
  72 precision operations.
  73
  74 Should a program respond incorrectly in response, this can correctly be
  75 considered a program bug rather then an optimisation bug, given that
  76 programs should not rely on hardware level floating point
  77 specifications. Especially given the fact double precision floating
  78 point numbers are mathematically more correct than single precision
  79 ones.
  80
  81
  82 BUGS:
  83
  84 A bug has been found with this program in relation to the dhrystone
  85 test. The strangeness of this result was that the problem
  86 manifested itself without optimising. The details of this problem
  87 include that the program does not seem to follow the code as given. Its
  88 behaviour changes when in the original C code changes are made to code
  89 which is not (supposed to be) executed. After following the runtime
  90 characteristics, at one point, it finds a jump expression, but does not
  91 continue the code from the corresponding label. Hence, it could be just
  92 an implementation error of Simple Scalar, but this issue requires more
  93 research. A fleshed down version of the dhrystone assembly code is
  94 included in the problems/ directory for further study on this issue.