This project is distributed in two forms: release and devel (development).
The release distribution contains only the documentation. However, the core VHDL sources are also included into the documentation.
This is useful for those who just want to take a quick look at pAVR, without trying to run / test / modify it (for the latter ones there's the devel package).
The release distribution comes in two flavors: CHM or HTML. My favorite is CHM, because it's much more compact. I kept HTML for portability issues.
The devel distribution contains:
-
documentation
-
VHDL sources (core architectures and simulation / synthesis test architectures)
-
test programs (ASM and C)
-
utilities (preprocessor, some useful scripts)
In short, the devel structure contains anything one needs to test this project, use it, or develop it further. As a side note, this project was developed under Windows XP. Yet, most software tools used here have Linux counterparts (Doxygen, VHDL simulator, C compiler, TCL interpreter, text editor). Exceptions are Atmel's AVR assembler & simulator, which are Windows only, as far as I know.
The documentation is generated via Doxygen. For those who don't know how about this wonderful tool, please check www.doxygen.org .
The directory structure of the devel pAVR project is:
pAVR
doc
chm
html
simulation
test_alu
test_interrupts
test_io_file
test_pavr_util
test_register_file
test_std_util
test_whole_controller
bin2vhdl
test_general
test_jeff
test_sieve
test_stefan
test_waves
src
synthesis
tools
backup
common
update_file_headers
The \doc directory contains the documentation of course. It's available in doxygen source format. Run Doxygen to compile it and obtain the HTML and CHM in the HTML and CHM folders. Some scripts are also provided in the doc folder, that can be used to compile the documentation, clean it up, or run (view) it.
The \simulation folder contains the bulk of the tests used to validate pAVR.
A bunch of VHDL sub-projects test individual modules of pAVR such as ALU, register file, IO file, the interrupt system, various utility routines used throughout pAVR core files (std_util, pavr_util), and finally the pAVR controller as a whole.
The tests that check the microcontroller as a whole use a unique VHDL testing architecture placed in \simulation\test_whole_controller. This architecture blends to the core pAVR files a program memory, a data memory and everything that is necessary to run real life applications on pAVR. This complete pAVR environment is configured to run any of the programs in \simulation\test_whole_controller.
The workflow looks like this: compile the source program (ASM or C file) to get the HEX file, run hex2bin on the HEX file to get the binary file, copy the binary file into \simulation\test_whole_controller\bin2vhdl, run bin2vhdl on the binary file to load it in the program memory VHDL file, and then just simulate the pAVR testing architecture in \simulation\test_whole_controller. Simple, huh? ;-)
The directory \src contains pAVR's core VHDL sources and pAVR's license .
Only "the main stuff" is here - just the bare pAVR controller core, with neither Program Memory (PM) nor Data Memory (DM). Of course these sources are not enough for any kind of test, but they make up a logical entity well enough defined - the pAVR kernel - to be dealt with separately. This core can be flavoured with other "condiments" (PM, DM, test architectures, etc) to make up any test - for simulation, synthesis, or whatever purpose. The tests in \simulation and \synthesis blend components to this core to make up their own "pAVR environments".
When simulating, synthesizing or doing anything that could alter these core VHDL sources, first copy the files from here into the right directory (\simulation, \synthesis, etc), and process them locally. This way, the kernel sources will be separated from the testing workflow and thus will be protected against accidental corruption during testing.
The source files are written based on a set of common-sense conventions (the process splitting strategy, signals naming, etc). As a result, pAVR is quite an easily maintainable design.
The \tools folder contains some utilities.
One important utility is a text preprocessor. Almost every source file in this project has XML-like tags, inserted as comments, that mark various sections in the file. For example, some tags mark non-synthesizable VHDL code that can easily removed when synthesizing pAVR, while other tags mark sections containing project info, etc.
The preprocessor parses the sources and interprets the tags - for example, by inserting VHDL code in the Program Memory, or by refreshing project info header.
The \tools folder also contains some useful scripts used by most of the pAVR sub-projects. The most important of these is the project_manager TCL/TK script, that's described below.
Throughout this project there are a few sub-projects that must be edited & compiled & run independently (for example, generating the documentation, or compiling test sources). For this purpose, I use a TCL console with stdin & stdout & stderr, and a few buttons: edit & compile & run & clean. Each button launches a script with the same name as the button, placed in the same folder as the console script (sub-project's folder). The stdout/stderr of the scripts are captured on the TCL console. I use this "project manager" (the TCL console) the very same way for, let's say, compiling a C source or generating Doxygen documentation. Placing shortcuts to the TCL console in each sub-project's folder makes it possible to use only one copy of the project manager for all sub-projects. (Neat, isn't it? Huh, you didn't understand anything? Hmm, next time I'll try to explain better...)
