| 1 | ============================================================================== |
| 2 | Instructions for OpenSPARC T2 Version 1.0 Legion |
| 3 | ============================================================================== |
| 4 | ## |
| 5 | ## Getting Started with Legion |
| 6 | ## |
| 7 | ## Legion is a fast instruction accurate simulator which provides a rapid |
| 8 | ## means of developing and testing software functionality in the absence |
| 9 | ## of actual hardware. Legion provides the fastest simulation environment |
| 10 | ## for developing and testing SPARC Software and is the primary simulation |
| 11 | ## environment for the Niagara/Niagara2 firmware and software teams. |
| 12 | ## |
| 13 | |
| 14 | [0] System Requirements: |
| 15 | |
| 16 | - Sparc system running Solaris 8 or higher |
| 17 | - 700MB of free disk space |
| 18 | - Root access to the system (if you want to modify the contents of the |
| 19 | disk image) |
| 20 | |
| 21 | [1] Compiling Legion: |
| 22 | |
| 23 | [1.1] Compiling Legion from source |
| 24 | |
| 25 | Legion source code is located under $SIM_ROOT/legion/src |
| 26 | |
| 27 | Tool Requirements: |
| 28 | - cc compiler |
| 29 | - gmake |
| 30 | |
| 31 | These are the steps needed to compile legion from source: |
| 32 | 1) Source the OpenSPARC_SAM.cshrc provided with this bundle |
| 33 | 2) cd legion |
| 34 | 3) mkdir build |
| 35 | 4) cd build |
| 36 | 5) sh ../src/configure.opensparc |
| 37 | 6) gmake -s |
| 38 | |
| 39 | This will generate a sim binary and a plugins directory within |
| 40 | the build directory. |
| 41 | |
| 42 | NOTE - bin/build_legion.sh script provided does all the steps |
| 43 | described above. |
| 44 | |
| 45 | Copy (or create a symbolic link) of sim binary and plugins |
| 46 | directory in to $SIM_ROOT/S10image directory. |
| 47 | |
| 48 | |
| 49 | [2] What is included: |
| 50 | |
| 51 | sim - Legion Simulator binary |
| 52 | plugins - Legion simulation plugins directory |
| 53 | reset.bin - Reset binary for basic processor configuration |
| 54 | q.bin - Hypervisor binary |
| 55 | q - Non Stripped Hypervisor binary (used for debugging) |
| 56 | openboot.bin - Openboot binary |
| 57 | disk1.img - Solaris 10 disk image (512MB, approx 250MB of |
| 58 | free space) |
| 59 | netcons - tool used to connect to legion console socket |
| 60 | |
| 61 | 1c1t/ - 1 core, 1 thread per core |
| 62 | 1c2t/ - 1 core, 2 threads per core |
| 63 | 1c8t/ - 1 core, 8 threads per core |
| 64 | 2c8t/ - 2 cores, 8 threads per core |
| 65 | 4c8t/ - 4 cores, 8 threads per core |
| 66 | 8c8t/ - 8 cores. 8 threads per core |
| 67 | |
| 68 | Each of the above configs directories includes the following files: |
| 69 | legion-guest-domain0.md - Guest Machine Description (used by OBP/OS) |
| 70 | legion-hv.md - Hypervisor Machine Description |
| 71 | legion.conf - Legion config file |
| 72 | |
| 73 | |
| 74 | [3] Environment requirements: |
| 75 | |
| 76 | - Make sure your DISPLAY variable is set so that you can run an xterm |
| 77 | and have it display on your desktop. |
| 78 | - Your path should include the following : |
| 79 | /usr/openwin/bin/xterm # or the path to the xterm of your choice |
| 80 | /usr/lib/cpp # or the path where cpp lives on your machine |
| 81 | . # Current directory |
| 82 | |
| 83 | [4] Running Legion: |
| 84 | |
| 85 | [4.1] Starting Legion: |
| 86 | |
| 87 | Legion need to be run with the -a option and needs to have a config |
| 88 | file specified. The config file is called 'legion.conf' and there is |
| 89 | a specific config file for each config (see list above). |
| 90 | |
| 91 | All of these configs will boot on a single processor sparc machine |
| 92 | although the boot times will take longer for the larger configs. |
| 93 | Legion is fully multi-threaded so it runs larger configs faster on |
| 94 | host machines with more cpus. |
| 95 | |
| 96 | ./sim -a 1c1t/legion.conf |
| 97 | |
| 98 | [4.2] Log file of Console output: |
| 99 | |
| 100 | Legion maintains a log file of the Guest Console. This output |
| 101 | is written to a file called guest1.log. The name of this file |
| 102 | can be changed by modifying the filename in the legion config |
| 103 | files (legion.conf). All output is appended to this file. |
| 104 | |
| 105 | [4.3] Booting Solaris from the ok prompt: |
| 106 | |
| 107 | Once you get the ok prompt, you can : |
| 108 | |
| 109 | [-] View the number of processors in your config: |
| 110 | ok .cpu-state |
| 111 | |
| 112 | [-] Boot from the disk by typing 'boot vdisk' or |
| 113 | 'boot vdisk -vV' for a verbose boot or boot |
| 114 | without any Solaris services for a quicker boot time |
| 115 | by 'boot vdisk -m milestone = none'. |
| 116 | |
| 117 | ok boot vdisk |
| 118 | -or- |
| 119 | ok boot vdisk -vV |
| 120 | -or- |
| 121 | ok boot vdisk -m milestone=none |
| 122 | |
| 123 | [-] There is no root password on this disk so just login as |
| 124 | root and hit return. |
| 125 | |
| 126 | [4.3] Killing the simulation |
| 127 | |
| 128 | When you are done with the simulation, you can terminate it by: |
| 129 | - Ctrl-C in the window where you ran legion |
| 130 | - ~z in the Guest console window |
| 131 | |
| 132 | [5] Debug Tools |
| 133 | |
| 134 | [5.1] Verbose mode: |
| 135 | |
| 136 | Legion can be started in verbose mode using the -v or --verbose flag |
| 137 | # ./sim -v -a 1c1t/legion.conf |
| 138 | |
| 139 | [5.2] Debug mode: |
| 140 | |
| 141 | Legion can be started in debug mode which will dump out debug state |
| 142 | while the simulation is running. An example is if you want to see |
| 143 | the %pc and all sparc instruction that the simulator is executing |
| 144 | along with the register and relevant processor state at each instn |
| 145 | you would use -debug 0x2 |
| 146 | |
| 147 | # ./sim -debug 0x2 -a 1c1t/legion.conf |
| 148 | |
| 149 | The list of debug flags that you can pass is: |
| 150 | |
| 151 | 0000.0000.0000.0001 Parsing messages, initialization, |
| 152 | 0000.0000.0000.0002 PC & Instruction & Registers |
| 153 | 0000.0000.0000.0004 PC & Instruction |
| 154 | 0000.0000.0000.8000 Hypervisor Calls |
| 155 | 0000.0000.0001.0000 Performance Counters |
| 156 | 0000.0000.0002.0000 Exceptions, XIR |
| 157 | 0000.0000.0004.0000 hpstate changes |
| 158 | 0000.0000.0008.0000 MMU |
| 159 | 0000.0000.0010.0000 MMU miss |
| 160 | 0000.0000.0020.0000 Memory controllers |
| 161 | 0000.0000.0040.0000 TSTATE, etc. |
| 162 | 0000.0000.0080.0000 Error injection |
| 163 | 0000.0000.0100.0000 SSI interrupts |
| 164 | 0000.0000.0200.0000 Little Endian |
| 165 | 0000.0000.0400.0000 Alignment errors |
| 166 | 0000.0000.0800.0000 Mondo |
| 167 | 0000.0000.1000.0000 SOFTINT |
| 168 | 0000.0000.2000.0000 TICK |
| 169 | 0000.0000.4000.0000 Instruction decode |
| 170 | 0000.0000.8000.0000 Device |
| 171 | 0000.0001.0000.0000 Execution Loop |
| 172 | 0000.0002.0000.0000 Error Traps |
| 173 | |
| 174 | You can combine multiple debug flags by OR'ing them together. |
| 175 | So if you want to see all the hypervisor calls (0x8000) along |
| 176 | with the parsing information (0x1), you can run it as follows: |
| 177 | |
| 178 | # ./sim -debug 0x8001 -a 1c1t/legion.conf |
| 179 | |
| 180 | [5.3] Dynamic tilde escape sequences: |
| 181 | |
| 182 | Once you have started the simulation you can use the ~ (tilde) |
| 183 | escape sequence in your Legion Guest Console window to dump out |
| 184 | some processor state. The list of tilde commands supported is |
| 185 | as follows: |
| 186 | |
| 187 | # BREAK |
| 188 | ~ generate tilde |
| 189 | z exit simulator |
| 190 | i dump I-TLB contents for CPUs in same domain |
| 191 | d dump D-TLB contents for CPUs in same domain |
| 192 | b toggle the debug output enable bits |
| 193 | n dump the current and delta instruction count for each CPU |
| 194 | ? this message |
| 195 | |
| 196 | So if you want to turn on the %pc and instruction tracing after |
| 197 | you have started the simulation, you can type ~b in the Legion |
| 198 | Guest console window. Typing this gain will turn off the |
| 199 | extra debug output. |
| 200 | |
| 201 | If you want to view the contents of the I-TLB (Instruction TLB) |
| 202 | you can dump it out for all cpus by typing ~i in the Guest |
| 203 | Console window. |
| 204 | |
| 205 | The output will appear in the window where you started legion. |
| 206 | |
| 207 | [6] Modifying the Disk Image |
| 208 | |
| 209 | [6.1] Adding/Removing files to/from the disk |
| 210 | |
| 211 | If you want to add/remove/modify files on the disk image provided, |
| 212 | you will need root access on a system. Here are the instructions |
| 213 | for doing this on a Solaris system. |
| 214 | |
| 215 | # Use the loopback file driver to moun the disk image: |
| 216 | |
| 217 | /usr/sbin/lofiadm -a /export/legion/disk1.img |
| 218 | |
| 219 | # Mount this device onto a mount point: |
| 220 | # where /dev/lofi/1 is the value returned from lofiadm |
| 221 | |
| 222 | /usr/sbin/mount /dev/lofi/1 /mnt |
| 223 | cd /mnt |
| 224 | |
| 225 | You can now add/remove files to/from your disk image |
| 226 | If you get permission problems when accessing the files: |
| 227 | 1) As root, chown/chmod the file/dir that you are modifying |
| 228 | 2) only modify files as the root-user on your host machine |
| 229 | |
| 230 | Once you are done, you can umount the disk image and boot |
| 231 | the simulator. It's always advisable to unmount the disk image |
| 232 | before booting it in the simulator. |
| 233 | |
| 234 | /usr/sbin/umount /mnt |
| 235 | /usr/sbin/lofiadm -d /dev/lofi/1 |
| 236 | |
| 237 | [6.2] Making your disk writable |
| 238 | |
| 239 | By default, legion mounts it's disk image as read-only. That means |
| 240 | that any changes to the disk while running legion will not be |
| 241 | written back to the disk image file on the host machine. If you |
| 242 | want to preserve the changes to the disk, you will have to mount |
| 243 | the disk under legion in write mode (or shared). |
| 244 | To do this: |
| 245 | - edit your legion config file and locate the block where the disk |
| 246 | is mounted (search for virtual_disk). |
| 247 | - change the rom keyword to shared |
| 248 | - now when you boot legion, any changes to the file system within |
| 249 | the simulation will be reflected on the disk image file. You |
| 250 | can get log files off the disk image my lofi mounting it as |
| 251 | described above. |
| 252 | |
| 253 | WARNING!!!: When mounting a disk as shared, you must gracefully exit |
| 254 | the simulation to avoid file system corruption on the disk image. |
| 255 | To do this, sync;halt Solaris within the simulation and wait until |
| 256 | you return to the ok prompt before terminating the simulation by |
| 257 | typing ~z in the Guest Console window. |
| 258 | WARNING!!! |
| 259 | |
| 260 | |
| 261 | [7] Limitations of this Environment: |
| 262 | - Legion only implements enough of the processor state to boot the |
| 263 | firmware and software needed to boot Solaris. There are many areas |
| 264 | of the processor that are not needed in this boot flow and are most |
| 265 | likely not implemented. Areas like caches, RAS, are not implemented |
| 266 | in legion. |
| 267 | - You cannot telnet into or out-of the simulation at this time. |