(chp:makesys)=
# The Build System
**Author: Lukas Bauer 2024**

(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' \

```