2.1. Getting Started With Nysa¶
This document has the following three parts:
- Installing Nysa on your system
- Set up Nysa
- Explore some of the features and commands available
2.1.1. Requirements¶
Python
Currently Nysa is built for Python 2 you can download it here
Pip
Pip simplifies the process of installing Python modules. You can test if you have pip installed by openning up a terminal and typing: pip --version
If you do not see a version number here’s how to get it:
- Download and install pip
get-pip.py <https://bootstrap.pypa.io/get-pip.py>
python ./get-pip.py
sudo pip install --upgrade pip
- Using apt-get install git, iverilog and gtkwave
sudo apt-get install git verilog gtkwave
2.1.2. Installation¶
From a terminal install nysa from the github repo using pip
Ubuntu
sudo pip install git+https://github.com/CospanDesign/nysa
Pip will install the nysa module as well as the command line tool
2.1.3. Nysa Command Line Tool¶
The Nysa command line tool is available to the user, to view all the commands type:
$> nysa --help
usage: nysa [-h] [-v] [-d]
{generate-slave,devices,image-builder,reset,ping,board-programmed,program,upload,sdb-viewer,init,utils,boards,platforms,install-platform,install-verilog-repo,install-examples,status}
...
Nysa Tool
optional arguments:
-h, --help show this help message and exit
-v, --verbose Output verbose information
-d, --debug Output test debug information
Tools:
Nysa Tools
{generate-slave,devices,image-builder,reset,ping,board-programmed,program,upload,sdb-viewer,init,utils,boards,platforms,install-platform,install-verilog-repo,install-examples,status}
Enter the toolname with a -h to find help about that specific tool
Tools:
cbuilder Functions to help create code to go into platforms
generate-slave create a project to generate a nysa compatible core
devices manage/view devices IDs and descriptions
ibuilder Functions to generate an entire image (or binary) to be downloaded into a platform
image-builder create a vendor specific project to generate an image for a platform
host Functions to view and control boards
reset performs a soft reset the specified board
ping performs a board ping, this is the simplest level of communicatio If a board responds to a ping it has been reset and the clock is running correctly
board-programmed reads the status of the FPGA 'Done' pin to determine if the FPGA is programmed
program Initiate a program sequence
upload upload a program file to the specified board
sdb-viewer display the contents of the SDB of the specified board
utility Functions to update and/or upgrade the nysa tool including adding new platforms and verilog packages
init creates the local nysa_projects directory, initializes the configuration files. To see the status of the current nysa setup run 'nysa status'
utils utility functions
boards list connected boards
platforms list platforms (installed and remotely available)
install-platform install a platform to the local system
install-verilog-repoinstall a verilog repository to the local system
install-examples install FPGA Project examples to the local system
status print the status of the nysa tools
We will be using some of these functions to configure Nysa and communicate with either a physical or simulated FPGA board.
2.1.4. Initializing Nysa¶
Initialize Nysa
nysa init
nysa install-examples all
What is it doing? Nysa needs to do the following things in order to be set up correctly
- Create a directory where users can create projects (both core projects and image projects), by default it creates a directory in <home>/Projects/nysa_base on Ubuntu.
- Retrieve the default verilog repositories. They will be installed in <home>/.local/nysa/verilog/ directory. A list of packages that will be installed can be found here: Verilog Repositories
- Install all of the supported platforms. Currently a list of packages are stored here: Board Platforms
- Install examples for the supported platforms: Examples Projects
2.1.5. Talking to an FPGA¶
Run the following command:
nysa boards
You should get an output that looks something like this:
Scanning artemis_usb2... Found 1 board(s)
Board ID: FTYNUFY9
Scanning dionysus... No boards found
Scanning sim... Found 11 board(s)
Board ID: dionysus_spi_pmod
Board ID: dionysus_sf_camera
Board ID: dionysus_i2c_pmod
Board ID: dionysus_dma_test
Board ID: dionysus_stepper_pmod
Board ID: dionysus_dma_controller_test
Board ID: dionysus_nes
Board ID: dionysus_i2s
Board ID: dionysus_pmod_oled
Board ID: dionysus_uart_pmod
Board ID: dionysus_pmod_tft
Scanning artemis... No boards found
Nysa will query the host computer for any boards attached. It even queried simulated boards. Any of the above boards can be used in the following examples.
Note about implicit names
When executing a command that interfaces with a board Nysa will attempt to determine which board the user is refering to. For example, if the ‘artemis_usb2’ board was the only board attached to my computer and I types nysa ping
Nysa will send a ping down to artemis_usb2. The command nysa ping
would be the same as typing nysa ping artemis_usb2 -s FTYNUFY9
(Assuming FTYNUFY9 was the board’s serial number). If there are multiple boards for a single platform the user will need to explicitly write the entire command.
As an example, if there were no physical boards attached and the nysa ping
was issued, the following would occur:
$> nysa ping
Error: ping_board: Serial number (ID) required because there are multiple platforms availble
Available IDs:
dionysus_spi_pmod
dionysus_sf_camera
dionysus_i2c_pmod
dionysus_dma_test
dionysus_stepper_pmod
dionysus_dma_controller_test
dionysus_nes
dionysus_i2s
dionysus_pmod_oled
dionysus_uart_pmod
dionysus_pmod_tft
The following variation to the command would resolve this: nysa ping sim -s dionysus_spi_pmod
$> nysa ping sim -s dionysus_spi_pmod
Pinging board... Received a Response!
2.1.5.1. Ping a board¶
Ping is the simplest form of communication, the purpose of the command is to verify that the
- The communication medium is working (UART, USB, PCIE, etc...).
- The clock is working correctly.
- The FPGA is programmed.
- The most basic functionality is working.
Simulation Example, pinging the simulated board ‘dionysus_spi_pmod’
$> nysa ping sim -s dionysus_spi_pmod
Pinging board... Received a Response!
Physical Board Example (in this case artemis_usb2)
$> nysa ping
Pinging board... Received a Response!
2.1.5.2. SDB Viewer¶
The SDB (Self Defined Bus) Viewer. When the Nysa image build tool creates an FPGA image it also generates a ROM that is embedded in that image. That ROM can be read and parsed to determine the behavior of the FPGA by the user.
Simulation Example, read/parse the SDB and display it on the command line
$> nysa sdb-viewer sim -s dionysus_spi_pmod
Important: NysaSDBManager:read_sdb: Parsing Top Interconnect Buffer
SDB
Bus: top @ 0x0000000000000000 : Size: 0x200000000
Number of components: 2
Bus: peripheral @ 0x0000000000000000 : Size: 0x04000000
Number of components: 4
SDB Type (Major:Minor) (01:00): SDB
Address: 0x0000000000000000-0x0000000000000380 : Size: 0x00000380
Vendor:Product: 8000000000000000:00000000
wb_spi_0 Type (Major:Minor) (05:01): SPI
Address: 0x0000000001000000-0x000000000100000C : Size: 0x0000000C
Vendor:Product: 800000000000C594:00000005
gpio1 Type (Major:Minor) (02:01): GPIO
Address: 0x0000000002000000-0x0000000002000008 : Size: 0x00000008
Vendor:Product: 800000000000C594:00000002
1:2 Type (Major:Minor) (00:00): Nothing
Address: 0x0000000003000000-0x0000000003000000 : Size: 0x00000000
Vendor:Product: 8000000000000000:00000000
Bus: memory @ 0x0000000100000000 : Size: 0x00800000
Number of components: 1
mem1 Type (Major:Minor) (06:02): Memory
Address: 0x0000000000000000-0x0000000000800000 : Size: 0x00800000
Vendor:Product: 800000000000C594:00000000
Physical Board Example (in this case artemis_usb2)
$> nysa sdb-viewer
Important: NysaSDBManager:read_sdb: Parsing Top Interconnect Buffer
SDB
Bus: top @ 0x0000000000000000 : Size: 0x200000000
Number of components: 2
Bus: peripheral @ 0x0000000000000000 : Size: 0x06000000
Number of components: 6
SDB Type (Major:Minor) (01:00): SDB
Address: 0x0000000000000000-0x0000000000000440 : Size: 0x00000440
Vendor:Product: 8000000000000000:00000000
artemis_usb2 Type (Major:Minor) (22:03): Platform
Address: 0x0000000001000000-0x0000000001000004 : Size: 0x00000004
Vendor:Product: 800000000000C594:00000000
gpio1 Type (Major:Minor) (02:01): GPIO
Address: 0x0000000002000000-0x0000000002000008 : Size: 0x00000008
Vendor:Product: 800000000000C594:00000002
sata Type (Major:Minor) (14:01): Storage Manager
Address: 0x0000000003000000-0x0000000003001000 : Size: 0x00001000
Vendor:Product: 800000000000C594:00000010
dma Type (Major:Minor) (13:01): DMA
Address: 0x0000000004000000-0x0000000004000095 : Size: 0x00000095
Vendor:Product: 800000000000C594:0000C594
artemis Type (Major:Minor) (22:02): Platform
Address: 0x0000000005000000-0x0000000005000003 : Size: 0x00000003
Vendor:Product: 800000000000C594:00000000
Bus: memory @ 0x0000000100000000 : Size: 0x08000000
Number of components: 1
ddr3_mem Type (Major:Minor) (06:03): Memory
Address: 0x0000000000000000-0x0000000008000000 : Size: 0x08000000
Vendor:Product: 800000000000C594:00000000
2.1.5.3. Other Host Commands¶
2.1.5.3.1. upload¶
Upload an image file to a board. The format of the files is platform specific. For Artemis USB2 and Dionysus the format is a ‘bin’ file that is generated from the Xilinx bitgen tool.
Uploading a binary to artemis USB2
$> nysa upload top.bin
Info: upload: Found: Numonyx 2048 KB, 32 sectors each 65536 bytes
Info: upload: Erasing the SPI flash device, this can take a minute or two...
Info: upload: Flash erased, writing binary image to PROM
addr: 00000000, len data: 0016A674, len self: 00200000
Info: upload: Reading back the binary flash
Info: upload: Verifying the data read back is correct
Info: upload: Verification passed!
2.1.5.3.2. program¶
Issue a signal that will reprogram the FPGA. This is platform dependent. For Artemis USB2 and Dionysus the command will pull the ‘PROGRAM_N’ pin low FPGA which tells the FPGA to read in the data from the SPI Flash ROM.
Issuing a program command
$> nysa program
Wait for board to finish programming...........................Done!
2.1.5.3.3. reset¶
Many times FPGA images have a reset signals, this command will pusle the reset signal which resets FPGA’s internal state machines
$> nysa reset
2.1.6. Conclusion¶
This is all the high level utility functions of Nysa to learn more about how to:
- Create a Wishbone slave core you can use to interface with your custom hardware and that can be used within an FPGA image: Getting started with CBuilder
- Build FPGA images with a configuration file: Getting started with IBuilder
- Interact with Nysa graphically using the Nysa GUI (nui)