********************************************************** ChipVault Help: (Ctrl-D to page down) --------------------------------------------------------------- Disclaimer and Terms of Use: 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 enclosed GNU General Public License for more details. In no event will the Author, Kevin M. Hubbard be liable for direct, indirect, special, incidental, or consequential damages resulting from the use of this software, even if advised of the possibility of such damages. Use of this software in the design or control of machinery involved in 'HIGH-RISK' activities, i.e. activities where failure of this software could reasonably be expected to cause DEATH, INJURY or the RELEASE OF HAZARDOUS MATERIALS, IS NOT PERMITTED. --------------------------------------------------------------- Web-Site: http://chipvault.sourceforge.net Please email the author at khubbard@users.sourceforge.net to let him know you have tried ChipVault and what you like/dislike about it. The author is always looking for improvement ideas. Table of Contents: i) Key Codes ii) Vi+Emacs Help iii) FAQ iv) Author Info v) GPL License ********************************************************** i) Key Codes: [ Navigation ] or : Navigate Up Hierarchy : Navigate Page Up Hierarchy or : Navigate Down Hierarchy : Navigate Page Down Hierarchy or : Navigate Left or : Navigate Right : Search forward on Module Name : Search backward on Module Name [ Hierarchy Expanding/Collapsing ] : Expand and Collapse hierarchy Views. <1> to <9> : Collapse all below level < >. [ Schematic'ish Block Viewing ]

: View Ports into each Block. Inputs on the left an outputs and bidis on the right. : View Children Blocks. Same as

