This is pintos.info, produced by makeinfo version 4.8 from pintos.texi.  File: pintos.info, Node: GDB, Next: Triple Faults, Prev: Backtraces, Up: Debugging Tools E.5 GDB ======= You can run Pintos under the supervision of the GDB debugger. First, start Pintos with the `--gdb' option, e.g. `pintos --gdb -- run mytest'. Second, open a second terminal on the same machine and use `pintos-gdb' to invoke GDB on `kernel.o':(1) pintos-gdb kernel.o and issue the following GDB command: target remote localhost:1234 Now GDB is connected to the simulator over a local network connection. You can now issue any normal GDB commands. If you issue the `c' command, the simulated BIOS will take control, load Pintos, and then Pintos will run in the usual way. You can pause the process at any point with . * Menu: * Using GDB:: * Example GDB Session:: * Debugging User Programs:: * GDB FAQ:: ---------- Footnotes ---------- (1) `pintos-gdb' is a wrapper around `gdb' (80X86) or `i386-elf-gdb' (SPARC) that loads the Pintos macros at startup.  File: pintos.info, Node: Using GDB, Next: Example GDB Session, Up: GDB E.5.1 Using GDB --------------- You can read the GDB manual by typing `info gdb' at a terminal command prompt. Here's a few commonly useful GDB commands: -- GDB Command: c Continues execution until or the next breakpoint. -- GDB Command: break function -- GDB Command: break file:line -- GDB Command: break *address Sets a breakpoint at FUNCTION, at LINE within FILE, or ADDRESS. (Use a `0x' prefix to specify an address in hex.) Use `break main' to make GDB stop when Pintos starts running. -- GDB Command: p expression Evaluates the given EXPRESSION and prints its value. If the expression contains a function call, that function will actually be executed. -- GDB Command: l *address Lists a few lines of code around ADDRESS. (Use a `0x' prefix to specify an address in hex.) -- GDB Command: bt Prints a stack backtrace similar to that output by the `backtrace' program described above. -- GDB Command: p/a address Prints the name of the function or variable that occupies ADDRESS. (Use a `0x' prefix to specify an address in hex.) -- GDB Command: diassemble function Disassembles FUNCTION. We also provide a set of macros specialized for debugging Pintos, written by Godmar Back . You can type `help user-defined' for basic help with the macros. Here is an overview of their functionality, based on Godmar's documentation: -- GDB Macro: debugpintos Attach debugger to a waiting pintos process on the same machine. Shorthand for `target remote localhost:1234'. -- GDB Macro: dumplist list type element Prints the elements of LIST, which should be a `struct' list that contains elements of the given TYPE (without the word `struct') in which ELEMENT is the `struct list_elem' member that links the elements. Example: `dumplist all_list thread all_elem' prints all elements of `struct thread' that are linked in `struct list all_list' using the `struct list_elem all_elem' which is part of `struct thread'. (This assumes that you have added `all_list' and `all_elem' yourself.) -- GDB Macro: btthread thread Shows the backtrace of THREAD, which is a pointer to the `struct thread' of the thread whose backtrace it should show. For the current thread, this is identical to the `bt' (backtrace) command. It also works for any thread suspended in `schedule()', provided you know where its kernel stack page is located. -- GDB Macro: btthreadlist list element Shows the backtraces of all threads in LIST, the `struct list' in which the threads are kept. Specify ELEMENT as the `struct list_elem' field used inside `struct thread' to link the threads together. Example: `btthreadlist all_list all_elem' shows the backtraces of all threads contained in `struct list all_list', linked together by `all_elem'. This command is useful to determine where your threads are stuck when a deadlock occurs. Please see the example scenario below. (This assumes that you have added `all_list' and `all_elem' yourself.) -- GDB Macro: btpagefault Print a backtrace of the current thread after a page fault exception. Normally, when a page fault exception occurs, GDB will stop with a message that might say: Program received signal 0, Signal 0. 0xc0102320 in intr0e_stub () In that case, the `bt' command might not give a useful backtrace. Use `btpagefault' instead. You may also use `btpagefault' for page faults that occur in a user process. In this case, you may also wish to load the user program's symbol table (*note Debugging User Programs::). -- GDB Macro: hook-stop GDB invokes this macro every time the simulation stops, which Bochs will do for every processor exception, among other reasons. If the simulation stops due to a page fault, `hook-stop' will print a message that says and explains further whether the page fault occurred in the kernel or in user code. If the exception occurred from user code, `hook-stop' will say: pintos-debug: a page fault exception occurred in user mode pintos-debug: hit 'c' to continue, or 's' to step to intr_handler In Project 2, a page fault in a user process leads to the termination of the process. You should expect those page faults to occur in the robustness tests where we test that your kernel properly terminates processes that try to access invalid addresses. To debug those, set a break point in `page_fault()' in `exception.c', which you will need to modify accordingly. In Project 3, a page fault in a user process no longer automatically leads to the termination of a process. Instead, it may require reading in data for the page the process was trying to access, either because it was swapped out or because this is the first time it's accessed. In either case, you will reach `page_fault()' and need to take the appropriate action there. If the page fault did not occur in user mode while executing a user process, then it occurred in kernel mode while executing kernel code. In this case, `hook-stop' will print this message: pintos-debug: a page fault occurred in kernel mode followed by the output of the `btpagefault' command. Before Project 3, a page fault exception in kernel code is always a bug in your kernel, because your kernel should never crash. Starting with Project 3, the situation will change if you use `get_user()' and `put_user()' strategy to verify user memory accesses (*note Accessing User Memory::). If you don't want GDB to stop for page faults, then issue the command `handle SIGSEGV nostop'. GDB will still print a message for every page fault, but it will not come back to a command prompt.  File: pintos.info, Node: Example GDB Session, Next: Debugging User Programs, Prev: Using GDB, Up: GDB E.5.2 Example GDB Session ------------------------- This section narrates a sample GDB session, provided by Godmar Back. This example illustrates how one might debug a Project 1 solution in which occasionally a thread that calls `timer_sleep()' is not woken up. With this bug, tests such as `mlfqs_load_1' get stuck. This session was captured with a slightly older version of Bochs and the GDB macros for Pintos, so it looks slightly different than it would now. Program output is shown in normal type, user input in *strong* type. First, I start Pintos: $ *pintos -v --gdb -- -q -mlfqs run mlfqs-load-1* Writing command line to /tmp/gDAlqTB5Uf.dsk... bochs -q ======================================================================== Bochs x86 Emulator 2.2.5 Build from CVS snapshot on December 30, 2005 ======================================================================== 00000000000i[ ] reading configuration from bochsrc.txt 00000000000i[ ] Enabled gdbstub 00000000000i[ ] installing nogui module as the Bochs GUI 00000000000i[ ] using log file bochsout.txt Waiting for gdb connection on localhost:1234 Then, I open a second window on the same machine and start GDB: $ *pintos-gdb kernel.o* GNU gdb Red Hat Linux (6.3.0.0-1.84rh) Copyright 2004 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "i386-redhat-linux-gnu"... Using host libthread_db library "/lib/libthread_db.so.1". Then, I tell GDB to attach to the waiting Pintos emulator: (gdb) *debugpintos* Remote debugging using localhost:1234 0x0000fff0 in ?? () Reply contains invalid hex digit 78 Now I tell Pintos to run by executing `c' (short for `continue') twice: (gdb) *c* Continuing. Reply contains invalid hex digit 78 (gdb) *c* Continuing. Now Pintos will continue and output: Pintos booting with 4,096 kB RAM... Kernel command line: -q -mlfqs run mlfqs-load-1 374 pages available in kernel pool. 373 pages available in user pool. Calibrating timer... 102,400 loops/s. Boot complete. Executing 'mlfqs-load-1': (mlfqs-load-1) begin (mlfqs-load-1) spinning for up to 45 seconds, please wait... (mlfqs-load-1) load average rose to 0.5 after 42 seconds (mlfqs-load-1) sleeping for another 10 seconds, please wait... ...until it gets stuck because of the bug I had introduced. I hit in the debugger window: Program received signal 0, Signal 0. 0xc010168c in next_thread_to_run () at ../../threads/thread.c:649 649 while (i <= PRI_MAX && list_empty (&ready_list[i])) (gdb) The thread that was running when I interrupted Pintos was the idle thread. If I run `backtrace', it shows this backtrace: (gdb) *bt* #0 0xc010168c in next_thread_to_run () at ../../threads/thread.c:649 #1 0xc0101778 in schedule () at ../../threads/thread.c:714 #2 0xc0100f8f in thread_block () at ../../threads/thread.c:324 #3 0xc0101419 in idle (aux=0x0) at ../../threads/thread.c:551 #4 0xc010145a in kernel_thread (function=0xc01013ff , aux=0x0) at ../../threads/thread.c:575 #5 0x00000000 in ?? () Not terribly useful. What I really like to know is what's up with the other thread (or threads). Since I keep all threads in a linked list called `all_list', linked together by a `struct list_elem' member named `all_elem', I can use the `btthreadlist' macro from the macro library I wrote. `btthreadlist' iterates through the list of threads and prints the backtrace for each thread: (gdb) *btthreadlist all_list all_elem* pintos-debug: dumping backtrace of thread 'main' @0xc002f000 #0 0xc0101820 in schedule () at ../../threads/thread.c:722 #1 0xc0100f8f in thread_block () at ../../threads/thread.c:324 #2 0xc0104755 in timer_sleep (ticks=1000) at ../../devices/timer.c:141 #3 0xc010bf7c in test_mlfqs_load_1 () at ../../tests/threads/mlfqs-load-1.c:49 #4 0xc010aabb in run_test (name=0xc0007d8c "mlfqs-load-1") at ../../tests/threads/tests.c:50 #5 0xc0100647 in run_task (argv=0xc0110d28) at ../../threads/init.c:281 #6 0xc0100721 in run_actions (argv=0xc0110d28) at ../../threads/init.c:331 #7 0xc01000c7 in main () at ../../threads/init.c:140 pintos-debug: dumping backtrace of thread 'idle' @0xc0116000 #0 0xc010168c in next_thread_to_run () at ../../threads/thread.c:649 #1 0xc0101778 in schedule () at ../../threads/thread.c:714 #2 0xc0100f8f in thread_block () at ../../threads/thread.c:324 #3 0xc0101419 in idle (aux=0x0) at ../../threads/thread.c:551 #4 0xc010145a in kernel_thread (function=0xc01013ff , aux=0x0) at ../../threads/thread.c:575 #5 0x00000000 in ?? () In this case, there are only two threads, the idle thread and the main thread. The kernel stack pages (to which the `struct thread' points) are at 0xc0116000 and 0xc002f000, respectively. The main thread is stuck in `timer_sleep()', called from `test_mlfqs_load_1'. Knowing where threads are stuck can be tremendously useful, for instance when diagnosing deadlocks or unexplained hangs.  File: pintos.info, Node: Debugging User Programs, Next: GDB FAQ, Prev: Example GDB Session, Up: GDB E.5.3 Debugging User Programs ----------------------------- You can also use GDB to debug a user program running under Pintos. Start by issuing this GDB command to load the program's symbol table: add-symbol-file PROGRAM where PROGRAM is the name of the program's executable (in the host file system, not in the Pintos file system). After this, you should be able to debug the user program the same way you would the kernel, by placing breakpoints, inspecting data, etc. Your actions apply to every user program running in Pintos, not just to the one you want to debug, so be careful in interpreting the results. Also, a name that appears in both the kernel and the user program will actually refer to the kernel name. (The latter problem can be avoided by giving the user executable name on the GDB command line, instead of `kernel.o', and then using `add-symbol-file' to load `kernel.o'.)  File: pintos.info, Node: GDB FAQ, Prev: Debugging User Programs, Up: GDB E.5.4 FAQ --------- GDB can't connect to Bochs. If the `target remote' command fails, then make sure that both GDB and `pintos' are running on the same machine by running `hostname' in each terminal. If the names printed differ, then you need to open a new terminal for GDB on the machine running `pintos'. GDB doesn't recognize any of the macros. If you start GDB with `pintos-gdb', it should load the Pintos macros automatically. If you start GDB some other way, then you must issue the command `source PINTOSDIR/src/misc/gdb-macros', where PINTOSDIR is the root of your Pintos directory, before you can use them. Can I debug Pintos with DDD? Yes, you can. DDD invokes GDB as a subprocess, so you'll need to tell it to invokes `pintos-gdb' instead: ddd --gdb --debugger pintos-gdb Can I use GDB inside Emacs? Yes, you can. Emacs has special support for running GDB as a subprocess. Type `M-x gdb' and enter your `pintos-gdb' command at the prompt. The Emacs manual has information on how to use its debugging features in a section titled "Debuggers." GDB is doing something weird. If you notice strange behavior while using GDB, there are three possibilities: a bug in your modified Pintos, a bug in Bochs's interface to GDB or in GDB itself, or a bug in the original Pintos code. The first and second are quite likely, and you should seriously consider both. We hope that the third is less likely, but it is also possible.  File: pintos.info, Node: Triple Faults, Next: Modifying Bochs, Prev: GDB, Up: Debugging Tools E.6 Triple Faults ================= When a CPU exception handler, such as a page fault handler, cannot be invoked because it is missing or defective, the CPU will try to invoke the "double fault" handler. If the double fault handler is itself missing or defective, that's called a "triple fault." A triple fault causes an immediate CPU reset. Thus, if you get yourself into a situation where the machine reboots in a loop, that's probably a "triple fault." In a triple fault situation, you might not be able to use `printf()' for debugging, because the reboots might be happening even before everything needed for `printf()' is initialized. There are at least two ways to debug triple faults. First, you can run Pintos in Bochs under GDB (*note GDB::). If Bochs has been built properly for Pintos, a triple fault under GDB will cause it to print the message "Triple fault: stopping for gdb" on the console and break into the debugger. (If Bochs is not running under GDB, a triple fault will still cause it to reboot.) You can then inspect where Pintos stopped, which is where the triple fault occurred. Another option is what I call "debugging by infinite loop." Pick a place in the Pintos code, insert the infinite loop `for (;;);' there, and recompile and run. There are two likely possibilities: * The machine hangs without rebooting. If this happens, you know that the infinite loop is running. That means that whatever caused the reboot must be _after_ the place you inserted the infinite loop. Now move the infinite loop later in the code sequence. * The machine reboots in a loop. If this happens, you know that the machine didn't make it to the infinite loop. Thus, whatever caused the reboot must be _before_ the place you inserted the infinite loop. Now move the infinite loop earlier in the code sequence. If you move around the infinite loop in a "binary search" fashion, you can use this technique to pin down the exact spot that everything goes wrong. It should only take a few minutes at most.  File: pintos.info, Node: Modifying Bochs, Next: Debugging Tips, Prev: Triple Faults, Up: Debugging Tools E.7 Modifying Bochs =================== An advanced debugging technique is to modify and recompile the simulator. This proves useful when the simulated hardware has more information than it makes available to the OS. For example, page faults have a long list of potential causes, but the hardware does not report to the OS exactly which one is the particular cause. Furthermore, a bug in the kernel's handling of page faults can easily lead to recursive faults, but a "triple fault" will cause the CPU to reset itself, which is hardly conducive to debugging. In a case like this, you might appreciate being able to make Bochs print out more debug information, such as the exact type of fault that occurred. It's not very hard. You start by retrieving the source code for Bochs 2.2.6 from `http://bochs.sourceforge.net' and saving the file `bochs-2.2.6.tar.gz' into a directory. The script `pintos/src/misc/bochs-2.2.6-build.sh' applies a number of patches contained in `pintos/src/misc' to the Bochs tree, then builds Bochs and installs it in a directory of your choice. Run this script without arguments to learn usage instructions. To use your `bochs' binary with `pintos', put it in your `PATH', and make sure that it is earlier than `/home/courses/cs3204/bin/bochs'. Of course, to get any good out of this you'll have to actually modify Bochs. Instructions for doing this are firmly out of the scope of this document. However, if you want to debug page faults as suggested above, a good place to start adding `printf()'s is `BX_CPU_C::dtranslate_linear()' in `cpu/paging.cc'.  File: pintos.info, Node: Debugging Tips, Prev: Modifying Bochs, Up: Debugging Tools E.8 Tips ======== The page allocator in `threads/palloc.c' and the block allocator in `threads/malloc.c' clear all the bytes in memory to 0xcc at time of free. Thus, if you see an attempt to dereference a pointer like 0xcccccccc, or some other reference to 0xcc, there's a good chance you're trying to reuse a page that's already been freed. Also, byte 0xcc is the CPU opcode for "invoke interrupt 3," so if you see an error like `Interrupt 0x03 (#BP Breakpoint Exception)', then Pintos tried to execute code in a freed page or block. An assertion failure on the expression `sec_no < d->capacity' indicates that Pintos tried to access a file through an inode that has been closed and freed. Freeing an inode clears its starting sector number to 0xcccccccc, which is not a valid sector number for disks smaller than about 1.6 TB.  File: pintos.info, Node: Development Tools, Next: Installing Pintos, Prev: Debugging Tools, Up: Top Appendix F Development Tools **************************** Here are some tools that you might find useful while developing code. * Menu: * Tags:: * cscope:: * CVS:: * VNC:: * Cygwin::  File: pintos.info, Node: Tags, Next: cscope, Up: Development Tools F.1 Tags ======== Tags are an index to the functions and global variables declared in a program. Many editors, including Emacs and `vi', can use them. The `Makefile' in `pintos/src' produces Emacs-style tags with the command `make TAGS' or `vi'-style tags with `make tags'. In Emacs, use `M-.' to follow a tag in the current window, `C-x 4 .' in a new window, or `C-x 5 .' in a new frame. If your cursor is on a symbol name for any of those commands, it becomes the default target. If a tag name has multiple definitions, `M-0 M-.' jumps to the next one. To jump back to where you were before you followed the last tag, use `M-*'.  File: pintos.info, Node: cscope, Next: CVS, Prev: Tags, Up: Development Tools F.2 cscope ========== The `cscope' program also provides an index to functions and variables declared in a program. It has some features that tag facilities lack. Most notably, it can find all the points in a program at which a given function is called. The `Makefile' in `pintos/src' produces `cscope' indexes when it is invoked as `make cscope'. Once the index has been generated, run `cscope' from a shell command line; no command-line arguments are normally necessary. Then use the arrow keys to choose one of the search criteria listed near the bottom of the terminal, type in an identifier, and hit . `cscope' will then display the matches in the upper part of the terminal. You may use the arrow keys to choose a particular match; if you then hit , `cscope' will invoke the default system editor(1) and position the cursor on that match. To start a new search, type . To exit `cscope', type `Ctrl-d'. Emacs and some versions of `vi' have their own interfaces to `cscope'. For information on how to use these interface, visit the `cscope' home page (http://cscope.sourceforge.net). ---------- Footnotes ---------- (1) This is typically `vi'. To exit `vi', type `: q '.  File: pintos.info, Node: CVS, Next: VNC, Prev: cscope, Up: Development Tools F.3 CVS ======= CVS is a version-control system. That is, you can use it to keep track of multiple versions of files. The idea is that you do some work on your code and test it, then check it into the version-control system. If you decide that the work you've done since your last check-in is no good, you can easily revert to the last checked-in version. Furthermore, you can retrieve any old version of your code as of some given day and time. The version control logs tell you who made changes and when. CVS is not the best version control system out there, but it's free, it's fairly easy to use, and it's already installed in most Unix-like environments. For more information, visit the CVS home page. If you are using an IDE, check whether it supports CVS automatically. * Menu: * Setting Up CVS:: * Using CVS:: * CVS Locking:: * Setting Up ssh::  File: pintos.info, Node: Setting Up CVS, Next: Using CVS, Up: CVS F.3.1 Setting Up CVS -------------------- To set up CVS for use with Pintos, start by choosing one group member as the keeper of the CVS repository. Everyone in the group will be able to use the CVS repository, but the keeper will actually create the repository and maintain permissions for its contents. The following instructions are specific to our local setup, starting with the Fall 2006 semester. Even if you've used CVS before, we ask that you read the instructions in their entirety. Repositories must be created on the machine 'ap2.cs.vt.edu'. This machine contains a directory that was specially set up for CS 3204 students' CVS repositories. To access the repository from the other machines, you should first configure ssh to log you on automatically, without requiring a password every time. *Note Setting Up ssh::, for more information. To connect to this machine use `ssh ap2.cs.vt.edu' from your machine. You should not be prompted for a password if you have configured ssh properly. The keeper has to perform several steps to set up the repository. First, log on to 'ap2.cs.vt.edu' and create a directory for storing the repository. The new directory must be created in the directory `/shared/cs3204' and should be named `Proj-KEEPER_PID', where KEEPER_PID is the pid of the keeper. Next, configure access to repository using the command `setfacl --set u::rwx,g::---,o::--- Proj-KEEPER_PID'. This command ensures that the user, i.e the keeper has the required permissions to access the repository, and no one else does. To set permissions for the other members in the group, use `setfacl -m u:MEMBER_PID:rwx Proj-KEEPER_PID' for each of the other members in the group, replacing MEMBER_PID with the pid of the group member. Next, set the permissions of the directories and files that would be created inside the repository using the command `setfacl -d --set u::rwx,g::---,o::--- Proj-KEEPER_PID'. To permit all the members of the group access to all the files and directories created in the repository, use `setfacl -d -m u:MEMBER_PID:rwx Proj-KEEPER_PID' once for each group member (should be used once for the keeper too), replacing MEMBER_PID with the pid of the group member. To make sure that the permissions are set correctly, use `getfacl Proj-KEEPER_PID'. Note that neither (Unix-) group members nor others should have read access to your CVS repository, hence the `g::---,o::---' part of the access control list. (Giving access to group members (in the Unix sense) would give access to, for instance, all CS majors if your default (Unix-) group is Major. We use ACLs to give individual access to your CS 3204 group members.) *Failing to protect your repository in this way is an honor code violation.* Now initialize the repository. To initialize the repository, execute `cvs -d /shared/cs3204/Proj-KEEPER_PID init'. Finally, import the Pintos sources into the newly initialized repository. If you have an existing set of Pintos sources you want to add to the repository, `cd' to its `pintos' directory now. Otherwise, to import the base Pintos source tree, `cd' to `/home/courses/cs3204/pintos/pintos' (note the doubled `pintos'). After changing the current directory, execute this command: cvs -d /shared/cs3204/Proj-KEEPER_PID import -m "Imported sources" pintos foobar start Here is a summary of the commands you have now executed: ssh ap2.cs.vt.edu cd /shared/cs3204 mkdir Proj-KEEPER_PID setfacl --set u::rwx,g::---,o::--- Proj-KEEPER_PID # for all other group members do: setfacl -m u:MEMBER-PID:rwx Proj-KEEPER_PID setfacl -d --set u::rwx,g::---,o::--- Proj-KEEPER_PID # for all group members, including the keeper, do: setfacl -d -m u:MEMBER_PID:rwx Proj-KEEPER_PID cvs -d /shared/cs3204/Proj-KEEPER_PID init cd /home/courses/cs3204/pintos/pintos cvs -d /shared/cs3204/Proj-KEEPER_PID import -m "Imported sources" pintos foobar start The repository is now ready for use by any group member, as described below. Having set the repository up, you need not log on to 'ap2.cs.vt.edu' for any other purposes. Keep in mind that the repository should only be accessed using CVS commands--it is not generally useful to examine the repository files by hand, and you should definitely not modify them yourself. Due to space constraints, 'ap2.cs.vt.edu'should be used only to store the repository and not for development purposes. Do not store any other files there and do not run any other programs on this machine. The reason for this somewhat unusual setup is that our shared file servers currently do not support the `setfacl' commands, making it impossible to protect your CVS repository.  File: pintos.info, Node: Using CVS, Next: CVS Locking, Prev: Setting Up CVS, Up: CVS F.3.2 Using CVS --------------- Some of the CVS commands require you to specify the location of the repository. As the repository has been set up in the machine 'ap2.cs.vt.edu' and you would not be using this machine for development purposes, you have to use `:ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID' as the location of the repository. YOUR_PID is your pid and is needed to log you on to 'ap2.cs.vt.edu'. CVS runs on top of ssh. Therefore, before using any of the CVS commands, make sure you have configured ssh to log you on without prompting for password (*Note Setting Up ssh::, for more information) and set the environment variable CVS_RSH to `/usr/bin/ssh'. Under csh you can set this environment variable using `setenv CVS_RSH /usr/bin/ssh'. To avoid having to type this line everytime you log on, add this line to the '.cshrc' file in your home directory. To use CVS, start by checking out a working copy of the contents of the CVS repository into a directory named `DIR'. To do so, execute `cvs -d :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -d DIR pintos'. If this fails due to some kind of permission problem, the CVS repository may not be initialized properly. Note that there are two `-d' switches in the previous command. The first switch specifies the location of the CVS repository to which the command applies. In this case, the repository is located on the machine AP2 and is reachable via ssh with your_pid. The second `-d' switch is specific to the cvs checkout command. It specifies the local directory into which to check out the module 'pintos'. If omitted, pintos will be checked out into a directory called 'pintos'. Your working copy is kept in your undergrad file space. Unlike the CVS repository, this directory is shared among the lab machines, so you do not need to be logged on to any specific machine to use it. Like the CVS repository, you must read-protect your working copy from (Unix-) group members and others to comply with the honor code. `chmod -R go-rwx DIR' will read-protect your working directory. At this point, you can modify any of the files in the working copy. You can see the changes you've made with `cvs diff -u'. If you want to commit these changes back to the repository, making them visible to the other group members, you can use the CVS commit command. Within the `pintos' directory, execute `cvs commit'. This will figure out the files that have been changed and fire up a text editor for you to describe the changes. By default, this editor is `vi', but you can select a different editor by setting the `CVSEDITOR' environment variable, e.g. with `setenv CVSEDITOR emacs' (add this line to your `.cshrc' to make it permanent). Suppose another group member has committed changes. You can see the changes committed to the repository since the time you checked it out (or updated from it) with `cvs diff -u -r BASE -r HEAD'. You can merge those change into your working copy using `cvs update'. If any of your local changes conflict with the committed changes, the CVS command output should tell you. In that case, edit the files that contain conflicts, looking for `<<<' and `>>>' that denote the conflicts, and fix the problem. You can view the history of FILE in your working directory, including the log messages, with `cvs log FILE'. You can give a particular set of file versions a name called a "tag". First `cd' to the root of the working copy, then execute `cvs tag NAME'. It's best to have no local changes in the working copy when you do this, because the tag will not include uncommitted changes. To recover the tagged repository later, use the `checkout' command in the form `cvs -d :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -r TAG -d DIR pintos', where DIR is the directory to put the tagged repository into. If you add a new file to the source tree, you'll need to add it to the repository with `cvs add FILE'. This command does not have lasting effect until the file is committed later with `cvs commit'. To remove a file from the source tree, first remove it from the file system with `rm', then tell CVS with `cvs remove FILE'. Again, only `cvs commit' will make the change permanent. To discard your local changes for a given file, without committing them, use `cvs update -C FILE'. To check out a version of your repository as of a particular date, use the command `cvs -d :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -D 'DATE' -d DIR pintos', where DIR is the directory to put the tagged repository into. A typical format for DATE is `YYYY-MM-DD HH:MM', but CVS accepts several formats, even something like `1 hour ago'. For more information, visit the CVS home page. If you are using an IDE, check whether it supports CVS automatically.  File: pintos.info, Node: CVS Locking, Next: Setting Up ssh, Prev: Using CVS, Up: CVS F.3.3 CVS Locking ----------------- You might occasionally see a message like this while using CVS: waiting for member_pid's lock in /shared/cs3204/Proj-keeper_pid/cvsroot/foo This normally means that more than one user is accessing the repository at the same time. CVS should automatically retry after 30 seconds, at which time the operation should normally be able to continue. If you encounter a long wait for a lock, of more than a minute or so, it may indicate that a CVS command did not complete properly and failed to remove its locks. If you think that this is the case, ask the user in question about it. If it appears that an operation did go awry, then you (or the named user) can delete files whose names start with `#cvs.rfl', `#cvs.wfl', or `#cvs.lock' in the directory mentioned in the message. Doing so should allow your operation to proceed. Do not delete or modify other files.  File: pintos.info, Node: Setting Up ssh, Prev: CVS Locking, Up: CVS F.3.4 Setting Up ssh -------------------- Ssh can be configured to log you on to any of the Remote Linux Cluster machines from any machine, without you having to enter your password. To enable automatic login, perform the following steps after logging on to any of the rlogin machines. * `ssh-keygen -t rsa -N ""' On your screen you should see something similar to what is shown below. Generating public/private rsa key pair. Enter file in which to save the key (/home/ugrads/your_pid/.ssh/id_rsa): Your identification has been saved in /home/ugrads/your_pid/.ssh/id_rsa. Your public key has been saved in /home/ugrads/your_pid/.ssh/id_rsa.pub. The key fingerprint is: 34:45:6d:4a:51:4e:1f:af:fe:66:dd:a9:a5:23:46:bb your_pid@some_machine.cslab Accept the defaults. This command creates a new file `id_rsa.pub' in the directory `$HOME/.ssh' if the default location is chosen. * `cd $HOME/.ssh' * `cat id_rsa.pub >> authorized_keys' * `cd $HOME' * `chmod +700 .ssh' To make sure that you have configured it correctly, try ssh'ing to another machine in the Remote Login Linux Cluster (rlogin). You should not be prompted for your password. If it is the first time you are ssh'ing to some machine, you might have to type `yes' to continue connecting.  File: pintos.info, Node: VNC, Next: Cygwin, Prev: CVS, Up: Development Tools F.4 VNC ======= VNC stands for Virtual Network Computing. It is, in essence, a remote display system which allows you to view a computing "desktop" environment not only on the machine where it is running, but from anywhere on the Internet and from a wide variety of machine architectures. It is already installed on the lab machines. For more information, look at the VNC Home Page.  File: pintos.info, Node: Cygwin, Prev: VNC, Up: Development Tools F.5 Cygwin ========== Cygwin provides a Linux-compatible environment for Windows. It includes ssh client and an X11 server, Cygwin/X. If your primary work environment is Windows, you will find Cygwin/X extremely useful for these projects. Install Cygwin/X, then start the X server and open a new xterm. The X11 server also allows you to run pintos while displaying the bochs- or qemu-emulated console on your Windows desktop. In addition, you can set up Cygwin's ssh client for password-less login as described earlier. *Note Setting Up ssh::.  File: pintos.info, Node: Installing Pintos, Next: Bibliography, Prev: Development Tools, Up: Top Appendix G Installing Pintos **************************** This chapter explains how to install a Pintos development environment on your own machine. If you are using a Pintos development environment that has been set up by someone else, you do not need to read this chapter or follow these instructions. The Pintos development environment is targeted at Unix-like systems. It has been most extensively tested on GNU/Linux, in particular the Debian and Ubuntu distributions, and Solaris. It is not designed to install under any form of Windows. Prerequisites for installing a Pintos development environment include the following, on top of standard Unix utilities: * Required: GCC (http://gcc.gnu.org/). Version 4.0 or later is preferred. Version 3.3 or later should work. If the host machine has an 80X86 processor, then GCC should be available as `gcc'; otherwise, an 80X86 cross-compiler should be available as `i386-elf-gcc'. A sample set of commands for installing GCC 3.3.6 as a cross-compiler are included in `src/misc/gcc-3.3.6-cross-howto'. * Required: GNU binutils (http://www.gnu.org/software/binutils/). Pintos uses `addr2line', `ar', `ld', `objcopy', and `ranlib'. If the host machine is not an 80X86, versions targeting 80X86 should be available with an `i386-elf-' prefix. * Required: Perl (http://www.perl.org). Version 5.8.0 or later is preferred. Version 5.6.1 or later should work. * Required: GNU make (http://www.gnu.org/software/make/), version 3.80 or later. * Recommended: QEMU (http://fabrice.bellard.free.fr/qemu/), version 0.8.0 or later. If QEMU is not available, Bochs can be used, but its slowness is frustrating. * Recommended: GDB (http://www.gnu.org/software/gdb/). GDB is helpful in debugging (*note GDB::). If the host machine is not an 80X86, a version of GDB targeting 80X86 should be available as `i386-elf-gdb'. * Recommended: X (http://www.x.org/). Being able to use an X server makes the virtual machine feel more like a physical machine, but it is not strictly necessary. * Optional: Texinfo (http://www.gnu.org/software/texinfo/), version 4.5 or later. Texinfo is required to build the PDF version of the documentation. * Optional: TeX (http://www.tug.org/). Also required to build the PDF version of the documentation. * Optional: VMware Player (http://www.vmware.com/). This is a third platform that can also be used to test Pintos. Once these prerequisites are available, follow these instructions to install Pintos: 1. Install Bochs (http://bochs.sourceforge.net/), version 2.2.6, as described below (*note Building Bochs for Pintos::). 2. Install scripts from `src/utils'. Copy `backtrace', `pintos', `pintos-gdb', `pintos-mkdisk' into the default `PATH'. 3. Install `src/misc/gdb-macros' in a public location. Then use a text editor to edit the installed copy of `pintos-gdb', changing the definition of `GDBMACROS' to point to where you installed `gdb-macros'. Test the installation by running `pintos-gdb' without any arguments. If it does not complain about missing `gdb-macros', it is installed correctly. 4. Compile the remaining Pintos utilities by typing `make' in `src/utils'. Install `squish-pty' somewhere in `PATH'. To support VMware Player, install `squish-unix'. If your Perl is older than version 5.8.0, also install `setitimer-helper'; otherwise, it is unneeded. 5. Pintos should now be ready for use. If you have the Pintos reference solutions, which are provided only to faculty and their teaching assistants, then you may test your installation by running `make check' in the top-level `tests' directory. The tests take between 20 minutes and 1 hour to run, depending on the speed of your hardware. 6. Optional: Build the documentation, by running `make dist' in the top-level `doc' directory. This creates a `WWW' subdirectory within `doc' that contains HTML and PDF versions of the documentation, plus the design document templates and various hardware specifications referenced by the documentation. Building the PDF version of the manual requires Texinfo and TeX (see above). You may install `WWW' wherever you find most useful. The `doc' directory is not included in the `.tar.gz' distributed for Pintos. It is in the Pintos CVS tree available via `:pserver:anonymous@footstool.stanford.edu:/var/lib/cvs', in the `pintos' module. The CVS tree is _not_ the authoritative source for Stanford course materials, which should be obtained from the course website. * Menu: * Building Bochs for Pintos::  File: pintos.info, Node: Building Bochs for Pintos, Up: Installing Pintos G.1 Building Bochs for Pintos ============================= Upstream Bochs has bugs and warts that should be fixed when used with Pintos. Thus, Bochs should be installed manually for use with Pintos, instead of using the packaged version of Bochs included with an operating system distribution. Two different Bochs binaries should be installed. One, named simply `bochs', should have the GDB stub enabled, by passing `--enable-gdb-stub' to the Bochs `configure' script. The other, named `bochs-dbg', should have the internal debugger enabled, by passing `--enable-debugger' to `configure'. (The `pintos' script selects a binary based on the options passed to it.) In each case, the X, terminal, and "no GUI" interfaces should be configured, by passing `--with-x --with-x11 --with-term --with-nogui' to `configure'. This version of Pintos is designed for use with Bochs 2.2.6. A number of patches for this version of Bochs are included in `src/misc': `bochs-2.2.6-big-endian.patch' Makes the GDB stubs work on big-endian systems such as Solaris/Sparc, by doing proper byteswapping. It should be harmless elsewhere. `bochs-2.2.6-jitter.patch' Adds the "jitter" feature, in which timer interrupts are delivered at random intervals (*note Debugging versus Testing::). `bochs-2.2.6-triple-fault.patch' Causes Bochs to break to GDB when a triple fault occurs and the GDB stub is active (*note Triple Faults::). `bochs-2.2.6-ms-extensions.patch' Needed for Bochs to compile with GCC on some hosts. Probably harmless elsewhere. `bochs-2.2.6-solaris-tty.patch' Needed for Bochs to compile in terminal support on Solaris hosts. Probably harmless elsewhere. `bochs-2.2.6-page-fault-segv.patch' Makes the GDB stub report a SIGSEGV to the debugger when a page-fault exception occurs, instead of "signal 0." The former can be ignored with `handle SIGSEGV nostop' but the latter cannot. `bochs-2.2.6-paranoia.patch' Fixes compile error with modern versions of GCC. `bochs-2.2.6-solaris-link.patch' Needed on Solaris hosts. Do not apply it elsewhere. To apply all the patches, `cd' into the Bochs directory, then type: patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-page-fault-segv.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-paranoia.patch patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch You will have to supply the proper `$PINTOSDIR', of course. You can use `patch''s `--dry-run' option if you want to test whether the patches would apply cleanly before trying to apply them. Sample commands to build and install Bochs for Pintos are supplied in `src/misc/bochs-2.2.6-build.sh'.  File: pintos.info, Node: Bibliography, Next: License, Prev: Installing Pintos, Up: Top Bibliography ************ * Menu: * Hardware References:: * Software References:: * Operating System Design References::  File: pintos.info, Node: Hardware References, Next: Software References, Up: Bibliography Hardware References =================== [IA32-v1]. IA-32 Intel Architecture Software Developer's Manual Volume 1: Basic Architecture. Basic 80X86 architecture and programming environment. Available via `developer.intel.com'. Section numbers in this document refer to revision 18. [IA32-v2a]. IA-32 Intel Architecture Software Developer's Manual Volume 2A: Instruction Set Reference A-M. 80X86 instructions whose names begin with A through M. Available via `developer.intel.com'. Section numbers in this document refer to revision 18. [IA32-v2b]. IA-32 Intel Architecture Software Developer's Manual Volume 2B: Instruction Set Reference N-Z. 80X86 instructions whose names begin with N through Z. Available via `developer.intel.com'. Section numbers in this document refer to revision 18. [IA32-v3a]. IA-32 Intel Architecture Software Developer's Manual Volume 3A: System Programming Guide. Operating system support, including segmentation, paging, tasks, interrupt and exception handling. Available via `developer.intel.com'. Section numbers in this document refer to revision 18. [FreeVGA]. FreeVGA Project. Documents the VGA video hardware used in PCs. [kbd]. Keyboard scancodes. Documents PC keyboard interface. [ATA-3]. AT Attachment-3 Interface (ATA-3) Working Draft. Draft of an old version of the ATA aka IDE interface for the disks used in most desktop PCs. [PC16550D]. National Semiconductor PC16550D Universal Asynchronous Receiver/Transmitter with FIFOs. Datasheet for a chip used for PC serial ports. [8254]. Intel 8254 Programmable Interval Timer. Datasheet for PC timer chip. [8259A]. Intel 8259A Programmable Interrupt Controller (8259A/8259A-2). Datasheet for PC interrupt controller chip.  File: pintos.info, Node: Software References, Next: Operating System Design References, Prev: Hardware References, Up: Bibliography Software References =================== [ELF1]. Tool Interface Standard (TIS) Executable and Linking Format (ELF) Specification Version 1.2 Book I: Executable and Linking Format. The ubiquitous format for executables in modern Unix systems. [ELF2]. Tool Interface Standard (TIS) Executable and Linking Format (ELF) Specification Version 1.2 Book II: Processor Specific (Intel Architecture). 80X86-specific parts of ELF. [ELF3]. Tool Interface Standard (TIS) Executable and Linking Format (ELF) Specification Version 1.2 Book III: Operating System Specific (UNIX System V Release 4). Unix-specific parts of ELF. [SysV-ABI]. System V Application Binary Interface: Edition 4.1. Specifies how applications interface with the OS under Unix. [SysV-i386]. System V Application Binary Interface: Intel386 Architecture Processor Supplement: Fourth Edition. 80X86-specific parts of the Unix interface. [SysV-ABI-update]. System V Application Binary Interface--DRAFT--24 April 2001. A draft of a revised version of *Note SysV-ABI:: which was never completed.  File: pintos.info, Node: Operating System Design References, Prev: Software References, Up: Bibliography Operating System Design References ================================== [Christopher]. W. A. Christopher, S. J. Procter, T. E. Anderson, `The Nachos instructional operating system'. Proceedings of the USENIX Winter 1993 Conference. `http://portal.acm.org/citation.cfm?id=1267307'. [Dijkstra]. E. W. Dijkstra, `The structure of the "THE" multiprogramming system'. Communications of the ACM 11(5):341-346, 1968. `http://doi.acm.org/10.1145/363095.363143'. [Hoare]. C. A. R. Hoare, `Monitors: An Operating System Structuring Concept'. Communications of the ACM, 17(10):549-557, 1974. `http://www.acm.org/classics/feb96/'. [Lampson]. B. W. Lampson, D. D. Redell, `Experience with processes and monitors in Mesa'. Communications of the ACM, 23(2):105-117, 1980. `http://doi.acm.org/10.1145/358818.358824'. [McKusick]. M. K. McKusick, K. Bostic, M. J. Karels, J. S. Quarterman, `The Design and Implementation of the 4.4BSD Operating System'. Addison-Wesley, 1996. [Wilson]. P. R. Wilson, M. S. Johnstone, M. Neely, D. Boles, `Dynamic Storage Allocation: A Survey and Critical Review'. International Workshop on Memory Management, 1995. `http://www.cs.utexas.edu/users/oops/papers.html#allocsrv'.  File: pintos.info, Node: License, Prev: Bibliography, Up: Top License ******* Pintos, including its documentation, is subject to the following license: Copyright (C) 2004, 2005, 2006 Board of Trustees, Leland Stanford Jr. University. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. A few individual files in Pintos were originally derived from other projects, but they have been extensively modified for use in Pintos. The original code falls under the original license, and modifications for Pintos are additionally covered by the Pintos license above. In particular, code derived from Nachos is subject to the following license: Copyright (C) 1992-1996 The Regents of the University of California. All rights reserved. Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without written agreement is hereby granted, provided that the above copyright notice and the following two paragraphs appear in all copies of this software. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. Code derived from MIT's 6.828 course code is subject to the following license: Copyright (C) 1997 Massachusetts Institute of Technology This software is being provided by the copyright holders under the following license. By obtaining, using and/or copying this software, you agree that you have read, understood, and will comply with the following terms and conditions: Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose and without fee or royalty is hereby granted, provided that the full text of this NOTICE appears on ALL copies of the software and documentation or portions thereof, including modifications, that you make. THIS SOFTWARE IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE OR DOCUMENTATION. The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders. See the file AUTHORS which should have accompanied this software for a list of all copyright holders. This file may be derived from previously copyrighted software. This copyright applies only to those changes made by the copyright holders listed in the AUTHORS file. The rest of this file is covered by the copyright notices, if any, listed below.