Repository Access
Home | People | Pictures | Publications | Downloads | About

Links

RAMP Sites
Getting Started
Infrastructure
Repository

Mar08 ASPLOS
Jan08 Retreat
Mar07 Bootcamp
Jan07 Retreat
Aug06 Workshop
Jan06 Workshop

Open System Repository

Related Research
ATLAS
BEE2 Project
BEE Projects
ParLab
ProtoFlex
RAMP Gold

Sponsors
NSF Grant CNS-0551739
This material is based upon work supported by the National Science Foundation under Grant No. 0551739

BWRC

GSRC
Xilinx
IBM
OpenSPARC

Power.org
Sparc International
Microsoft Research

UC Berkeley
EECS Department
CS61C Course Site
CS150 Course Site
CS152 Course Site


Repository Information
Server: repository.eecs.berkeley.edu
SVN Repository Location: /public
Login Method: SSH with public keys(See the section on accounts below...)
URL: svn+ssh://repositorypub@repository.eecs.berkeley.edu/public/
Web Access: Open System Repository
Do not attempt to check out the entire repository, it is over 4GB at the current time, and only growing. See below for documentation about how to find what you need. Note that there is also a private repository, which contains sensitive information.


Access
There are two ways to access the repository. Public access is available through the Open System Repository. Most code is published this way and licensed under the BSD license. The repository website will show an older version (6 months old) of the repository contents. To see the current contents, you will need SSH access. SSH access will be granted only to researchers and industrial partners affiliated with RAMP, BWRC, GSRC, BEE2, BEE3, ParLab and related projects.

Access to the Subversion Repository is controlled by SSH public keys. To gain access you will need to send an SSH public key, along with the following information to repository-admin <at> lists.berkeley.edu (plain text e-mail preferred).

  • Full Name (Last name, first name):
  • Affiliation(University or Company):
  • Preferred Email Address:
  • Personal Website:
  • Requested Username:
  • Requested Projects Access: See the repository layout at the bottom of this page for a list of projects in the repository.
  • Project Name:
  • Project Website:
  • Grad Student Supervisor (Undergrads only. Last name, first name):
  • Grad Student E-mail:
  • Professor (Grad students & undergrads. Last name, first name):
  • Professor E-mail:
  • Please attach your SSH public key. See below for instructions on generating one, or you may use one you already have.
  • Please list the repository etiquette rules, shown in bold below, as a sign that you have at least glanced over this page.
Once we have this information you will receive access within one business of our confirming your information. In particular, access for people not associated with the RAMP project will likely be delayed. Anyone with access to the repository must be on the mailing list for special announcements. This is not optional, but it is a low traffic list. Changes to the information on this page will be announced on that list.

Finally, there are some files which must be heavily restricted for NDA, licensing or security reasons. It is highly unlikely that anyone needs access to these, but inquires should go to repository-admin <at> lists.berkeley.edu.


