(chp:makesys)= # Makesystem (sec:makesys:toplevel)= ## Integrate a Core/Memu into the piconut toplevel When creating a new core or memory, it needs to be integrated into the piconut toplevel. The makesystem provides a way to select different cores and memories to be used in the piconut. For this `#ifdef` statements are used in the `piconut.h` file to select the correct core and memory. The name of the define is generated by the makesystem and is the same as the folder name of the core or memory. The format is the folder name in uppercase surrounded by two underscores. For example if the core is in the folder `hw/core/my_core` the define will be `__MY_NUCLEUS__`. In order to integrate a new core or memory into the piconut toplevel the following steps need to be done: 1. Add an `#include` statement to the `piconut.h` file. the `#include` statement should be inside an `#ifdef` statement with the name of the core or memory. ```c #ifdef __MY_NUCLEUS__ #include "my_core.h" #endif ``` 2. Add a Instance variable to the `SC_MODULE` in the `piconut.h` file. For cores use the varaible name `core` and for memories use the variable name `memu`. This also needs to be inside an `#ifdef` statement with the name of the core or memory. ```c #ifdef __MY_NUCLEUS__ my_core *core; #endif ``` (sec:makesys:config)= ## Adding a configuration option to the piconut To add a configuration option to the piconut, it needs to be added to three different files: * `hw/piconut/config.mk` * `hw/common/piconut-config.template.h` * `hw/common/Makefile` (sec:makesys:config:config.mk)= ### `hw/piconut/config.mk` In the `config.mk` file, the Option is added as a makefile variable. The option starts with `CFG_` followed by the name of the option in uppercase and with underscores instead of spaces. After this a `?=` followed by the default value of the option is added. Above the option, a comment must be added to describe the option. ```make # The option ..... CFG_MY_OPTION ?= 0 ``` (sec:makesys:config:config_template)= ### `hw/common/piconut-config.template.h` This file is used to include the configuration options into the hardware source code. The options are included as `#define` statements. The name of the option must be the same as in the [config.mk](sec:makesys:config:config.mk) file. As a value the name of the option enclosed in curly braces is used. This is used to replace fill in the value of the option during the build process. Each option must have a doxygen comment to describe the option above it. ```c /** * @brief Brief description of the option * * The option ..... */ #define CFG_MY_OPTION {CFG_MY_OPTION} ``` (sec:makesys:config:Makefile)= ### `hw/common/Makefile` To use the configuration option in the hardware source code, the `piconut-config.h` needs to be generated with values from the `config.mk` file. To do this the `sed` command at the end of the `Makefile` in the `hw/common` needs to be modified. The `sed` command replaces the curly braces in the `piconut-config.template.h` file with the values from the `config.mk` file. For this you need to add a line to the `sed` command for each configuration option. ```makefile @sed \ -e 's#{CFG_REGFILE_SIZE}#$(CFG_REGFILE_SIZE)#g' \ -e 's#{CFG_MY_OPTION}#$(CFG_MY_OPTION)#g' \ ``` (sec:makesys:jenkins)= ## Creating a jenkins pipeline When developing hardware or software for the piconut, it is important to test on a regular basis. To automate this process a jenkins server is used to run tests. For this, a jenkins pipeline needs to be created. The pipelines are scripts written in groovy and define the steps that need to be executed. (sec:makesys:jenkins:config)= ### Create a new pipeline file The pipeline files are located in a separate repository, in which some configuration steps need to be taken. The following steps need to be done to create a new pipeline file: 1. Clone the repository: ```bash $ git clone https://ti-build.informatik.hs-augsburg.de:8443/piconut_developers/piconut_jenkins-pipeline.git ``` 2. Switch to the `develop` branch: ```bash $ git checkout develop ``` **Note:** New pipelines should be created on the `develop` branch. 3. Create a folder for the new pipeline: The repository is structured for `build` and `test` pipelines. Build pipelines are used to build the hardware and software, while test pipelines are used to run tests e.g. testbenches for hardware or running the software in the simulator. The `build` directory is divided further into the following folders: * `doc`: for building the documentation * `software`: for building software * `sysc_synthesis`: for running systemc synthesis of modules * `v_synthesis`: for running synthesis of whole systems. Generating bitstreams for different FPGA boards The `test` folder currently does not have any subfolders. The folders mentioned above contain the pipeline files. They mirror the structure of the source code repository. For example, if a pipeline for the testbench of the `my_core` module which is located in the `hw/core/my_core` in the source code repository, the pipeline file would be located in the `test/hw/core/my_core` folder in the jenkins pipeline repository. If a pipeline for the ICSC SystemC synthesis of the `my_core` module is needed, the pipeline file would be located in the `sysc_synthesis/hw/core/my_core` folder in the jenkins pipeline repository. 4. Create the pipeline file: The easiest way to create a new pipeline file is to copy an existing pipeline file of the same test type and modify it. Meaning if a pipeline for ICSC SystemC synthesis is needed, copy an existing pipeline from the `sysc_synthesis` folder and modify it. The name of the pipeline file needs to be changed accordingly. 5. Modify the pipeline file: When modifying the pipeline file, two lines need to be changed ```groovy args "-u jenkins --name test_hw_peripheral-bootram -v ${env.WORKSPACE}:/home/jenkins" ``` The `--name` argument needs to be adjusted to reflect the name of the hardware or software component that is being tested. It is required that the name is unique so all pipelines can be run in parallel. ``` groovy steps { sh '/bin/bash -c "cd /home/jenkins && cd hw/peripherals/bootram && make clean && \ make run-tb"' } ``` The path that the `cd` command navigates to needs to be adjusted to the path of the hardware or software component that is being tested. **Important:** If the pipeline is not of the same type (e.g. `testbench` or `sysc-synthesis`), the `make` command in the second line needs to be adjusted to run the correct make target. (sec:makesys:jenkins:jenkins_config)= ### Add the pipeline to the jenkins server 1. Log in to the jenkins server The jenkins server is located at [https://ti-build.informatik.hs-augsburg.de:8444/](https://ti-build.informatik.hs-augsburg.de:8444/) Log into the jenkins server with your RZ credentials. 2. Add the pipeline The jenkins webinterface uses the same structure as the pipeline repository. So it is important to create the same folder structure in the jenkins webinterface as in the pipeline repository. To add a new pipeline, navigate to the folder where the pipeline file is located in the repository. If the folder does not already exist, create it by clicking on the `New Item` button in the side menu. Then enter the folder name and select the `Folder` option. Click `OK`. In the next screen enter the folder name again and click `OK`. When the folder structure is complete, click on the `New Item` button in the side menu. Select `free-style project` and use the `copy from` field at the bottom to assign a relative path to an already existing pipeline file. Then enter the name pipeline. The name must start with the appropriate pipeline type. The type starts with an uppercase letter. This is followed by the name of the hardware or software component that is being tested. E.g `Test_blockram_tb`. At the bottom of the page change the path to the absolute path of the pipeline file in the repository. **Important:** When creating a new pipeline, that tests code that is not on the develop branch, the parameter `BRANCH` at the top of the pipeline configuration needs to be adjusted to the correct branch name. When the merge to the develop branch is done, this value needs to be changed back to `develop`. 3. Test the pipeline To ensure that the added pipeline works, click on the `build with parameters` button in the side menu and click `Build`. This will start the pipeline. To show the output of the pipeline click on the most current buildnumber in the bottom left of the screen. E.g. `#`. Then click on the `Console Output` button in the side menu, to see the output of the pipeline. If the pipeline fails, the output will show `FAILED` otherwise it will show `SUCCESS`.