Makesystem

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:

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.

#ifdef __MY_NUCLEUS__
#include "my_core.h"
#endif

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.

#ifdef __MY_NUCLEUS__
my_core *core;
#endif

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

`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.

# The option .....
CFG_MY_OPTION ?= 0

`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 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.

/**
 * @brief Brief description of the option
 *
 * The option .....
 */
#define CFG_MY_OPTION {CFG_MY_OPTION}

`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.

	@sed \
	-e 's#{CFG_REGFILE_SIZE}#$(CFG_REGFILE_SIZE)#g' \
    -e 's#{CFG_MY_OPTION}#$(CFG_MY_OPTION)#g' \

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.

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:

Clone the repository:

$ git clone https://ti-build.informatik.hs-augsburg.de:8443/piconut_developers/piconut_jenkins-pipeline.git

Switch to the develop branch:

$ git checkout develop

Note: New pipelines should be created on the develop branch.

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.

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.

Modify the pipeline file:

When modifying the pipeline file, two lines need to be changed

    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.

    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.

Add the pipeline to the jenkins server

Log in to the jenkins server

The jenkins server is located at https://ti-build.informatik.hs-augsburg.de:8444/

Log into the jenkins server with your RZ credentials.

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.

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. #<number>. 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.