Glossary
Some definitions of terms used with AWB:
A workspace is simply a directory where one works on an AWB-based project. Any awb commands that need a workspace context in which to operate will automatically search up the directory tree until they find the root of a workspace to determine the workspace in which they are running.
Workspaces contain a stylized directory structure, which looks as follows:
|-- [[awb.config]] - the configuration file for the workspace
|
|-- build/ - a directory containing builds for awb-based designs
| `-- default/
| |-- design1/ - the build area for 'design1'
| | |-- bm/ - a place to run benchmarks for this design
| | `-- pm/ - the code for 'design1'
| |
| |-- design2/
| | |-- ...
| | `-- ...
| |
| `-- ...
| |-- ...
| `-- ...
|
|-- run/ - an area to run experiments on multiple benchmarks using awb-run
| |-- ...
| |
|
|-- src/ - an area to hold checked out packages
| |-- package1/
| | |-- ...
| | `-- ...
| |
| |-- package2/
| | |-- ...
| | `-- ...
| |
| `-- ...
| |-- ...
| `-- ...
|
`-- var/ - various temporary files used for workspace management
`-- log/
Note: The src/ area starts out almost empty, and must be populated by checking out packages using awb or awb-shell. Similarly, the build/default/ area starts out empty and is populated when a user configures and builds a specific model using awb or awb-shell.
To configure a model (using either awb or awb-shell) in the context of the the awb system means to collect a set of source files together that can be built into a specific design or model. In the awb system a model is constructed plug-n-play style out a large pool of modules, where each module is comprised of a set of source files. The specific set of modules (and hence source code) that comprise a specific model are specified in an .apm file. Thus given an .apm file, the configure process involves placing copies of the designated source files (via symbolic links) and some automatically created glue files into a model-specific subtree in the build area of the workspace. The build instructions (currently in the form of scons scripts) are also placed into this build area and so a build of the design simply consists of invoking scons at the root of the model’s build tree.
A bundle is a collection of repositories (with optional versions) that can used to check out as a group of packages using a single bundlename. Like repositories, bundles also can take an optional version. For those awb-shell commands that take a bundlename they are specified as follows:
<bundle_name>[/<bundle_version>]
Bundles are specified in bundlefiles.
A repository is a source code repository using one of the supported source code management systems. Currently there is support for CVS, SVN and Bitkeeper. Work is in progress on git and mercurial. A user checks out a package (see below) by specifying a repository name and optionally a version, which specifies a revision, tag, or branch in the repository. For awb-shell commands this specification looks like:
<repository_name>[/<version>]
The set of available repository names are specified in a .pack file.
A package is simply a portion of a repository that has been checked out in a workspace. For example in an SVN repository, the portion of a repository that corresponds to a package will typically be the trunk, and different versions of the package could come from any tagged version or branch of the trunk. A package generally has a stylized format as follows:
. |-- configure - a configure file to configure the tools in a package |-- Makefile.in - a file that ./configure will convert into a Makefile |-- Makefile - a file created by ./configure to build the tools in the package | |-- changes - a text file with a changelog for the package | |-- admin/ | | | |-- mytags - a bookkeeping file for keeping track of commits | | | `-- packages/ - a directory with information on the package | `-- packagename - a file with information about the package | |-- config/ | |-- modules/ - a directory tree containing modules that can be used in models | | | `-- ... | `-- ... | |-- experiments/ - a directory containing experiments for awb-run | `-- tools/ - a directory containing tools
Note: the configure/Makefile.in/Makefile files are optional and do not build a user’s model, but simply the tools that might exist in the package. Building a model is accomplished through a separate sequence that uses awb or awb-shell to configure/build/run a specific user-created model.
An AWB model is a hierarchical representation of a design, where each node of the hierarchy is a module, which might have other child nodes. Within a workspace there can be many models that are each constructed plug-n-play style out of the pool of modules available in all the packages in a workspace.
Models are represented in an .apm file, which are typically found under the config/pm directory of a workspace and can be edited with the apm-edit program.
In the AWB editor GUI, models are marked with an icon which looks like a double cog 
whose color can be interpreted using this chart.
Note: the terminology model dates from when these tools were designed specifically for doing performance modeling. We later realized that AWB is capable of representing general programs or hardware designs in which plug-n-play replacement of modules is useful, so this might better be referred to as an application or design.
A module is the individual node of a model. Each module has an awb-type and the modules within a model can be replaced plug-n-play style by any alternative module of the same awb-type.
Each module is specified in an .awb file which specifies the awb-type of the module, the types of the children modules that it ‘requires’ and the source files that implement the module.
In the AWB editor GUI, modules are marked with an icon which looks like a single cog 
whose color can be interpreted using this chart
Each module specifies an awb-type that it ‘provides’, which is a meta-type that is used to identify different module implementations that are compatible plug-n-play replacement modules that satisfy another module’s requires as specified in that module’s .awb_file.
In an attempt to simplify the use of multiple packages in a workspace and ease to movement of files from one package to another, awb supports the notion of a union mount-like directory structure that overlays the files from a set of packages. This set of packages is specified as a uniondir search path. The directories in all the packages in this search path are examined when the user specifies a file path. Thus when a users asks for a file with a relative file path, like config/pm/hasim/test.apm, a search is conducted in-order through all of the packages in the search path for a file of that name relative to the root of each package. The first match in that search is returned.
Packages are added to the package search path when awb-shell commands such as ‘checkout package’ are invoked. The search path itself is actually specified in the SEARCHPATH variable in the [Paths] section of the awb.config file at the root of a workspace.
One can check the resolution of a searchpath lookup using the awb-resolver command. For example:
% awb-resolver config/pm/hasim/demos/traffic_light/traffic_light_exe_nosynth.apm
/home/jsemer/asim/src/hasim/config/pm/hasim/demos/traffic_light/traffic_light_exe_nosynth.apm