T-CREST startup sequence and application exit

[Emoun]

This issue will track the redesign of the T-CREST platform's startup sequence and application exit.

Motivation

Our three environment (hardware, emulator, simulator) each have their own startup sequence:

• Hardware:

1. Starts executing at address 0, where the boorloader resides
2. Bootloader loads the application ELF from UART and saves its sections in the correct addresses
3. _start label is read from the ELF and called
4. The main function will eventually return to the _start function in the standard library, which will execute brnd 0, spinning forever

• Emulator:

1. Reads the ELF of the application
2. Before execution starts, forces the internal pins entering the program counter to the address of _start from the ELF. This is to avoid the bootloader starting to run
3. After execution starts, unforces the pins to free the core (this does not work correctly)

• Simulator:

1. Reads the ELF of the application
2. Start executing at the address of _start from the ELF immediately

We have complexity and maintainability issues because of the different ways execution start in each environment. But, most importantly, the current solution does not work for the emulator because the unforcing of the pins does not happen correctly.

Instead, we want a solution that is flexible and can be supported by all environments

Design

2 new read-only registers are added to the CpuInfo device (see table 3.4 in the handbook):

• EnvironmentID: Value describing the environment we are running in. I.e. hardware, emulator, or simulator (or in the future, other potential implementations of Patmos).
• EntryAddr: Undefined for the hardware and simulator, but specifies the address of “_start” for the emulator

The startup sequence for the bootloader changes to check EnvironmentID first.
If EnvironmentID=1, it know it is running on the emulator and should instead call the address in EntryAddr, skipping the download.
For other values of EnvironmentID, the bootloader continues to download.

When running on the simulator, the bootloader is not present at all, so supporting the new registers would be only to ensure compatibility with the platform.
However, the EnvironmentID also adds the benefit that application code can check what environment it is running in. This could be used for various things, like optimizing for a specific implementation, or logging the environment during benchmarking.

To support application exit detection, the emulator and simulator may treat any writes to EnvironmentID as an explicit application exit. The hardware needs to just ignore such a write.
The standard library _start is then updated to write to EnvironmentID after an application returns from main, then return to the bootloader.
Since the hardware will ignore the write, the bootloader will be returned to.
On the emulator and simulator, the write will trigger exit and the bootloader is ignored.

Open Questions

• Name of EntryAddr: While the purpose of this register is clear for the emulator, it is currently undefined for other environments. To be forward-looking, we could call this something else that doesn't specify as much meaning. E.g., could EnvironmentInfo could be generic enough to allow any environment (future ones we haven't thought of yet) to use this to provide any information it wants.

Implementation

The changes needed to implement this new startup sequence require all the environments to switch to the new implementations simultaneously.
Therefore, all repositories should create a new branch called startup2 where the code will live until the switch is done.

Here is a list of distinct tasks that need to be done (feel free to make new issues for each and then link them here):

• Patmos hardware: Update CpuInfo device with to add EnvironmentID=0 and EntryAddr=0, at the next two addresses (0x38, 0x3c).
• Patmos hardware: New top-level device is implemented using BoringUtils to set EnvironmentID=0 and expose EntryAddr as pins for the emulator to set. (for multicore, all cores get the same EntryAddr, i.e., no exposed pins for each core)
• Patmos handbook: Update section 3.2.1 and table 3.4 with the two registers.
• Patmos emulator: C++ harness is updated to set exposed EntryAddr pins to the application ELF _start address before execution starts. It is never unforced.
• Patmos emulator: Updated to continuously check for writes to EnvironmentID for exit
• Patmos simulator: CpuInfo device is update with EnvironmentID=2 and EntryAddr=0
• Patmos simulator: Updated to continuously check for writes to EnvironmentID for exit. Should no longer treat brnd 0 as halt.
• All repositories are switched at the same time to use startup2 as HEAD.

[torurstrom]

This is currently implemented as a new multi-core device EnvInfo, located at address 0xE8030000. The registers are:

• 0xE8030000: Platform type. Defaults to 0, is set to 1 by the emulator.
• 0xE8030004: Program entrypoint. Set by the emulator. If the bootloader sees that it is running in the emulator it will jump to the given address instead of trying to download a program via the UART.
• 0xE8030008: Exit register. A write to it sets the exit code and indicates to the emulator that it should exit.
• 0xE803000C: Exit code register. Value is read by the emulator and used as its exit code.

As we use Chisels BoringUtil instead of relying on Verilator to expose the internal signals, it is no longer important that we have a multi-core device, so we could switch to using core 0's CpuInfo.

[Emoun]

What is the difference between 0xE8030008 and 0xE803000C?

[torurstrom]

What is the difference between 0xE8030008 and 0xE803000C?

0xE8030008 is 0 normally and 1 if the bootloader wants to exit. 0xE803000C is the actual exit code. Of course, if the exit code is limited to 1 byte we could use the same register for both things.