add datalab

DataLab/README-datalab.txt

@@ -0,0 +1,202 @@
+#####################################################################
+# CS:APP Data Lab
+# Directions to Instructors
+#
+# May 31, 2011: Now includes the "Beat the Prof" contest
+#
+# Copyright (c) 2002-2016, R. Bryant and D. O'Hallaron
+######################################################################
+
+This directory contains the files that you will need to run the CS:APP
+Data Lab, which helps develops the student's understanding of bit
+representations, two's complement arithmetic, and IEEE floating point.
+
+For fun, we've also provided a new user-level HTTP-based "Beat the
+Prof" contest that replaces the old email-based version. The new
+contest is completely self-contained and does not require root
+password.  The only requirement is that you have a user account on a
+Linux machine with an IP address.
+
+System requirements: Uses bison and flex to build dlc.
+
+************
+1. Overview
+************
+
+In this lab, students work on a C file, called bits.c, that consists
+of a series of programming "puzzles".  Each puzzle is an empty
+function body that must be completed so that it implements a specified
+mathematical function, such as "absolute value". Students must solve
+the non-floating point puzzles using only straight-line C code and a
+restricted set of C arithmetic and logical operators. For the
+floating-point puzzles they can use conditionals and arbitrary
+operators.
+
+Students use the following three tools to check their work.
+Instructors use the same tools to assign grades.
+
+1. dlc: A "data lab compiler" that checks each function in bits.c for
+compliance with the coding guidelines, checking that the students use
+less than the maximum number of operators, that they use only
+straight-line code, and that they use only legal operators. The
+sources and a Linux binary are included with the lab.
+
+2. btest: A test harness that checks the functions in bits.c for
+correctness. This tool has been significantly improved, now checking
+wide swaths around the edge cases for integers and floating point
+representations such as 0, Tmin, denorm-norm boundary, and inf.
+
+3. driver.pl: A autograding driver program that uses dlc and btest to
+check each test function in bits.c for correctness and adherence to
+the coding guidelines
+
+The default version of the lab consists of 15 puzzles, in
+./src/selections.c, chosen from a set of 73 standard puzzles defined
+in the directory ./src/puzzles/. You can customize the lab from term
+to term by choosing a different set of puzzles from the standard set
+of puzzles.
+
+You can also define new puzzles of your own and add them to the
+standard set. See ./src/README for instructions on how to add new
+puzzles to the standard set.
+
+NOTE: If you define new puzzles, please send them to me (Dave
+O'Hallaron, [email protected]) so that I can add them to the standard
+set of puzzles in the data lab distribution.
+
+********
+2. Files
+********
+
+All CS:APP labs have the same simple top-level directory structure:
+
+Makefile	   Builds the entire lab.
+README		   This file.
+src/		   Contains all source files for the lab.
+datalab-handout/   Handout directory that goes to the students. Generated
+		   by the Makefile from files in ./src. Never modify anything
+		   in this directory. 
+grade/		   Autograding scripts that instructors can use to 
+		   grade student handins.
+writeup/	   Sample Latex lab writeup.
+contest/           Everything needed for the optional "Beat the Prof" contest.
+
+********************
+3. Building the Lab
+*******************
+
+Step 0. If you decide to run the "Beat the Prof" contest (section 5),
+then edit the ./contest/Contest.pm file so that the driver knows where
+to send the results. See ./contest/README for the simple
+instructions. If you decide *not* to offer the contest, then do
+nothing in this step.
+
+Step 1. Select the puzzles you want to include by editing the file
+./src/selections.c.
+
+The default ./src/selections.c comes from a previous instance of the
+Data Lab at CMU.  The file ./src/selections-all.c contains the
+complete list of puzzles to choose from.
+
+Step 2. Modify the Latex lab writeup in ./writeup/datalab.tex to 
+tailor it for your course. 
+
+Step 3. Type the following in the current directory:
+     unix> make clean
+     unix> make 
+
+The Makefile generates the btest source files, builds the dlc binary
+(if necessary), formats the lab writeup, and then copies btest, the
+dlc binary, and the driver to the handout directory.  After that, it
+builds a tarfile of the handout directory (in ./datalab-handout.tar)
+that you can then hand out to students.
+
+Note on Binary Portability: dlc is distributed in the datalab-handout
+directory as a binary. Linux binaries are not always portable across
+distributions due to different versions of dynamic libraries. You'll
+need to be careful to compile dlc on a machine that is compatible with
+those that the students will be using.
+
+Note: Running "make" also automatically generates the solutions to the
+puzzles, which you can find in ./src/bits.c and ./src/bits.c-solution.
+
+
+******************
+4. Grading the Lab
+******************
+
+There is a handy autograder script that automatically grades your
+students' handins.  See ./grade/README for instructions.
+
+**************************
+5. "Beat the Prof" Contest
+**************************
+
+For fun, we've included an optional "Beat the Prof" contest, where
+students compete against themselves and the instructor. The goal is to
+solve each Data Lab puzzle using the fewest number of
+operators. Students who match or beat the instructor's operator count
+for each puzzle are winners. See ./contest/README for the simple
+instructions on how to set up the contest.
+
+NOTE: The contest is completely optional. Whether you decide to
+offer it or not has no affect on how you build and distribute the lab.
+
+NOTE: If you do decide to offer the contest, then you should configure
+the contest *before* you build the lab, so that the driver knows the
+server and port to send the contest results of each student (using the
+constants defined in the ./src/Driverhdrs.pm file, which is
+autogenerated from the ./contest/Contest.pm config file).
+
+If you decide to offer the contest *after* you've built and handed out
+the lab to the students, you're still OK:
+
+1) Configure the contest as described in contest/Makefile
+
+2) Rebuild the lab in the usual way:
+   linux> cd datalab
+   linux> make
+
+3) Distribute the new ./src/Driverhdrs.pm file to the students.
+
+
+***************************
+6. Experimental BDD checker
+***************************
+
+For fun, we have included an experimental correctness checker based on
+binary decision diagrams (BDDs) (R. E. Bryant, IEEE Transactions on
+Computers, August, 1986) that uses the CUDD BDD package from the
+University of Colorado. The BDD checker does an exhaustive test of the
+test functions in bits.c, formally verifying the correctness of each
+test function against a reference solution for *ALL* possible input
+values. For functions that differ from the reference solution, the BDD
+checker produces a counterexample in the form of a set of function
+arguments that cause the test solution to differ from the reference
+solution.
+
+The sources are included in ./src/bddcheck. To compile:
+
+  unix> cd src/bddcheck
+  unix> make clean
+  unix> make
+
+To use BDDs to check ./src/bits.c for correctness:
+
+  unix> cd src
+  unix> ./bddcheck/check.pl     # with error messages and counterexamples
+  unix> ./bddcheck/check.pl -g  # compact tabular output with no error messages
+
+Note that check.pl must be run from the parent directory of ./bddcheck.
+
+We've been using this BDD checker instead of btest at CMU for several
+years and the code appears to be stable. The main weakness is in the
+Perl code that extracts the functions from bits.c. It usually works,
+but some things -- such as calls to other functions, or functions that
+don't end with a single brace -- confuse it. So we're reluctant to
+make it the default checker for the distributed CS:APP labs. However,
+if you have any questions about the correctness of a particular
+solution, then this is the authoritative way to decide.
+
+Please send any comments about the BDD checker to [email protected].
+

