arch/m68k-all/m680x0/060sp/dist/test.doc

   1 #
   2 # $NetBSD: test.doc,v 1.1 2000/04/14 20:24:40 is Exp $
   3 #
   4
   5 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   6 # MOTOROLA MICROPROCESSOR & MEMORY TECHNOLOGY GROUP
   7 # M68000 Hi-Performance Microprocessor Division
   8 # M68060 Software Package Production Release
   9 #
  10 # M68060 Software Package Copyright (C) 1993, 1994, 1995, 1996 Motorola Inc.
  11 # All rights reserved.
  12 #
  13 # THE SOFTWARE is provided on an "AS IS" basis and without warranty.
  14 # To the maximum extent permitted by applicable law,
  15 # MOTOROLA DISCLAIMS ALL WARRANTIES WHETHER EXPRESS OR IMPLIED,
  16 # INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
  17 # FOR A PARTICULAR PURPOSE and any warranty against infringement with
  18 # regard to the SOFTWARE (INCLUDING ANY MODIFIED VERSIONS THEREOF)
  19 # and any accompanying written materials.
  20 #
  21 # To the maximum extent permitted by applicable law,
  22 # IN NO EVENT SHALL MOTOROLA BE LIABLE FOR ANY DAMAGES WHATSOEVER
  23 # (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
  24 # BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS)
  25 # ARISING OF THE USE OR INABILITY TO USE THE SOFTWARE.
  26 #
  27 # Motorola assumes no responsibility for the maintenance and support
  28 # of the SOFTWARE.
  29 #
  30 # You are hereby granted a copyright license to use, modify, and distribute the
  31 # SOFTWARE so long as this entire notice is retained without alteration
  32 # in any modified and/or redistributed versions, and that such modified
  33 # versions are clearly identified as such.
  34 # No licenses are granted by implication, estoppel or otherwise under any
  35 # patents or trademarks of Motorola, Inc.
  36 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37
  38 68060 SOFTWARE PACKAGE (Kernel version) SIMPLE TESTS
  39 -----------------------------------------------------
  40
  41 The files itest.sa and ftest.sa contain simple tests to check
  42 the state of the 68060ISP and 68060FPSP once they have been installed.
  43
  44 Release file format:
  45 --------------------
  46 The release files itest.sa and ftest.sa are essentially
  47 hexadecimal images of the actual tests. This format is the
  48 ONLY format that will be supported. The hex images were created
  49 by assembling the source code and then converting the resulting
  50 binary output images into ASCII text files. The hexadecimal
  51 numbers are listed using the Motorola Assembly syntax assembler
  52 directive "dc.l" (define constant longword). The files can be
  53 converted to other assembly syntaxes by using any word processor
  54 with a global search and replace function.
  55
  56 To assist in assembling and linking these modules with other modules,
  57 the instaler should add symbolic labels to the top of the files.
  58 This will allow the calling routines to access the entry points
  59 of these packages.
  60
  61 The source code itest.s and ftest.s have been included but only
  62 for documentation purposes.
  63
  64 Release file structure:
  65 -----------------------
  66
  67 (top of module)
  68         -----------------
  69         |               | - 128 byte-sized section
  70    (1)  |   Call-Out    | - 4 bytes per entry (user fills these in)
  71         |               |
  72         -----------------
  73         |               | - 8 bytes per entry
  74    (2)  | Entry Point   | - user does "bsr" or "jsr" to this address
  75         |               |
  76         -----------------
  77         |               | - code section
  78    (3)  ~               ~
  79         |               |
  80         -----------------
  81 (bottom of module)
  82
  83 The first section of this module is the "Call-out" section. This section
  84 is NOT INCLUDED in {i,f}test.sa (an example "Call-out" section is provided at
  85 the end of this file). The purpose of this section is to allow the test
  86 routines to reference external printing functions that must be provided
  87 by the host operating system. This section MUST be exactly 128 bytes in
  88 size. There are 32 fields, each 4 bytes in size. Each field corresponds
  89 to a function required by the test packages (these functions and their
  90 location are listed in "68060{ISP,FPSP}-TEST call-outs" below). Each field
  91 entry should contain the address of the corresponding function RELATIVE to
  92 the starting address of the "call-out" section. The "Call-out" section must
  93 sit adjacent to the {i,f}test.sa image in memory. Since itest.sa and ftest.sa
  94 are individual tests, they each require their own "Call-out" sections.
  95
  96 The second section, the "Entry-point" section, is used by external routines
  97 to access the test routines. Since the {i,f}test.sa hex files contain
  98 no symbol names, this section contains function entry points that are fixed
  99 with respect to the top of the package. The currently defined entry-points
 100 are listed in section "68060{ISP,FPSP}-TEST entry points" below. A calling
 101 routine would simply execute a "bsr" or "jsr" that jumped to the selected
 102 function entry-point.
 103
 104 For example, to run the 060ISP test, write a program that includes the
 105 itest.sa data and execute something similar to:
 106
 107         bsr     _060ISP_TEST+128+0
 108
 109 (_060ISP_TEST is the starting address of the "Call-out" section; the "Call-out"
 110 section is 128 bytes long; and the 68060ISP test entry point is located
 111 0 bytes from the top of the "Entry-point" section.)
 112
 113 The third section is the code section. After entering through an "Entry-point",
 114 the entry code jumps to the appropriate test code within the code section.
 115
 116 68060ISP-TEST Call-outs:
 117 ------------------------
 118 0x0: _print_string()
 119 0x4: _print_number()
 120
 121 68060FPSP-TEST Call-outs:
 122 -------------------------
 123 0x0: _print_string()
 124 0x4: _print_number()
 125
 126 The test packages call _print_string() and _print_number()
 127 as subroutines and expect the main program to print a string
 128 or a number to a file or to the screen.
 129 In "C"-like fashion, the test program calls:
 130
 131         print_string("Test passed");
 132
 133                 or
 134
 135         print_number(20);
 136
 137 For _print_string(), the test programs pass a longword address
 138 of the string on the stack. For _print_number(), the test programs pass
 139 a longword number to be printed.
 140
 141 For debugging purposes, after the main program performs a "print"
 142 for a test package, it should flush the output so that it's not
 143 buffered. In this way, if the test program crashes, at least the previous
 144 statements printed will be seen.
 145
 146 68060ISP-TEST Entry-points:
 147 ---------------------------
 148 0x0: integer test
 149
 150 68060FPSP-TEST Entry-points:
 151 ----------------------------
 152 0x00: main fp test
 153 0x08: FP unimplemented test
 154 0x10: FP enabled snan/operr/ovfl/unfl/dz/inex
 155
 156 The floating-point unit test has 3 entry points which will require
 157 3 different calls to the package if each of the three following tests
 158 is desired:
 159
 160 main fp test: tests (1) unimp effective address exception
 161                     (2) unsupported data type exceptions
 162                     (3) non-maskable overflow/underflow exceptions
 163
 164 FP unimplemented: tests FP unimplemented exception. this one is
 165                   separate from the previous tests for systems that don't
 166                   want FP unimplemented instructions.
 167
 168 FP enabled: tests enabled snan/operr/ovfl/unfl/dz/inex.
 169             basically, it enables each of these exceptions and forces
 170             each using an implemented FP instruction. this process
 171             exercizes _fpsp_{snan,operr,ovfl,unfl,dz,inex}() and
 172             _real_{snan,operr,ovfl,unfl,dz,inex}(). the test expects
 173             _real_XXXX() to do nothing except clear the exception
 174             and "rte". if a system's _real_XXXX() handler creates an
 175             alternate result, the test will print "failed" but this
 176             is acceptable.
 177
 178 Miscellaneous:
 179 --------------
 180 Again, itest.sa and ftest.sa are simple tests and do not thoroughly
 181 test all 68060SP connections. For example, they do not test connections
 182 to _real_access(), _real_trace(), _real_trap(), etc. because these
 183 will be system-implemented several different ways and the test packages
 184 must remain system independent.
 185
 186 Example test package set-up:
 187 ----------------------------
 188 _print_str:
 189         .                       # provided by system
 190         rts
 191
 192 _print_num:
 193         .                       # provided by system
 194         rts
 195
 196         .
 197         .
 198         bsr     _060FPSP_TEST+128+0
 199         .
 200         .
 201         rts
 202
 203 # beginning of "Call-out" section; provided by integrator.
 204 # MUST be 128 bytes long.
 205 _060FPSP_TEST:
 206         long    _print_str - _060FPSP_TEST
 207         long    _print_num - _060FPSP_TEST
 208         space   120
 209
 210 # ftest.sa starts here; start of "Entry-point" section.
 211         long    0x60ff0000, 0x00002346
 212         long    0x60ff0000, 0x00018766
 213         long    0x60ff0000, 0x00023338
 214         long    0x24377299, 0xab2643ea
 215                 .
 216                 .
 217                 .