SSH Public Keys
This section includes instructions for creating and using SSH public keys. Please let us know if you find errors or missing information. There are a number of SSH key tutorials online. The author found HOWTO: set up ssh keys particularly helpful.
  • Generating an SSH key pair
    1. Find a machine with command line SSH (OpenSSH) installed. Linux, UNIX and Cygwin machines should all fit the bill.
    2. If you need to convert an existing key, see below.
    3. Create your key pair: ssh-keygen -t dsa [-f keyfile]. This command will generate keyfile and keyfile.pub. The default for keyfile is ~/.ssh/id_dsa, which is perfectly acceptable if you don't already have a key pair.
    4. When prompted for a password, give one. Do not create a password-less key pair unless you know what you're doing, and if you're reading these instructions you probably don't yet.
    5. keyfile is your SSH private key. Save it for use on the machine from which you want to log in.
    6. keyfile.pub is your SSH public key. Save a copy for yourself, and send a copy to repository-admin <at> lists.berkeley.edu.
    7. You may wish to run chmod 600 keyfile keyfile.pub to ensure that other users cannot access your keys. Remember that allowing another user to access your public key is not a problem, but your private key should be just that: private.

  • Converting SSH Keys
    1. These instructions are courtesy of //burnz.blog
    2. Find a machine with command line SSH (OpenSSH) installed. Linux, UNIX and Cygwin machines should all fit the bill.
    3. Convert OpenSSH to SSH2: ssh-keygen -e -f [openssh-keyfile.pub] > ssh2-keyfile.pub. This command will generate ssh2-keyfile.pub.
    4. Convert SSH2 to OpenSSH: ssh-keygen -i -f [ssh2-keyfile.pub] > openssh-keyfile.pub. This command will generate openssh-keyfile.pub.
    5. An SSH2 key can be easily identified as if starts with the line -- BEGIN SSH2 PUBLIC KEY --.
    6. An OpenSSH key by contrast starts with either ssh-dsa or ssh-rsa, with the DSA keys being regarded as more secure.

  • Using & Testing Your Key
    1. If you wish to test your key pair, or use it for purposes other than the RAMP SVN Repository, these steps are for you.
    2. You will need two machines, lets call them A and B. These instructions assume you are running on A and wish to SSH in to B.
    3. Copy your keyfile.pub to system B: scp keyfile.pub username@B:~/keyfile.pub
    4. Concatenate your key to your authorized_keys file which lists those keys which are allowed to login through that account: ssh username@B "cat ~/keyfile.pub >> ~/.ssh/authorized_keys". Note that the password you enter should be the one for the login (username) not the one for your key yet.
      Dissecting this command, it is logging you in to B from A and concatenating your public key to the end of the ~/.ssh/authorized_keys file, which SSH reads when you try to log in.
    5. Test your login: ssh [-i keyfile] username@B. Assuming that your keyfile was the default, you may omit the -i option. When you are prompted for a password, use the password from your key. If the login succeeds you are in business.
    6. Feel free to delete keyfile.pub on B: ssh [-i keyfile] username@B "rm keyfile.pub"

  • Testing Your Repository Access
    1. Generate an SSH key (see above) and request repository access (see above).
    2. This example will show how to use your public key with command line subversion. For other clients (SmartSVN), please see their help files.
    3. Attempt to just log in: ssh -i keyfile repositorypub@repository.eecs.berkeley.edu. This should print something like ( success ( 1 2 ( ANONYMOUS EXTERNAL ) ( edit-pipeline svndiff1 absent-entries ) ) ) and you will need to press Control-C to exit. If this succeedes, you have access to the repository.
    4. Check out the repository test directory (works on Linux, UNIX and cygwin): ssh-agent sh -c "ssh-add keyfile && svn co 'svn+ssh://repositorypub@repository
      /public/GettingStarted/trunk/' 'GettingStarted'". You may need to use repository.eecs.berkeley.edu as the hostname, if you are not on the Berkeley network. Make sure there is no space in the middle of your URL (between repository and /public).
      This command will load ssh-agent, create a sh subshell, and then load your SSH key into the agent, and run svn to check out a test directory. The convoluted form of this command is necessary (on some machines) to ensure that the copy of ssh which svn runs has access to your SSH key.


How to Use Subversion (SVN)
The primary and best source of help for subversion usage is the subversion book, though first time users may wish to instead start with Basic Usage. Google will also return numerous useful pages including a brief list of commands.
The main subversion project website will allow you to download the standard client command line tools.

Many of the people on the RAMP project use the SmartSVN client, which is platform agnostic (Java based) and provides an easy-to-use GUI.

We hope to be adding some more detailed tutorials soon, please let us know if there's anything in particular that isn't clear to you so that we can document it.


Repository Etiquette
Make use of the repository!
  • The first rule of the repository: commit everything not automatically generated.
  • The second rule of the repository: commit everything not automatically generated. This means that all source code, documentation, web page, papers and even installers and the documentation you are relying on are fair game. However, you should avoid comitting the PDF of a paper written in Tex, a Java .class file for which you have the .java file, or the non-code files from a ModelSim or Xilinx ISE project.
  • Learn it, live it, love it: if it's not in the repository, it doesn't exist!
  • E-mail repository-admin <at> lists.berkeley.edu if you have trouble rather than avoiding using the repository. We're nice people
  • If you're worried about someone seeing what you think isn't your best work, consider using your /trunk/Private/username directory.
  • If you've got a class project related to RAMP, we're happy to give you space in /trunk/Shared with proper access control so that other current students in the class can't see your work, but we can move it to a more prominent location when it turns out to be useful.


