EE 4702-1 - Procedures

Contents

Account Setup (Updated Fall 2022)

Account Setup

Remote Access

Programming Homework Work Flow and Debugging (Updated Fall 2018)

Obtaining the Assignment

Running and Debugging the Assignment

Emacs Text Editor (Spring 2009)

Using Emacs to Edit a File

Using Emacs to Edit C and C++

Running the Emacs Tutorial

Starting Info, Emacs' Help

Account Setup (Updated Fall 2022)

Account Setup

The instructions below setup your Linux account for EE 4702-X, GPU Programming.

If one of the steps below does not work as described it's possible that the step was performed correctly but the machine does not have the necessary software or is otherwise misconfigured. Please report this problem but also try another machine.
Workstations capable of running the class assignments can be found in the back of Room 2241 Patrick F. Taylor Hall. The host names of suitable machines can be found on the Computer Status page under the Host Name column. Look for a machine in which Yes appears under the OGL column. Find a machine in 2241 PFT with a matching label on the front. The labels might only show the first component of the domain name, for example, pulsar instead of pulsar.ece.lsu.edu. Their login screens should display Red Hat Enterprise Linux.
It's possible to perform some or all steps remotely if you have an X-server on your machine. If you have no idea what an X-server is, just find the lab.
Log into a Linux machine with your class account.
A Gnome graphical desktop should appear.
Start a shell (command-line interpretor). One way to do this is to right-click the desktop and select Open Terminal.
A window with "Terminal" in the title should appear with a Unix prompt.
Test for availability of the git client
[xyz.ece.lsu.edu]% git --version Tell git to just print its version. git version 2.31.1
For background on git, which is used in these instructions, see the thorough online documentation. Git is kind of like pointers and dynamically allocated memory in C: conceptually simple and at worst a little tricky for those who understand, but for those who stubbornly refuse to learn, a http://xkcd.com/1597/{source of endless frustration}. One more thing: don't get mixed up between Git, a distributed version control system, and https://github.com{GitHub}, a Git repository hosting service. The Git repo for this course is hosted on ECE computers, not GitHub, not BitBucket.
Check out the files needed for the class from the git repository.
[xyz.ece.lsu.edu]% cd ~ Change to home directory. [xyz.ece.lsu.edu]% git clone git://dmk.ece.lsu.edu/gp Cloning into 'gp'... remote: Counting objects: 10436, done. remote: Compressing objects: 100% (8094/8094), done. remote: Total 10436 (delta 7294), reused 3397 (delta 2180) Receiving objects: 100% (10436/10436), 60.41 MiB | 29.19 MiB/s, done. Resolving deltas: 100% (7294/7294), done. Updating files: 100% (1076/1076), done.
The git clone command made a copy of the gp repository, which is used for this course and the graduate GPU course, in your home directory. The repository contains the code used in classroom examples, homework assignments, starter code for projects, plus support files.
The git clone command can be done on any computer. You might run git clone on your own computer to view the files, even though you can't run them.
Verify that the repository was cloned and have a look around.
[xyz.ece.lsu.edu]% ls List entries in current directory. gp The list of entries just includes gp.
All of the class material is in the directory gp.
[xyz.ece.lsu.edu]% cd ~/gp Change to directory gp in home dir. [xyz.ece.lsu.edu]% ls List directory entries (files and directories). Makefile cuda gpgpu hw lib lisp proj-base util cpu-only dev-vulkan gpup include libs opengl shader-include vulkan
Classroom examples are in the gpup directory and homework assignments for the 2022 semester are in the hw/gpup/2022 directory. Code in these directories includes (verb) files from the include (noun) directory. The lisp directory contains support files for the Emacs text editor. The cpu-only and vulkan directories contain code for the undergraduate GPU class, and the gpgpu and proj-base directories contain larger code examples, which can be used as the starting point for projects. The directories opengl and gpup contain code that was previously used.
Link the .emacs file, if you don't have your own.
The step below moves an existing .emacs file out of the way. Class accounts are initialized with a simple .emacs file which we won't use.
[xyz.ece.lsu.edu]% cd ~ [xyz.ece.lsu.edu]% mv .emacs .emacs-old Rename (move) [xyz.ece.lsu.edu]% ln -s ./gp/lisp/.emacs Create a symbolic link.
The .emacs file contains preferences for the Emacs text editor and also settings needed to complete some of the assignments. If you have your own .emacs file or want to start adding stuff to the one provided see the .emacs file in the lisp directory for instructions and if necessary, find and read documentation on the symbolic link command ln -s.
Make sure graphics code can build (compile and link). Start by changing to the vulkan directory, which has most of the examples used during lectures.
[xyz.ece.lsu.edu]% cd ~/gp/vulkan
Next, build (using the make program) the simple bouncing ball code, demo-01-simple.
[xyz.ece.lsu.edu]% make demo-01-simple Build the program demo-01-simple ar: creating libvstroke.a g++ -g -I../include -I/usr/local/cuda/include -I/home/faculty/koppel/pub/lunarg/x86_64/include -I/home/faculty/koppel/pub/lunarg/x86_64/include/glslang -I../libs/vstroke -Wall -Wno-parentheses -fopenmp -march=native -Wno-sign-compare -std=c++17 -I/usr/include/GraphicsMagick -O3 -c demo-01-simple.cc /usr/local/cuda/bin/nvcc -g -I../include -I/usr/local/cuda/include -I/home/faculty/koppel/pub/lunarg/x86_64/include -I/home/faculty/koppel/pub/lunarg/x86_64/include/glslang -I../libs/vstroke -Xcompiler -Wall -Xcompiler -Wno-parentheses -Xcompiler -fopenmp -Xcompiler -march=native -Xcompiler -Wno-sign-compare -std c++17 --gpu-architecture=sm_61 -lineinfo -O3 -o demo-01-simple demo-01-simple.o -lm -lpthread -lstdc++fs -lrt -lvulkan -lglfw -L/home/faculty/koppel/pub/lunarg/x86_64/lib -Xlinker '-rpath=/home/faculty/koppel/pub/lunarg/x86_64/lib' -lshaderc_combined -lglslang-default-resource-limits -lGraphicsMagick++ -lnvidia-ml -lcuda -L../libs/vstroke -lvstroke [xyz.ece.lsu.edu]$
The command make demo-01-simple builds just that one program. The command make will build the default target, which in the vulkan directory is everything. The make command reads what's called a makefile, that file has name Makefile.
If the step above worked then skip the remainder of this step. Otherwise, let Dr. Koppelman know which machine encountered the problem and what when wrong. If the problem is with the machine then the name of the machine (something like pulsar.ece.lsu.edu) should be sufficient. If the cause is specific to the account then note the error message and if possible E-mail the output of make. One easy way to do this is to start a browser and use it to send mail (via myLSU or your favorite Web mail).
If the build seems to have worked, try running the program again.
[xyz.ece.lsu.edu]% ./demo-01-simple Run the demo program. Don't overlook the dot and slash.
A window showing a bouncing ball should appear.
At this point the account has been set up. The next step is probably to checkout the homework assignment and follow its instructions.

