= Example target setup

This directory provides an example target you can use as a template to build your own target for the
latest version of the framework.

Any target that needs to be ported will need to provide the following three items:

- a linker script defining the entry point and the location of various sections of the test
- a `model_test.h` header file provding target specific assembly macro definitions. Please refer to
  the link:../../spec/TestFormatSpec.adoc[`TestFormatSpec`]
- a `device` directory defining the extensions supported by the target and a routines on how tests
  should be compiled and executed on the target.

== The linker script

For linking you have two options.  

. If your environment is a monolithic runtime (i.e. both code and data reside in the same contiguous memory area) then you will want to use `linkmon.ld` as the template for your linker script.  
. If your environment has separate code and data sections then you will want to use `linksplit.ld` as a template for your linker script. You can find detailed analysis of this script link:./linker_script.adoc[`Here`]

Whichever linker script you choose to use, you will have to modify the example to fit your enviroement address space.

== The model_test.h header file

The architectural tests enable target-specific code and environment to interact with the each test
via model specific macros. These macros need to be defined by the target in a file named
`model_test.h`

The `model_test.h` file provided in this directory is *not* meant to be consumed as is and will
require modifications from the target owner. The file provides common placeholders for each macro,
which have been known to common across targets. 

Each point of modification is prefixed with a `TODO` and a comment. The target ownwer is encouraged
to refer to the link:../../spec/TestFormatSpec[`TestFormatSpec`] for more details of each macro.

For example if you are using the `linksplit.ld` file for a template for your linker script then in the 
`model_test.h` file you will have use a similar code as below, to copy the data sections from the 
boot device to ram.  

----
// For code that has a split rom/ram area
// Code below will copy from the rom area to ram the 
// data.strings and .data sections to ram.
// Use linksplit.ld 

#define RVTEST_TARGET_INIT \
la t0, _data_strings; \
  la t1, _fstext; \
  la t2, _estext; \
1: \
  lw t3, 0(t0); \
  sw t3, 0(t1); \
  addi t0, t0, 4; \
  addi t1, t1, 4; \
  bltu t1, t2, 1b; \
  la t0, _data_lma; \
  la t1, _data; \
  la t2, _edata; \
1: \
  lw t3, 0(t0); \
  sw t3, 0(t1); \
  addi t0, t0, 4; \
  addi t1, t1, 4; \
  bltu t1, t2, 1b;

//RVTEST_TARGET_INIT
// Any specific target init code should be put here
// Code for one monolithic ram area
// Use linkmono.ld 
#define RVTEST_TARGET_INIT \

----

With regards, to the signature it is required that the signature regions (defined by
RVMODEL_DATA_BEGIN/END in `model_test.h`) start and end at a 16-byte boundary. This achieved by the
explicit `.align 4` syntax added in those macros.

== The 'device' directory

Each subdirectory under device (rv32i_m and rv64i_m) have Makefile.include files that are then symlinked
to the subdir under each of these device directories (I, C, M, privilige, Zifencei). The existence
of these extension directories under `device` indicate that the target supports this extension. Only
create those extension directories for which tests need to be run on your target.

If you have specific makefile changes for these subtargets then you will need to replace the symliked Makefile.include.