Use good commit messages.
Commit messages are how other people know what you're up to. Make it easy for them.
  • Bad Examples:
    • "Initial Import"
    • "Changed some stuff"
    • "Fixed"
  • Good Examples:
    • "BEEKeeper - Initial Import"
    • "RDLC1 & 2 - Updated copyright dates to include 2008"
    • "RAMP Website - Posted RAMP Blue v4.0 photos"
  • Awesome Example (1 message!):
    BSD License Correction - Switch to 2 clause Below is a list of regular expressions used to accomplish this Regex1 Search Regex1 Replacement Regex2 Search Regex2 Replacement
  • Notice that the "awesome example" is an 8 line commit message which includes not just an explanation of the changes, but the regular expressions used to make them happen! So then when some poor student has to figure out how someone changed 200 files in one commit it is real clear.


Use svn:externals rather than duplicating things!
Of course it's better to just reference the relevant code or document, e.g. in a makefile, but for those rare occasions where the thing you're interested in is somewhere completely different in the repository (or in another repository altogether) use svn:externals so that the person who comes after you can find all the relevant files.

Basically you set a "property" (something SVN supports) on a directory which means "when you check out this directory, go check out this other crap and put it at the given path". The SVN Book explains externals in great detail.

If you're using SmartSVN, just right click on the directory, go to "external" and you'll get a helpful little dialog box. Watch out for spaces in path names (if it's in the local path it will cause trouble, if it's in the URL, change it to %20 to avoid trouble). Use svn copy and svn move!
These commands will allow SVN to track the fact that you moved or copied a file, instead of thinking you just created a new file. Feel free to also use a client like SmartSVN, which will try to help you out when you forget this, but guessing (and asking you) if files were copied.

