Emulator

Let’s play with SDK emulator. For more details about the SDK Emulator, refer to documentation.

Running SDK emulator enables developers to prototype, test, and debug SDK functionalities without physical hardware, significantly enhancing productivity.

Installation

There are two ways to install Emulator:

1. Install from Emulator Package

Emulator package URL will be provided separately.

   wget <URL_to_emulator_xxx.tar.xz>
   tar xvf emulator_xxx.tar.xz
   cd emulator_xxx

2. Use Docker

- Step 1. Prepare Docker Container  
    Obtain prebuilt container from [Docker Hub](https://hub.docker.com/). Ensure you have a correct repository & tag name.  
    Example:  

    ```bash
    # Usage: docker pull <repository name>:<tag name>
    docker pull xcenadev/sdk:latest
    ```

    Alternatively, you can build the image manually using the Dockerfile provided in the SDK repository (`dockerfiles/README`).  

- Step 2. Run Docker Container  
    Run Docker with KVM support, SYS_ADMIN capability, and user option (`--device /dev/kvm`, `--cap-add=SYS_ADMIN`, `-e USER=$USER`).  

    Example:  

    ```bash
    docker run -it --name xcena_sdk --device=/dev/kvm --cap-add=SYS_ADMIN -e USER=$USER xcenadev/sdk:1.4.0
    ```

- Step 3. Verify the Container is Running
    To confirm that the container has started successfully, use the `docker ps` command:  

    ```bash
    docker ps
        # Expected output:
        # CONTAINER ID   IMAGE               COMMAND     CREATED          STATUS          PORTS     NAMES
        # abcdef123456   xcenadev/sdk:latest  "/bin/bash" 2 minutes ago    Up 2 minutes              xcena_sdk
    ```

- Step 4. Connect to the Running Container
    To connect to the running container and access its shell environment, use the following command:

    ```bash
    # USAGE : docker exec -it <container_name> /bin/bash
    docker exec -it xcena_sdk /bin/bash
    ```

- Step 5. Navigate to the emulator repository  
    After entering the container, navigate to the emulator directory provided within the SDK environment.  
    ```bash
    cd emulator
    ```

Run Emulator

Launch QEMU
```
 # In emulator repository,
 ./run.sh
```
To emulate multiple CXL devices, use the -n option.
```
 ./run.sh -n 4
```
For more details on QEMU execution options, please refer to the Documentation/Emulator section.

Verify CXL Interface
Once QEMU launches, verify basic CXL interface functionality.

CXL device detection

  root@localhost:~# lspci
  ... ...
  0d:00.0 CXL: Device 20a6:ce00 (rev 01)  

Check CXL region and DAX mode

  root@localhost:~# cxl list
  [
  {
      "memdevs":[
      {
          "memdev":"mem0",
          "ram_size":12616466432,
          "serial":0,
          "host":"0000:0d:00.0",
          "firmware_version":"xcena-1.0.0"
      }
      ]
  },
  {
      "regions":[
      {
          "region":"region0",
          "resource":53955526656,
          "size":12616466432,
          "type":"ram",
          "interleave_ways":1,
          "interleave_granularity":256,
          "decode_state":"commit",
          "qos_class_mismatch":true
      }
      ]
  }
  ]
  root@localhost:~# daxctl list
  [
  {
      "chardev":"dax0.0",
      "size":12616466432,
      "target_node":0,
      "align":2097152,
      "mode":"devdax"
  }
  ]

Test .mem write & read

  cd ~/app/rwmem
  ./build.sh
  ./dax 0x2000 0x100 0x1234
  ./dax 0x2000 0x100

Run SDK Examples
Execute example applications included in ~/sdk/example.
```
 cd ~/sdk/example/sort
 ./build.sh
 ./sort_with_ndarray
```
Develop a new application
To develop a new application efficiently in the QEMU environment, use virtfs to share files between the host and the QEMU instance.
~/app folder inside QEMU is mapped to the app folder in the emulator repository. Example:
```
 # Copy a new file to the shared folder in emulator repository  
 cp myApp.cpp app/
```
Then, In QEMU:
```
 # Verify the file in QEMU
 ls ~/app/myApp.cpp
```
Exit Emulator
1. Exit QEMU
  Press Ctrl + a, then x to safely exit QEMU.
2. (Optional) Detach from Docker Container
  To detach without stopping it:
```
 # In Docker
 Ctrl + p, Ctrl + q
```
  To reattach to the container, use the following command:
```
 docker attach xcena_sdk
```
3. Stop and Remove Docker Container
  
  If you want to stop or remove the container, run following commands:
```
 # Stop the running container
 docker stop xcena_sdk

 # Remove the container
 docker rm xcena_sdk
```