READ_ME 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136
  1. This directory contains test programs for EM implementations.
  2. The test programs are all part of the file "tests".
  3. Each individual test program looks like:
  4. TEST 004: test ...
  5. ... ; data declarations etc.
  6. MAIN nlocal
  7. ... ; part of the body of MAIN
  8. PROC
  9. ... ; subroutines used by this test
  10. The PROC part is optional, so the smallest test program looks like:
  11. TEST 000: null test
  12. MAIN 0
  13. The keywords used by "select", like TEST, MAIN, PROC, HOL, OK and ERRLAB,
  14. all consist of upper case letters and start in column one.
  15. A convention for test numbers is to use 3 digit numbers, possibly left
  16. padded with zero's.
  17. A program, called "select", is provided to combine a range of tests
  18. into a single test program.
  19. "Select" expects a range as argument, like 0-127, or -127, or 0-.
  20. Tests that have a TEST number in that range are included.
  21. "Select" also expects the file from which the tests should
  22. be selected as an argument.
  23. If no argument is given, or only a range argument, select expects
  24. the tests to slect from on standard input.
  25. To prevent name clashes, some rules must be obeyed:
  26. - data label names, procedure names and instruction label numbers
  27. must be unique over all tests. A good habit is to use the
  28. three digit test number as suffix.
  29. - only keyword of "select" may start with uppercase letters in column
  30. one, to allow for expansion in the future.
  31. - because only a single 'hol' pseudo is allowed, "select" must
  32. generate the 'hol' pseudo. An individual test may request
  33. some 'hol' space by a special HOL line, starting in column one
  34. and followed by a single number, the number of bytes needed.
  35. This number must consists of digits only, no constant symbols,
  36. because "select" must compute the maximum, so before the
  37. preprocessor has replaced the constant symbols by their values.
  38. - a similar problem is caused by the number of bytes of local
  39. storage for 'main'. An individual test may specify the number
  40. of bytes it needs as parameter to the MAIN line.
  41. Again, the number must consist of digits only.
  42. Test programs print a sequence of integers greater than 1.
  43. This sequence is terminated by the number 1 as soon as an error is detected.
  44. If all tests are performed correctedly the number 0 is printed.
  45. To allow test programs to print integers without the full machinery of
  46. conversion and i/o routines, the EM instruction 'nop' is used.
  47. Each time this instruction is executed, the current line number as
  48. maintained by the 'lin' instruction must be printed, followed by a
  49. newline, at least during debugging.
  50. The following abbrevation may be used in test programs:
  51. OK -> lin n
  52. nop
  53. Numbers are automatically assigned in order of static appearance.
  54. As soon as an error is detected you must branch to label 1, by instructions
  55. like 'bra *1' and 'zne *1'.
  56. Label 1 is automatically provided in the main routine.
  57. If you jump to label 1 in a subroutine, then that subroutine must
  58. end with ERRLAB, like in:
  59. PROC
  60. pro $test,0
  61. ...
  62. bra *1
  63. ...
  64. ret 0
  65. ERRLAB
  66. end
  67. An option to "select" is to generate 'fil' instructions whenever a
  68. new test starts.
  69. This is useful if 'nop' prints the 'fil' string as well as the 'lin' number.
  70. This 'f' option is on by default, off if a '-f' flag is given.
  71. The EM file generated by "select" includes "test.h".
  72. "test.h" may contain definitions of the following symbols:
  73. W2S: the size of double precision integers, if implemented.
  74. FS: the size of single precision floats, if implemented.
  75. F2S: the size of double precision floats, if implemented.
  76. The value of these symbols, if defined, must be the size of the object involved.
  77. Two other symbols are used:
  78. EM_PSIZE: pointer size
  79. EM_WSIZE: word size
  80. The machine dependent translation program, like 8086 and vax2, give
  81. definitions of these symbols while calling the EM encode program.
  82. Because these size names occur quite often, they may be abbreviated:
  83. WS -> EM_WSIZE
  84. PS -> EM_PSIZE
  85. Before running the tests in the file "tests", it is wise to test
  86. the necessary basic functions with some simple tests like
  87. TEST 000: null
  88. MAIN 0
  89. and
  90. TEST 001: ok
  91. MAIN 0
  92. OK
  93. and
  94. TEST 998: error
  95. MAIN 0
  96. bra *1
  97. and
  98. TEST 999: test lni
  99. MAIN 0
  100. lin 1
  101. lni
  102. loe 0
  103. loc 2
  104. bne *1
  105. OK
  106. The first two of these are part of "tests" as well. The last two are
  107. not included in "tests" intensionally, because they would fail.
  108. The last tests fails because it references the ABS block which is
  109. inaccessable after an 'hol' pseudo.
  110. Proceed as follows for each of these basic tests:
  111. - make a file called 'basic' containing the test
  112. - run select:
  113. select basic >basic.e
  114. - compile by
  115. machine basic.e
  116. - and load and run
  117. where machine should be replaced by the name of program
  118. used to compile EM programs for the current machine.