Documentation - introduction

doc/report/.gitignore

@@ -0,0 +1,2 @@
+html/*
+latex/*

doc/report/content/01_introduction.tex

@@ -15,11 +15,49 @@ \chapter{Introduction}
 % context. Motivate the questions addressed in this work and summarize
 % your contributions. Related work should also be mentioned here,
 % especially if you do not have a separate chapter for it.
+\pulpino is a micro-controller like system based on IPs mostly taken from its bigger brother the \gls{pulp} project.
 
-\section{First Section}
+This project origins from the idea to open-source the PULP project. Since \gls{pulp} is a huge project \pulpino is
+the first effort in doing so. The direct relation to the \gls{pulp} project is even expressed in the name chosen for
+the project: In Italian, adding an "-ino" at the end of a word usually means that word corresponds to a smaller version.
 
+Apart from the open source release, having a smaller platform has some tremendous advantages for the \gls{pulp} project as
+well. The \pulpino platform easily allows us to evaluate new features without considering the overhead of the whole \gls{pulp}
+platform in the first place. This is true regarding simple RTL simulation as well as for Synthesis estimates.
 
-\section{Second Section}
+In addition to the opportunity stated above there is still the educational aspect of the project. Due to its simplicity
+it can be of great value for students who want to gather deep understanding of the basic building blocks of a
+micro-controller like system. This relates to the SoC architecture as well as the idea and construction of a RISC core.
+It is often useful for ones understanding of a concept to have the possibility to observe a working implementation.
+
+\section{General Overview}
+
+\pulpino pursues a simple Harvard architecture (e.g. it has physically separated instruction and data RAMs). At its heart it
+has a \gls{RISC} core operating. We currently support two different instruction sets (ISA) for two distinct cores. This can either be
+our OpenRISC core OR1ON or our RISC-V implementation RI5CY. The cores are pin compatible and can therefore be swapped at one's
+convenience.
+The core has debug support enabled through the Advanced Debug Unit (ADB) partially adapted from the OpenCores project. The debug
+unit provides outside world communication via standard JTAG TAP. The core region (including the core, the debug unit and the RAMs)
+is communicating over a standard \gls{AXI}.
+
+A dedicated AXI to APB bridge connects the internal AXI bus to the (slower) \gls{APB}. Both bus specifications are part of the
+\gls{AMBA} specification.
+
+\section{Document Structure}
+
+This document is separated into two different parts. Part I deals with the general concept behind \pulpino and
+everything that is needed to start developing programs and/or specialized IPs easily. It starts with an introduction to
+the build framework and on how to get everything up and running so that the reader can easily follow along.
+
+I then aim to give a more detailed description of the overall architecture, the different IP cores and their peculiarities.
+This section concludes in a explanation of the functional verification framework that is shipped alongside the \pulpino project.
+
+The second part contains ASIC (Imperio) specific information. It gives insight on the measures taken for the tape-out as
+well as chip related information and concludes with a chip data sheet. Since Imperio is the ASIC of \pulpino everything explained in the
+first part of the document is directly applicable to Imperio as well.
+
+In the appendix you can find a summary of details needed to start developing for \pulpino. This includes a register description and
+a API description amongst others and it is supposed to act as a quick reference card for application developer.
 
 
 %%% Local Variables:

doc/report/content/02_preliminaries.tex

@@ -11,34 +11,11 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Preliminaries / Background}
-This chapter can be skipped if the theory/algorithms are clear enough
-such that they can be explained without very much background
-information (e.g., within another chapter).
 
-\section{First Section}
+\section{Getting Started}
 
 
-
-\subsection{First Subsection}
-
-
-\subsection{Second Subsection}
-
-
-\subsubsection{First Subsubsection}
-
-\subsubsection{Second Subsubsection}
-
-
-\section{Second Section}
-
-
-\subsection{First Subsection}
-
-
-\subsection{Second Subsection}
-
-%%% Local Variables: 
+%%% Local Variables:
 %%% mode: latex
 %%% TeX-master: "../report_template"
-%%% End: 
+%%% End:

doc/report/content/05_architecture.tex

@@ -17,6 +17,14 @@ \chapter{Hardware Architecture}
 usually is more general than what you actually implemented and can
 even be in a parameterized form.
 
+\begin{figure}[tb]
+  \centering
+  \includegraphics[width=\linewidth]{./figures/pulpino_blockdiagram}
+  \caption{Functional verification setup.}
+  \label{fig:block_diagram}
+\end{figure}
+
+
 \section{First Section}
 
 

doc/report/content/z_01_appendix_examples.tex → doc/report/content/z_01_appendix_taskdescription.tex

@@ -11,10 +11,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Task Description}
-Include the task description \textbf{pdf} you got from your
-assistant(s) with the \shell{\textbackslash includepdf} command.
-% include the task description pdf!
-%\includepdf[pages=-, turn=false, scale=0.9]{../../task/TaskDescription.pdf}
+\includepdf[pages=-, turn=false, scale=0.9]{task/TaskDescription.pdf}
 
 
 \chapter{Declaration of Originality}\label{chap:originality}

doc/report/glossaries/glossaries.tex

@@ -65,9 +65,17 @@
 \newacronym{iis}{IIS}{Integrated Systems Laboratory}
 \newacronym{asic}{ASIC}{Application-Specific Integrated Circuit}
 \newacronym{fpga}{FPGA}{Field Programmable Gate Array}
+\newacronym{pulp}{PULP}{Open Parallel Ultra-Low-Power Processing-Platform}
+\newacronym{soc}{SoC}{System on Chip}
+\newacronym{RISC}{RISC}{Reduced Instruction Set Computer}
+\newacronym{ISA}{ISA}{Instruction Set Architecture}
+\newacronym{ADB}{ADB}{Advanced Debug Unit}
+\newacronym{AXI}{AXI}{Advanced eXtensible Interface Bus}
+\newacronym{APB}{APB}{Advanced Peripheral Bus}
+\newacronym{AMBA}{AMBA}{Advanced Microcontroller Bus Architecture}
+
 \newacronym{led}{LED}{Light-Emitting Diode}
-\newacronym{nist}{NIST}{National Institute of Standards and
-Technology}
+\newacronym{nist}{NIST}{National Institute of Standards and Technology}
 \newacronym{aes}{AES}{Advanced Encryption Standard}
 \newacronym{ecc}{ECC}{Elliptic Curve Cryptography}
 \newacronym{ecdsa}{ECDSA}{Elliptic Curve Digital Signature Algorithm}

doc/report/report.tex

@@ -100,11 +100,13 @@
 %%%%%
 \mainmatter
 
+\part{\pulpino}
 % Include the actual content files.
 \include{./content/01_introduction}
 \include{./content/02_preliminaries}
 \include{./content/03_related_work}
 \include{./content/04_theory}
+\part{Imperio}
 \include{./content/05_architecture}
 \include{./content/06_implementation}
 \include{./content/07_results}
@@ -116,7 +118,7 @@
 %%%%%
 \appendix
 
-\include{./content/z_01_appendix_examples}
+\include{./content/z_01_appendix_taskdescription}
 \include{./content/z_02_directories}
 \include{./content/z_03_latex_tips}
 \include{./content/z_04_writing_tips}

sw/apps/CMakeSim.txt

@@ -98,6 +98,36 @@ macro(add_sim_targets NAME)
     COMMENT "Running ${NAME} in ModelSim (post layout)"
     ${USES_TERMINAL})
 
+  # run in modelsim with GUI post layout
+  add_custom_target(${NAME}.vsim.boot.pl
+    COMMAND ${CMAKE_COMMAND} -E remove stdout/*
+    COMMAND ${CMAKE_COMMAND} -E remove FS/*
+    COMMAND tcsh -c "${SETENV} ${VSIM} -64 -do 'source tcl_files/run_boot_pl.tcl\\;'"
+    WORKING_DIRECTORY ./${SUBDIR}
+    DEPENDS ${NAME}.slm.cmd ${NAME}.stim.txt ${NAME}.links
+    COMMENT "Running ${NAME} in ModelSim (post layout)"
+    ${USES_TERMINAL})
+
+  # run in modelsim with GUI post layout
+  add_custom_target(${NAME}.vsim.boot.ps
+    COMMAND ${CMAKE_COMMAND} -E remove stdout/*
+    COMMAND ${CMAKE_COMMAND} -E remove FS/*
+    COMMAND tcsh -c "${SETENV} ${VSIM} -64 -do 'source tcl_files/run_boot_ps.tcl\\;'"
+    WORKING_DIRECTORY ./${SUBDIR}
+    DEPENDS ${NAME}.slm.cmd ${NAME}.stim.txt ${NAME}.links
+    COMMENT "Running ${NAME} in ModelSim (post synthesis)"
+    ${USES_TERMINAL})
+
+  # run in modelsim with GUI post layout and dump vcd
+  add_custom_target(${NAME}.power
+    COMMAND ${CMAKE_COMMAND} -E remove stdout/*
+    COMMAND ${CMAKE_COMMAND} -E remove FS/*
+    COMMAND tcsh -c "${SETENV} ${VSIM} -64 -do 'source tcl_files/run_power.tcl\\;'"
+    WORKING_DIRECTORY ./${SUBDIR}
+    DEPENDS ${NAME}.slm.cmd ${NAME}.stim.txt ${NAME}.links
+    COMMENT "Running ${NAME} in ModelSim (post layout)"
+    ${USES_TERMINAL})
+
   # run in modelsim with GUI scan chain testing
   add_custom_target(${NAME}.vsim.sc.pl
     COMMAND tcsh -c "${SETENV} ${VSIM} -64 -do 'source tcl_files/run_sc_pl.tcl\\;'"

vsim/scripts/vcompile_imperio_ps.sh

@@ -1,8 +1,6 @@
 #!/bin/tcsh
 source scripts/colors.sh
 
-#!/bin/tcsh
-
 echo "${Green}--> Compiling imperio components... ${NC}"
 
 echo "${Green}Compiling component:   ${Brown} Imperio components ${NC}"

vsim/tcl_files/pl_disable_synch_checks.tcl

@@ -11,4 +11,3 @@ proc disable_tchecks { path } {
 }
 
 disable_tchecks /imperio_tb/top_i/pulpino_i/peripherals_i/axi_spi_slave_i/axi_spi_slave_i/u_syncro/*
-disable_tchecks /imperio_tb/top_i/pulpino_i/peripherals_i/axi_spi_slave_i/axi_spi_slave_i/u_dcfifo_tx/u_din/full/full_synch/*

vsim/tcl_files/run_boot_pl.tcl

@@ -0,0 +1,10 @@
+#!/bin/bash
+# \
+exec vsim -64 -do "$0"
+
+set TB            imperio_tb
+set VSIM_FLAGS    ""
+set MEMLOAD       "STANDALONE"
+
+source ./tcl_files/vsim_pl.tcl
+

vsim/tcl_files/run_boot_ps.tcl

@@ -0,0 +1,10 @@
+#!/bin/bash
+# \
+exec vsim -64 -do "$0"
+
+set TB            imperio_tb
+set VSIM_FLAGS    ""
+set MEMLOAD       "STANDALONE"
+
+source ./tcl_files/vsim_ps.tcl
+

vsim/tcl_files/vsim_ps.tcl

@@ -2,7 +2,7 @@
 # e.g. it did not recognize the -pli ./something.so argument
 #
 
-set cmd "vsim -quiet imperio_tb \
+set cmd "vsim -quiet $TB \
   -L imperio_lib_ps \
   -L fll_lib \
   +nowarnTRAN \

vsim/tcl_files/waves_pl.tcl

@@ -0,0 +1,121 @@
+add wave -group "Padframe" \
+sim:/imperio_tb/top_i/pad_clk_i \
+sim:/imperio_tb/top_i/pad_rstn_i \
+sim:/imperio_tb/top_i/pad_clk_sel_i \
+sim:/imperio_tb/top_i/pad_clk_standalone_i \
+sim:/imperio_tb/top_i/pad_testmode_i \
+sim:/imperio_tb/top_i/pad_fetch_enable_i \
+sim:/imperio_tb/top_i/pad_ssclk_i \
+sim:/imperio_tb/top_i/pad_scs_io \
+sim:/imperio_tb/top_i/pad_sio0_io \
+sim:/imperio_tb/top_i/pad_sio1_io \
+sim:/imperio_tb/top_i/pad_sio2_io \
+sim:/imperio_tb/top_i/pad_sio3_io \
+sim:/imperio_tb/top_i/pad_msclk_o \
+sim:/imperio_tb/top_i/pad_mcs_io \
+sim:/imperio_tb/top_i/pad_mio0_io \
+sim:/imperio_tb/top_i/pad_mio1_io \
+sim:/imperio_tb/top_i/pad_mio2_io \
+sim:/imperio_tb/top_i/pad_mio3_io \
+sim:/imperio_tb/top_i/pad_rx_i \
+sim:/imperio_tb/top_i/pad_tx_o \
+sim:/imperio_tb/top_i/pad_rts_o \
+sim:/imperio_tb/top_i/pad_cts_i \
+sim:/imperio_tb/top_i/pad_scl_io \
+sim:/imperio_tb/top_i/pad_sda_io \
+sim:/imperio_tb/top_i/pad_gpio_io \
+sim:/imperio_tb/top_i/pad_tck_i \
+sim:/imperio_tb/top_i/pad_trstn_i \
+sim:/imperio_tb/top_i/pad_tms_i \
+sim:/imperio_tb/top_i/pad_tdi_i \
+sim:/imperio_tb/top_i/pad_tdo_o
+
+add wave -group "Core" \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/clk \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/rst_n \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/test_en_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/boot_addr_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/core_id_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/cluster_id_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/instr_req_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/instr_gnt_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/instr_rvalid_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/instr_addr_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/instr_rdata_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_req_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_gnt_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_rvalid_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_we_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_be_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_addr_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_wdata_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_rdata_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/data_err_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/irq_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_stall_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_bp_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_strobe_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_ack_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_we_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_addr_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_data_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/dbginf_data_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/fetch_enable_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/RISCV_CORE/core_busy_o
+
+add wave -group "Instr MEM Top"  \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/clk \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/rst_n \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/en_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/addr_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/wdata_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/rdata_o \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/we_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/be_i \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/bypass_en_i
+
+add wave -group "Instr MEM 0" \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/DO \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/DI \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/A \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/DVSE \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/DVS \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/WEB \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/CK \
+sim:/imperio_tb/top_i/pulpino_i/core_region_i/instr_mem/sp_ram_wrap_i_sp_ram_bank_i_sram_bank_gen_0__bank_mem_bank_i_cut/CSB
+
+add wave -group "APB SPI Master OE"  \
+sim:/imperio_tb/top_i/oe_msio_int
+
+add wave -group "APB SPI Master"  \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/HCLK \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/HRESETn \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PADDR \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PWDATA \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PWRITE \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PSEL \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PENABLE \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PRDATA \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PREADY \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/PSLVERR \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/events_o \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_clk \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_csn0 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_csn1 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_csn2 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_csn3 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_mode \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdo0 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdo1 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdo2 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdo3 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdi0 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdi1 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdi2 \
+sim:/imperio_tb/top_i/pulpino_i/peripherals_i/apb_spi_master_i/spi_sdi3
+
+configure wave -namecolwidth  250
+configure wave -valuecolwidth 100
+configure wave -justifyvalue left
+configure wave -signalnamewidth 1
+configure wave -timelineunits ns