VHDL-HOWTO.f-cpu created Wed Aug 22 21:48:25 2001 by whygee@f-cpu.org version YG-12/30/2001 updated Fri Jun 21 12:22:59 2002 : YG spellchecked "license" ... updated Sun Jun 23 04:15:47 2002 : adding the tools database and included Michael's Vanilla error explanation revision Sat Jun 29 03:43:01 2002 revision Sat Jul 27 02:52:46 2002 : some updates on the tools ________________________________ FOREWORDS ________________________________ License : This file is distributed under GFDL. (include the correct license notice here). This text file explains some stuffs about the F-CPU, its sources and how to use VHDL tools in this context. It is oriented towards beginners who simply want to compile the source tree, and specifically who want to contribute to the F-CPU project. We would like to reduce the entry efforts to a minimum and concentrate on RTL coding rather than tool configuration. Too many off-topic efforts means that nothing gets done and people get frustrated. You are welcome to contribute to this HOWTO and share your knowledge and experience. After all, this is what F-CPU is about (too). Remark : the object of this HOWTO is NOT to learn VHDL or give lessons. It's a scratch-course for newcomers who already have enough RTL/VHDL knowledge. Otherwise, there are a lot of interesting VHDL ressources on the Net, for example the newsgroup comp.vhdl and its FAQ. Buying a few good books will also help a lot. The big Ashenden's "The Designer's Guide to VHDL" is a very valuable book and is worth the price. "VHDL for logic synthesis" 2nd ed. by Andrew Rushton is also clear and useful. Au fait, j'ai rédigé un article en français à ce sujet, pour Linux Magazine France si vous n'aimez pas lire l'anglais. Le texte est disponible à http://f-cpu.seul.org/new/lm02.tgz. ______________________________________ Chapter 1 : The F-CPU VHDL source code ______________________________________ The F-CPU project aims at providing a high-performance 64-bit CPU core under a Copyleft License (or a license that is better suited than GPL, a "Free Hardware License", if we can ever write or find one). Freedom of the VHDL sources is a very important side of the project but this is worthless if we don't ensure that the sources do comply with the industry standards. We try to provide all the facilities that are required to test the design, use it with different tools and facilitate its maintainace and use by people foreign to the project's core team. In other words : make it easy for others to contribute. 1.1) Why VHDL ? As the project started, VHDL was a natural choice because the contributors are located in Europe, where VHDL is often taught in schools. VHDL is also a very powerful langage which can express one thing in many ways and at different abstraction levels. This is useful when writing testbenches for example. We would like to maximize the source file reuse throughout the whole design process, from specification to synthesis and verification. Finally it is easily readable (though often not easy to write) and the syntax+semantics are specified in a set of IEEE standards. VHDL can be very complex. However : - most of the contributors are not VHDL gurus and we are all learning when we write VHDL code, - synthesisers often limit the accepted syntax, - some simulation tools like Vanilla VHDL are rather incomplete, so don't worry too much. If some code is not obvious, it will be explained and commented. Separating the "logic" (combinational) layers from the clocked ("sequential") parts also helps us to separate the many problems and solve them one by one. 1.2) How ? This document explains how to get, install, configure and test several VHDL tools. They are chosen for their ease of use, their (relative) freedom of use, their portability and their compliance with the VHDL specifications. This last point is maybe more critical than the freedom of the tools because it also determines the freedom of the sources. The efforts of the F-CPU team must remain ununcumbered from tool-specific features in order to keep other's freedom to contribute. A script is provided in f-cpu/vhdl/tools.desc : it contains the low-level tool invocations and is a single entry point to all tools. With this tool, the contributors are free from the scripting chores and they can add new tool descriptions without having to modify all the existing scripts. Ideally, there should be no tool-specific VHDL sources either. 1.3) Hierarchy All the VHDL sources are available under the f-cpu/vhdl directory. of this package. It contains all the READMEs and some "common" configuration/definition files, plus some TGIF/PS drawings (the .obj files are the TGIF sources, so you could remove the PS files if you're short on room). Each control or execution unit is located in an individual subdirectory, with the associated testbenches and compilation scripts for individual tests. FC0 (the first F-CPU core) is assumed to be the current core : other F-CPU cores would be distributed in different packages later. It is important to remember that FC0 has several "layers" : 1) execution core (scheduler, decoder, BIST, EUs and SRs) 2) memory access (fetcher, LSU, TLB and cache) 3) interruption/exception/trap model (and all the OS and protection stuffs). Every layer will be implemented progressively and extended as the others require more sophistication. Level 0 could be considered as the "configuration" package which defines the ISA and user-defined characteristics. It is left to a higher level, and it is "implemented" with a whole set of means in this package. The other levels are packed into the usual subdirectory structure. If another F-CPU core is released, we will try our best to keep the directory structure and the semantics of the constants such as MAXSIZE. The configuration tools should also be reused as much as possible. In addition to the "configuration" layer, we also use a portable set of VHDL tool configuration database that reduces the coding efforts, whatever tool you have installed on your machine. Additionally, a set of test routines are provided to check the VHDL sources against other versions written in other langages. The goal is NOT to verify and test the unit but to ensure that all versions in all langages (currently only C and VHDL) behave the same way in a "black box" perspective. Hence, it uses .hex files, it is a bit slow, there are few security checks, and it can be very large : the goal is not speed or security, but equivalence of all versions. 1.4) standards The F-CPU files are primarily written in VHDL'93 langage, using as few "specific features" as possible to facilitate the port (to Verilog for example) and synthesis. However, like any langage, VHDL has some idioms that may not be straight-forward to port easily, we can't garantee that porting to any langage will be easy. For example, C is a nightmare ("don't do this at home"). We try to emphasize a lot on the documentation, with as many in-line comments as possible, and with a documentation directory. Quality is further ensured through peer-review and cross-testing using several different tools during development. A bug-tracking system is being setup on savannah (FSF version of sourceforge). We care for your feedback on the f-cpu main mailing list (f-cpu@seul.org). Ideally, the F-CPU files are considered distributable when they have been tested with several simulators (at least Simili and Vanilla) and synthesisers, and reviewed by several people. Of course, this doesn't mean that the files would then be perfect, but at least it's a first step. 1.5) configuration As written before, the source tree provides with a portable, bash-based tool detection and abstraction layer. You can let high-level scripts (ie f-cpu/install.sh) call it for you. Then, all the detected and installed tools will be run when you simulate a design. You can configure what your preferred tool is if you don't want to use all of them. Running all the tools at a time may be CPU-consuming but catches development errors faster. The F-CPU source code tree, which includes C and VHDL files as well, is configurable to a certain extent. Some parameters can be defined by the user, the others are reserved to the f-cpu core team. Since many different projects can be influenced by a single parameter, we have chosen to centralize all the definitions in one set of common files. A text preprocessor ("m4") is used to generate the destination files at the apropriate locations. The f-cpu/configuration/ directory contains all the .m4 files and .in sources. f-cpu/configure.sh is a simple script that generates the necessary files in f-cpu/include/ (C include files) and f-cpu/vhdl/configuration/f-cpu_config.vhdl for example. The original files (before processing) are kept in f-cpu/configuration/. When you modify a .m4 or .in file in f-cpu/configuration/, you have to run f-cpu/configure.sh afterwards. It currently "embeds" a Makefile to cope with the increasing number of files and relieve us from the pain of updating every file everytime a new one is added... 1.6) how to use it We will now assume this example : you just downloaded this package and you want to play with it. The F-CPU project grants you the right to compile, examine and run all the files. In fact, you are even encouraged. And particularly, please read the documentation :-P Once you have read the F-CPU License (f-cpu/LICENSE.txt) and all the necesary documentation, you can proceed with the configuration phase. Some distributions might come with pre-processed files (for those platforms without m4) but if files seem to miss (in /f-cpu/include for example) then run f-cpu/configure.sh. This will generate the missing files. 1.6.1 simulation/test If you have an installed VHDL tool, you can start to compile the sources after you configured the source tree and detected the installed tools. Your tool might probably not be "supported" yet so look at f-cpu/vhdl/tools.desc : there is a script that you can tune and in which you can add new tools. If you accept the F-CPU license terms, we will be happy to include it back in the F-CPU distribution. Simulation of the testbenches (for the individual units) will probably cause some problems if your tool doesn't like sophisticated text I/O. Then you can try to emulate the whole circuit if you implement the BIST unit (which will test every implemented unit on "power-up"). Note : The BIST unit is still in its infancy at the time of writing... 1.6.2 synthesis Not much has been done yet. Stay tuned. A few contributors can access synthesis tools but no script or configuration file is available yet. We welcome your help. 1.7) how to modify Before you decide to contribute and modify files, you have first to agree with the distribution license (a Copyleft) which specifies that you have to redistribute all the changes you make to this package. Read the F-CPU License for some of the rights and duties of the contributors. Don't worry but don't expect too much either : F-CPU is not your average IP core from the shop in the corner. The License explains some of the things to do when developping the F-CPU. The first important thing is to respect other's copyright and coding style. Some people are very concerned by these points. The second thing is to not forget to update the copyright notice (add the time/date to the existing list). Third : when you have a working set of files, upload it on the Web, for example on the anonymous ftp at seul.org. There, people will be able to test your modifications, enhance them and put it on the CVS base. Fame is not garanteed but it will certainly help your karma :-) Do not hesitate to contact the developers on the f-cpu@seul.org mailing list. 1.8) VHDL writer's guidelines The F-CPU source code base is split into two parts : one is the "core" that is meant to be synthesised, the other is the galaxy of shell scripts and testbenches. There may be other langages (C, Verilog) : portable test vectors are provided and you can check that your unit behaves like in the other langages. The "core" must obey to the strict and constraining rules imposed by the synthesisers : no fancy or complex code, only "hardware description" code. In practice, the architectures contain almost everything in one process per pipeline stage. The pipeline buffers and the other FF are clearly separated. Remember that the logic "depth" of the pipeline stages is very thin : equivalent to a 8-bit addition/substraction. Look at the ROP2 unit for an example of the expected complexity. Be careful with the fanout problems too ! Propagating a bit to 64 inputs can use more "time" than expected and "hidden" problems like that can decrease the maximum clock speed of the core (use the "fanout" entity if such a case occurs). FC0 must work so fast that every detail counts. The "testbenches" are not subject to these strict rules. However they should be written in the simplest and safest way : one easily bumps into a hidden corner of the VHDL langage that the different tool implementors did not understand the same way. For example, Vanilla is a rather limited software and does not understand all the "sophisticated" VHDL'93 that other tools do. When a feature is not "portable", another architecture of the entity is provided with stripped-down capabilities by default. You will have to later compile the "extended" architecture if you want to use it. In addition to the usual filename, date, description, author name and copyright, all the VHDL files must contain the following block : --------------------------BEGIN-VHDL-LICENSE----------------------------- -- This program is free software; you can redistribute it and/or modify -- it under the terms of the GNU General Public License as published by -- the Free Software Foundation; either version 2 of the License, or -- (at your option) any later version. -- -- This program is distributed in the hope that it will be useful, -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -- GNU General Public License for more details. -- -- You should have received a copy of the GNU General Public License -- along with this program; if not, write to the Free Software -- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ---------------------------END-VHDL-LICENSE------------------------------ When included in C files, you can remove the comments but you have to change "-BEGIN-VHDL-LICENSE-" with "-BEGIN-LICENSE-". Shell cripts have their own marker, too : # --BEGIN-SH-LICENSE---- that includes the proper comment syntax. This is a safety net and "lazy" precaution, in the case the F-CPU licensing terms change. In this case, a simple sed/awk/perl/whatever script will be enough to replace the license in all the files, thus sparing us a lot of efforts. I know it's lame, but if you have another simple solution, please tell me. When i had to replace the headers from all the distributed files with the new address of the FSF, i wished the system existed before :-/ Later, when i corrected the spellings, i was happy that 'find' and 'sed' existed :-). _____________________________________ Chapter 2 : The VHDL simulation tools _____________________________________ This chapter presents the tools that can be used to develop the F-CPU. This is not exhaustive but to my knowledge it is probably the most useful part :-) The minimum requirements for a F-CPU developper are a text editor and a decent VHDL tool suite. There is no a priori about the OS, except that it should support long file names. A Unix, and preferably Linux are best suited because they contain the necessary management tools (scripting, automation, preprocessors...). The development and the regression tests require tools such as m4 and make, their absence makes things less easy. However we try to keep the generated outputs for convenience. If you use Simili under Win32, you'll have to derive the .bat script for the .sh files, because it might be absent. Now back to the VHDL tool suites. At the time of writing, there should be no problem whether you use one or another, as long as it supports enough VHDL syntax. The minimum requirement is Vanilla VHDL, which is rather restrictive, but there are some even more restrictive tools. Then, whether you have one or many, it's almost the same because all the tools go through an abstract level and no tool-specific script is needed. The F-CPU contributors have tried a lot of tools and unfortunately, no software is perfect. To our greatest sadness, no tool is going to be the "preferred" one and we have to test all the tools we find, check the compliance and modify the sources only when necessary. This increases the coding efforts but the side effect is that the resulting VHDL sources are more portable and more stable. There are better chances that if you use a completely different tool, you won't have to change anything :-) I have personally tried a lot of tools before i found a suitable one. Our main source of informations comes from http://www.opencollector.org where there is a very comprehensive database of free tools and designs. The definition of `free' is not very strict because we don't have much choice... Some personal opinions about what i've seen : * Alliance is huge, and far from straight-forward. It is not available on non-unix platforms (except Windows where it is a big mess due to X emulation). This "experimental patchwork of files" is more focused on synthesis and their supported VHDL syntax is _really_ reduced as well as far from compliant with any tool one can find in the wild. We may use that tool for synthesis in the future, but not directly/primarily, more as a backend. I'm seeking an EDIF "wrapper", for example. * Electric Editor : this "all in one" tool refused to compile VHDL files that were not generated by himself. The compilation was painful too. * FreeHDL is still in its infancy. What i have tried was a painful experience (it generates HUGE files) and i finally got a SIGSEGV after a long compilation. At least i learnt how to setup a swap file... A newer version appeared recently, i will maybe try it again. * PICA is very old and does not even compile. Too bad. * i certainly forget a few others... i think that i have not tested SAVANT, version 2 should appear soon. I can't test everything, because i have to code something sometimes (at last). If you have suggestions, don't hesitate to mail us. Of course, there are several "commercial tools" but they are often sold at very high prices. Their support is welcome but it is not our goal to encourage the F-CPU contributors to buy them. These tools are often accessed by contributors in the companies where they work or in the school/universities where they study. These "commercial/professional" tools are often really huge and require hardware ressources that are often not available to "beta testers" for example. However, they often cause less portability problems because they operate (by design) in very heterogeneous and critical environment. Tools like Modelsim never reported any problem, for example. Cadence has offered to help the F-CPU contributors by providing them with free licenses. In fact, we would rather need synthesiser licenses but we can't refuse anyway. Another class of tools is the "limited edition" commercial tools, for example those provided by FPGA vendors to promote their own workflow : they can be "free of charge" but are crippled on purpose and can cause other portability problems, at least for testing purposes, because TEXTIO might not be available and it can't output debug messages. Some other parameters can also be reduced, such as complexity/size of the design. You can try these tools but don't rely on them. I remark that we tend to use tools that are distributed in binary form, because it saves the user a compilation step that is often difficult. Compiling can become a nightmare, specifically for Un*x newcomers, and the contributors often don't want to be bothered by non-technical matters. However, there are sometimes some little library and dependency problems, depending on the Linux distribution. A fresh RedHat version should be safe enough. Conclusion : If Linux existed because GCC was available, F-CPU exists despite the lack of really free leading compiler. We hope that such a key tool will become available in the near future. In the meanwhile we have to do what we can with the existing stuff. Some call this "engineering" or "reinventing the wheel" but it's a pity anyway. 2.1) SIMILI 2.1.1) presentation : SIMILI is a very attractive software which has all the expected qualities for being used with the F-CPU project, except that it is not distributed under GPL. Otherwise, it is : - free (as "free beer", for the command line tools) - very simple - rather compact - console-only tool (with possible extensions) running in a DOS box (but it is a "real" win32 application) or under Linux - not dog slow - doesn't eat up all your memory (at least for the F-CPU sources) - complete (at least for us beginners) - almost completely VHDL'93 compliant (the few exceptions are not likely to be harmful) - independent from the vendors - the author is very responsive A port to Linux recently appeared with Simili2, read about it at the bottom of this chapter. For those with old versions, i have left the old part (with the heavy wine stuff). The strategy that the author has chosen is to use IEEE i/o for communicating with the user, thus favoring the portability of the designs : we are not bound to this tool and testbenches run on other tools too (it's perfect for the compatibility with Vanilla, for example). 2.1.2) Win32 Installation : a) download the package from http://www.symphonyeda.com/ (the latest version was VHDLSimili15b17.exe, 2847KB) --- NEW : Simili 2 build #23 is around 7MB with a GUI. --- b) "execute" the package and follow the instructions when prompted on the screen by the installation software. This is fairly non-intrusive. c) customize your autoexec.bat file to include the executable path, as needed. This way, you won't have to click on the simili link to setup the environment each time. d) read the documentation, run some tests. The package will install the documentation, the binaries and the base libraries, including all the IEEE, several vendor (FPGA) specific libraries and VITAL. We don't need all of them for the F-CPU preliminary development but they can be useful later when synthesis will start. Some documentation (5 minutes read) is provided in HTML format. 2.1.3) Usage : It is rather straight-forward : it is a two-pass process. 0- Open a DOS console with the necessary environment (one or two environment variables need to be setup, see above) and then 1- run "vhdlp myfile.vhdl" to compile the specified vhdl file(s). If necessary, add a '87 compliance argument (unnecessary for the F-CPU). It creates a subdirectory with a few result files. If several files must be compiled, vhdlp can be run sequentially with each file name or once with all the file names as command line parameter (in the right order). The second choice is faster but be aware of the 127-byte limitation of the DOS console for the command line. 2- type "vhdle" followed by the name of the entity you want to emulate. The output of the simulation is sent to the console, it can be redirected to a file with a pipe (">" or "|"). The F-CPU sources are all compatible with Simili (except one or two possible exceptions on code being debugged). The source tree provides (when possible) some batch files which contain the commands to compile the design and test it under Windows but it may lag... Run them after reading their contents and the READMEs. 2.1.4) Simili under Wine : If you successfully installed wine, you can use Simili under your favorite Unix flavour. In fact, if you read the wine manpages, and with a lot of good sense, wine's installation is the most difficult part. Configuration and use : 0- Running the windows installation package directly under wine doesn't work well, at least with the simili and wine versions that i tested. You may probably succeed if you can configure wine perfectly. Keep us informed. 1- Copy a working installed Simili directory wherever needed. If you didn't succeed installing the package directly (that is : if you didn't succeed with part 0) at least you can find a win32 box, run the installation program and transfer the generated files where you think ir fits best. Simili's installer asks where you want to put the files, so just go to this directory (with the Bin, Doc, Lib etc. subdirectories) and compact everything. note : If you use wine, i presume that it is because your computer doesn't have dual boot. However, your computer might have several partition types (FAT16 for examples). It makes no difference where you put the files, just take care of the user access rights and of the directory coherency. 2- Edit the wine configuration files so the searched paths include the location (in DOS view) where you have installed the files (there's a Bin directory which the installer creates). There is no wine.conf file provided with the F-CPU package. If you have read up to here, you will certainly figure out that "man wine" is a very iseful read, and carefully reading the comments in /etc/wine.conf will reduce the chances of errors. 3- Still with wine.conf, add a "drive" which points to your F-CPU installation directory. This way, the paths won't get too mixed up. This is not mandatory but it can help. You are also required to update the PATH environment in wine.conf, for example : [wine] Path=c:\;c:\windows;c:\windows\system;c:\vhdl\simili\Bin; 4- If you want to compile a file and emulate the result, type : $> wine "vhdlp file.vhdl" Wine usually displays a lot of error messages but they are harmless. they can be suppressed with a wine option : $> wine -debugmsg -all "vhdlp file.vhdl" 5- The setup time for running wine "vhdlp" (several seconds ?) can be reduced a lot when you compile several files at once. 2.1.5) Simili at work : Like other tools, SIMILI stores its results in a subdirectory ("work.sym") that it creates and manages itself under the current working directory ($PWD/work.sym/). So you'll have to go to the same directory ($PWD) if you want to work with a particular set of files. Remark that due to the limitations concerning the file system emulation, you can't access files that are located in other subdirectories, for example ../file.vhdl or ../anotherdirectory/file.vhdl (wine emulates the '\' but the file names might be too long or your "drive" points to the current directory, so you can't go below the root). 2.1.6) Limitations and constraints on the code : Simili accepts a lot of things but other tools can reject them. It is a good practice to double-check with Vanilla, in case you didn't feel yourself slipping in a dark corner of the VHDL LRM... OTOH there is a "-strict" option which restricts the syntax to pure IEEE compliance. Its use is recommended. The coverage of the VHDL'93 standard is explained in a document named Doc/vhdl93_readme.html in the Simili installation directory. With wine, Simili imposes a constraint on the directory tree because of the inability to access complex paths (this is due to wine/dos, not Simili). The F-CPU source tree is thus compiled from the root directory of the distribution (f-cpu/vhdl) Another limitation (still related to the file system) is that it is not possible to access "special files", ie for /dev/random. The workaround is to create a symlink in the directory. A little remark is that it sometimes output a warning at the end of a simulation : Warning: CSSIM0017: Found 1 ACCESS type object(s) that were never deallocated Note: CSSIM0018: xxxxxx.vhdl: (line yyy): 1 Leaked ACCESS object(s) allocated at this line It appears when files are used, so it is limited to the testbenches. It is harmless as long as the number of objects is low. 2.1.7) Simili2 : During november, 2001, Hanneef Mohammed released a new version of his tools with a native linux/x86 binary : no need to configure wine or hack around MSDOS' limitations ! Its use is as easy as under MSDOS but you can use more shell tricks ! OTOH some new tools are introduced (mainly the SONATA GUI) but it is not "free" (you have to request a "key" and own an ethernet interface card) and it is not required by F-CPU (everything is done with command-line tools and bash scripts). FlexLM is used but it is mostly transparent. Don't forget to rename the license file in 7-. There is still a Windows version but it is not much changed. For the Linux-x86 version : 1- Go fetch the distribution archive from http://www.symphonyeda.com/proddownloads.htm The Linux version weights more than 7MB. 2- Extract the archive in a temporary directory 3- Execute install.sh and follow the instructions 4- Install.sh will ask for the location where you want the files to be installed : prepare a directory where you have the necessary access rights No need to have root rights during the whole process. 5- Update your .bashrc (or .cshrc) with the parameters given by the installation script. It is as simple as updating your $PATH and sourcing a provided script. 6- The temporary directory can now be erased. (advice : don't install the tool to the temporary directory...) 7- In the new Simili bin/ directory, copy or rename the license file "freelic.txt" to "symphony.lic". Concerning the execution, it is freed from wine and all the parameters remain the same. All you have to do is compile the files and run the simulator like before, with "vhdlp -strict" and "vhdle". 2.2) Vanilla VHDL 2.2.1) Presentation : This is another little tool which is designed for use under Unix and DOS. It is a "simple" solution under Linux. It does not contain all the features and support libraries that SIMILI does ("impure" is not supported for example) but it is enough for small attempts. It should be ok to compile the F-CPU core source but some complex testbenches which use a lot of complex VHDL'93 can't compile. If Vanilla is the only thing you can work with, you'll have to wait until all the source code is cleaned. Here, only the "Unix" (linux) version is presented. The DOS version shouldn't be very different but i don't know where to find it. 2.2.2) Installation : It is not too complex, once you understand how it works. This is the original purpose of this HOWTO, too :-) 1- Download the archive at http://www.freehdl.seul.org/vvhdlt_1.tgz (around 300KB). It will provide you with # Vanilla Cad VHDL System version 1.5.7 # Copyright (c) Vanilla CAD Tools, Inc. 1995-1998 (please tell us if/where another version becomes available). 2- Create a subdirectory where you think it fits best. 3- Go to this directory and extract the archive : $> tar xvzf where/the/file/is/vvhdlt_1.tgz => this will create an apropriate set of files and subdirectories. You can then "chmod 644" the text files to avoid autocompletion troubles. 4- Update your $PATH so it points to the directory where Vanilla HDL is installed. You can do this in your .bashrc for example : "export PATH=~/vanilla:$PATH" if you have installed it in your home directory. Remark that you don't need to be root so you don't need to ask the admin/IT guy :-) 5- Optional part : Vanilla VHDL comes in two flavours : statically linked or dynamically linked to libc5. The small executable programs are wrappers for use in a shell or a batch file/Makefile, while the larger "vv87" is statically linked. If libc5 is available, or if you can install it (Debian Linux provides old libraries, including this one), go for it : you will be able to write nice scripts. Otherwise, you will have to use shell pipes to input a set of commands in "vv87", for example : $> vv87 < commands The F-CPU-provided scripts support this version by default. 2.2.3) test drive : Of course, reading the provided PS manual will be somewhat helpful but it's still a bit cryptic for me. From now on, i will assume that you can only work with vv87 only, for example when the small tools complain about "can't load library 'libc.so.5'". After this quick introduction, you will probably want to install the library. The syntax for vv87 and the shell tools is very similar, most tool filenames correspond to the associated command in vv87 (type "help" at the vv87 prompt for the list of available commands). Here are some steps to perform if you want to compile a file : 1- Go to the directory where the VHDL source file(s) is(are) located. If you have not set the path as hinted above, it will be more complex. 2- Run "vv87". You will be running in an "interactive shell", type "help" to see the list of available commands. The first thing to do (if not done before) is to create a "work" directory with (and only with) the command below (mkdir won't work) : v> mkvlib work The directory will be created under your current directory and all the files that you will compile will go there (like SIMILI and other tools, but it is not done automatically). 3- You can try to compile and simulate the example file "mux.v". Enter the following commands : " analyze mux.v (if you are in the proper directory) simulate work.multiplex run " Here is the output : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ v> mkvlib work v> analyze mux.v # Analyzing file "mux.v". # Entity: multiplex # Architecture: behave # Configuration: mux_config # Analysis of 32 lines is complete with 0 errors, 0 warnings. v> simulate work.multiplex # Linking... # /usr/yg/vanilla/std/standard # /usr/yg/vanilla/ieee/std_logic_1164 # /usr/yg/vanilla/work/multiplex__behave # # Elaborated 3 processes, 10 signals, 7 drivers. (0 ns) run (2147483647 ns) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4- Now, you can modify mux.v by removing the comment in the line : "-- clk <= not clk after 20 ns;" You will now have a 40ns clock cycle. Type : " analyze mux.v run " It will now take much more time (minutes ?) before the run completes because the clock runs continuously. Dynamic version : The commands (at shell prompt) are almost the same. 2.2.4 : Vanilla and F-CPU It is currently being supported in parallel with Simili. You are able to develop source code with either one (both are recommended). Because the provided individual shell commands (wrappers) do work only with an "old" version of libc.so, it is often difficult to make the usual kind of scripts. This is managed by the scripts so you don't have to mess with your machine's configuration (at the cost of a naughty bash hack). 2.2.5 : Limitations and constraints Vanilla VHDL is rather limited. However if the source files compile and run with it, they should work for any decent compiler as well. The whole VHDL syntax and semantics are not completely supported. Read Vanilla's manual for the list of the supported features. Some parts of the langage are supported in a very straight-forward way, while others are not provided at all. Topic one : it is not possible to write the following declaration : signal a : std_ulogic_vector(7 downto 0) := init(a); where init() is a function that takes std_ulogic_vector as input parameter. Often, this parameter is necessary to determine the size of the vector. While this declaration is correctly handled by Simili, this limitation of Vanilla is annoying, but a "wrapper" can be used for the init function. Such a case is seen in the rand() function (see vhdl/common/random.vhdl). Topic two : "shared variables" are not allowed in a package. Vanilla can't share a variable between functions and/or procedures. The variables must be declared IN the procedures, but can't communicate. Simili groks it. If it is not critical, use constants instead. Only exception (?) is the declaration of a FILE. Go figure. Topic three : In some (still obscure) circumstances, the vector sizes may be limited (bad interaction between integers or functions and bit vectors ?). Michael Riepe found that at least one error message is misleading (hey ! an error in an error message !). The problem is that mixing litteral and symbolic array indices confuses the compiler. Look at f-cpu/vhdl/common/others/fanout_linear.vhdl.diff for an example. vv87 says: # -- Failure: t: signal has multiple drivers with no resolution function. This is not true, of course - but vanilla doesn't grok it. This happens when certain combinations of range attributes are used (in particular, 'high and 'low seem to cause problems). If you use explicit ranges, e.g. `WIDTH-1 downto 0', everything is fine again. Topic four : it's not a big failure but be warned anyway : it does not display vectors longer than 127 elements or so... 2.3) ncsim Thanks to the help of Martyn Pollard, F-CPU contributors can use some Cadence tools, including ncvhdl and ncsim, under the condition and in hope that the F-CPU files be compatible with it. It's a fair deal if you consider the "value" of the provided software. OTOH, the installation is far from being straight-forward if you have some exotic hardware (like ... guess who) and you don't have a hotline if you have a problem (except complaining on the f-cpu mailing list or on comp.lang.vhdl). Usually this kind of tool is setup and installed by competent, trained and paid system administrators (well, at least the third point is sure) and you will need a lot of patience and hard disk space (1GO ?) before you consider the use of this tool _at your own risks_. 2.3.1) Prerequisite ***** WARNING ! ***** You MUST contact mjp@cadence.com before going further ! Only Martyn will give you the authorization to use this software. The other F-CPU contributors are not responsible for anything and are not allmighty. I won't explain you that it is illegal to use it without explicit consent from Cadence. If you behave badly and pay for this, nobody will be sorry for you. The information contained in this file is only for informational use, it is not endorsed by Cadence etc., it only relates someone's experience. End of legal/moral disclaimer. ***** /WARNING ! ***** Due to other legal and corporate pressures that you will certainly understand, you have to provide Martyn with the following informations : 1> confirm that you have a background (and which) in electronics/computing 2> your full name, address, phone number, email address 3> full name, address, phone number and email address of the person acting as reference (teacher, chief, manager, ...) 4> Name of the university/college that you attend, or the current employer. 5> Explicit your intention for using the software Please note that these terms can vary. If you agree with the terms of use (the tool is only for personal use and limited to the frame of the F-CPU project), Martyn will ask you to send him the MAC address of the Ethernet network interface adapter that is plugged in your computer. * Don't know your MAC address ? I'm a real network/linux newbie so one day i discovered it when running dhclient (!). Expert advice needed. Martyn's documentation is not always consistent, it speaks about $HOSTID and IP address. I hope that the situation will become clear. ### Anyway the TRUE way to check this is to run "ifconfig -a" ### * If you have no Ethernet card, you can find cheap ones today (<$13 ?). * If you are like me (broke and using a laptop) you can find used PC-cards for around $30 with some efforts (computer fairs, flea markets... second hand stuff or refurbished hardware). If it's only for the use as the key, then no need of a full-speed 1 terabit/sec adapter of course. * If you don't know how to configure a network, it's time to learn. Not that Cadence's software requires a functionning network (it works in local mode) but it's always useful. Who knows. Now that you know your MAC address (a set of 6 pairs of hexadecimal digits, such as "05:02:89:23:AC:EF" for example), send it to Martyn. He will send you an e-mail back containing some instructions and a "key" file that is valid during two or three months (it's renewable so don't worry, just contact him again if the license timed out.). At this time, you get some instruction files that you have to read. If you succeeded with Vanilla and Simili, you can go on but it's not easier either. In the rest of this document, i will relate my experience and try to fill the gap or inconsistencies of the instructions. I will only speak about the GNU/Linux/x86 platform. Be aware that it will work only on recent versions of Linux, specifically RedHat > 7. 2.3.2) Download If you have solved the problems of the prerequisites, don't think that the fun is over. Martyn will give you an address in the ftp site from Cadence. It's often a "blind" address (you can't list the directory contents so you have to know the address correctly) and the file is __very__ heavy. So here comes another class of problem : you have to retrieve around 130MB off the net. FYI it takes 36 minutes at 60KB/s, or a whole day by RTC modem. Fortunately for me, a friend equipped with ADSL has downloaded the file for me and sent me a CD. Another solution is to go to a cybercafé, a university or at work if they have a CD burner or a hard disk drive rack... To solve this problem, we might need an agreement with Cadence so F-CPU contributors can pass the package to other newcomers. Since the package is relatively independent from the license key, it may be possible that someone sends you his package but this is only an eventuality. If you have a slow connexion to the Net, Simili and Vanilla are the best ways to start anyway. 2.3.3) Installation Please read all the provided text and PDF files ! They may supersede this file. However the files i have seen contained mixed DOS paths, csh and bash syntax, some files where even targeted at non-x86 platforms, so this HOWTO is still a useful read. It is necessary to have access to root privileges, so you can install the Cadence package relatively low in your file tree : /var/cadence or /usr/vhdl/cadence, wherever you are sure to have "enough room". The network configuration will also need access to the low layers and the provided pgp executable can complain about the lack of libstdc++.so.2.8 (2.9 and 2.10 were installed on Debian, but 2.8 is available in the binary2 CD and needs direct installation). [why isn't PGP compiled statically ?] If you have successfully extracted the .pgp file and run the pgp binary, now you need the pass phrase. You will have to request it from Martyn Pollard. You see, it's a complex and long procedure. Then you can decompress the resulting .gz file : at this point the whole stuff takes around 460MB (.pgp file plus resulting .tar file). Hint : typing directly "tar xzvf file.tgz" skips one step and uses less memory :-) But let me tell you that even at this point, you need a rather fast hard disk drive and a stable/robust kernel. If you don't have already optimised your HDD , it's time to run hdparm ! The package that i have contains 117MB of documentation (including a large amount of pictures) and 228MB of tools. 2.3.4) Configuration Follow all the instructions in the READMEs and PDF files, but be careful about the syntax. A few lines need to be added or changed in a few files, particularly the provided license.dat and your /etc/profile or ~/.bashrc for the environment variables. Here is a BASH version where several typing errors are corrected (you can copy/paste this one more safely): export CDS_INST_DIR= export LD_LIBRARY_PATH=.:$CDS_INST_DIR/tools/lib:$LD_LIBRARY_PATH export PATH=$PATH:$CDS_INST_DIR/tools/bin export CDS_LIC_FILE=$CDS_INST_DIR/flexlm/license.dat you have to modify the key file to reflect your configuration The documentation asks you to %cd %ln -s tools.lnx86 tools but the version i tested did it automatically. Then : " To sanity check the installation is valid, source your .cshrc file. %which ncsim " (note that "which" might be different in bash, use autocompletion instead) " should return; %/tools/bin/ncsim and %ncsim -version should return the version number of the installation " If the sanity check and the IEEE libraries installation succeeds, then there should be no dynamic library problems anymore. Before you proceed to the license management configuration, check (just in case ...) that your ethernet network is up and working : bad kernel or rc.d parameters might delay the proper installation of the package. type "ifconfig -a" to be sure. If you can successfully run nclaunch, you have won the right to read all the tool's documentation... WARNING ! run flexlm with a single user or be cautious ! when the flexlm deamon is started, it will create a directory where the PID and other informations are stored. If this directory doesn't exist, it will create it, and other users won't be able to run lmgrd. In this case, the solution is to chmod this directory (/usr/tmp/.flexlm) 2.3.5) Usage ncsim is a trio : there is the usual compilation phase then the elaboration and simulation parts are split, unlike simpler tools. This is because ncsim uses binary instructions from the target, instead of interpreting an intermediate representation, and the compilation can take "some time" that can be skiped if the source code has not changed between simulations. ncsim also requires a set of "configuration files". The first is called cds.lib, which contains for F-CPU : INCLUDE $CDS_INST_DIR/tools/inca/files/cds.lib -> this line links the design with the standard library DEFINE fcpu_lib ./cds_work_dir -> this line defines the name of our current working space/library. These two lines currently require manual intervention by the user : * $CDS_INST_DIR must be correctly set and working * cds_work_dir must exist : do not forget the mkdir * the library "work" is mapped to "fcpu_lib". This is transparent to the other tools and you don't need to fiddle with this unless you work with other designs as well, and want to reuse some files or connect to other components. "fcpu_lib" is currently an arbitrary name but i'll use it in the future. the "-" is removed to avoid syntax problems. This should be handled by the compilation script. However, be sure that your environment variable $CDS_INST_DIR is correctly set, or you'll have to manually modify the file f-cpu/vhdl/cds.lib. The other file is hdl.var which contains : DEFINE WORK fcpu_lib so the toolset knows where we work :-) Note that the integrity of these file is important ... Then the workflow is : $ mkdir ./cds_work_dir # (working library directory) $ ncvhdl -V93 filename.vhdl filename.vhdl ... $ ncelab work.entity:arch $ ncsim [options] [lib.]cell[:view] (and it finally finished for this tool !) 2.3.6) Limitations and constraints As you have seen (and experienced), it is not straight-forward to setup : it took a year before i could use it on my laptop and i still even have troubles from time to time... This is the first limitation (add to that that it is not "free" and it's a big drawback). Simili2 under Linux is so much more handy (that's why it's described first) ! Another constraint is the library organisation : it takes the LRM's specifications even more seriously than Simili (one better has to have it on his desk) and it requires the funky files "cds.lib" and "hdl.var". It took some time before i could make them work (big thanks to the Cadence guys who had the patience to guide me through) and this might influence (for the good) the file and entity hierarchy. Understanding what these little files mean, however, is not straight-forward to beginners. Just copy and paste them if you don't know. In F-CPU, it is symlinked to reduce size and avoid coherency problems (so just don't care unless it breaks). In practice, it seems to be very picky, even compared to "vhldp -strict". OTOH, it is really fast ! I measured a 60x speedup when running MR's exhaustive test loops, compared to Simili. The difference is even more important with Vanilla. It is an interesting point if one wants to run some sofware on the simulated core. Or simply when running MR's tests... 2.4) modelsim Not ready yet. I don't have access to it but reportedly no problem has ever occured with it. I once tried it (when i was at Mentor) and it's rather straight-forward, there is no pressure on the source code AFAIK. Support should also be easy, as it is called similarly to Riviera. It is half-supported in the abstraction script but not tested, I inferred the commands from old scripts written by Erik Hansen. 2.5) Savant (if i ever succeed to compile it) (MR reported coredumps like with FreeHDL) 2.6) Alliance There are many reasons to not use it, and the fact that no company uses it is one argument. It is used in some universities but the file formats it uses, the methodology and the workflow are compatible with nothing. Maybe it would be useful if given EDIF instead of VHDL but it's only speculation... Although it is not useful yet, there is a way to setup Alliance quickly under Linux/x86. A MS/Windows version exists but the compatibility layers make the installation difficult (though possible but i don't have tried it myself). Alliance comes in several flavours and for several platforms. The installation will deal with the easiest and recommended version : the "unstable/development" package. They are usually available from the ASIME department on CDROM or FTP/web at http://asim.lip6.fr. The "unstable" package can be found at ftp://asim.lip6.fr/pub/cdrom or ftp://asim.lip6.fr/pub/alliance/unstable/development/alliance-4.5.0 (some F-CPU contributors can provide the files if necessary). [note : Alliance 5.0 was released in june 2002] This package is a precompiled version for Linux/x86 only and a recent OS, like RedHat 7.1, is recommended. It requires the Motif (lesstif ?) library for the GUI-based tools. Make sure you have enough room to extract the 120MB uncompacted files (50MB binaries, 12MB tutorials, 20MB of precharacterised cells, 6MB docs, 12MB libs...) The installation is very simple : - copy/untargz the files under the desired directory. - go to the Linux/etc/ directory of the alliance package and edit "alc_env.(c)sh" : modify ALLIANCE_TOP to reflect the directory where the files are installed. - modify your .bashrc or /etc/bashrc to source this file during startup. You can then access most tools except Yagle and Hitas which are now commercial tools. Alliance is not adapted to VHDL'93 development. It uses a lot of internal, poorly documented and unstable file formats and tools, making it useless for our project's source tree that wants to only use stable and widely used standards. It is defined as a "prototype", a kind of playground, but i wish it will evolve. 2.7) Aldec's Riviera 2.7.1) Description : This is another compiler/simulator duo that ressembles Simili and Vanilla, both from the installation and the user's points of view. It is also sometimes used in replacement or parallel with Modelsim so the commands are similar. I will only cover the command-line tools and skip the GUI and batch modes because we use only bash scripts. Riviera is claimed to be used as a backup tool for other commercial tools so i expect that this description will implicitely cover more than Aldec's package. Just look at the existing tool descriptions and see which looks almost the same... Riviera is a commercial tool and works with the flexlm system, refer to the previous parts about it. I have no price indication but i presume that it is not in the price range of students and hobbyists. However you can request a demo key that lasts 20 days. Go to http://www.aldec.com and fill an online form (or send an email). 3 month keys are also available to F-CPU developpers but ALDEC's policy is not clear yet. 2.7.2) Installation : This should be rather simple, follow the indications on the booklet of the CD case or the online doc. The flexlm part might need some network configuration, however. 2.7.3) Usage : It looks like Vanilla because we need to care for the work directory. Compilation is like Simili but the simulation seems to be scriptable only with the provided shell. The whole toolset provides other means but the existing portable F-CPU framework is adapted. Beware however when Modelsim is used on the same computer because Riviera uses by default the same command names : vlib, vcom, vsim... The current solution is to call Riviera through a script that reads the environment variables that the start script sets. This way, there is no name collision in practice. Don't forget to update your .bashrc so it runs $ . 'path/to/riviera/etc/setenv' The invokation looks like this : $ $VSIMSABIN/vlib work work_riviera (there is a directory name collision with Vanilla => we use this command to put the temporary directory somewhere else) $ $VSIMSABIN/vcom -work work filename.vhdl Pour la simulation, il faut lancer $VSIMSABIN/vsim et taper set worklib work asim (ENTITY) (ARCHITECTURE) run -all 2.7.4) Riviera and F-CPU It is a compromise between Simili and ncsim in terms of ease of use, price and other things. It is smaller than ncsim (40MB) and is easier to install than ncsim, yet has attracting features (i'll name the new code coverage function for example, and i did not try EDIF simulation either). But Simili still wins in terms of installation and requirements. When it comes to speed, i measured that it is almost as fast as ncsim for MR's heavy test loops (beware since it can depend on the type of code). 2.8) what else ? _____________________________________ Chapter 3 : The FC0 code architecture _____________________________________ This part is going to repeat a lot of stuff that is already written into README's etc. but read everything anyway (it is always worth and will save some errors). This part is looking at a higher level than the individual files so you can better understand them. 3.1 clocking F-CPU uses a stable, square-phase clock that feeds the whole core synchronously. The pipeline stages are so thin and the scheduling is already so complex that asynchronous clocking (self-clocking or varying clock phase) is not considered. "Wave pipelining" (a N-stage unit without pipeline gates in the middle) for the multiplier or the cache are possible but too difficult for us. It would change the unit's latency when the clock frequency varies, and it is out of question because of the static/hardwired instruction scheduler. The main F-CPU clock is considered as running at the highest frequency possible. It is therefore not possible to make a local 2x clock for example. Phase quadrature clock is not possible either, because there would not be enough time to discriminate between the four phases. So we run on one clock signal of the highest possible frequency. The clock is active on a rising edge and the CPU state is "frozen" and stable at that time. If you stop the clock, you can examine the internal registers with boundary scan for example. Dynamic clocking (relying on the CMOS gate capacitance to hold the pipeline gate with a simple inverter) is not considered because it would make the design too much process-dependent, not easily synthesized and too difficult for us to debug. However, adapting the F-CPU for other clocking methods should not be too difficult. The clocking strategy is simple and robust so specific implementations are possible. For example, I have investigated the possibility to use "2-edge flip-flops" (they latch data on both clock edges). The difficulty is still to design a valid cell but in theory its use would allow the clock network speed to decrease by 50%, thus possibly sparing some energy (25%). The F-CPU should be able to run below its frequency rating, for example when running in low-power mode or when the silicon process varies in quality (so you don't throw the chip away simply because it can only run at 80% of the expected speed). The F-CPU clock is ideally generated with a programmable PLL, which could be programmed from an internal SR (still in the ideal world). The clock unit is available from f-cpu/vhdl/clock and can be replaced at will if you have specific needs or a particular platform-dependent clocking strategy (ie : FPGA). The generated clock should have a 50% phase, with a possible variation (as small as possible) if the clock frequency is reduced from its maximum. Changes in the clock speed must be as smooth as possible. I have tried to design an internal PLL that will progressively modify the internal speed in order to avoid power spikes and expensive power supplies. Look at a PentiumIII motherboard and all the big condos around the chip... Then read the Intel application notes to see why they are necessary. Ideally, current changes should not be shorter than 10us, avoiding expensive noise-reducing techniques on the power plane etc. In fact i think that it is not possible all the time, such as when an IRQ happens when the core is asleep, but we can try to enforce this measure where it is reasonably possible. Most design units in the individual subdirectories are asynchronous, purely "logic" layers. Most pipeline buffers are inserted in the top-level package so the clocking strategy can be changed at any time without causing impact on the execution units. Ideally. Note : for the VHDL simulation, the clock_stop signal is used to stop the simulation (the simulator stops if no new event occurs, so this is a clean and simple trick ; virtually tie it to VCC in a real implementation so the signal gets discarded during the optimisation). 3.2 Reset : Hard reset is a signal coming from outside the core. It stops the internal clocks and resets some internal data when it is low. When released (high), the BIST is started and the CPU can then start to execute the bootstrap loader. For power and clocking reasons, the internal RESET signal is delayed until the PLL has reached a steady state (if an internal PLL is implemented). The PLL has to provide a way to indicate that it is stable, releasing the internal reset. This is done in the clock entity. On top of that, RESET can be released only when the power is "good" (the power supply has reached a steady voltage). Please use the apropriate external component to drive this pad (usually : a RC cell connected to ground and VCC, followed by some Schmidt triggered inverters). This can not be easily simulated with digital VHDL so be careful with the synthesis !!! Finally, signals may float or reach unstable/forgitten states when the power is on. You will have to verify that the reset is correctly released WELL AFTER the power is on. For simulation and test purposes, the F-CPU bundle provides a package that initializes the variables to random values, thus ensuring that RESET does its work correctly and at the appropriate location. Reset signals have to be used when necessary but not everywhere (otherwise it would bloat the IC and reduce the operating frequency) : Reset is used in critical locations only, BIST performs the initialisation for the remaining latches. The pipeline latches and the register set are not reset but flushed by the BIST procedure. 3.3 Power On procedure : From the above, we can deduce the following chart for the outside connectors : 1 Apply power * wait until power stable and good 2 Start clock * wait until clock is stable (usually, the clock starts when the power is on) 3 Release the reset signal * wait until BIST success. 4 Start executing boot code at address 0. From the core's point of view, all we need is a clock and a RESET signal, so this is what is done by the most simple versions of the clock unit. More complex configurations can allocate different things in the clock unit : PLL or frequecy divider and multiplier for example. Some functions can be done with an external circuit or inside the core. There is no strict line between the clock unit and the external world in this case, as long as the SR interface is not changed. The power-on sequence can also start from any point if the preceding points are complete, for example when soft-resetting the circuit. Note : the BIST unit contains a memory bit which is cleared at power up and set when BIST procedure succeeded. This way, BIST is not triggered when RESET is requested a second time. Note 2 : by default, at power-up and after RESET, the clock unit is configured with external, full-speed frequency. It must be reconfigured by the bootup program. Note 3 : frequency dividers and multipliers as well as PLLs are optional, btw. When not available, the corresponding SRs should have a special hardwired value (the clock status register must indicate that the PLL is absent). 3.4 Power Management : The strategy is that the kernel must manage the ressources itself. For example, if a "sleep" order is sent to the CPU, a HW mechanism could stop the process of a vital operation, so the OS's kernel is the best place where deciding whether to shut the CPU down is correct. Power management signals should be normal interrupts. All the PM ressources (query, status and control signals) must be mapped to SRs. The user (HW implementor) must not change the external clock frequency, the software running on the CPU must do it itself. ___________________________________________________ Chapter 4 : file dependencies and package hierarchy ___________________________________________________ (ASCI trees here)