上传文件至 ''

1 month ago · a265a0df20
--- a/README-datalab.txt
+++ b/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-2018, 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, droh@cs.cmu.edu) 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 randy.bryant@cs.cmu.edu.

--- a/datalab-handout.tar
+++ b/datalab-handout.tar
--- a/datalab-release.html
+++ b/datalab-release.html
@ -0,0 +1,171 @@
 <html>
  <head>
    <title>Data Lab Release Notes</title>
  </head>

  <body bgcolor=white>
    <h1>Data Lab Release Notes</h1>

 <table width=700><tr><td>

 <h2>12/16/2019</h2>
 <ul>
  <li>Updated writeup and grade directory to match the default puzzle set.
  <i>Thanks to Chen Su</i>
 </ul>

 <h2>11/1/2018</h2>
 <ul>
  <li>Corrected a header comment in the satAdd puzzle.
  <i>Thanks to Prof. Hugh Lauer, Justin Aquilante, and Nick Krichevsky, WPI.</i>
 </ul>

 <h2>10/24/2018</h2>
 <ul>
  <li>Fixed a build bug in the BDD checker.
 </ul>

 <h2>10/23/2018</h2>
 <ul>
  <li>Added some new puzzles, fixed a typo in the comment for the
  rotateRight puzzle, and fixed a build bug in an earlier version.
 <i>Thanks to Prof. Hugh Lauer, WPI, for identifying the build bug.</i>
 <i>Thanks to Prof. Bryan Dixon, Cal State Chico, for identifying the rotateRight typo.</i>
 </ul>

 <h2>5/4/2016</h2>
 <ul>
 <li>Added the <kbd>-std=gnu89</kbd> flag to the dlc Makefile so that gcc 5 will correctly 
 compile dlc (addresses a constraint on inline functions introduced in gcc 5).
 <i>Thanks to Prof. Branch Archer, West Texas A&M University.</i>
 </ul>

 <h2>2/17/2016</h2>
 <ul>
 <li>Added a note to the README that bison and flex must be installed in order to rebuild dlc.
 <i>Thanks to Prof. Michael Ross, Portland Community College.</i>
 </ul>

 <h2>9/16/2014</h2>
 <ul>
 <li>Applied patch to the ANSI C grammar for dlc to accomodate stricter type rules in more recent versions of bison. 
 <li>Eliminated unneccessary calls to bison and flex in the dlc Makefile. 
 <i>Thanks to Prof. Robert Marmorstein, Longwood University.</i>
 </ul>

 <h2>9/2/2014</h2>
 <ul>
 <li>Fixed bug in <kbd>grade/grade-datalab.pl</kbd> autograding script.
 </ul>

 <h2>1/30/2014</h2>
 <ul>
 <li>Fixed comment in code for logicalShift to indicate that '!'
 is an allowed operator.
 <i>Thanks to Prof. Aran Clauson of Western Washington University</i>
 </ul>

 <h2>9/19/2012</h2>
 <ul>
 <li>Fixed bug in line 147, btest.c: incorrect initial value for NaN.
 <i>Thanks to Prof. Cary Gray,  Wheaton College</i>
 </ul>

 <h2>4/26/2012</h2>
 <ul>
 <li>Added a clarifying note to the main README file reminding
 instructors that, because there are different versions of dynamic libraries,
 Linux binaries such as dlc are not necessarily portable
 across different Linux platforms. 
 <i>Thanks to Prof. Hugh Lauer,  Worcester Polytechnic Institute</i>

 <li>Cleaned up some compiler warnings in the
 <kbd>isLessOrEqual.c</kbd> and <kbd>isPositive.c</kbd> puzzle solutions
 </ul>

 <h2>8/22/2011</h2>
 <ul>

 <li>Modified the "start" rule in Makefile to touch the log.txt file
 before starting up the lab daemons, so that an empty scoreboard is
 created initially. <i>Thanks to Prof. Godmar Back, Virginia Tech.</i>

 </ul>

 <h2>5/31/2011</h2>
 <ul>
 <li>For fun, we've added an optional user-level HTTP-based "Beat the
 Prof" contest that replaces the old email-based version. The new
 contest is very simple to run, 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.

 <li> Corrected a few minor typos in various README files.
 </ul>

 <h2>1/2/2011</h2>
 <b>This is a major update of the Data Lab:</b>
 <ul>
 <li> Introduced floating-point puzzles. 

 <li> Added many new integer puzzles (There are now 73 puzzles total). 

 <li> Made significant improvements to <kbd>btest</kbd>. It now does
 millions of tests for each puzzle, checking wide swaths around Tmin,
 0, denorm-normalized boundary, and inf. Also added support for
 floating-point puzzles.

 <li> Added support for floating-point puzzles to <kbd>dlc</kbd>.

 <li> Added a new autograder called <kbd>driver.pl</kbd> that uses
 <kbd>dlc</kbd> and <kbd>btest</kbd> to check for correctness and
 conformance to the coding guidelines.

 <li> Top-level directory now conforms to the CS:APP convention of putting all source files in the ./src directory.

 <li> In <kbd>driver.pl</kbd>, replaced "the cp {f1,f2,..,fn} target" notation,
 which some shells don't handle, with the more portable "cp f1 f2 ... fn target" form.

 <li> The lab writeup is longer included in the
 <kbd>datalab-handout</kbd> directory, to allow instructors greater
 flexibility in distributing and updating the writeup while the lab is
 being offered.  

 </ul>

 <h2>8/29/2003</h2>
 <ul>
 <li> Fixed a minor bug that caused <kbd>btest</kbd> to test the
 <kbd>tc2sm</kbd> puzzle with an input of <kbd>Tmin</kbd>, which isn't defined
 in sign-magnitude.
 </ul>

 <h2>1/27/2003</h2>
 <ul>
 <li> More operator-efficient solution to the <kbd>isPower2.c</kbd>
 puzzle. <i>Thanks to Al Davis, Univ of Utah.</i>
 <li> The <kbd>selections-all.c</kbd> file now lists all 41 puzzles.
 </ul>

 <h2>9/26/2002</h2>
 <ul>
 <li> Now includes a prebuilt Linux/IA32 binary for the <kbd>dlc</kbd> compiler.
 <li> Fixes a bug (an uninitialized stack variable) that
 caused "<kbd>dlc -Z</kbd>" to crash on some systems.

 <li> Contains some new scripts for running an interactive 
 <a href="http://www.cs.cmu.edu/afs/cs/academic/class/15213-f02/www/daemons/dlcontest.html">"Beat the Prof" contest </a>,<br> 
 where students try to outperform the
 instructor's (intentionally non-optimal) solution.
 </ul>

 <h2>6/3/2002</h2>
 <ul>
 <li> Initial release.
 </ul>


 </td></tr></table>
 </body>
 </html>
--- a/datalab.pdf
+++ b/datalab.pdf
--- a/datalab.tar
+++ b/datalab.tar