Programming Homework Work Flow and Debugging (Updated Fall 2018)

Obtaining the Assignment

These step show how to get a homework assignment into your class account.
Follow instructions above for setting up the class account.
Pull (update your copy of) the repository when the homework is assigned, and whenever the availability of an important update is announced. A pull requires just one command when you have not modified any files that are changed by the pull. If you have modified such files, then three commands are needed. In either case start with the commands:
[xyz.ece.lsu.edu]% cd ~/gp Change to dir ~/gp (~ means home directory). [xyz.ece.lsu.edu]% git pull Tell git to fetch new stuff and update your copy. remote: Counting objects: 9, done. remote: Compressing objects: 100% (5/5), done. remote: Total 5 (delta 4), reused 0 (delta 0) Unpacking objects: 100% (5/5), done. From git://dmk.ece.lsu.edu/gp a4c6dfd..dc9a031 master -> origin/master Updating a4c6dfd..dc9a031 Fast-forward vulkan/demo-01-simple.cc | 65 +++++++++++++--------------------------- 1 files changed, 20 insertions(+), 45 deletions(-)
In the output above everything has gone smoothly. Your copy is updated, in particular file demo-01-simple.cc has changed. Skip ahead to the step Locate and read, below.
If your output looks like the one below (especially the last two lines) then you've modified a file, demo-01-simple.cc in the example below, that would be changed by the pull. Follow the next step to fix the problem.
remote: Counting objects: 9, done. remote: Compressing objects: 100% (5/5), done. remote: Total 5 (delta 4), reused 0 (delta 0) Unpacking objects: 100% (5/5), done. From git://dmk.ece.lsu.edu/gp dc9a031..a52f04e master -> origin/master Updating dc9a031..a52f04e error: Your local changes to vulkan/demo-01-simple.cc' would be overwritten by merge. Aborting. Please, commit your changes or stash them before you can merge.
If your git pull output ended with a line Please, commit your changes... and you want to keep your changes to the modified files then execute these commands:
[xyz.ece.lsu.edu]% git stash Stash (save) changes, then set files to original state. [xyz.ece.lsu.edu]% git pull Gather updates, and apply to my files. Updating dc9a031..a52f04e Fast-forward vulkan/demo-01-simple.cc | 8 ++++++++ 1 files changed, 8 insertions(+), 0 deletions(-) [xyz.ece.lsu.edu]% git stash pop Try to apply stashed changes to updated files. Auto-merging vulkan/demo-01-simple.cc # On branch master # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: vulkan/demo-01-simple.cc # # Untracked files: --- [SNIP] --- no changes added to commit (use "git add" and/or "git commit -a") Dropped refs/stash@{0} (88772f8f7607fc4859040e1889f5cec865824b14)
The git stash command sets aside (stashes) your modified files and replaces them with unmodified versions. The git pull command updates your copy of the repo. Finally git stash pop brings back your stashed files, and tries to merge them with the new versions from the repository. The merge will go smoothly when the changes you made are far away from the changes in the new versions (for example, you modified lines 10-20 and in the changed version lines 50-60 were changed). Otherwise, you'll need to edit the files to manually merge your changes to the changes from the repo. If that's the case search for <<<<< and >>>> and make the necessary changes.
If your git pull output ended with a line Please, commit your changes... and you don't want to keep your changes to the modified file then execute the commands below. Remember, these commands will OVERWRITE your changes. Use this command if you don't mind losing your changes to file ~/gp/vulkan/demo-01-simple.cc.
[xyz.ece.lsu.edu]% cd ~/gp [xyz.ece.lsu.edu]% git checkout vulkan/demo-01-simple.cc Restore to original state, OVERWRITING YOUR CHANGES. [xyz.ece.lsu.edu]% git pull Updating a52f04e..55348b1 Fast-forward cuda/stream/stream-full.cu | 6 ++++++ 1 files changed, 6 insertions(+), 0 deletions(-)
The git checkout command must be executed for every file you want to revert. REMEMBER, this command will clobber any changes you have made. If you want to keep your changes follow the previous step.

