# Hog: HDL on git ## Introduction Coordinating firmware development among many international collaborators is becoming a very widespread problem. Guaranteeing firmware synthesis with Place and Route **reproducibility** and assuring **traceability** of binary files is paramount. Hog tackles these issues by exploiting advanced git features and integrating itself with HDL IDEs: **Xilinx Vivado**, **Xilinx ISE (planAhead)** or **Intel Quartus**. The integration with these tools intends to reduce as much as possible useless overhead work for the developers. :::{admonition} Quartus support :class: warning Not all Hog features are supported for Quartus. If a feature described in the documentation is supported only by Xilinx IDEs, it is clearly stated. If some of the functions you are looking for are not cited in the documentation they might be [scheduled for development in a future release](https://gitlab.cern.ch/hog/Hog/-/issues) ::: :::{admonition} ISE support :class: warning Hog provides a minimal support for earlier generations of Xilinx chips using the planAhead tool. The planAhead GUI is very similar to Vivado and should be very familiar to Vivado users. Under the hood it still uses the same tools as ISE but provides a tcl-scriptable front-end that allows for easy integration with Hog. It has been tested only in version 14.7 and has some limitations, but does allow you to create, compile and keep track of the versioning of a project both locally and in the gitlab CI/CD. ::: ### What is Hog Hog is a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a Gitlab repository. Hog is included as a submodule in the HDL repository (a `Hog` directory is always present in Hog-handled repository) and allows developers to create the Vivado/PlanAhead/Quartus project(s) locally and synthesise and implement it or start working on it. The main features of Hog are: - a simple and effective way to maintain HDL code on git, - automatic tag creation for versioning - automatic Gitlab release creation (including timing reports, changelog, and binary files) - yml files to run continuous integration in your Gitlab repository - multi-platform compatibility, working both with Windows and Linux Other optional features are: - the possibility of creating multiple projects sharing the same top level file - the possibility to store the output binary files on EOS - compatibility and support for IPBus - automatic creation of Sigasi project Everything is as transparent as we could think of. Hog is designed to use just a small fraction of your time to set up your local machine and get you to work to the HDL design as soon as possible. ### Rationale For synthesis and Place and Route (P&R) **reproducibility**, we need absolute control of: - HDL source files - Constraint files - IDE settings (such as synthesis and implementation strategies) For **traceability**, every time we produce a binary firmware file, we must: - Know exactly how the binary files were produced - Be able to go back to that point in the repository To do this, Hog **automatically** embeds the git **commit SHA** into the binary file together with a more understandable **numeric version** __M.m.p__. Moreover, it automatically renames the file, including the version and inserts the hexadecimal value of the SHA so that it can be retrieved (using a text editor) in case the file gets renamed. Avoiding errors is impossible, but the goal of Hog is to leave as little room as possible. Another important principle in Hog is to **reduce to the minimum** the time needed for an external developer to **get up to speed** to work on an HDL project. For this reason, Hog **does not rely on any external tool** or library. Only on those, you must have to synthesise, implement (Vivado/PlanAhead/Quartus) and simulate (Modelsim/Questasim) the design. To start working on any project contained in a Gitlab repository handled with Hog, you just need to: ```console git clone --recursive cd ./Hog/CreateProject.sh ``` The project will appear in `./Projects/` and you can open it with your Vivado (ISE/Quartus) GUI. :::{tip} If you don't know the project name, just run `./Hog/CreateProject.sh` and a list will be displayed. ::: ### What is in the Hog folder The Hog folder contains plenty of Tcl and Shell scripts. E.g. you can run: ```console ./Hog/Init.sh ``` to initialise the repository locally, following the instructions. You can always have a look by yourself. Most of the scripts have a *-h* option to give you detailed instructions. One of the most important script is ```console ./Hog/CreateProject.sh my_project ``` that serves to create the Vivado/PlanAhead/Quartus project locally into the `Projects` directory. When creating the project, Hog integrates a set of Tcl scripts (contained in `Hog/Tcl/integrated`) into the IDE software. If you don't know the project name, just launch `./Hog/CreateProject.sh` to find out the names of the projects in the repository. Another useful scripts is ```console ./Hog/LaunchWorkflow.sh my_project ``` which runs the complete workflow of the desired HDL project, creating the binary files in the `bin` directory. At last ```console ./Hog/LaunchSimulation.sh my_project ``` runs the simulation workflow. Other scripts are stored inside the `Hog/Tcl` and `Hog/Other` folders. ### Other folders A folder called `Top` shall be in the root of the repository and it contains a sub-folder for each Vivado/PlanAhead/Quartus project in the repository. Each of these directories has a fixed easy-to-understand structure and contains everything that is needed to re-create the Vivado/PlanAhead/Quartus project locally, apart from the source files[^source] that the developer can place in the repository at their convenience. :::{tip} Source files are the HDL files (.vhd, .v) but also the constraint files (.xdc, .sdc, .qsf, .tcl, ...) and the IP files (.xci, .ip, .qip, ...) ::: ### Hog user manual In this website, you can find a quick guide to learn how to work in a [Hog-handled repository](../../01-Getting-Started/01-howto-existingProjects) or to [set up a new one](../../01-Getting-Started/03-howto-update-hog), as well as a complete user manual to understand all the details and learn how to maintain a Hog-handled repository. ### Quartus support Currently Hog provides a minimal Quartus support allowing you to create, compile and keep track of the versioning of a project both locally and in the gitlab CI/CD. Note that not all hog/quartus features are supported. We tried to clearly state if a feature refers only to Xilinx FPGA. If some of the functions you are looking for are not cited in the documentation they might be [scheduled for development in a future release](https://gitlab.cern.ch/hog/Hog/-/issues) ### Contacts Would you like to have fun with git and a Tcl? Please join us and read the [Developing for Hog](../../04-Developing-for-Hog/01-contributing) section. To report a [problem](../../03-Report-Suggest/01-Report) or suggest a [feature](../../03-Report-Suggest/02-Suggest), use the git issues in the [Hog git repository](https://gitlab.cern.ch/hog/Hog). Please check in existing and solved issues before opening a new one. For questions related to Hog, please get in touch with [Hog support](mailto:hog-group@cern.ch). For anything related to this site, please get in touch with [Nicolò Biesuz](mailto:nbiesuz@cern.ch) or [Davide Cieri](mailto:davide.cieri@cern.ch) ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Getting Started 01-Getting-Started/* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: User Manual 02-User-Manual/* 02-User-Manual/01-Hog-local/00* 02-User-Manual/02-Hog-CI/01* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Bug Report and Suggestions 03*/* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Developing for Hog 04*/* Hog Doxygen Develop Hog Doxygen Master ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Releases 06*/* Hog Releases ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: License and Authors 05-License/* ```