Directory Structure
It is highly recommended that you do not check out the entire repository, as it is over 10GB for a single working copy. Instead, find the directories you need and check them out one by one. Each user and project in the repository has it's own source control tree include the standard SVN layout (branches, tags and trunk) according to the Recommended Repository Layout and Branching and Merging, thereby allowing individual projects to have separate branches and tags, and simply access control.
  • /GettingStarted/trunk/:
    Contains a readme file for those people testing their SVN access, as well as some notes about undergrad RAMP project ideas and how to get access to BWRC where RAMP research at U.C. Berkeley is centered. Should be readable to everyone and writeable to no one.
  • /Private/username/trunk/:
    Each user will have read and write access to their own source control tree under /Private. No other users (aside from repository admin and backup users) will have any access to this tree.

    If you have code or documentation which is related to RAMP, BEE2 or another hosted project, the best option is to put it within the /Project directory, but if this makes you nervous, your private directory is a better choice than not putting it in SVN at all. Not only does this mean we have a vague record, should your computer die tomorrow, but once you are ready to make it available to others, we can simply use SVN to copy it to the correct location, and all the history can be effortlessly preserved.

    One possible trick for those interested in avoiding a complete working copy checkout: use svn:external properties on your private directory to mount the various projects, papers and other useful directories which you actually need. Remember, an external doesn't have to come from a different repository!

  • /Projects/:
    Contains one source control tree per project, please be careful to create only one tree per major project.
    • AppServer/trunk/:
      Contains the application server, a program designed to launch an application on a computer architecture simulator and provide runtime support.
    • BDB/trunk/:
      A debugging project by Kevin Camera.
    • /Projects/BEE/trunk/:
      • 2:
        Contains the new BEE2 repository. This include several example applications, hardware cores as well as pristine linux (software/linuxppc-2.4) and BORPH (software/borph) for the control FPGA, and of course the PCBs. This directory is over 1GB!
      • 3:
        Contains the BEE3 repository. This includes both hardware cores and software. It also includes the externals/BEE3 directory which contains all the documentation received from BEEcube, Chen Chang and Microsoft about the BEE3, including the main UCF file.
      • BEEKeeper:
        Contains the source code (hardware and software) for the BeeKeeper, a JTAG over Ethernet board meant to help in the programming and debugging of large multi-BEE systems.
      • IBOB:
        Contains the PCBs for the IBOB, ADC, DAC and various other BEE2 aadd-on boards.
      • Website:
        Contains the BEE2 and BEE websites in source form.
    • BORPH/trunk/:
      The BORPH FPGA operating system by Hayden So.
      • borph:
        The BORPH source code, including the "patches" needed to modify the linux kernel.
      • BEE2:
        Contains externals for pristine BEE2 linux (linuxppc-2.4) and the complete BORPH linux kernel (borph) which is created by patching the linuxppc-2.4 kernel.
    • Classes/trunk/:
      Course material and code for EECS150 and CS194-6 Fall2008 at U.C. Berkeley. There is also some common course development materials related to these, and a few other classes. Other course material should be added over time.
    • Externals/trunk/:
      Collected code and documentation from external projects. For example if two projects in this repository both need the same library, it belongs here. For more information about the layout of this project, please see the GateLib documentation.
    • GateLib/trunk/ & GateLib/branches/dev/:
      A standard Gateware, Firmware and Tools library, used by EECS150, RAMP and a number of other projects at U.C. Berkeley. Contains the I/O library and FPGA_TOP files library for the CaLinx boards, along with a number of the Digilent FPGA boards. Most importantly GateLib contains standard Verilog modules which should be widely used. GateLib also contains the XTools (ANTEDA, ANTTools, SVNTools, PubTools) and XLink (UART, VPI, Ethernet) suites. Write access to the dev branch is relatively freely given, and fixes and suggestions are highly encouraged. Over time stable cores are published to trunk for wider circulation.
    • HomeGateway/trunk/:
      Source code and papers from the Protean Living project, formerly called "Home Gateway."
    • IIAB/trunk/:
      Code from the Internet-in-a-Box project, including a SPARC processor implementation, an FPU and a network emulator.
    • Misc/trunk/ & Misc/branches/dev:
      Contains a number of miscellaneous projects, mostly those which are not directly related to research, or which are not yet integrated in to a larger project. Development happens in the dev branch, and code is occasionally "released" to the trunk. Many sub-projects start here until they are ready for wider use. Some projects such as XTools (Including ANTEDA, BibTools, Publications Common, etc.) and XLink (Including JavaVPI) have already graduate from this project to a more permanent home in GateLib.
    • RAMP/trunk/:
      The code and papers for the RAMP Project.
      • Climate:
        Contains the source code for the Climate machine. Note that there are externals in this directory which reference the private repository, and which reference other parts of the repository. In particular this project uses Tensilica processors, which are covered by various contracts and thus private, as well as GateLib.
      • Cluster:
        Contains code and notes for the BEE3, Website and VM cluster being assembled at UC Berkeley.
      • Gold:
        Contains the source code for RAMP Gold. Note that there are externals in this directory which reference the private repository.
      • Publications:
        All the publications, papers, degrees, presentations and documents associated with the RAMP project.
        • Events:
          One directory per event with the RAMP related posters, presentations, notes and such from that event. Please create subdirectories as appropriate if there are multiple posters or presentations per event.

          Please use SVN tags to tag the version of any talks which are given on various days, at various events. Directories should contain all of the source files for the any presentation or poster be it a single powerpoint deck, or a myriad of included images.
        • Memos:
          Contains incomplete publications, working notes (in the Notes directory) and general documentation detritus. Highly useful, particularly to those new to the project.
        • Papers:
          One directory per paper, named with the paper title. Please make sure to include all source files (illustrations) as well as the text of the paper. Be sure not to include auxiliary files or e.g. the output of latex (not even a PS or PDF since they can be easily generated). This directory should include technical reports, publications and even dissertations.
      • RDLC:
        Contains the source code for RDLC1 and RDLC2. This includes the complete code history for both versions.
      • White:
        Contains some example Bluespec source code from the RAMP white project.
      • Website:
        Contains the RAMP website in source form.
    • Repository/trunk/:
      Support code, scripts and the Repository website in source form.

  • /Shared/special/trunk/:
    Though this is primarily a research repository, many students will check class projects, particular those related to their research in to their /Private/username/trunk/ directory. This directory is similarly intended for not-yet ready to be widely seen code, for example class projects or other such loosely related work, which should be shared rather than private.

    Course project directories should be of the form: Class - usernamess or Class - teamname or even Class SemesterYear, which might contain all the course projects for that semester. These directories will only be readable to the people in the relevant group, to handle the situation where multiple students are in the same class but are not working together.