DataLab/datalab-handout/Driverhdrs.pm

@@ -0,0 +1,12 @@
+#
+# This file contains configuration variables for drivers.
+# It was generated by genhdrs.pl. Do not modify it.
+#
+package Driverhdrs;
+
+$LAB = "datalab";
+$SERVER_NAME = "changeme.ics.cs.cmu.edu";
+$SERVER_PORT = 8081;
+$COURSE_NAME = "csapp";
+$AUTOGRADE_TIMEOUT = 0;
+1;

DataLab/datalab-handout/Driverlib.pm

@@ -0,0 +1,138 @@
+###############################################################
+# Driverlib.pm - A package of helper functions for Perl drivers
+# 
+# Copyright (c) 2005 David R. O'Hallaron, All rights reserved.
+###############################################################
+
+package Driverlib;
+
+use Socket;
+
+# Autogenerated header file with lab-specific constants
+use lib ".";
+use Driverhdrs;
+
+require Exporter;
+@ISA = qw(Exporter);
+@EXPORT = qw(
+	     driver_post
+	     );
+
+use strict;
+
+#####
+# Public functions
+#
+
+#
+# driver_post - This is the routine that a driver calls when 
+#    it needs to transmit an autoresult string to the result server.
+#
+sub driver_post ($$) {
+    my $userid = shift;       # User id for this submission
+    my $result = shift;       # Autoresult string
+    my $autograded = shift;   # Set if called by an autograder
+
+    # Echo the autoresult string to stdout if the driver was called
+    # by an autograder
+    if ($autograded) {
+        print "\n";
+        print "AUTORESULT_STRING=$result\n";
+        return;
+    }	
+
+    # If the driver was called with a specific userid, then submit
+    # the autoresult string to the result server over the Internet.
+    if ($userid) {
+        my $status = submitr($Driverhdrs::SERVER_NAME, 
+                             $Driverhdrs::SERVER_PORT, 
+                             $Driverhdrs::COURSE_NAME, 
+                             $userid, 
+                             $Driverhdrs::LAB, 
+                             $result);
+
+        # Print the status of the transfer
+        if (!($status =~ /OK/)) {
+            print "$status\n";
+            print "Did not send autoresult string to the result server.\n";
+            exit(1);
+        }
+        print "Success: Sent autoresult string for $userid to the result server.\n";
+    }	
+}
+
+
+#####
+# Private functions
+#
+
+#
+# submitr - Sends an autoresult string to the result server
+#
+sub submitr ($$$$$$) {
+    my $hostname = shift;
+    my $port = shift;
+    my $course = shift;
+    my $userid = shift;
+    my $lab = shift;
+    my $result = shift;
+
+    my $internet_addr;
+    my $enc_result;
+    my $paddr;
+    my $line;
+    my $http_version;
+    my $errcode;
+    my $errmsg;
+
+    # Establish the connection to the server
+    socket(SERVER, PF_INET, SOCK_STREAM, getprotobyname('tcp'));
+    $internet_addr = inet_aton($hostname)
+        or die "Could not convert $hostname to an internet address: $!\n";
+    $paddr = sockaddr_in($port, $internet_addr);
+    connect(SERVER, $paddr)
+        or die "Could not connect to $hostname:$port:$!\n";
+
+    select((select(SERVER), $| = 1)[0]); # enable command buffering
+
+    # Send HTTP request to server
+    $enc_result = url_encode($result);
+    print SERVER  "GET /$course/submitr.pl/?userid=$userid&lab=$lab&result=$enc_result&submit=submit HTTP/1.0\r\n\r\n";
+
+    # Get first HTTP response line
+    $line = <SERVER>;
+    chomp($line);
+    ($http_version, $errcode, $errmsg) = split(/\s+/, $line);
+    if ($errcode != 200) {
+        return "Error: HTTP request failed with error $errcode: $errmsg";
+    }
+
+    # Read the remaining HTTP response header lines
+    while ($line = <SERVER>) {
+        if ($line =~ /^\r\n/) {
+            last;
+        }
+    }
+
+    # Read and return the response from the result server
+    $line = <SERVER>;
+    chomp($line);
+
+    close SERVER;
+    return $line;
+
+}
+
+#
+# url_encode - Encode text string so it can be included in URI of GET request
+#
+sub url_encode ($) {
+    my $value = shift;
+
+    $value =~s/([^a-zA-Z0-9_\-.])/uc sprintf("%%%02x",ord($1))/eg;
+    return $value;
+}
+
+# Always end a module with a 1 so that it returns TRUE
+1;
+

DataLab/datalab-handout/Makefile

@@ -0,0 +1,26 @@
+#
+# Makefile that builds btest and other helper programs for the CS:APP data lab
+# 
+CC = gcc
+CFLAGS = -O -Wall -m32
+LIBS = -lm
+
+all: btest fshow ishow
+
+btest: btest.c bits.c decl.c tests.c btest.h bits.h
+	$(CC) $(CFLAGS) $(LIBS) -o btest bits.c btest.c decl.c tests.c
+
+fshow: fshow.c
+	$(CC) $(CFLAGS) -o fshow fshow.c
+
+ishow: ishow.c
+	$(CC) $(CFLAGS) -o ishow ishow.c
+
+# Forces a recompile. Used by the driver program. 
+btestexplicit:
+	$(CC) $(CFLAGS) $(LIBS) -o btest bits.c btest.c decl.c tests.c 
+
+clean:
+	rm -f *.o btest fshow ishow *~
+
+