= Migration guide 
:toc:
:icons: font
:numbered:
:source-highlighter: rouge

This document serves as a guide to users of the architectural suite to migrate their targets from an
older version to a newer version with minimal changes. This guide thus provides a patch scheme to get
the previous versions of the targets up and running with the new versions of the framework. 

However, users are strongly encouraged to completely migrate to the newer versions, as and when
available, and avoid using these patches.

== Migration from v0.1 to v0.2

This section will describe the changes required to transition your targets ported on v0.1 to v0.2
framework. For examples please see: `riscv-target/riscvOVPsim_0p1` and `riscv-target/spike_0p1`.

=== Change header filename

In version v0.1 the target specific assembly macros were split across two files: `compliance_test.h`
and `compliance_io.h`. In version v0.2 these macros are to merged into a single file named
`model_test.h`. The following commands can the achieve the above:

----
mv compliance_test.h model_test.h
cat compliance_io.h >> model_test.h
rm compliance_io.h
----

=== Change device directory structure

In version v0.1 a target would have one or multiple of the directories defined to indicate supported
extensions: `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and `rv32Zifencei`. In version v0.2 the
directories of the extensions have changed in order to provide more consistency and less ambiguity.

For version v0.2, the `device` directory first needs to have either a `rv32i_m` directory to indicate 
that the target is a 32-bit machine. The extension directories, as supported by the target, are 
now to be created in each of these directories using the following mapping scheme:

. device/rv32i          -> device/rv32i_m/I
. device/rv32im         -> device/rv32i_m/M  
. device/rv32imc        -> device/rv32i_m/C
. device/rv32Zicsr      -> device/rv32i_m/privilege
. device/rv32Zifencei   -> device/rv32i_m/Zifencei

The contents of the extension directories need not change, unless there are dependencies on the path
of the directory itself. The following commands will achieve the above:

----
cd device
mkdir rv32i_m
mv rv32i rv32i_m/I
mv rv32im rv32i_m/M
mv rv32imc rv32i_m/C
mv rv32Zicsr rv32i_m/privilege
mv rv32Zifencei rv32i_m/Zifencei
----

=== Changes in target macro names.

Since some of the macros from the old framework have been re-purposed in the new v0.2 framework,
there will be name conflicts rendering the old ones useless. In order to retain the old macros, they
have been renamed with a post-fix `_OLD`. The macros that have been renamed are given below:

. `RVTEST_CODE_BEGIN` -> `RVTEST_CODE_BEGIN_OLD`
. `RVTEST_CODE_END`   -> `RVTEST_CODE_END_OLD`
. `RVTEST_DATA_BEGIN` -> `RVTEST_DATA_BEGIN_OLD`
. `RVTEST_DATA_END`   -> `RVTEST_DATA_END_OLD`

The user is thus required to make the above changes in the new `model_test.h` that was created
as part of this migration. The following commands will help achieve the above:

----
sed -i 's/RVTEST_CODE_BEGIN/RVTEST_CODE_BEGIN_OLD/g' model_test.h 
sed -i 's/RVTEST_CODE_END/RVTEST_CODE_END_OLD/g' model_test.h 
sed -i 's/RVTEST_DATA_BEGIN/RVTEST_DATA_BEGIN_OLD/g' model_test.h 
sed -i 's/RVTEST_DATA_END/RVTEST_DATA_END_OLD/g' model_test.h 

----

note:: the RVTEST_DATA_END in v0.1 enforced a 16-byte alignment before the signature end. This
constraint has been removed.

=== Changes in device Makefile.include files

No changes required.