------------------------------------------------------------------------------
CS 572 Assignment 2
teensy-usb driver

Author: Rebekah Leslie
Group:  Thomas DuBuisson and John Ochsner

------------------------------------------------------------------------------
Overview:

Our driver provides the initial steps towards a secure USB storage device for Linux.
We use the available dynamic memory on the Teensy device to store data objects
supplied by a user-level process.  In principle the data objects could be any size,
so long as they fit on the device. These data objects are keyed to a user-supplied
index.  The gadget-side driver displays the index at storage time to demonstrate that
the device is operating properly.  Our ultimate goal is for the gadget-side driver to
perform a private transformation to the data at storage time to protect the data
stored on the device.

The teensy device currently supports read and write operations that operate on the
data-object at a particular index in the store.  We envision adding support for more
operations, such as deleting a data object, clearing the entire memory, or querying
the device for statistics.  

Given the time permitted for the assignment, we were not able to achieve all of our
initial goals for the project.  The device only handles fixed-size 16-bit data
objects and does not perform any transformation to the data prior to storage.
However, we were able to complete a framework for accessing the teensy device that we
think is robust enough to accomodate the components of the original plan.

------------------------------------------------------------------------------
Testing the device:

The test script for the device will build and load the driver, build and run all of
the tests, then unload the driver before returning.  Test failures print an error
message, while driver errors (failure to build or load/unload) terminate the script.
The script must be run with root privilege.

In this directory, as root, simply type "./runteensy" to execute the script.

For more information about the specific tests performed, please see the test
README located in 'tests/README'.

The test scripts are written by Rebekah Leslie.  Thomas DuBuisson performed most of
the debugging of the driver during development. 

------------------------------------------------------------------------------
Design of the Gadget/Host Interface
Author: Entire Team

The host- and gadget- side of the driver communicate over a set of three endpoints.
From the host's perspective, there is a bulk-out endpoint for sending control
information to the gadget, a bulk-out endpoint for writing data-objects, and a
bulk-in endpoint for reading data-objects.  When the user requests a particular
operation, the host-side driver issues an instruction (currently read or write) over
the command endpoint the issues a data request over the appropriate data endpoint
(input or output).

	GADGET					HOST
		|				|
		|				|
                |      command :: BULK OUT      |
		| <<----------------------------|
		|				|
		|    data output :: BULK OUT	|
		| <<----------------------------|
		|				|
		|     data input :: BULK IN	|
		|---------------------------->>	|
		|				|
		|				|

With only read and write operations, the command endpoint is not strictly necessary
(the operations could be associated with the endpoints, so that a bulk-in request is
treated as a read and a bulk-out request is treated as a write), however, our design
allows for extension to the command set in the future.  We already have a placeholder
ioctl implementation for deleting a data object and for clearing the store.

------------------------------------------------------------------------------
Host-side configuration of the device:
Author: Rebekah Leslie
File:   main.c (and ./Makefile)

The host-side configuration provides all of the setup necessary for managing the
teensy device and interfacing with USB core.  The probe method performs most of the
work---we don't want to initialize all of our structures until there is some hope of
the device being used.  We require that the configuration presented by the USB device
precicely match the expected configuration (the four previously discussed endpoints);
loading the device will fail otherwise.

In addition to the configuration performed by the driver once loaded, Rebekah
researched the mechanics of hotplugging.  Running "make install" as root should
configure the host system to auto-load the correct driver when the Teensy board is
plugged in.  There were some issues with this during testing due to conflict with
another driver---in this case the driver has to be manually loaded using insmod or
modprobe.

------------------------------------------------------------------------------
Communicating between the gadget and host
Author: Thomas DuBuisson

The read and write operations provide the user interface to the device.  The
host-side driver performs some basic validation of the request submitted by the user,
then issues the appropriate message to the gadget-side driver.  The gadget-side
driver waits for requests to come in and modifies the store as appropriate (using the
gadget-side storage library, see below).

In addition to responding to storage requests, the gadget-side driver must handle
requests from USB core to identify and describe the the device.  This includes
specifying the configurations that are supported by the device.  We use the
Lightweight USB Framework for AVRs (LUFA) library to handle the low-level management
of the Teensy device.  Though this in principle allows us to focus more attention on
the interesting control elements of the gadget-side driver, learning to use the LUFA
library was a significant investment in and of itself.  Ultimately, we think this is
the right choice for creating a robust and comprehensible driver in spite of the high
learning curve (after all, the underlying USB protocol is even more difficult to
master).

------------------------------------------------------------------------------
Gadget-side storage and display
Author: John Ochsner

We represent the storage of the device as an array of data-objects (currently of a
fixed size).  The storage library provides an abstraction over this array and
performs argument validation (making sure that the specified index is within bounds).

When the gadget-side driver receives a request to access a particular index, the
driver displays the specified index on a 4 character hexidecimal display connected to
the device.  This allows us to demonstrate a connection between a user request and
the actual operation of the device.