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