Running and Debugging the Assignment

These steps describe how to check whether the assignment has been properly copied, and how to debug your assignment.
Locate and read the comments in the main file associated with the assignment, for 2016 hw01 they are in file ~/gp/hw/gpup/2016/hw01/hw01.cc. (For other assignments the homework handout will specify what file or files to edit.) The recommended way is to use Emacs to load the file and then read the file within Emacs. Use the File Open... dialog to find the directory and file.
Make sure that your copy of the repo is in the correct place, ~/gp. This is where the TA-Bot will look for your assignment. The tilde is your home directory, so the full path might be /home/classes/ee470200/gp. A common error is to clone the repo into directory ~/Desktop (which the TA-Bot will find). Even worse is to clone the repo to both ~/gp and ~/Desktop. The TA-Bot will copy the homework from ~/gp, it has no way of knowing which solution you wanted to submit.
Edit the file to solve one of the problems, but intentionally make a syntax error by declaring a variable integer.
Compile by pressing F9 and then Enter.
Compilation started at Fri Sep 2 18:33:47 g++ -I ../../include -fopenmp -I/usr/include/ImageMagick -fopenmp -I/usr/include/ImageMagick --std=c++11 -g -Wall -Wno-strict-aliasing -Wno-parentheses hw01.cc -O3 \ -o hw01 -lX11 -lglut -lGL -lGLU -lm -lpthread -lrt -lMagick++ -lMagickCore hw01.cc: In member function 'void World::ball_setup_1()': hw01.cc:204:9: error: 'integer' was not declared in this scope for ( integer i=0; i<chain_length; i++ ) ^ hw01.cc:204:17: error: expected ';' before 'i' for ( integer i=0; i<chain_length; i++ ) ^ hw01.cc:204:22: error: 'i' was not declared in this scope for ( integer i=0; i<chain_length; i++ ) ^ gmake: *** [hw01] Error 1 Compilation exited abnormally with code 2 at Fri Sep 2 18:33:47
The output above appears in a pane below the one showing the program.
Middle-click over the error to jump to the line with the error or, press F5 and enter the line number to jump to. Then correct the mistake, and repeat until compilation is successful.
Run the code under the debugger within Emacs by selecting the Tools | Debugger (gdb) menu items, then if necessary changing the gdb command in the minibuffer to hw01-debug and pressing Enter.
Current directory is /home/faculty/koppel/teach/gpcom/gp/hw/2009/hw1/ GNU gdb Red Hat Linux (6.5-25.el5_1.1rh) Copyright (C) 2006 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". (gdb)
The homework makefile may build two versions of the homework program, one for debugging and one for regular use. The only difference between the two is that the debug version is not optimized.
Run
(gdb) run Starting program: /home/faculty/koppel/teach/gpcom/gp/hw/2009/hw1/hw1-debug [Thread debugging using libthread_db enabled] [New Thread -1208965392 (LWP 4349)] S GL_VENDOR - "NVIDIA Corporation" S GL_RENDERER - "GeForce 8800 GT/PCI/SSE2" S GL_VERSION - "2.1.2 NVIDIA 169.07" Program exited normally. (gdb)
The output before "Program exited normally" is displayed while the program is running.
Set a breakpoint to examine variable values: Position the cursor over the line at which you want to break and enter C-x C-a C-b (Hold down Ctrl then press and release x, press and release a, press and release b, and finally let go of Ctrl.).
Breakpoint 1 at 0x804b99f: file hw1.cc, line 452. (gdb)
If this didn't work take the time to figure it out or ask someone.
Re-run, print out some variables, and continue. The transcript below shows the use of a variety of commands. The text in red is comments inserted into the transcript. Note that user input and gdb output are intermixed in the text below.
Breakpoint 1, render_hw1 (frame_buffer=@0xbfc9e17c) at hw1.cc:452 (gdb) print scale Print value of variable 'scale'. $1 = 0.0623286702 (gdb) p length p is equivalent to print $2 = 2.00249839 (gdb) print length * length $3 = 4.0099997951056707 (gdb) print v.red $4 = 249 (gdb) next Single-step execution. (gdb) print v.red $5 = 15.5198393 (gdb) info break List active breakpoints. Num Type Disp Enb Address What 1 breakpoint keep y 0x0804b99f in render_hw1(pFrame_Buffer&) at hw1.cc:452 breakpoint already hit 1 time (gdb) print v.z $6 = -4 (gdb) cond 1 v.z < -5 Set a condition for breakpoint 1. (gdb) continue Continuing. Breakpoint 1, render_hw1 (frame_buffer=@0xbfc9e17c) at hw1.cc:452 (gdb) print v.z $7 = -5.25 (gdb) info break Num Type Disp Enb Address What 1 breakpoint keep y 0x0804b99f in render_hw1(pFrame_Buffer&) at hw1.cc:452 stop only if v.z < -5 breakpoint already hit 2 times (gdb) disable 1 Temporarily turn off breakpoint 1. (gdb) c Continuing.
Use gdb's help command to find out more about each command.
Re-compile, run, and debug until code is working.