but shows all the children instantiated by the current block. [ Tool Control ] : Perform Tool Bar Operation on File (Edit, CheckIn,etc) : Tool Popup Scroll Menu. Select tool and press : Bang History. Recall prior used tools via <1>..<9> <@> : Macro Tools. Call pre-assigned tools via <1>..<9> [ Misc ] : Resize Screen and Redraw. : Toggle Split Display Modes. : Toggle Debug Mode. Useful for displaying key codes. : Quit [ Macro Assigned Keys ] : Compile : Edit : View Log File : Checkfile In/Out ********************************************************** ii) Vi + Emacs Help Vi Help (Brief): [Saving and Exitting] ":w" : Write file to disk ":q" : Quit Vi. (use :q! to abandon edits) ":w foo" : Write file foo to disk ":r foo" : Read and Insert file foo from disk ":e foo" : Edit file foo [Switching between Commands and Edit modes] "": Switch from text edit mode to command mode. "i" : Start inserting text at current cursor position "R" : Start overwriting text at current cursor position "A" : Start overwriting text at end of current line [Cut and Paste] "2yy" : Yank-Yank 2 Lines (Copy) at current cursor position "3dd" : Delete-Delete 3 Lines (Cut) at current cursor position "p" : Paste Yanked or Deleted line(s) to current cursor. "dw" : Delete Word right of the cursor. "5d: Delete 5 characters right of the cursor. [Scrolling] ":1" : Go to Line 1 (Top of File) ":n" : Go to Line n ":$" : Go to Last Line (End of File) ":set number" : Display Line Numbers [Search] "/foo" : Search forward in file for "foo" "?foo" : Search backward in file for "foo" [Search and Replace] ":.,+8s/foo/bar/g" : Replace "foo" with "bar" on the next 8 lines. [Block Move] (Yes a mouse would be nice here.) 1) Position Cursor at top of block, leftmost column. 2) "ma~". 3) Position Cursor at bottom of block, leftmost column. 4) "ms\". 5) "`sd`a" (can sub "d" for "y" for Yanking instead of Deleting). 6) Paste ( "p" ) at desired location. (End VI Help) ********************************************************** Emacs Help (Brief): [Saving and Exitting] "Ctrl-X Ctrl-S" : Save "Ctrl-X Ctrl-C" : Quit [Navigating] "Ctrl-A" : Start of Line "Ctrl-E" : End of Line [Cut and Paste] "Ctrl-Space" : Set Mark "Ctrl-W" : Cut Mark to Cursor "Ctrl-Y" : Paste "Ctrl-X U" : Undo "Ctrl-K" : Delete Cursor to End of Line (End Emacs Help) ********************************************************** iii) Frequently Asked Questions (FAQ) 1) What is ChipVault? ChipVault is an interactive Perl program for controlling hierarchy of a chip design. It can handle both VHDL and Verilog, or any clear text design effort that may be sorted by hierarchy. 2) What are the main features? a) Hierarchy Organization of Source Files. b) Simple Revision Control for Group Projects. c) Instant Port Views for VHDL sublocks. d) Issue Tracking Database. e) Auto Instantiate VHDL and Verilog blocks. f) Hardware and OS Flexible. g) Free (Open-Source GPL'd). a) Hierarchy Organization of Source Files: ChipVault organizes your source files via hierarchy and allows you to rapidly navigate thru hundreds of source files deep into a design. CV can be used to launch your favorite editor like Vi or Emacs. ChipVault is fully customizable allowing you to launch other tools such as compilers, Synthesis, Perl scripts, Lints, etc. Since ChipVault knows the hierarchy of your design, any tool you configure for launching from CV may be launched for bottom up hierarchy execution. b) Simple Revision Control for Group Projects. ChipVault provides a Check_Out and Check_In feature for source files. Checking a file out generates a copy of the file for you to edit. The original file remains untouched until you check in your changes, allowing a group of designers to share the same source tree. WhatThisIsnt : This isnt RCS,CVS, etc. . IMHO those tools are great for big SW project, but overkill for HW designs and they slow down the design effort with an extra layer of complexity. Revision Control in ChipVault is tailored for HW designers. Only one designer may check out a file at a time. HowThisWorks : When you check out "foo.vhd", ChipVault creates a copy called "wip.foo.vhd". So long as "wip.foo.vhd" exists, no one else may check out foo.vhd. The mainline foo.vhd still exists and will exists until you check "wip.foo.vhd" back in. When you check the file back in, you are prompted to describe the changes made which is then automatically added to a ChangeLog file. When file archiving is enabled (default), every time a user checks a file in or out, the file is automatically added to a hidden gzip'd tarball file. RTL is highly compressable, so it is practical to archive everything. c) Instant Port Views for VHDL sublocks. One of ChipVaults built-in tools is a VHDL reader for reading entity declarations and deciphering port declarations. ChipVault uses this information to draw a block diagram of all signals going in and out of a block. d) Issue Tracking Database. ChipVault will generate a data base for you for tracking issues that come up during your design phase. Issues can be sorted by ID, Reporter, AssignTo, Title,etc. Everything is stored in a readable text file issues.txt. e) Auto Instantiate VHDL and Verilog Blocks. ChipVault has the ability to read in your existing RTL blocks and generate new template files on the fly which instantiate your existing block. f) Hardware and OS Flexible. ChipVault runs on UNIX,Linux and Windows. The UserInterface scales from a dumb terminal 80x24 Telnet display to 1280x1024 (or 160x128) making it an ideal tool for large designs as well as dialup access. g) Free (Open-Source GPL'd). ChipVault is Open-Source GPL'd, meaning all are free to download ChipVault from http://chipvault.sourceforge.net and execute ChipVault without having to pay any license fees. The author maintains copyrights to the ChipVault source, preventing 3rd parties from modifying the source and then selling a compiled commercialized application. Please read the full enclosed GNU General Public License for full details on license agreement. 3) Which version should I use? For serious work, the UNIX/Linux port of course. The author uses the basic POSIX console version on a day to day basis. A Curses version existed once which is slightly faster than POSIX. It was removed as installing Curses libs for Perl wasnt trivial and the benefits (like mouse support) were minor compared to the overhead of supporting. Win32 users now only have the Console version for ActivePerl. but Caveot Emptor, different versions of Win32 OSs out of Redmond tend to have different Console IO behaviors running the same version of ActivePerl. The author runs on Win2K but the Console has to be setup for BufferSize equal to ScreenSize. By default, the Console window has a buffer larger than the screen which then maps the cursor keys for scrolling the buffer (and ChipVault never hears the key presses). The author generates a shortcut which has the Buffer set to 25 lines. ie: ShortCut Properties which work for win2K The Tab Buttons are represented via [] brackets. [Shortcut] Target : perl.exe cv_win32.pl Start in : Your_Design_Path_Containing_hlist.txt [Layout] ScreenBufferWidth : 80 ScreenBufferHeight : 25 Window Size Width : 80 Window Size Height : 25 Once this shortcut is created, you can double-click to start ChipVault on your desired design with the Console set properly. 4) I hate all GUIs. What good is ChipVault to me? Use ChipVault in batch mode for doing bottom-up stuff like Compiling and Synthesis. ie: %cv.pl hlist.txt -c "cp FILE_NAME FILE_NAME.foobak" will make a foobak copy of every file in your design. Insert a Pound inside your hlist.txt for files to skip. 5) I don't want to use the ChipVault GUI but I need to participate on a group project using ChipVaults simple Revision Control System. How do I check files in and out via the UNIX command line? Thats easy. To see who has what already checked out: "ls -l wip.*.vhd" To check out a file: "cp foo.vhd wip.foo.vhd" To check a file back in: "cp wip.foo.vhd foo.vhd" Note: Auto-archiving will not be performed using this this method. You'll need to manually add the files to existing TAR-balls if you need an archive. 6) How do I assign my own tools for the tool bar? Grep on my_tool assignments and copy examples. Tags like FILE_NAME get replaced by current selected file. 7) What is/is_not supported in the Win32 port? The author tried in ernest to make ChipVault portable over to a Win32 environment. Unfortunately POSIX terminal emulation is spotty for Win32 ports of Perl, so the native Win32 console interface instead. To run on a Win32 system you need to install ActivePerl from www.activestate.com. This is a port of standard Perl5 with some hooks to Win32 routines. By definition, Win32 is lacking in features that come standard in UNIX environments. ChipVault on Win32 does Not Supported: o GZIPping. o File ownership information. (checked out files will be listed as owned by "USER" ) o Email notifications on CheckIns, New Issues. o etc,etc,etc. On a plus side, the Win32 port does have some limited mouse support. Double-Click on "+" and "-" to expand and collapse views. Double-Click on Module Names to activate tool. Single Click to change cursor position. For some reason, when system calls are made and fail (ie compiling or something), the mouse seems to break. So, in-short, ChipVault was written for UNIX/Linux, but it seems to work on Win32 too, so here it is. 8) Why is my Win32 window so small? ChipVault runs as a console app on Win32. Win32 defaults to 24 lines. Change your window properties for more lines after starting ChipVault then press esize. Also see the generated cv.lnk file. 9) How do I assign my own keyboard macros to avoid the tool bar? Grep on macro_hash to see examples of setting up macros. 10) How do I get Mouse support on Linux/UNIX? Mouse support once existed under Curses but was removed as the author never used it and the overhead to support Curses wasn't worth the hassle. ChipVault is much like Vi, Pine, MightNightCommander - fast and efficient via rapid keystrokes. 11) How do I enable Email Notification on file CheckIns? Email notification on file CheckIns is turned off by default. To turn this feature on, you need to set up the email_list array with all the people to Email to. Then set the variable send_email_on_check_in to 1. 12) How do I setup a component library for all designers to have access to? Fill in the lib_list array to point to other hlist.txt files that you want read in. Or manually insert a line like [include] foo.txt in your hlist.txt file. When ChipVault reads in hlist.txt it will spot the [include] tag and automatically read in foo.txt as well. 13) Why is ChipVault slow on screen refreshes on my machine? Believe it or not, this isn't because ChipVault is interpreted by Perl rather than compiled into machine code. On some machines, the User Interface may be slow as ChipVault uses POSIX compliant terminal IO commands (think VT100) for doing things like cursor placement, screen erases, etc. On some OS's this can be really slow. I've noticed that a SunUltra60 is sluggish, but my AMD AthlonXP-2000 Linux box just screams. If you are stuck with a slow OS, you can still speed things up my giving ChipVault less to draw on every keystroke. Ways to speed up the UI are: o) Disable Split-Display Mode with: $enable_split_display = 0; (or press until it goes away) o) Turn off "file=" window with: $disp_file_in_main = 0; $disp_file_xterm_title = 0; o) Shrink your window size (ie 25 or 50 lines instead of 120). o) Switch from Solaris to Linux. 14) How do I import libraries for browsing? Either explicitly type an [include] lib.txt into your hlist file, or set the CV_INCLUDE environment variable to lib.txt. ie: setenv CV_INCLUDE /home/me/foo.txt;/home/you/bar.txt will automatically append the 2 libraries foo and bar to your CV hlist session. 15) What is split_display? When your Xterm screen is sufficiently large in either the X or Y direction, ChipVault will enable split_display and simultaneously display your hierarchy view alongside a port view of the block the cursor is on. 16) What is CV_World? CV_World (or ChipVault World) is a feature of ChipVault for handling global design projects via the Web, either unsecured (open-source cores), or 448bit encrypted. Open-Source Example: A group of grad-students at 12 different universities are working on a PC-in-a-chip design. Each designer keeps his RTL posted on a university web server and sends the URLs (not the files) to the other 11 team members who then copy the URL into their CV hlist. On ChipVault envocation, ChipVault then copies the remote URL files to a local file (mirror). HLIST.TXT Example: foo foo.v http://www.site.com/foo.v Proprietary-Example: Two companies are working on a chip and need to share IP on a daily basis. Designers use ChipVault with Blowfish 448bit encryption to secure their files before placing them on a public web-server. The 448bit keys are then inserted (along with URL) in the hlist of remote site for web access. ChipVault will then autocopy over any updates every time ChipVault is envoked. HLIST.TXT Example: foo foo.v http://www.site.com/foo.v.cv_world=EncryptionKey / / Encrypted version of foo.v --- 8-56 ASCII key - generated by ChipVault for En/DeCryption 17) How can I Help the ChipVault project? o) Use ChipVault and spread the word. The author's marketing budget for last year was $0.00, so word-of-mouth is key. o) Send author Email feedback on problems and feature requests. o) Fix bugs and send author patches to be included in future releases. 18) Can I get phone-support? Try email support first. If we find you really need phone support, the author is available on Saturdays and Sundays. You'll need to set up a 800 dialin conference call thru ATT or something. Email support works quite well with response time generally less than 12 hours. ***************************************************************** iv) Author Info: The Author's name is Kevin Hubbard. He is an ASIC designer living in Issaquah, Washington, USA and may be contacted at khubbard@users.sourceforge.net Please drop the author a brief Email after you've tried ChipVault and let him know if you intend to use it. If nobody uses ChipVault, maintenance will be stopped. Email with contributions, suggestions, requests for new features, etc is also welcome. The author is also compiling a world map of ChipVault users. Please send an Email indicating the country and city of your location. Contributions : Please support the open-source community by 1) Using OpenSource software. Linux/GNU software is more reliable and higher performance than all other OSs I've used. Try it. Even Microsoft has good things to say about Linux these days. http://www.opensource.org/halloween/halloween7.php 2) Contributing OpenSource software. Distributing OpenSource software is incredibly easy. Check out www.sourceforge.net for details. 3) Buying books of open-source developers so that they may see ~some~ financial rewards for their efforts. Recommended Book Reading List: Non-Fiction: Just for Fun: The Story of an Accidental Revolutionary by Linus Torvalds, David Diamond ISBN: 0066620724 http://www.amazon.com/exec/obidos/search-handle-form/103-0109863-7405479 (how the Linux Revolution came to being) The Cathedral and the Bazaar: Musings on Linux and Open Source by an Accidental Revolutionary by Eric S. Raymond, Bob Young ISBN: 0596001088 http://www.amazon.com/exec/obidos/search-handle-form/103-0109863-7405479 (why quality of open-source software is superior to closed proprietary) The Future of Ideas: The Fate of the Commons in a Connected World by Lawrence Lessig ISBN: 0375726446 http://www.amazon.com/exec/obidos/ASIN/0375726446/qid=1030395035/sr=2-2/ref=sr_2_2/103 (how large corporate titans have influenced Copyright and Patent laws to guarantee their survival while stifling outside innovation) Fiction: Everything by Philip K. Dick