# Hello World CL Example



## Table of Contents

1. [Overview](#overview)
2. [Functional Description](#description)


<a name="overview"></a>
## Overview

This *hello_world* example builds a Custom Logic (CL) that will enable the instance to "peek" and "poke" registers in the Custom Logic (CL).
This example demonstrate a basic use-case of the Virtual LED and Virtual DIP switches.

<a name="description"></a>
## Functional Description

The cl_hello_world example demonstrates basic Shell-to-CL connectivity, memory-mapped register instantiations and the use of the Virtual LED and DIP switches.
The cl_hello_world example implements two registers in the [FPGA AppPF BAR0 memory space](../../../docs/AWS_Fpga_Pcie_Memory_Map.md) connected to the OCL AXI-L interface. 
The two registers are:

1. Hello World Register (offset 0x500)
2. Virtual LED Register (offset 0x504)

The Hello World Register is a 32-bit read/write register. However, in order to demonstrate that the register is being accessed correctly, the read data returned for the register will be byte swapped.

The Virtual LED register is a 16-bit read-only register that shadows the lower 16 bits of the Hello World Register such that it will hold the same value as bits 15:0 of the Hello World Register.

The cl_hello_world design utilizes the Virtual LED and DIP switch interface which consists of two signals described in the [cl_ports.vh](./../../../common/shell_stable/design/interfaces/cl_ports.vh) file:


```
   input[15:0] sh_cl_status_vdip,               //Virtual DIP switches.  Controlled through FPGA management PF and tools.
   output logic[15:0] cl_sh_status_vled,        //Virtual LEDs, monitored through FPGA management PF and tools
```

In this example the Virtual LED Register is used to drive the Virtual LED signal, cl_sh_status_vled. 
In addition, the Virtual DIP switch, sh_cl_status_vdip, is used to gate the Virtual LED Register value sent to the Virtual LEDs. 
So, for example, if the sh_cl_status_vdip is set to 16'h00FF, then only the lower 8 bits of the Virtual LED Register will be signaled on the Virtual LED signal cl_sh_status_vled. 

While running on F1, the developer can use the FPGA tools `fpga-get-virtual-led` to read the LED values on the CL-to-Shell interface. 
While `fpga-set-virtual-dip-switch` tool is used to set the DIP switch values on the Shell-to-CL interface.

  
### Unused interfaces

The Hello World example does not use most of AWS Shell interface, hence the unused signals are tied off.
At the end of `cl_hello_world.sv` file, there is a specific `include` command for an interface-specific `.inc` file, to handle the tie-off\'s for every unused interface.