Commit | Line | Data |
---|---|---|
920dae64 AT |
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. |