Project

General

Profile

Pitanga User Guide
2021.08 - Piratininga



OVERVIEW

Pitanga is a digital circuit emulator. It reads a circuit design coded in Verilog and maps the circuit behavior to a virtual board for fast prototyping. Digital circuit prototyping is a well-established technique for verifying the functionality and performance in the very early design stage of integrated circuits (ICs). It usually uses an electronic board with a Field Programmable Gate Array device (FPGA). An FPGA is a programmable device that can be configured by the user. Unlike an ASIC, an FPGA can be configured, and reconfigured, as many times as needed.

However, prototyping requires real hardware and it may be expensive depending on the user's needs. Sometimes, the user just wants to prototype a very simple circuit to experiment with ideas and design concepts. This is the case of undergrad students that need to "see" their design in action. In addition to that, the software available in the market for prototyping is quite complex for a beginner. The challenge starts during the software installation: the system requirements. Therefore, prototyping a simple led blinking may require not only the acquisition of a prototyping board (a.k.a development kit) but the upgrade of computer parts required to run the FPGA design software.

Another solution for starting into the digital circuit design realm is the usage of digital circuit simulators. Nowadays, there are quite good open-source solutions, like Verilator and Icarus Verilog. However, simulators do not provide the user experience on prototyping. Simulators do not intent to give the user the experience of pressing a button and "see a led turn on and off". In a simulator, a button press action must be coded in Verilog somewhere in the simulation timeline, and the output that drives the led will respond as a waveform switching its value from one logic state to another logic state. The user doesn't get the instant feedback that emulations give because simulators are intended to provide an environment for debugging the circuit design, not prototyping it.

Pitanga Emulator is an effort to provide an affordable, easy-to-use, and fast-prototyping tool. It implements professional-grade software techniques, providing you not only the prototyping design experience. Pitanga does not eliminate the need to use a simulation tool, neither a development kit. Instead, it works together to bring real design experience to those in the initial stages of learning digital circuit design. To put it in a nutshell, Pitanga gives the user experience on prototyping without any programmable device.

INSTALLATION

Pitanga Emulator supports both Linux and Windows operating systems. However, as these systems contain several different versions and distros, the next sections explain how to install Pitanga on some of the most common Linux and Windows versions.

Linux OS (x86_64)

The base development OS for this version of Pitanga is Fedora release 34, x86_64, using Python 3.9.2. However, Pitanga has been deployed and tested in other different versions for better compatibility.

Read the next sections for instructions on how to install and configure Pitanga on different Linux flavors.

CentOS 7.9

