************************** OS/161 on Linux ************************** .. topic:: Learning Outcome Set up and run OS161 for all COMP3231 assignments on a computer running Linux. .. topic:: Introduction In this module, there are several steps marked with *do once per...* - these indicate if you need to repeat those steps if you have already done them. Just follow the steps in order (from the valid *once per...* label), replacing ** with the assignment number and <20t1> with the trimester number. .. topic:: Applicable subjects COMP3231 ---- Setting up your folders ========================= *Do once per computer* Create a folder called cs3231 within your home directory: :: $ cd ~ $ mkdir cs3231 GDB User Initialization File ================================ *Do once per computer* The user initialization file contains commands that are executed upon the startup of GDB. It is located in your home folder under the path: :: ~/.gdbinit Create/ edit this file and add the following line to this file: :: set auto-load safe-path / This allows our programs to use the current drectory initialization file. Install the conf file ======================== *Do once per computer* Install the sys161-asst0.conf file in the ~/cs3231/root directory by running: :: $ mkdir ~/cs3231/root $ cd ~/cs3231/root $ wget http://cgi.cse.unsw.edu.au/~cs3231/19T1/assignments/asst1/sys161.conf -O sys161.conf Clone your repository ======================= *Do once per assignment* Git is not only helpful for retreiving the files, but also for transferring files to and from CSE, backups, and collaborating with your partner. Clone the git repo using the command below: :: $ cd ~/cs3231 $ git clone gitlab@gitlab.cse.unsw.EDU.AU:/<20t1>-comp3231-asst.git asst-src Don't forget to substitute in your zID, session number and the assignment number (removing the angle brackets). GDB Current Directory Initialization File =========================================== *Do once per assignment* The current directory initialization file contains commands to be executed upon the startup of GDB within the current folder. Since we will be running GDB within the root folder of cs3231, the path is: :: ~/cs3231/root/.gdbinit Create/ edit this file and add the following line to this file (replacing with the appropriate assignment number): :: set can-use-hw-watchpoints 0 define connect dir ~/cs3231/asst-src/kern/compile/ASST target remote unix:.sockets/gdb b panic end .. The file now contains several important commands: :: set can-use-hw-watchpoints 0 This line forces gdb to use software watchpoints (see :ref:`watch_display` for an explanation of watchpoints). A connect function has 3 main components 1. ``dir ~/cs3231/asst-src/kern/compile/ASST`` Tells GDB where to find the source file. You will need to change this line for each assignment. 2. ``target remote unix:.sockets/gdb`` Connects GDB to the currently running instance of OS/161 3. ``b panic`` Sets a breakpoint on panic. This allows GDB to be used at the point right before OS/161 crashes. Make your Assignment the First Time ====================================== *Do once per assignment* For each assignment, run the following commands to set up the files. You only need to run these commands once (for the current assignment). Make sure you replace ** with the current assignment number.:: $ cd ~/cs3231/asst-src $ ./configure $ bmake $ bmake install $ cd ~/cs3231/asst-src/kern/conf $ ./config ASST $ cd ../compile/ASST $ bmake depend $ bmake $ bmake install Make Your Assignments Additional Times =========================================== *Do before you run your assignment if you have changed code* Each time you make changes to your code and want to run your code, run the following commands: :: $ cd ~/cs3231/asst-src/kern/compile/ASST $ bmake && bmake install Note: If you have added more files or changed #includes, then you should use *bmake depend* as well. Remember to replace ** with the appropriate assignment number. Running OS/161 (with or without GDB) ======================================= *Do each time you want to run/ debug your code* +--------------------------------+---------------------------------------------+----------------------------------------+ | | terminal 1 | terminal 2 | +================================+=============================================+========================================+ | Run OS/161 without GDB | | $ cd ~/cs3231/root | | | | | | | | | | | | $ sys161 kernel | | | +--------------------------------+---------------------------------------------+----------------------------------------+ | Debug from the beginning | | $ cd ~/cs3231/root | | $ cd ~/cs3231/root | | | | | | | | | | $ sys161 -w kernel | | | | | | | | $ os161-gdb kernel | | | | sys161: Waiting for debugger connection..| | | | | | | | | | | | | | (gdb) connect | | | | sys161: New debugger connection | | | +--------------------------------+---------------------------------------------+----------------------------------------+ | Debug already running instance | | $ cd ~/cs3231/root | | $ cd ~/cs3231/root | | | | | | | | | | $ sys161 kernel | | | | | | | | | | | | OS/161 kernel [? for menu]: | | | | | | | | | | | | | | | | | | | | | | | | ctrl+G | | | | | | | | | | | | sys161: Waiting for debugger connection..| | | | | | | | $ os161-gdb kernel | | | | | | | | | | | | (gdb) connect | | | | sys161: New debugger connection | | | +--------------------------------+---------------------------------------------+----------------------------------------+ Using GBD ============ *Do when gdb is attached to an instance of OS/161 (i.e. after option 2 and 3 of the previous step)* The OS/161 instance is currently stopped at a breakpoint and is awaiting instructions from the debugger. Most commonly we want to set breakpoints, then continue through our program. See :ref:`all_gdb` for more information. .. moduleauthor:: Liz Willer :Date: 2020-01-29