Emacs Text Editor (Spring 2009)

Using Emacs to Edit a File

Emacs, at its core, is a text editor, however surrounding that core are many commands and modes to help with programming tasks of all kinds and other activities from the practical, such as editing files on remote computers (look for Remote Files in the documentation), to the amusing, such as inserting keywords designed to attract the attention of counterespionage agents (M-x spook). Emacs has commands for practically anything. These steps show how to use Emacs to edit a file.
Type emacs & in a command shell or start Emacs using the Applications | Accessories | Emacs Text Editor menu items.
A window should pop up, the frame will be labeled Emacs.
Load a file by selecting Open File... from the Files menu.
Enter a file name. Note that text may appear in the bottom of the main window in an area called the minibuffer, or in a dialog box. (Once loaded, the file name will appear in the mode line near the bottom of the window.)
Enter text in the buffer to try out the editor.
Select Save Buffer from the Files menu to save.
When done with editing for the day select Exit Emacs from Files to exit.
Many users prefer to leave Emacs open with multiple files rather than exiting and re-starting Emacs for each file edited.

Using Emacs to Edit C and C++

Special features for editing C and C++ code. (Some work with other languages.)
Load a C file into a buffer. Enter C code (any C code).
Code should be syntax highlighted (different colors should be used for C keywords, comments, etc.), alerting you to some syntax errors and giving you something pretty to look at.
Pressing Tab will automatically indent the line the cursor is over. This is useful for catching syntax errors and keeping the description properly indented.
Pressing F9 will build the program (using the Makefile that is in the directory). A window will open showing the compiler output. Clicking on an error message with the center mouse button will move the cursor to the line with the error.

Running the Emacs Tutorial

(The tutorial is an introduction for first-time users.)
Start emacs.
Select Emacs Tutorial from the Help menu. Do not attempt to learn everything the first day.

Starting Info, Emacs' Help

(Info provides detailed documentation for Emacs and other programs.)
Start Emacs
Select Browse Manuals from Help menu.
Following instructions, select the Emacs manual.