Skip to content

O
OHR Support

Project structure guidelines

Last edited by OHWR Gitlab support
Page history

Project Structure Guidelines

Top project & sub-projects

This structure is suitable for complete hardware module design projects, with PCB, HDL, software and tests.

**** * Name * * Repository * * Wiki * * Issues * * Documents * * Files * * Mailing-list * * News * * Roadmap * * License *
Top/main project NO YES YES[1] YES YES YES YES Optional N/A
Gateware sub-project (HDL) -gw Gateware[2] YES YES YES Optional Optional Optional Optional Optional LGPL
Hardware sub-project (PCB, mechanical parts) -hw Hardware[3] YES YES YES Optional Optional Optional Optional Optional CERN OHL
Software sub-project (driver, library, test program) -sw Software[4] YES YES YES Optional Optional Optional Optional Optional GPL
Testing sub-project (production/functional tests[5]) -tst Testing[6] YES YES YES Optional Optional Optional Optional Optional GPL

Tips to re-structure a project following those guidelines.

Remarks

  • Keep issues separate (e.g. PCB revision, HDL versions), top project gathers issues from all sub-projects.
  • No need for several git repositories per project.
  • To minimise the drawback of having several wikis to edit, the sub-project wiki is optional for small projects.
  • In big projects, the hardware sub-project can be split in two: PCB and mechanical.
  • If needed an additional sub-project for firmware can be considered (e.g. code for embedded CPU).
  • The roadmap and issue features can be used to create release changelog.

Pending questions:

  • Usage of files vs documents?
  • The default project page should be the wiki. "Overview" should be renamed in "About" (or something similar).
  • There is a link from parent project to sub-project but not the other way round!

TODO

  • Make a template project.
  • It would be nice to have the top project display the news from all subprojects

Single project

A single project structure is preferable in case of non-mixed project (e.g. HDL library, stand-alone PCB, test framework).

  • Project -> repository, issue, wiki, files

Git repositories

Git sub-modules will be used in order to organise and solve dependencies.
This way we will:

  • avoid dependency on hdlmake in HDL projects.
  • have more flexibility.
  • avoid copy of source files.
  • avoid huge & messy repositories (c.f. PTS).

Proposed git sub-modules structure:

  • Hardware (PCB, mechanical parts, no sub-modules)
  • Software (e.g. dedicated board driver, library and test program)
    • Software dependencies (e.g. carrier, fmc-bus, zio)
  • HDL sources (operational, testing)
    • HDL dependencies (e.g. hdl cores)
  • Test (specific production/functional tests)
    • Testing framework (e.g. PTS), common libraries

Folder structure example

Git repository usage policy

  • No binary or huge simulation files.
    -> Binary files (.bin, .pdf, ...) only in the "Files" section.
  • ONE person (maintainer) commits to master.
  • No rebase of master.
  • Other developers commit to proposed_master.
  • See Repository-use

Testing (production and functional)

  • Common part in it's own project -> PTS (single project scheme).
  • Specific test in a sub-project of the board.
  • Test system
    -> Automate installation as much as possible -> install scripts.
    -> Documentation.
  • Store testing log files in MTF (CERN specific).
    -> Note: A log file must correspond to a serial number (barcode).

TODO

  • Wiki page "How to batch upload files in MTF" (CERN specific).
  • Write a unique, platform independent API for testing the hardware modules.
    -> single r/w, block r/w, wait irq, sdb, fmc eeprom, flasher
    -> C lib + python wrapper
    -> part of the fmc-bus?
    -> raw backend with direct memory mapped access => for non-fmc boards
  • Get rid of rawrabbit/gnurabbit.
    -> Requires a replacement first (cf. block read/write support in spec-sw).
  • Clean-up jpts.

About releases (To be discussed)

  • min/maj (v3.2) or date-based (v02.2014) -> sdb is not foreseen for date-based versioning.
  • wiki release pages
    • templates
    • md5sum of binaries
    • changelog only in one place
    • automate page creation (Would be nice to have), python-redmine to be investigated...
  • git tags
  • package releases (pcb+hdl+sw ?+test?)
  • zip/tar of sources+binaries?
  • update doc

non-ohwr projects (CERN specific)

  • Use official cern git repos.
  • Page on wikis.cern.ch as the central info point.
  • One JIRA space per board to gather issues.
    -> Issues summary in the wiki.
  • Official/operational gateware release location is on nfs:
    -> /acc/loacl/share/firmware/
  • Binary files location: nfs (operational), wiki (public)

TODO

  • Write a "how to migrate a svn repo to git" wiki page.
  • Update wiki page template.
    -> Issues summary

Matthieu Cattin, Erik van der Bij - August 2014

  1. Automatically gathers issues from sub-projects.

  2. Gateware (HDL design) for xx.

  3. Hardware design of xx.
    Includes schematics, PCB layout and manufacturing files.

  4. Software to support the xx, including Linux device driver, library and test program.

  5. Board specific part of PTS.

  6. Production and functional tests for xx.