Skip to content

G
Getting Started with the SPEC
Commit ea83c885 authored by Javier D. Garcia-Lasheras's avatar Javier D. Garcia-Lasheras
Browse files
Options

Upgraded after Mathieu and Erik review

parent 64361f7a
Hide whitespace changes
Inline Side-by-side
Showing with 138 additions and 130 deletions
README
View file @ ea83c885
DATE 20140224
DATE 20140324
First version of the Getting Started with the SPEC project is released.
"Getting Started with the SPEC" project. Version 1.0 (March, 2014)
doc/spec-getting-started.in
View file @ ea83c885
......@@ -33,14 +33,14 @@
@setchapternewpage on
@set update-month Feb 2014
@set update-month March, 2014
@finalout
@titlepage
@title Getting Started with the SPEC
@c @subtitle Version 0.1 (@value{update-month})
@subtitle A tutorial for the Simple PCI Express Carrier project newcomers
@subtitle Version 1.0 (@value{update-month})
@author Javier D. Garcia-Lasheras for CERN (BE-CO-HT)
@end titlepage
@headings single
......@@ -60,14 +60,14 @@
@chapter Introduction
The @i{Getting started with the SPEC} project provides a detailed
This @i{Getting started with the SPEC} project provides a detailed
tutorial on how to get ready to work with the @i{Simple PCI Express Carrier}
@url{http://www.ohwr.org/projects/spec/wiki}.
@sp 1
The @i{Getting started with the SPEC} project is hosted at
@url{http://www.ohwr.org/projects/spec-getting-started} and is composed
by two main parts:
of two main parts:
@itemize @bullet
@item Document covering the process of building a full SPEC design,
......@@ -82,13 +82,13 @@ by two main parts:
The document and demos assume that the user has no previous or very little
experience inside the @i{Open Hardware Repository} initiative. For this
reason, the tutorial introduces different resources from @i{OHR} while
covering the next design issues:
covering the following design issues:
@itemize @bullet
@item An in depth explanation of the SPEC hardware board, exposing its
main features, introducing the PCB design and the FMC standard and
available modules and explaining the different operation modes.
@item How to design a FPGA gateware for the SPEC board, from introducing
@item How to design an FPGA gateware for the SPEC board, from introducing
the Wishbone bus and its associated OHR tools to building a bitstream
from the included HDL demos.
@item How to handle the SPEC board from a Linux Host, including the use
......@@ -102,8 +102,8 @@ covering the next design issues:
@node Prerequisites
@section Prerequisites
In order to follow the @i{Getting Started with the SPEC} tutorial, the
next prerequisites must be accomplished (note that some application
In order to perform the @i{Getting Started with the SPEC} tutorial, the
following prerequisites need to be fulfilled (note that some application
specific tools will be installed later):
@sp 1
......@@ -119,8 +119,7 @@ specific tools will be installed later):
Designed to be Kernel independent for a maximum compatibility, the tutorial
has been successfully performed in every Linux distribution in which has been
tested. (e.g. Debian 6, Debian 7, Ubuntu 12.04LTS, Ubuntu 14.04LTS(testing),
Scientific Linux 6).
tested and there are at this moment no incompatible distributions known.
@sp 1
@b{Clone the Getting Started with the SPEC git repository}
......@@ -133,7 +132,7 @@ user$ git clone git://ohwr.org/fmc-projects/spec/spec-getting-started.git
@b{Python environment}
Minimum Python 2.x and optional Python 3.x
(tested on Python 2.6.6, Python 2.7.6 and Python 3.3.3)
(tested on Python 2.6.6, 2.7.5, 2.7.6 and Python 3.3.2, 3.3.3).
@sp 1
@b{Packages dependencies for building the code:}
......@@ -191,14 +190,14 @@ The Simple PCI Express Carrier is an FMC carrier that can hold one FMC card
and an SFP connector. On the PCIe side it has a 4-lane interface, while the
FMC mezzanine slot uses a low-pin count connector. This board is optimised
for cost and is usable with most of the FMC cards designed within the OHR
project (e.g. ADC cards, Fine Delay). The board is commercially available.
project (e.g. ADC cards, Fine Delay).
@sp 1
@center @image{pictures/spec_v1.1_top, 10cm}
@center @i{Top view of the SPEC 1.1 first prototype}
@center @image{pictures/spec_v4_top, 12cm}
@center @i{Top view of the SPEC v4 board}
@center @image{pictures/spec_v1.1_bottom, 10cm}
@center @i{Bottom view of the SPEC 1.1 first prototype}
@center @image{pictures/spec_v4_bottom, 12cm}
@center @i{Bottom view of the SPEC v4 board}
@c ==========================================================================
......@@ -248,13 +247,12 @@ to develop highly precise applications:
@b{On-board Memory}:
The SPEC mounts both volatile and non volatile memory ICs:
@itemize @bullet
@item 1x 2Gbit (256 MByte) DDR3 (MT41J128M16HA-15E).
@item 1x SPI 32Mbit flash PROM for multiboot FPGA powerup configuration,
storage of the FPGA firmware or of critical data.
@item 1x 2 Gbit (256 MByte) DDR3 (MT41J128M16HA-15E).
@item 1x SPI 32 Mbit flash PROM (M25P32-VMF6P) for multiboot FPGA powerup configuration, storage of the FPGA firmware or of critical data.
@end itemize
@b{Miscellaneous}:
The SPEC includes the next extra functionalities:
The SPEC includes the following extra functionalities:
@itemize @bullet
@item on-board thermometer IC (DS18B20U+).
@item unique 64-bit identifier (DS18B20U+).
......@@ -262,7 +260,7 @@ The SPEC includes the next extra functionalities:
@b{Front Panel}:
The mechanical design features a front panel that fits in standard
PCI slots and contains the next items:
PCI slots and contains the following items:
@itemize @bullet
@item 1x Small Formfactor Pluggable (SFP) cage for fibre-optic transceiver.
@item Programmable Red and Green LEDs.
......@@ -270,11 +268,10 @@ PCI slots and contains the next items:
@end itemize
@b{Internal Connectors}:
The next interfaces are available in the SPEC's PCB out of the front panel:
Several interfaces are available in the SPEC's PCB out of the front panel:
@itemize @bullet
@item 1x JTAG header for Xilinx programming during debugging.
@item 2x SATA connector.
@item 1x mini USB AB (USB-UART bridge).
@end itemize
@b{FPGA configuration}:
......@@ -292,8 +289,8 @@ stand-alone operation:
@itemize @bullet
@item External 12V power supply connector.
@item mini USB connector (USB-UART bridge).
@item 4x auxiliar user LEDs.
@item 2x auxiliar user buttons.
@item 4x auxiliary user LEDs.
@item 2x auxiliary user buttons.
@end itemize
@b{Power Consumption}:
......@@ -301,7 +298,7 @@ The SPEC board power consumption ranges from 5 to 12 Watt depending on
both the application and the operation mode (stand-alone vs PCIe slave).
@b{Optimised for cost}:
The SPEC's PCB uses a 6-layer stack-up for a cheaper production cost.
The SPEC's PCB uses a 6-layer stack-up for a lower production cost.
@sp 1
@c ==========================================================================
......@@ -327,9 +324,9 @@ licensee, more information can be found in
@sp 1
The SPEC design files are placed online in the file tab of the official
project website (@url{http://www.ohwr.org/projects/spec/files}).Current SPEC
version is 4.0 and the associated design files can be downloaded by using any
of the next links:
project website (@url{http://www.ohwr.org/projects/spec/files}).
The current SPEC version is 4.0 and the associated design files can be
downloaded by using any of the following links:
@itemize @bullet
@item @url{http://www.ohwr.org/attachments/download/918/SPEC_V4.tar.bz2}.
@item @url{http://www.ohwr.org/attachments/download/919/SPEC_V4.zip}.
......@@ -347,7 +344,7 @@ documentation set for the design is released in pdf format too.
@b{Note:} in the SPEC project site hosted on OHR you may find a SVN
repository in which some outdated SPEC design files are hosted. If you have
any doubts about the specific design version and associated documentation
that matches your SPEC unit, contact with your SPEC board provider
that matches your SPEC unit, contact your SPEC board provider
in order to get more information as granted by CERN-OHL.
......@@ -356,27 +353,22 @@ in order to get more information as granted by CERN-OHL.
@section FMC interface
The SPEC board is designed to act as a carrier for a low pin count (LPC)
FPGA Mezzanine Card (VITA 57).
In order to get more information about the VITA 57.1 FPGA Mezzanine Card
(FMC) standard, visit FMC Projects in the Open Hardware Repository
(@url{http://www.ohwr.org/projects/fmc-projects}). Here, you'll find
which FMC Mezzanines and Carriers are developed in the context of the
Open Hardware Repository project. Furthermore it gives practical info that
can help you in designing custom FMC modules.
FPGA Mezzanine Card (VITA 57). In order to get more information about the VITA 57.1 FPGA Mezzanine Card (FMC) standard, visit FMC Projects in the
Open Hardware Repository
(@url{http://www.ohwr.org/projects/fmc-projects}).
@sp 1
In this getting started guide for the SPEC board, two different FMC use
cases will be considered in the demo examples:
@itemize @bullet
@item No FMC module is plugged in.
@item fmc-dio-5chttla (@url{http://www.ohwr.org/projects/fmc-dio-5chttla})
@item fmc-dio-5chttla is plugged in (check @url{http://www.ohwr.org/projects/fmc-dio-5chttla}).
@end itemize
The fmc-dio-5chttla 5-channel digital I/O module has been selected
because its flexibility as a demonstrative platform and because it is
commercially available from different hardware providers. In addition, this
FMC module is licensed under CERN-OHL too.
as a demonstrative platform and because it is commercially available
from different hardware providers. In addition, this FMC module is
licensed under CERN-OHL too.
@center @image{pictures/fmc-dio-5chttla_v2_small, 10cm}
@center @i{Front and top view of the fmc-dio-5chttla module}
......@@ -390,9 +382,9 @@ FMC module is licensed under CERN-OHL too.
The SPEC board is designed to allow the operation in both stand-alone and
PCIe slave modes. In this getting started guide, we will consider only
the case in which the SPEC board is attached to a PC through the
PCI Express port. This option has been chosed because it doesn't require
PCI Express port. This option has been chosen because it does not require
additional third-party hardware tools to handle the SPEC and because it
makes the things easier for a newcomer, i.e. the control is on the Host PC
makes the things easier for a newcomer, as the control is on the Host PC
side and the gateware designs can be simplified.
@sp 1
......@@ -400,26 +392,26 @@ side and the gateware designs can be simplified.
The SPEC board can be deployed as an independent stand-alone unit. In order
to enable this operation mode, the Simple PCI Express Carrier includes the
next functionalities:
following functionalities:
@itemize @bullet
@item External 12V power supply connector.
@item mini USB connector (USB-UART bridge).
@item 4x auxiliar user LEDs.
@item 2x auxiliar user buttons.
@item 4x user LEDs.
@item 2x user buttons.
@end itemize
By embedding a soft processor in the Spartan-6 FPGA, the SPEC unit can be
used as a FMC enabled Single Board Computer (SBC). This topic is not
covered in this guide, but the mainstream choice for the most of the projects
in the Open Hardware Repository is deploying a Wishbone bus enabled
LM32 processor. You can find more info about this IP-core and its companion
used as an FMC enabled Single Board Computer (SBC). This topic is not
covered in this guide, but deploying a Wishbone bus enabled
LM32 processor may be an appropriated choice when working in the OHR
environment. You can find more info about this IP-core and its companion
Wishbone peripherals in the @i{Platform Independent Core Collection} project
on the Open Hardware Repository
@url{http://www.ohwr.org/projects/general-cores/wiki}
@url{http://www.ohwr.org/projects/general-cores/wiki}.
In order to program and debug the SPEC board when operating in stand-alone
mode, the recommended third-party tool is Xilinx's @i{Platform Cable USB}
@url{http://www.xilinx.com/products/boards-and-kits/HW-USB-II-G.htm}
@url{http://www.xilinx.com/products/boards-and-kits/HW-USB-II-G.htm}.
@center @image{pictures/xilinx_platform_cable_usb_ii, 10cm}
@center @i{Xilinx Platform Cable USB II}
......@@ -434,12 +426,16 @@ standard port with x4 lane width or greater (x4, x8, x16 or x32). If the slot
lane width is greater than x4, the Gennum GN4124 and the PC host will
automatically negotiate the highest mutually supported lane count, i.e. x4.
Note that multiple SPEC boards can be attached to a single Host if this sports
multiple x4 compatible PCIe slots. In this getting started guide, only one
available PCIe port will be required as only one SPEC board is used in the
It's important to highlight in this point that the SPEC board does not fit in
a PCIe x1 slot. Because this kind of ports are widely used in x86 embedded
mother boards, you should be cautious when selecting a new one that claims
to be PCIe enabled if you are planning to use it with the SPEC.
Note that multiple SPEC boards can be attached to a single Host if multiple x4 compatible PCIe slots are available. In this getting started guide, only
one free PCIe port will be required as only one SPEC board is used in the
demonstration.
In the next picture, a SPEC board mounting a fmc-dio-5chttla module is
In the following picture, a SPEC board mounting an fmc-dio-5chttla module is
shown while attached to a standard desktop PC PCIe slot. This is
the full hardware setup required to go through all the getting started guide.
......@@ -452,8 +448,8 @@ the full hardware setup required to go through all the getting started guide.
@node Designing your own SPEC Gateware
@chapter Designing your own SPEC Gateware
In this chapter, we will cover the topic of building some simple gateware
examples to be loaded on the SPEC's Spartan-6 FPGA. In order to do that,
In this chapter we will cover the topic of building some simple gateware
examples to be loaded on the SPEC's Spartan-6 FPGA. In order to do that
we will learn how to design and synthesize a simple Wishbone based embedded
system by using standard and custom HDL cores and specific tools hosted in the
@i{Open Hardware Repository}.
......@@ -463,9 +459,9 @@ system by using standard and custom HDL cores and specific tools hosted in the
@node The Wishbone Bus and the OHR Core libraries
@section The Wishbone Bus and the OHR Core libraries
The @b{Wishbone Bus} is an open source hardware computer bus intended to let
The Wishbone Bus is an open source hardware computer bus intended to let
the parts of an integrated circuit communicate with each other. The aim is to
allow the connection of differing cores to each other inside of a chip/FPGA.
allow the connection of different cores to each other inside of a chip/FPGA.
Initially designed for being used as the standard bus in the OpenCores project,
the @b{Wishbone Bus} is the mainstream bus used in most of the Open Hardware
......@@ -473,28 +469,27 @@ Repository projects too. In this way, Wishbone provides a standard way for
designers to combine already available generic hardware logic designs
(called "cores") with custom ones designed for application specific purposes.
While Wishbone is defined to have 8, 16, 32, and 64-bit buses, the most of
While Wishbone is defined to have 8, 16, 32, and 64-bit buses, most of
the cores used in the Open Hardware Repository projects use a 32-bit bus.
This is because the reference processor used in OHR flagship projects is the
LM32 (LatticeMico32), an Open Source 32-bit RISC processor that has been
designed for efficient FPGA implementation.
For an in-depth description of the Wishbone bus internals, you can get the
full Wishbone specification by following the next links:
full Wishbone specification by following the following link:
@itemize @bullet
@item @b{Version B3:} @url{http://cdn.opencores.org/downloads/wbspec_b3.pdf}.
@item @b{Version B4:} @url{http://cdn.opencores.org/downloads/wbspec_b4.pdf}.
@end itemize
@sp 1
In the demos covered by this tutorials, different already available cores from
In the demos covered by this tutorial, different cores from
the Open Hardware Repository are used for building the HDL embedded system
examples. In order to fetch the code of this required core libraries, the
examples. In order to fetch the code of these required core libraries, the
@code{git submodule} mechanism is used.
In order to do that, once the @code{spec-getting-started} repository has been
cloned, we must jump to the main folder inside a shell and execute the next
git command sequence:
cloned, we must jump to the main folder inside a shell and execute the
following git command sequence:
@example
user$ cd spec-getting-started
......@@ -504,7 +499,7 @@ user$ git submodule update
Once the @code{update} command has finished, two new folders are created in
@code{hdl/ip_cores} directory. These are @code{general-cores} and
@code{gn4124-core}, and their contents are described in the next sections.
@code{gn4124-core}, and their contents are described in the coming sections.
@sp 1
@c --------------------------------------------------------------------------
......@@ -519,6 +514,10 @@ For this purpose, the @i{gn4124-core} project is included in the
@i{Open Hardware repository}. This project aims to provide a Wishbone master
generic interface for FMC projects controlled by a PCI express access.
@center @image{pictures/GN4124core_arch, 16cm}
@center @i{Overview of the GN4124 Core architecture}
@sp 1
The @i{gn4124-core} is used in the @i{Getting Started with the SPEC} demos
in order to communicate from the Host PC to the SPEC board. This is the case
too for all the projects included in the OHR that make use of the Gennum
......@@ -532,7 +531,7 @@ its official OHR project site:
@sp 1
The @code{git} repository in which the stable code is hosted, can be accessed
by using the next Git Read-Only URL:
by using the following Git Read-Only URL:
@itemize @bullet
@item @url{git://ohwr.org/hdl-core-lib/gn4124-core.git}
@end itemize
......@@ -561,19 +560,19 @@ The library comprises 3 different packages:
@sp 1
In the @i{Getting Started with the SPEC} project demos, both
@code{gencores_pkg} and @code{wishbone_pkg}, the first for getting some
simple standard HDL building blocks and the later for a cleaner Wishbone bus
signals handling.
@code{gencores_pkg} and @code{wishbone_pkg} libraries are needed, the first
for getting some simple standard HDL building blocks and the latter for
cleaner Wishbone bus signals handling.
The official project site for @i{general-cores} can be found in the
next OHR link:
The official project site for @i{general-cores} can be found at the
OHR link:
@itemize @bullet
@item @url{www.ohwr.org/projects/general-cores/wiki}
@end itemize
@sp 1
The @code{git} repository in which the stable code is hosted, can be accessed
by using the next Git Read-Only URL:
by using the following Git Read-Only URL:
@itemize @bullet
@item @url{git://ohwr.org/hdl-core-lib/general-cores.git}
@end itemize
......@@ -585,12 +584,12 @@ by using the next Git Read-Only URL:
@section Building a simple Wishbone Slave
After reviewing the different HDL core libraries from OHR that are used in the
@i{Getting Started with the SPEC} gateware demos, we must face the issue of
@i{Getting Started with the SPEC} gateware demos, we will be
building a new Wishbone compatible custom core from the ground up. While
designing an application specific HDL core is a task that worths the design
effort (e.g. when a new FMC module is going to be handled), linking this core
by hand to the Wishbone bus supposes a non-recurring engineering cost that
should be avoided.
designing an application specific HDL core is a task that implies an
inevitable design effort (e.g. when a new FMC module is going to be handled),
linking this core by hand to the Wishbone bus supposes an engineering cost
that should be avoided.
@sp 1
......@@ -615,7 +614,7 @@ As a result, we get:
@item Automatic address space layout generation
@item Generation of C header files containing memory map consistent with the
HDL core
@item Support for popular synthesizable VHDL data types
@item Support for popular synthesizable data types
@end itemize
@sp 1
......@@ -636,7 +635,7 @@ official OHR project site:
@code{wbgen2} is actively used accross the OHR repository, and this is the
case for the custom demo cores in the Getting Started with the SPEC examples.
In the next sections, the Wishbone generator descriptions for the different
In the coming sections, the Wishbone generator descriptions for the different
demo slave cores will be introduced, but we must learn how to install this
tool as a previous step.
@sp 1
......@@ -654,14 +653,14 @@ First of all, we need to install the @code{wbgen2} dependencies. This tool
is written in @i{lua} language, so we need to install the appropriated
software packages for our Linux distribution.
In the current Ubuntu Linux and other Debian derivatives, this can be made
by issuing the next apt command in a shell:
In Ubuntu Linux and other Debian derivatives, this can be made
by issuing the following apt command in a shell:
@example
user$ sudo apt-get install lua5.1
@end example
In Red Hat Enterprise Linux derivatives, such as Scientific Linux,
this can be made by issuing the next yum command in a shell:
this can be made by issuing the following yum command in a shell:
@example
root$ yum install lua
@end example
......@@ -676,10 +675,9 @@ user$ make
@end example
After building the tool, the @code{wbgen2} binary is available inside the
@code{wishbone-gen} folder. Next step is including it inside the user
shell path. For this purpose, and being the tag @i{<wishbone-gen dir>} the
absolute path to the @code{wishbone-gen} folder, we will need to export
the directory with the next command:
@code{wishbone-gen} folder. The next step is including it inside the user
shell path. For this purpose, we will need to export
the @code{wishbone-gen} directory with the following command:
@example
user$ export PATH=$PATH:<wishbone-gen dir>
@end example
......@@ -704,10 +702,11 @@ includes two different examples:
@end itemize
In this way, the @i{Getting Started with the SPEC} allows both the use of a
standalone SPEC board and the handling of the Digital I/O FMC when available.
PCIe attached SPEC board with or without an available Digital I/O FMC module.
@sp 1
The directory layout for the provided HDL code is shown in the next scheme:
The directory layout for the provided HDL code is shown in the following
scheme:
@itemize @minus
@item @code{spec-getting-started/}.
@itemize @minus
......@@ -796,6 +795,10 @@ By using this HDL design, we can control the Green/Red LEDs in the SPEC front
panel, read the SPEC PCB version or access to the internal pushbuttons and
LEDs.
@center @image{pictures/demo_user, 14cm}
@center @i{Block diagram for the SPEC Demo User gateware}
@sp 1
In order to do this, the Demo User includes the @code{spec_user_interface}
custom core, that has been implemented by using the
@i{Wishbone Slave Generator} tool. The most important files that can be found
......@@ -841,7 +844,7 @@ Control register
@item @code{0x4} @tab
REG @tab
@code{aux} @tab
Auxiliar interface
Auxiliary interface
@end multitable
@sp 1
@b{@code{ctrl} - Control register}
......@@ -875,9 +878,9 @@ front panel
panel
@end multitable
@sp 1
@b{@code{aux} - Auxiliar interface}
@b{@code{aux} - Auxiliary interface}
A register mapping the SPEC internal auxiliar interface
A register mapping the SPEC internal auxiliary interface
@multitable @columnfractions .10 .10 .15 .10 .55
@headitem Bits @tab Access @tab Prefix @tab Default @tab Name
@item @code{0}
......@@ -900,7 +903,7 @@ User Leds
@headitem Field @tab Description
@item @code{button1} @tab Status bit for the internal push-button 1
@item @code{button2} @tab Status bit for the internal push-button 2
@item @code{leds} @tab Control field for the 4 internal auxiliar LEDs
@item @code{leds} @tab Control field for the 4 internal auxiliary LEDs
@end multitable
@sp 1
......@@ -917,6 +920,10 @@ By accessing to these registers, we can configure the DIO pin direction,
read/write each pin value or configure the termination resistor. In addition,
the Top/Bottom LEDs in the FMC DIO front panel can be controlled too.
@center @image{pictures/demo_user_dio, 14cm}
@center @i{Block diagram for the SPEC Demo User + DIO gateware}
@sp 1
In order to do this, the Demo User + DIO adds to the previous demo Wishbone bus
a new @code{fmc_dio_ch5_ttl} custom core that has been implemented by using
the @i{Wishbone Slave Generator} tool. The most important files that can be
......@@ -945,8 +952,8 @@ found inside this module directory are:
@item fmc_dio_ch5_ttl.vhd
A VHDL interface that connects the Wishbone slave registers to the
FPGA pinout. This code includes the Wishbone slave as a component
A VHDL code that connects the Wishbone slave registers to the
FPGA. This code includes the Wishbone slave as a component
and is the file that is actually instantiated from the top level
design VHDL description.
......@@ -1135,7 +1142,7 @@ Windows.
In this way, before building our gateware desigs, we need to download and
install the @i{ISE WebPACK Design Software for Linux}, that can be found in
the next link:
the following link:
@url{www.xilinx.com/products/design-tools/ise-design-suite/ise-webpack.htm}.
The install binary for Linux supports both 32 and 64 bits Operating Systems,
......@@ -1146,7 +1153,7 @@ such as Scientific Linux.
Note that, once the ISE software has been installed, pointing to a valid
WebPACK license file is mandatory before running any of the Xilinx tools.
You can request a WebPACK license by using a valid Xilinx registration
account in the next link: @url{http://www.xilinx.com/getlicense}
account in the following link: @url{http://www.xilinx.com/getlicense}
@sp 1
......@@ -1177,8 +1184,8 @@ our user home directory.
@sp 1
@c --------------------------------------------------------------------------
@node Automated synthesis with HDLMake
@subsection Automated synthesis with HDLMake
@node Automated synthesis with Hdlmake
@subsection Automated synthesis with Hdlmake
Despite the fact that Xilinx ISE includes very powerful graphic user interface
tools, sometimes we feel that working with HDL code just in the way we do
......@@ -1198,7 +1205,7 @@ project site hosted on the @i{Open Hardware Repository}.
@end itemize
@sp 1
@b{NOTE}: Current Hdlmake version is under heavy development. For this reason,
@b{Note:} Current Hdlmake version is under heavy development. For this reason,
we will use an older but stable Hdlmake release for synthesizing our demos.
@sp 1
......@@ -1218,10 +1225,9 @@ user$ make
@end example
After building, the @code{hdlmake} Python app is available inside the
@code{hdl-make} folder. Next step is including it inside the user
shell path. For this purpose, and being the tag @i{<hdl-make dir>} the
absolute path to the @code{hdl-make} folder, we will need to export
the directory with the next command:
@code{hdl-make} folder. The next step is including it inside the user
shell path. For this purpose, we will need to export
the @code{hdl-make} directory with the following command:
@example
user$ export PATH=$PATH:<hdl-make dir>
@end example
......@@ -1368,7 +1374,7 @@ Each one of the PCI devices listed, can be pointed in the PCI system by the
@i{devfn}=0x00.
@sp 1
The only way of checking if a PCI device at the @i{Sysfs} PCI system is a
A simple way of checking if a PCI device at the @i{Sysfs} PCI system is a
SPEC board, is checking the content of its associated @file{device} and
@file{vendor} files. If these values match with the known identifiers for
the SPEC board, then we know that the PCI device is actually a SPEC board.
......@@ -1442,12 +1448,12 @@ From the user-space point of view, the most important files in the exported
In this way, by memory mapping this files in any programming language,
e.g. C, Python, we can control any SPEC board functionality by performing
low level acesses to the different mapped registers. In the next sections,
low level acesses to the different mapped registers. In the coming sections,
we will introduce how we can use the @i{spec-sw} user-space code for a
higher level operation.
@sp 1
@b{NOTE:} by default, the access to the @i{Sysfs} devices, including
@b{Note}: By default, the access to the @i{Sysfs} devices, including
@file{resource0} and @file{resource4} files, requires super user privileges.
@sp 1
......@@ -1460,7 +1466,7 @@ repository, but then we only need to build the user-space code placed in the
@file{spec-sw/tools} folder.
@sp 1
@b{NOTE}: As part of the @i{Getting Started with the SPEC} development, the
@b{Note}: As part of the @i{Getting Started with the SPEC} development, the
@i{spec-sw} code has been upgraded in order to support a fully kernel
independent operation. In addition, the building process has been modified
in order to generate a @file{libspec.so} shared object library from the
......@@ -1494,7 +1500,7 @@ root# ./specmem 0x04 0xff
@sp 1
If we want to add the @file{spec-sw/tools} folder to the execution path,
we must issue the next command, considering that the tag
we must issue the following command, considering that
@i{<spec-sw/tools dir>} is the absolute path to this folder.
@example
user$ export PATH=$PATH:<spec-sw/tools dir>
......@@ -1506,9 +1512,10 @@ we must append the export command to the end of the @file{.bashrc} file in the
user folder and, if desired, to the root one.
@sp 1
@b{Note}: in some Linux distributions, in order to make the extended user path
available when using a sudo command, we need to edit the @file{/etc/sudoers}
file by using @file{visudo} and comment out the next line if present:
@b{Note}: some Linux distributions, in order to make the extended user path
available when using a sudo command, need the edition of the
@file{/etc/sudoers} file by using @file{visudo} for commenting out
the following line if present:
@example
Defaults secure_path="..."
@end example
......@@ -1589,7 +1596,8 @@ includes a collection of @i{Python classes} that can be used to create SPEC
objects in which different high level methods has been defined.
@sp 1
The directory layout for the provided Python code is shown in the next scheme:
The directory layout for the provided Python code is shown in the following
scheme:
@itemize @minus
@item @code{spec-getting-started/}.
@itemize @minus
......@@ -1606,7 +1614,7 @@ The directory layout for the provided Python code is shown in the next scheme:
@end itemize
@sp 1
The specific role for each of these Python files is the next.
Now, the specific role for each of these Python files will be introduced:
@table @file
@item spec_libc.py
......@@ -1662,8 +1670,8 @@ user$ sudo cp spec-sw/tools/libspec.so /usr/lib/
@end example
@sp 1
@b{Note}: in the next demos, we will assume that a valid @file{libspec.so}
library is placed into the @file{/usr/lib/} folder.
@b{Note}: when introducing the following demos, we will assume that a valid
@file{libspec.so} library is placed into the @file{/usr/lib/} folder.
@sp 1
......@@ -1681,7 +1689,7 @@ front panel and finally destroy the Spec() object.
Note that we have included a @code{help(spec)} in our example. By doing this,
we get printed in the Python shell the help for all the methods included on
Spec() class (push 'q' for exit).
Spec() class ('q' for exit).
@sp 1
@example
......@@ -1766,7 +1774,7 @@ Note that we have included a @code{help(spec)} in our example. By doing this,
we get printed in the Python shell the help for all the methods included on
the SpecDemoUser() class and those inherited from the Spec() class. In this
section, we have only included the SpecDemoUser() specific help.
(push 'q' for exit).
('q' for exit).
@sp 1
@example
......@@ -1818,16 +1826,16 @@ class SpecDemoUser(spec_libc.Spec)
| Clear to OFF the SPEC Front Panel Red LED.
|
| specGetAuxLEDs(self, hexformat=True)
| Return the hex value corresponding to the four auxiliar LEDs.
| Return the hex value corresponding to the four auxiliary LEDs.
| If hexformat=True, the returned value is a string in hex format.
| Note that the Auxiliar LEDs are active low.
| Note that the auxiliary LEDs are active low.
|
| specGetButton1(self)
| Test the state of the internal auxiliar Button1.
| Test the state of the internal auxiliary Button1.
| Return 0 when pressed and nonzero when released.
|
| specGetButton2(self)
| Test the state of the internal auxiliar Button2.
| Test the state of the internal auxiliary Button2.
| Return 0 when pressed and nonzero when released.
|
| specGetGreenLED(self)
......@@ -1842,8 +1850,8 @@ class SpecDemoUser(spec_libc.Spec)
| returns a nonzero result if the LED is ON, 0 if the LED is OFF.
|
| specSetAuxLEDs(self, value)
| Set the hex value corresponding to the four auxiliar LEDs.
| Note that the Auxiliar LEDs are active low.
| Set the hex value corresponding to the four auxiliary LEDs.
| Note that the auxiliary LEDs are active low.
|
| specSetGreenLED(self)
| Set to ON the SPEC Front Panel Green LED.
......@@ -1871,7 +1879,7 @@ Note that we have included a @code{help(spec)} in our example. By doing this,
we get printed in the Python shell the help for all the methods included on
the SpecDemoUserDIO() class and those inherited from the Spec() and the
SpecDemoUser() classes. In this section, we have only included the
SpecDemoUseDIOr() specific help. (push 'q' for exit).
SpecDemoUserDIO() specific help. ('q' for exit).
@sp 1
@example
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment