Emulator Development Using the FW-Dev Container

To help facilitate development of the fw emulators a development container has been created that contains all the tools necessary in order to successfully build a new emulator block.

The dev container comes with the following:

  • GCC / G++ 12

  • Python 3.12

  • Poetry

  • A pre-cloned ska-mid-cbf-emulators repository at the root level, which will be discovered automatically by the run-emulator and invoke commands. (You should generally not need to modify this.)

  • A FW workspace folder you specify, mounted in the container at /workspace.

  • A tasks.py file at the root level, which provides a simplified set of commands for interacting with the emulator/injector APIs via the invoke utility. See the list of emulator commands for more details.

Prerequisites

  • VS Code
    • Extensions:

      • Dev Containers

Setup and Configuration

SSH into Remote Dev Server

First using VS Code we need to connect to the server that will run the FW development container.

Note

This will only need to be done once or when using a new remote server.

  1. Open VS Code

  2. Check that the Dev Containers extension is installed by clicking the Extensions icon from the side menu bar.

    ../_images/vscode_extensions_1.png

    Note

    If it’s not installed, search for it using the Extensions search and click install.

    ../_images/vscode_dev_containers_ext.png

  3. Open the Remote Explorer from the side menu.

    ../_images/remote_explorer.png

  4. Select Remotes (Tunnels/SSH) from the top right dropdown.

    ../_images/remote_explorer_ssh_menu.png

  5. Add a new SSH Connection using the + icon next to SSH.

    ../_images/add_ssh_connection_1.png

  6. Enter username and remote address for SSH connection, e.g.: <username>@rmdskadevdu002.mda.ca

    ../_images/add_ssh_connection_2.png

  7. Next, select the SSH config file in your users directory to update.

    ../_images/add_ssh_connection_3.png

  8. Connect to the server by clicking the Connect in Current Window or Connect in New Window option.

    ../_images/add_ssh_connection_4.png

  9. Once inside, open the explorer from the side menu and Open Folder on the server.

    ../_images/remote_server_1.png

Starting the FW Dev Container

Initially after you have SSH’d into the remote server, you have to clone the project and start up the FW Dev Container.

Note

If you have already cloned and started the FW dev container, skip to the next section: Attaching to the FW Dev Container.

  1. Run the following to clone the ska-mid-cbf-emulators project:

    git clone https://gitlab.com/ska-telescope/ska-mid-cbf/infra/ska-mid-cbf-emulators

  2. Navigate inside the ska-mid-cbf-emulators project and run the following to initiate the makefile:

    git submodule init
git submodule update

  3. Run the following to start the FW dev container:

    make run-fw-dev

    which will prompt you for your workspace location and the name of the persona that was used to generate the workspace (this should match the name of the persona folder inside the workspace folder). Alternatively, you can specify them all in one command:

    make run-fw-dev WORKSPACE=<path to your workspace> PERSONA=<name of the persona used to generate the workspace>

    Note

    The default workspace location is ~/workspace, and the default persona name is ska_vcc_persona.

  4. If successful, the following should be displayed in the terminal:

    ../_images/fw_dev_container_running.png

Attaching to the FW Dev Container

  1. Press Ctrl-Shift-P or F1 from within VS Code to open the command search prompt.

  2. Search for the following and run it from the opened prompt:

    Dev Containers: Attach to running container...
    ../_images/attach_to_dev_container_1.png

  3. Attach to the container named /emulator-dev-<your user name>

    ../_images/attach_to_dev_container_2.png

Note

The following steps from 4 - 6 only need to be performed once, on the initial run of the FW dev container.

  1. If this is the first time attaching to the container, one extra step must be completed. Press Ctrl-Shift-P or F1 to open the command search prompt.

  2. Search for and run the following command:

    Dev Containers: Open Container Configuration File
    ../_images/attach_to_dev_container_3.png

  3. In the configuration file, add the following extra item to the list and save. This will make it so any files you create / save will match your user on the host machine, as the fwdev user is set up to match your user’s UID and GID:

    "remoteUser": "fwdev"
    ../_images/attach_to_dev_container_4.png

  4. To finish enabling the fwdev user, close the VS Code window that’s attached to the container, and then re-attach it following from step 1.

Running an Interactive Shell

To run an interactive shell inside the dev container, from the dev server running the container, run:

docker exec -it emulator-dev-<your username> bash

OR if within the emulators repository, you can run:

make enter-fw-dev

Running the Emulator

Firstly, you need to make sure you have a valid emulator configuration file available. This should be located at $WORKSPACE/$PERSONA/emulator/config.json (e.g. path_to/my_workspace/ska_vcc_persona/emulator/config.json); if you haven’t specified a valid persona, however, or if the specified persona does not contain emulator/config.json, then the emulator will attempt to fall back to $WORKSPACE/config.json if it exists (you must create this yourself in this instance). For details about the emulator configuration file, see Bitstream Emulator Configuration.

Once any changes to the IP block emulators have been made and you would like to test them, from within the FW dev container you can start the bitstream emulator by running the following:

run-emulator [options]

This will spin up the emulator engine and automatically pull in your changes from the /workspace directory. See Run the emulator in the dev environment or use –help for the list of allowed options.

Note

For changes to be applied, you must terminate and restart the bitstream emulator.

Once the bitstream emulator is running, please see the following list of emulator commands for some commands you can send to the emulator and/or injector APIs from within the FW dev container.

Teardown

Note

This is to be performed from the server you are SSH’d into, not the FW dev container.

  1. If open, close the attached dev container VS Code window, then from the server you’re SSH’d into, navigate into the ska-mid-cbf-emulators project.

  2. Run the following to shut down the FW dev container:

    make remove-fw-dev

  3. On successful shutdown, the output to the terminal should be as follows:

    ../_images/container_shutdown.png