To install Pitanga Emulator in CentOS7.9:

  1. Install the Python 3 interpreter
    sudo yum install python3
    
  2. Download Pitanga Emulator (also available at https://www.inplace-da.com)
  3. Open the Linux Terminal in the Pitanga Emulator folder
    unzip pitanga-v21.08.zip
    cd pitanga-v21.08/
    
  4. Setup Pitanga Python Virtual Environment
    python3 -m venv env
    . env/bin/activate
    
  5. Install the python package requirements (upgrade pip before if neded).
    pip install --upgrade pip
    python3 -m pip install -r requirements.txt
    
  6. Finally, run Pitanga Emulator from the terminal
    python3 pitanga.py -v samples/general-post.v -p samples/general-post.pinout
    

Done! Now, take a moment and press the buttons to check this awesome design written in Verilog. Close the window and deactivate the python environment:

deactivate

Take a look in the Tutorials section. There, you will find good resources that will help you to start prototyping.

Red Hat Enterprise Linux 8.2

There is no need to install Python as Pitanga works fine with the pre-installed Python (Python 3.6.8).
Just follow the steps in CentOS 7.9 section, steps 2-6.

Fedora 32 Workstation

There is no need to install Python as Pitanga works fine with the pre-installed Python.
Just follow the steps in CentOS 7.9 section, steps 2-6.

Manjaro 21.1.0

There is no need to install Python as Pitanga works fine with the pre-installed Python.
Just follow the steps in CentOS 7.9 section, steps 2-6.

Ubuntu 18.04 LTS

You will have to install the Python Virtual Environment package after the step 3 in CentOS 7.9 section:

sudo apt-get install python3-venv

Then, just follow the installation steps 4-6.

Python 3 is already installed in this distro (do not execute step 1).

Linux Mint 20.2

You will have to install the Python Virtual Environment package after the step 3 in CentOS 7.9 section:

sudo apt-get install python3-venv

Then, just follow the installation steps 4-6.

Python 3 is already installed in this distro (do not execute step 1).

Windows OS (x86_64)

The base development OS for this version of Pitanga is Windows 10. However, Pitanga has been deployed and tested in Windows 7 and Virtualized Windows for better compatibility.

Windows 10

  1. Open the Microsoft Store by clicking on Start > Microsoft Store
  2. In the Microsoft Store search box, type Python 3.9. Click on Install.
  3. Download and unzip the Pitanga Emulator, also available at https://www.inplace-da.com
  4. Open the Command Prompt by typing cmd into the search box
  5. Change to the Pitanga Emulator folder by typing cd <path_to_pitanga_files>
  6. Setup the Pitanga Python Virtual Environment by typing the following commands in the Command Prompt. The command prompt will change
    python -m venv env
    env\Scripts\activate.bat
    
  7. Install the python package requirements (this action may take some minutes)
    python -m pip install -r requirements.txt
    
  8. Finally, run Pitanga Emulator from the prompt
    python pitanga.py -v samples\general-post.v -p samples\general-post.pinout
    

Done! Now, take a moment and press the buttons to check this awesome design written in Verilog. Then, close the window and deactivate the python environment before closing the command prompt:

deactivate

Finally, take a look in the Tutorials section and start prototyping more designs now!

Windows 7

You still can run Pitanga if you have an old version of Windows. See steps below:

  1. Download and install Python 3.6.5 - March 28, 2018: https://www.python.org/ftp/python/3.6.5/python-3.6.5-amd64.exe
  2. Download and unzip the Pitanga Emulator, also available at https://www.inplace-da.com
  3. Click the Start button, then select All Programs > Accessories. In the resulting program list, click on Command Prompt
  4. Change to the Pitanga Emulator folder by typing cd <path_to_pitanga_files> (see Win10 example)
  5. Setup the Pitanga Python Virtual Environment by typing the following commands:
    py -m pip install --upgrade pip setuptools virtualenv
    py -m pip install kivy[base] kivy_examples
    py -m virtualenv env
    env\Scripts\activate.bat
    py -m pip install -r requirements.txt
    
  6. Finally, run Pitanga Emulator
    py pitanga.py -v samples\general-post.v -p samples\general-post.pinout
    

Done! Remember to deactivate the Python environment after closing Pitanga.

Windows VM Users

If you are trying to run Pitanga Emulator from a Virtual Machine (VM), you will experience a "Kivy Fatal Error" message like displayed in the image below.

This happens because your system does not contain the OpenGL libraries required for Pitanga (version 2.0 or above).

This issue can be easily solved by installing or updating your graphic card driver. However, if for some reason you cannot install or update your video driver (e.g., running from a virtual machine, the available driver is unstable, etc), then you should download and install the Mesa 3D Graphics Library. Just follow the steps below:

  1. Download the pre-built Windows installer "Mesa3D OpenGL Libraries 21.1.6" available at https://github.com/pal1000/mesa-dist-win/releases (direct link here)
  2. Extract the downloaded file and double click the systemwidedeploy script. Select option 1, "Core desktop OpenGL drivers" and press Enter. Wait for the installation and exit (option 10)

Done! Pitanga is now ready to run.

TUTORIALS

This section provides tutorials to help you build your designs on Pitanga. We recommend you follow these tutorials before trying your own designs.

The tutorial was developed for Linux users. So, whenever you find a list of command-line instructions, make sure to adapt these instructions to the respective Windows commands.

My Inverter

In this tutorial, you will prototype a very simple design. You will learn how to:

  • code an inverter in Verilog;
  • map the Verilog input and output ports to the board components;
  • emulate your design.

Coding in Verilog

The first step is to code the basic structure of a Verilog file. A basic Verilog file is composed of a module declaration followed by a list of non-module items (the circuit logic itself). The module declaration is identified by the keyword module succeeded by the module identifier as shown below:

module my_inverter(
    // this is a line comment
    // module ports go here
    );

    /* this is a multi-line comment:
       logic code goes here
    */
endmodule

Now, let's instantiate the inverter and declare the module input and output ports:

module my_inverter(
    // this is a line comment
    // module ports go here
    input  btn0_i,
    output led0_o
    );

    /* this is a multi-line comment:
       logic code goes here
    */
    buf(led0_o, btn0_i);
endmodule

Done! Open a file editor of your preference and save this code as my_inverter.v.

Mapping to board components

We need to instruct Pitanga to map the module ports to the board components. Here is the code that does this job:

// VERILOG PORT     BOARD COMPONENT
btn0_i              btn0         ;
led0_o              led0         ;

Each line of the pinout file is a statement and it must end with a semicolon (';'). Save this code as my_inverter.pinout.

Notice that in this pinout code, only the components btn_0 and led0 are being used. There are more components available in the Pitanga virtual board. The diagram below shows the names of every board component:

Use this diagram to help you in the next designs.

Emulate your design

At this point, you have the files required to emulate your design. Open a terminal, go to the Pitanga Emulator directory, and run the following commands:

cd <pitanga directory>
. env/bin/activate
python pitanga.py -v <verilog file> -p <pinout file>

Example:

cd Softwares/Pitanga-v21.08/
. env/bin/activate
python3 pitanga.py -v my_inverter.v -p my_inverter.pinout

Congratulations on your first inverter! Pressing the push-button btn0 and the led0 LED will turn on and off.

Additional designs

There are more designs available for emulating. These designs are available in the samples folder.

$ cd samples
$ ls
components-mux21.pinout          instantiation-buf-clean.pinout
components-mux21.v               instantiation-buf-clean.v
components-xnor2.pinout          instantiation-nand2-clean.pinout
components-xnor2.v               instantiation-nand2-clean.v
components-xor2.pinout           instantiation-nor2-clean.pinout
components-xor2.v                instantiation-nor2-clean.v
general-post.pinout              instantiation-not-clean.pinout
general-post.v                   instantiation-not-clean.v
instantiation-and2-clean.pinout  instantiation-or2-clean.pinout
instantiation-and2-clean.v       instantiation-or2-clean.v

These designs are very basic but they will help you to build your own designs.

Add picture from clipboard (Maximum size: 10 MB)