Subversion Repositories phr

%$Id: schedule.tex 228 2014-04-14 16:21:29Z guanucoluis $
\documentclass[11pt,a4paper,oneside]{article}
\usepackage[utf8]{inputenc}
\usepackage[spanish]{babel}
\usepackage{acronym}
\usepackage{graphicx}
\usepackage{multicol}
\usepackage{balance}
%\usepackage{subfig}
%\usepackage[cm]{fullpage}
\usepackage[a4paper]{geometry}
%\usepackage{subfigure}
\usepackage{float}
\usepackage{fancyhdr}
\usepackage{caption}
\usepackage{subcaption}
\usepackage{amssymb}
\usepackage{fancyvrb}
\usepackage{listings}
\usepackage{xcolor}
 
\definecolor{light-gray}{gray}{0.9}
 
\lstset{
  basicstyle=\ttfamily\footnotesize,%\scriptsize,
  backgroundcolor=\color{light-gray},
  language=bash,
  keywordstyle=\bfseries,
  breaklines=true,
  keywords=[2]{INT8U,INT16U,DIO\_DI,DIO\_DO,CPU\_INT16S,CPU\_INT08U}
}
 
\lstset{literate=
  {á}{{\'a}}1 {é}{{\'e}}1 {í}{{\'i}}1 {ó}{{\'o}}1 {ú}{{\'u}}1
  {Á}{{\'A}}1 {É}{{\'E}}1 {Í}{{\'I}}1 {Ó}{{\'O}}1 {Ú}{{\'U}}1
  {à}{{\`a}}1 {è}{{\'e}}1 {ì}{{\`i}}1 {ò}{{\`o}}1 {ù}{{\`u}}1
  {À}{{\`A}}1 {È}{{\'E}}1 {Ì}{{\`I}}1 {Ò}{{\`O}}1 {Ù}{{\`U}}1
  {ä}{{\"a}}1 {ë}{{\"e}}1 {ï}{{\"i}}1 {ö}{{\"o}}1 {ü}{{\"u}}1
  {Ä}{{\"A}}1 {Ë}{{\"E}}1 {Ï}{{\"I}}1 {Ö}{{\"O}}1 {Ü}{{\"U}}1
  {â}{{\^a}}1 {ê}{{\^e}}1 {î}{{\^i}}1 {ô}{{\^o}}1 {û}{{\^u}}1
  {Â}{{\^A}}1 {Ê}{{\^E}}1 {Î}{{\^I}}1 {Ô}{{\^O}}1 {Û}{{\^U}}1
  {œ}{{\oe}}1 {Œ}{{\OE}}1 {æ}{{\ae}}1 {Æ}{{\AE}}1 {ß}{{\ss}}1
  {ç}{{\c c}}1 {Ç}{{\c C}}1 {ø}{{\o}}1 {å}{{\r a}}1 {Å}{{\r A}}1
  {€}{{\EUR}}1 {£}{{\pounds}}1 {"}{{``}}1 {~}{{$\sim$}}1
}
 
\renewcommand{\lstlistingname}{Código}
 
\title{Plataforma de hardware reconfigurable \\ \small{JTAG -- Configuración OOCD-Links, (\textsl{Hardware \& Software})}}
\author{Luis A. Guanuco}
\date{Marzo 2013\\\scriptsize{$Rev: 231 $}}
\pagestyle{fancy}
\addtolength{\textheight}{2cm}
%\addtolength{\voffset}{-1cm}
%\addtolength{\textwidth}{1cm}
 
\begin{document}
 
\maketitle{}
 
%\chead{\includegraphics[width=0.1\textwidth]{images/logov2_ES}}
\begin{figure}[h]
  \centering
  \includegraphics[width=0.3\textwidth]{images/logov2_ES}
\end{figure}
 
\tableofcontents{}
 
\section{Introducción}
\label{sec:intro}
 
El presente reporte desarrolla la continuación del armado, testeo de las distintas placas que conformarán la \emph{\ac{PHR}}. Además, gran parte del informe se basa en el \textsl{software} que permitirá la comunicación entre la PC y el programador \ac{jtag}.
 
\section{\textsl{Software} \ac{openocd}}
\label{sec:soft-openocd}
Los \textsl{scripts} utilizados se obtuvieron del manual de usuario del \textsl{software} \ac{openocd} que se encuentra publicado en la web\footnote{http://openocd.sourceforge.net/doc/html/index.html}.
Anteriormente al uso de \ac{openocd} se intentó utilizar el \textsl{software} UrJTAG\footnote{http://urjtag.org/} pero debido a la limitaciones que presentaba la versión estable se lo descartó.
 
La instalación y puesta en funcionamiento del \textsl{software} \ac{openocd} se realiza en tres etapas:
\begin{itemize}
\item Instalación del \textsl{software} \ac{openocd}
\item \textsl{Interface}
\end{itemize}
 
\subsection{Instalación del \textsl{software} \ac{openocd}}
\label{sec:instal-openocd}
Se recomienda descargar la última versión estable de \ac{openocd} y compilarlo manualmente con los correspondientes argumentos necesarios para el \textsl{driver} a utilizar. En nuestro caso utilizaremos el \textsl{driver} libftdi\footnote{http://www.intra2net.com/en/developer/libftdi/}. Además en la documentación oficial de \ac{openocd} se hace referencia a los requerimientos para cada \ac{SO}. Como ya se mencionó en anteriormente reportes, se utilizará herramientas libres, por lo que se realizará la instalación en un \ac{SO} GNU/Linux Debian ``Squeeze'' 6.0. Como así también los drivers para el \textsl{hardware} están licenciados como \ac{GPL}.
Un documento de referencia muy útil es la Nota Técnica \emph{Entorno de desarrollo de \textsl{firmware} sobre arquitecturas ARM Cortex-M3, basado en herramientas libres}\cite{2012-SSE-FIUBA-NT01-00}.
 
\subsection{\textsl{Interface}}
\textsl{Interface} hace referencia al \textsl{hardware} que realiza el enlace entre el puerto \ac{jtag} del dispositivo al que se quiere acceder y la PC. En éste caso el \textsl{interface} será nuestra placa OOCD-Links. \ac{openocd} dispone de \textsl{scripts} para varios \textsl{interface} entre los cuales se encuentra nuestra placa programadora. La información que proporciona éste código hace a que tipo de driver se utilizará como así también identificación del dispositivo central. A continuación se puede ver la estructura del archivo \texttt{oocdlink.cfg}.
 
\begin{lstlisting}
#
# Joern Kaipf's OOCDLink
#
# http://www.joernonline.de/contrexx2/cms/index.php?page=126
#
 
interface ft2232
ft2232_device_desc "OOCDLink"
ft2232_layout oocdlink
ft2232_vid_pid 0x0403 0xbaf8
jtag_khz 5
\end{lstlisting}
 
Para obtener el VIP (vendor ID) y el PID (product ID) se lo puede obtener una vez conectada el \textsl{interface} a la PC y listando los dispositivos conectados al puerto USB, por ejemplo,
 
\begin{lstlisting}
luis@luis-laptop:openocd$ lsusb
Bus 008 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 002: ID 0403:6010 Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 0bda:0158 Realtek Semiconductor Corp. USB 2.0 multicard reader
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
\end{lstlisting}
 
En la salida del \texttt{lsusb} se puede ver que tenemos el dispositivo \emph{0403:6001 Future Technology Device International}. Luego utilizamos éste dato para modificar o crear nuestro archivo \texttt{openocd.cfg} que será argumento de \ac{openocd}.
 
\subsection{Documentación de comandos y \textsl{scripts}}
Una vez que se logra comunicar el \textsl{interface} \ac{jtag} con el  \textsl{software} \ac{openocd}, se crean los archivos necesarios para acceder a los dispositivos que se encuentren conectados en el protocolo \ac{jtag}.
Para correr \ac{openocd} correctamente se necesita pasarle algunos simples argumentos,
\begin{lstlisting}
luis@luis-laptop:trunk$ openocd -h
Open On-Chip Debugger 0.6.1 (2012-12-08-02:21)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.sourceforge.net/doc/doxygen/bugs.html
Open On-Chip Debugger
Licensed under GNU GPL v2
--help       | -h	display this help
--version    | -v	display OpenOCD version
--file       | -f	use configuration file <name>
--search     | -s	dir to search for config files and scripts
--debug      | -d	set debug level <0-3>
--log_output | -l	redirect log output to file <name>
--command    | -c	run <command>
\end{lstlisting}
 
Los más importantes de éstos son \texttt{--file}, que permite definir que archivo de configuración \ac{openocd} utilizará. Dentro de éste archivo se podría agregar cualquiera de los otros comandos.
Es recomendable que la estructura de archivos sea la siguiente,
\begin{itemize}
\item Directorio raíz de trabajo (por ej.: \texttt{openocd\_dir})
  \begin{itemize}
  \item [$\rightarrow$] \texttt{core.cfg}, contiene los comandos básicos para que \ac{openocd} reconozca el \textsl{interface}
  \item [$\rightarrow$] \texttt{openocd.cfg}, contiene los comandos que configura el acceso al protocolo \ac{jtag}
  \item [$\rightarrow$] \texttt{device.cfg}, contiene los comandos propios de los dispositivos a conectar en la cadena \ac{jtag}, por ejemplo ID, cantidad de bits de los registros, etc.
  \item [$\rightarrow$] \texttt{files/...}, también se debe conciderar tener un subdirectorio en el cual almacenar archivos que se transerirán a los dispositivos mediante \ac{jtag}, por ejemplo: archivos .svf, archivos .elf, etc.
  \end{itemize}
\end{itemize}
 
A continuación se describen comandos útiles que se pueden aplicar en forma general a cualquier dispositivo a conectar.
 
\subsection{Agregar un \ac{TAP}}
Para acceder a un dispositivo mediante el protocolo \ac{jtag}, se debe proporcionar especificaciones del mismo. Muchas veces ésta información no se encuentra fácil de acceder en la hoja de datos de los dispositivos conectados al \textsl{interface}. Para situaciones como la descrita, \ac{openocd} dispone de un modo llamado \textsl{Autoprobing}\cite{openocd-manual-autoprobing}.
 
En definitiva, para capturar la información del dispositivo conectado se debe generar una archivo base \texttt{openocd.cfg} como el que se muestra a continuación,
\begin{lstlisting}
# OpenOCD configuration script  
# 2013-03-25 lguanuco
# Hardware:
# - OOCD-Link-s 
 
# ("3": max. verbosity level)
debug_level 3
# (set log file)
log_output out.log
 
source [find core.cfg]
 
# 3. Other configs
 
reset_config trst_and_srst
jtag_rclk 8
\end{lstlisting}
Luego de correr \ac{openocd}, se debe acceder al archivo de salida con el nombre que se asignó en el archivo \texttt{openocd.cfg}, \texttt{out.log}. Este archivo registra todos los mensajes de salida que genera \ac{openocd}, a continuación se muestra parte de éste archivo donde se puede observar información útil para generar el \ac{TAP} de dicho dispositivo.
\begin{lstlisting}
...
Debug: 129 273 core.c:323 jtag_call_event_callbacks(): jtag event: TAP reset
Warn : 130 359 core.c:1145 jtag_examine_chain(): AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x4f1f0f0f ..."
Debug: 131 359 core.c:1323 jtag_tap_init(): Created Tap: auto0.tap @ abs position 0, irlen 0, capture: 0x1 mask: 0x3
Debug: 132 359 core.c:1208 jtag_validate_ircapture(): IR capture validation scan
Warn : 133 369 core.c:1244 jtag_validate_ircapture(): AUTO auto0.tap - use "... -irlen 4"
Debug: 134 369 core.c:1267 jtag_validate_ircapture(): auto0.tap: IR capture 0x01
Debug: 135 369 openocd.c:145 handle_init_command(): Examining targets...
...
\end{lstlisting}
 
Una vez obtenida éstas lineas se puede rescatar los datos más importantes que son,
\begin{itemize}
\item \emph{id}
\item \emph{irlen}
\item \emph{capture} 
\item \emph{mask} 
\end{itemize}
 
Por lo tanto, con estos datos se puede generar nuestro propio \textsl{script} en el cual agregar manualmente el \ac{TAP}, por ejemplo \texttt{lpc2124.cfg}
\begin{lstlisting}
jtag newtap arm_lpc2124 tap -irlen 4 -ircapture 0x01 -irmask 0x3 -expected-id 0x4f1f0f0f
\end{lstlisting}
 
\subsection{Multiples \ac{TAP}}
Muchas plataformas o kits de desarrollo tienen multiples TAPs. Por ejemplo, en nuestro caso tenemos conectados dos dispositivos a la cadena \ac{jtag} que son la \ac{FPGA} y la memoria \ac{PROM} de programación del mismo. Si la conexión es tal que,
 
\begin{itemize}
\item OpenOCD TDI(output) $\rightarrow$ XC3S50A pin TDI(BS input).
\item XC3S50A pin TDO(BS input) $\rightarrow$ XCF01S pin TDI.
\item XCF01S pin TDO(BS output) $\rightarrow$ OpenOCD TDO(input).
\end{itemize}
 
Los comandos para agregar éstos TAPs deberán respetar él orden con el que fueron conectados físicamente,
\begin{lstlisting}
...
jtag newtap xcf01s tap -irlen ...
jtag newtap xc3s50a tap -irlen ...
...
\end{lstlisting}
 
Es decir, se agrega los TAPs recorriendo la cadena JTAG desde el pin TDO al pin TDI desde el interface, aquí sería desde la placa OOCDLink.
 
\subsection{Programación del \ac{CPLD}}
Para los \ac{CPLD}, primero se debe tener el archivo \ac{SVF}, que es generado por la herramienta con la que se diseña y sintetiza el código VHDL o Verilog. En éste caso se utiliza el \textsl{software} ISE Xilinx. Una vez que se tiene el archivo \ac{SVF}, desde \ac{openocd}, se corre el siguiente comando;
\begin{lstlisting}
svf -tap tap_name file.svf quiet
\end{lstlisting}
Lo que generaría una salida como la que sigue,
\begin{lstlisting}
svf processing file: ``file.svf'' 
500 kHz 
...
...
Time used: 0m7s478ms 
svf file programmed successfully for 8468 commands
\end{lstlisting}
 
En el caso de que se tenga problemas en la transferencia del archivo, se podría probar bajando la frecuencia de la comunicación \ac{jtag}.
 
Algo interesante se puede observar en el archivo \texttt{file.svf}, pues en una de sus lineas tiene el IDCODE del dispositivo al que se va a transferir, que debería coincidir con el que se le pasa cuando se agrega el \ac{TAP} al código de \ac{openocd}. O quizá diferenciarse con el valor hexadecimal más significativo, que indica la versión del dispositivo.
\begin{lstlisting}
...
//Loading device with 'idcode' instruction.
SIR 8 TDI (fe) SMASK (ff) ;
SDR 32 TDI (00000000) SMASK (ffffffff) TDO (f9604093) MASK (0fffffff) ;
//Check for Read/Write Protect.
SIR 8 TDI (ff) TDO (01) MASK (e3) ;
//Boundary Scan Chain Contents
//Position 1: xc9572xl
...
\end{lstlisting}
 
La placa OOCD-Links cuenta con un dispositivo central, FT2232D. Éste dispositivo posee dos alimentaciones, por una parte la alimentación de núcleo del circuito integrado y por otro lado la alimentación de los interfaces de salida. La primera alimentación es tomada desde el puerto USB al que se encuentra conectado, mientas que la alimentación de sus puertos de conexión lo toma del conector \ac{jtag}, del \emph{Pin 1}. De tal manera que la tensión de los puertos de conexión \ac{jtag} del \textsl{interface} siempre tiene la misma tensión que maneja las señales \ac{jtag} de la placa conectada. Es decir, si se hace una conexión entre la placa OOCD-Links y una placa con un CPLD XC9572XL, ambas tendrán la misma tensión en sus puertos \ac{jtag}, en éste caso 3.3V. 
 
Un inconveniente podría ser el consumo de corriente, pues el regulador de la placa OT-CPLD se tendría que proporcionar energía a la placa OOCD-Links, pero como es en el proceso de programación y como proceso de testeo, no debería haber inconvenientes. Igualmente se debe tener en cuenta.
 
Se encontró en la nota de aplicación de Xilinx [\emph{ug445.pdf}] que para los pines TDI y TMS de los CPLD XC9572XL, se dispone de resistores \textsl{pull-ups} internos. Por lo que no es necesario colocar resistores externos en el diseño del PCB.
 
\subsection{\textsl{Debugging}}
Para el \textsl{debugging} se utiliza varias herramientas y todas ellas corren sobre terminales \textsl{bash} de nuestro \ac{SO}. Entre éstos \textsl{software}, tenemos
\begin{itemize}
\item \emph{terminator}, múltiples terminales en una sola ventana (escritorio GNOME).
\item \emph{tailf}, sigue la escritura de un archivo( por ej.: archivos de .log).
\item \emph{ccze}, un robusto visor de archivos log con la posibilidad de colorear las líneas.
\item \emph{grep}, imprime las líneas similares a un patrón.
\end{itemize}
 
Todos éstos comandos son utilizados a la vez. La forma de trabajo es correr \emph{terminator} y luego dividir la pantalla en varios terminales al vez, eso será útil para ingresar comandos al puerto telnet 4444 donde se puede acceder al \textsl{interface} \ac{jtag}. Los otros \textsl{software} se utilizar a modo de \textsl{debugger}, pues nos permiten resaltar mensajes que genera \ac{openocd}. Por ejemplo, una forma estándar de ver la salida es,
 
\begin{lstlisting}
luis@luis-laptop:~$ tailf  codigo/jtag/openocd/find_tap/out.log | ccze -A -o scroll 
\end{lstlisting}
 
También se podría utilizar \emph{grep} para filtrar o diferenciar las líenas en función si son \emph{\textsl{Error, Warning, Debug \& User}}. 
 
 
\section{\textsl{Software} \emph{xc3sprog}}
\label{sec:soft-xc3sprog}
 
Si bien el \ac{openocd} se consideró como el \textsl{software} a utilizar, se encontraron algunos inconvenientes a la hora de interactuar con la placa \ac{PHR}. El problema, en principio, se debía a que el \ac{openocd} no puede manejar archivos binarios que pesaran más de 2Mb[REF]. Existe la posibilidad de modificar \ac{openocd} de forma tal que se pueda transferir datos binarios con tamaños superiores a 2Mb pero quizá genere otro tipos de errores como consecuencia. 
 
Frente al inconveniente planteado en el párrafo anterior, se busco herramientas alternativas. Mediante el contacto con otros desarrolladores/usuarios de plataformas basadas en PLDs se encontró el \textsl{software} \emph{xc3sprog}. Este programa permite con unos simples comandos programar varias FPGAs, memorias PROM y hasta microcontroladores mediante el interfaz \ac{jtag}.
 
En una aplicación típica, xc3sprog lee un archivo \texttt{.bit} generado por la herramienta de diseño de la FPGA y programará el chip PROM de la placa que contiene la FPGA. Como su nombre lo indica, xc3sprog fue diseñado originalmente para la familia de FPGA Sparta-3 de Xilinx. Sin embargo se ha extendido el manejo a varios otros tipos de dispositivos que incluyen otras FPGAs, CPLDs, XCF flash PROMs, microprocesadores AVRs de Atmel y memorias flash SPI. El \textsl{software} xc3sprog soporta varios cables JTAG, incluyendo cables de puerto paralelo y programadores USB.
 
 
\subsection{Instalación del \textsl{software} xc3sprog}
\label{sec:install-xc3sprog}
 
Para obtener el xc3sprog, primero se debe descargar el código fuente desde SourceForge\footnote{http://sourceforge.net/projects/xc3sprog/}. El proceso se realizará sobre un terminal del \ac{SO} GNU/Linux que estemos utilizando. 
 
\begin{lstlisting}
luis@luis-laptop:~$ cd ~/
luis@luis-laptop:~$ mkdir sourceforge
luis@luis-laptop:~$ cd sourceforge
luis@luis-laptop:~$ svn co https://xc3sprog.svn.sourceforge.net/svnroot/xc3sprog/trunk xc3sprog
\end{lstlisting}
 
Luego se debe compilare e instalar el programa
 
\begin{lstlisting}
luis@luis-laptop:~$ cd  xc3sprog
luis@luis-laptop:~$ cmake .
luis@luis-laptop:~$ make
luis@luis-laptop:~$ make install
\end{lstlisting}
 
En esta sección no se hace referencia al \textsl{driver} de la placa OOCDLink pues los pasos para la instalación del controlador son los mismos que se describieron en la sección \ref{sec:instal-openocd}. 
 
\subsection{Documentación de comandos y \textsl{scripts}}
 
Al igual que el \textsl{software} \ac{openocd}, xc3sprog recibe varios argumentos en función de como se quiera interactuar con  los dispositivos a programar. Para listar las opciones que se tienen, se debe correo el programa desde el directorio donde se construyó el proyecto, llamado \texttt{build},
 
\begin{lstlisting}
luis@luis-laptop:~$ cd ~/sourceforge/xc3sprog/build
luis@luis-laptop:~$ ./xc3sprog
XC3SPROG (c) 2004-2011 xc3sprog project $Rev: 231 $ OS: Linux
Free software: If you contribute nothing, expect nothing!
Feedback on success/failure/enhancement requests:
	http://sourceforge.net/mail/?group_id=170565 
Check Sourceforge for updates:
	http://sourceforge.net/projects/xc3sprog/develop
 
usage:	xc3sprog -c cable [options] <file0spec> <file1spec> ...
	List of known cables is given with -c follow by no or invalid cablename
	filespec is filename:action:offset:style:length
	action on of 'w|W|v|r|R'
	w: erase whole area, write and verify
	W: Write with auto-sector erase and verify
	v: Verify device against filename
	r: Read from device,write to file, don't overwrite existing file
	R: Read from device and write to file, overwrite existing file
	Default action is 'w'
 
	Default offset is 0
 
	style: One of BIT|BIN|MCS|IHEX|HEX
	BIT: Xilinx .bit format
	BIN: Binary format
	MCS: Intel Hex File, LSB first
	IHEX: INTEL Hex format, MSB first (Use for Xilinx .mcs files!)
	HEX:  Hex dump format
	Default for FPGA|SPI|XCF is BIT
	Default for CPLD is JED
	Default for XMEGA is IHEX
	Default length is whole device
\end{lstlisting}
 
xc3sprog utiliza dos archivos más que ofrecen mayor información y configuración tanto al \textsl{interface} JTAG como también sobre los dispositivos que vayamos a programar. Estos archivos se encuentran en el mismo directorio \texttt{build} donde se compiló el programa, estos son: \texttt{cablelist.txt} y \texttt{devlist.txt}. 
 
\subsubsection{Configuración del \textsl{interface}}
\label{sec:xc3sprog-cablelist}
 
El archivo \texttt{cablelist.txt} contiene, por cada línea, diferentes tipos de configuraciones para \textsl{interface} de programación JTAG. Si bien son varios, a continuación se listan algunos de los más reconocidos en los sistemas embebidos.
\begin{lstlisting}
luis@luis-laptop:build$ cat cablelist.txt
# Alias       Type  OptString Max_Freq
# OptString for ftdi:
# VID:PID:PRODDESC:INTERFACE:DBUS_DATA:DBUS_EN:CBUS_DAT:ACBUS_EN
# OptString for pp: 
# OptString for xps:  VID:PID
# Max_Freq == 0 mean use maximum speed of device
# Use 1500000 for all cable connected cables and max for all on board cables
 
ftdi          ftdi    1500000 0x0403:0x6010:                                    
ftdiphr       ftdi    6000000 0x0403:0x6010:
papilio       ftdi    6000000 0x0403:0x6010: 
ft232h        ftdi    1500000 0x0403:0x6014:                                      
amontec       ftdi    1500000 0x0403:0xcff8::1:0x00:0x10:0x00:0x00                 
olimex        ftdi    1500000 0x15b1:0x0003::1:0x00:0x10:0x00:0x08                 
knob2usb      ftdi    0       0x0403:0x6010:KNOB2USB:0:0x00:0x10:0x00:0x40         
xpc           xpc     0       0x03fd:0x0008                                        
llbbc08       fx2     0       0xfffe:0x0018                                        
pp            pp      0       NULL                                                 
dlc5          pp      0       NULL                                                 
jtaghs1       ftdi    1500000 0x0403:0x6010:Digilent Adept USB Device:0:0x80:0x80:0x00:0x0
turtelizer    ftdi    1500000 0x0403:0xbdc8:Turtelizer JTAG/RS232 Adapter:0:0x00:0x10:0x00:0x0
arm-usb-ocd-h ftdi    1500000 0x15ba:0x002b::1:0x00:0x10:0x00:0x08
\end{lstlisting}
Se puede ver que el formato de este documento consiste en
\begin{itemize}
\item El nombre con que se define el \textsl{inteface}
\item El \textsl{hardware} que se utiliza, es decir, si se utiliza el puerto paralelo, el usb a través de un dispositivo FTDI, etc.
\item La frecuencia en Hertz a la que trabajará el \textsl{interface} JTAG
\item El identificador del \textsl{hardware} según el \ac{SO} GNU/Linux. 
\end{itemize}
Se toma como ejemplo algunas de estas configuraciones que utilice como base el dispositivo FTDI y se agrega una nueva línea con la configuración de nuestra placa OOCDLink. Es la segunda configuración  disponible del archivo \texttt{cablelist.txt}, 
\begin{lstlisting}
  ftdiphr       ftdi    6000000 0x0403:0x6010:
\end{lstlisting}
 
\subsubsection{Dispositivos soportados}
\label{sec:xc3sprog-devlist}
 
El archivo \texttt{devlist.txt} contiene información de los diferentes dispositivos soportados por xc3sprog. Este documento se presente a modo descriptivo pues no tenemos por que modificar ninguna de las líneas de este archivo. El programa xc3sprog utiliza este documento para obtener fundamentalmente el tamaño de algunos registros mediante la identificación del \emph{IDCODE} que proporciona todo los dispositivos JTAG cuando son escaneados. Como se podrá apreciar, se ha evitado incluir todos los dispositivos ya que son varias líneas, por lo que se utilizó los puntos $\cdots$ para acortar el documento. 
 
\begin{lstlisting}
luis@luis-laptop:build$$ cat devlist.txt
# IDCODE IR_len ID_Cmd Text
...
04001093      6    0x9 XC6SLX9
04002093      6    0x9 XC6SLX16
04004093      6    0x9 XC6SLX25  
...
02210093      6    0x9 XC3S50A
02218093      6    0x9 XC3S200A
02220093      6    0x9 XC3S400A
02228093      6    0x9 XC3S700A
02230093      6    0x9 XC3S1400A
...
05044093      8    0xfe XCF01S
05045093      8    0xfe XCF02S
05046093      8    0xfe XCF04S
...
#XC95XL
09602093      8  0xfe XC9536XL
09604093      8  0xfe XC9572XL
09608093      8  0xfe XC95144XL
09616093      8  0xfe XC95288XL
...
#unsupported
#Virtex2
01020093      6     5 XC2V500
#XC95
09502093      8  0xfd XC9536
09504093      8  0xfd XC9572
09506093      8  0xfd XC95108
...
##Atmel
#list should not care for the version part
0978203f      4   0x1 AT90USB
0958103f      4   0x1 AT90CAN32
0968103f      4   0x1 AT90CAN64
0978103f      4   0x1 AT90CAN128
...
#ARM 7 in ICE Mode (e.g. AT91SAM7X)
3f0f0f0f      4   0xe  ARM-ICE-MODE
4f1f0f0f      4   0xe  ARM-ICE-MODE(ARM7TDMI-S rev4)
 
#AVR32
01e8203f     5   0x1 AT32AP7000
 
#STM 
06410041     5   0x1 STM32L1_Med_density
...
#ARM Debug
3BA00477     4   0xe ARM_Cortex-M3_r1p1-01rel0
4BA00477     4   0xe ARM-Cortex-M4F_r0p1
 
#Unsure about IR_Len...
0270817f     11  0x1 BCM2835
 
#Manufacturer list
00000093        99  0 Xilinx_Unknown
0000003f        99  0 Atmel_Unknown
\end{lstlisting}
 
\subsubsection{Comandos básicos}
\label{sec:xc3sprog-com-bas}
 
En el \textsl{usage} del xc3sprog define una estructura básica para correr comandos. El comando se debe correr desde el directorio \texttt{build} donde se ha compilado el programa.
\begin{lstlisting}
  xc3sprog -c cable [options] <file0spec> <file1spec> ...
\end{lstlisting}
En este comando, lo principal es definir que \emph{cable} se utilizará de la lista que tenemos en el archivo \texttt{cablelist.txt}. Para esto, se debe indicar luego del \texttt{-c} el nombre de la lista de \textsl{interfaces}. Una vez definido el cable, se concatenan demás tareas que debe procesar el xc3sprog, pero ya teniendo referencia a que tipo de \textsl{interface} está conectado. Los tareas son,
\begin{description}
\item[\texttt{-j}] Detecta la cadena JTAG e imprime una lista de dispositivos encontrados. La numeración de la posición del dispositivo en la cadena se cuenta desde el dispositivo conectado al pin TDO del \textsl{interface}.
\item[\texttt{-p val}] Define a que dispositivo de la cadena JTAG se está por acceder, donde \texttt{val} es el número que ocupa en la cadena y es visualizado por el comando \texttt{-j}. El valor por defecto de \texttt{val} es 0. 
\item[\texttt{-T n}] Testea la cadena JTAG \texttt{n} veces. Cuando se corre en modo ISF, se testea la conexión SPI.
  \begin{itemize}
  \item Si \texttt{n} no se específica, el valor por defecto es de 10,000 veces.
  \item Si \texttt{n = 0} se mantendrá en un testeo para siempre.
  \end{itemize}
\item[\texttt{-J freq}] Ejecuta a una frecuencia específica el clock del JTAG (\texttt{freq} se encuentra en Hz). Si no se proporciona este dato, o \texttt{freq = 0}, el \textsl{interface} trabajará a la máxima frecuencia que soporte y se encuentre definido en el archivo \texttt{cablelist.txt} (véase \ref{sec:xc3sprog-cablelist}).
\item[\texttt{-e}] Borra el dispositivo seleccionado por el parámetro \texttt{-p}.
\item[\texttt{-I file}] Define si se trabaja en modo ISF para programar una memoria serial \textsl{flash} interna. La memoria \textsl{flash} está junta al dispositivo JTAG primario, pero no es accesible directamente mediante la cadena JTAG. El \textsl{interface} JTAG primario es usado como un \emph{proxy} para enviar datos sobre SPI a la memoria \textsl{flash}. Si se especifica el argumento \texttt{file}, se comenzará por programar el bitfile especificado en el \textsl{interface} JTAG primario (típicamente una FPGA).
\item[\texttt{-R}] Envía un comando de reconfiguración al dispositivo de memoria del \textsl{hardware} utilizado (por ejemplo: XVC, XCF, XCFP para las FPGA o directamente a los dispositivos XC3S, XC6S, XC2V).
\item[\texttt{-m mapdir}] Búsqueda de archivos de mapeo (XC2C) en el directorio especificado por \texttt{mapdir}. Los archivos de mapeo (\textsl{map files}) son requeridos para manejar archivos JEDEC durante la programación de los CPLDs. Si se especifica el directorio, por defecto el valor que se toma es \texttt{\$XC\_MAPDIR}.
\item[\texttt{-d /dev/parportN}] Especifica el puerto paralelo a utilizar. Si no es especificado, por defecto se utiliza el valor \texttt{\$XCPORT} o \texttt{/dev/parport0}.
\item[\texttt{-s serialnum}] Utiliza el puerto USB con \textsl{string} de número de serie específico.
\item[\texttt{-L}] Usa el controlador \emph{libFTD2XX} en luag de \emph{libftdi} para acceder a un \textsl{interface} basados en los dispositivos FTDI.
\item[\texttt{-D}] Genera los archivos \texttt{cablelist.txt} y \texttt{devlist.txt} en el directorio actual. Si ya existiesen, xc3sprog intentará generar los mismos archivos pero agregando al nombre de los archivos un número que incrementará. 
\item[\texttt{-v}] Habilita la salida formal detallada (\textsl{verbose}).
\item[\texttt{-h}] Imprime un texto de ayuda para el programa.
\end{description}
 
Luego de reconocer los diferentes comandos que permiten ejecutarse con xc3sprog, se presenta a continuación algunas acciones posibles que se pueden correr. Cada una de estas acciones está compuesta de un archivo \texttt{filename} seguido opcionalmente por atributos de la forma:
\begin{lstlisting}
<filename:action:offset:style:length>
\end{lstlisting}
\begin{description}
\item[\texttt{filename}] Corresponde al archivo que será escrito por el dispositivo seleccionado, o también puede ser el archivo que almacena el dato para luego ser leído por el dispositivo que se encuentra en la cadena JTAG.
\item[\texttt{action}] Es una letra que indica si se escribe, lee, o verifica el dispositivo. Si es especificado, la acción de escritura es indicado por defecto.
  \begin{description}
  \item[\texttt{w}] Borra, luego escribe los datos desde el archivo al dispositivo y por último verifica.
  \item[\texttt{W}] Escribe con un tipo de borrado \textsl{auto-sector}, luego verifica. Este modo permite borrar solo el espacio necesario.\\
  \item[\texttt{v}] Verifica el dato del dispositivo comparando el un archivo especificado.
  \item[\texttt{r}] Lee los datos desde el dispositivo y los escribe al archivo (sin sobre-escritura).
  \item[\texttt{R}] Lee los datos desde el dispositivo y los escribe al archivo, si ya existe el archivo lo sobreescribe.
  \end{description}
\item[\texttt{offset}] El desplazamiento interno en \textsl{byte} del dispositivo donde la escritura/lectura deberá comenzar. Solo soportado para dispositivos SPI, XCFxxS y XMEGA.
\item[\texttt{style}] Define el formato del archivo especificado.
  \begin{description}
  \item[\texttt{BIT}] Formato de archivo de Xilinx \texttt{.BIT}. Por defecto para los dispositivos FPGA, XCF y memorias SPI.
  \item[\texttt{BIN}] Archivo binario.
  \item[\texttt{MCS}] Formato de archivo de Xilinx \texttt{.MCS}.
  \item[\texttt{IHEX}] Formato de Intel \texttt{HEX}. También usado por los formatos PROMGEN de Xilinx cuando escribe archivos MCS. Por defecto para los archivos XMEGA.
  \item[\texttt{HEXRAW}] Secuencia en bruto de dígitos hexadecimales.
  \item[\texttt{JEDEC}] Por defecto para los dispositivos CPLDs.
  \end{description}
\item[\texttt{length}] El número de \textsl{bytes} a programar/leer. Solo soportado para SPI, XCFxxS y XMEGA.
\end{description}
 
\subsection{Programación de \ac{FPGA} y memoria PROM}
 
Para demostrar el uso del xc3sprog se realizan algunas pruebas sobre la placa \ac{PHR}. Esta placa dispone de un puerto JTAG al cual se le conectan dos dispositivos en cadena, la FPGA de Xilinx Spantan-3 XC3S200A y su correspondiente memoria de PROM de programación XCF02S. Aquí no se detallará el manejo de la herramienta de \textsl{software} del fabricante de la FPGA (Xilinx). El \textsl{software} ISE Xilinx permite diseñar sistemas digitales y sintetizar esto a una FPGA o CPLD. Como generar los archivos de salida de un proyecto en el ISE Xilinx se puede encontrar en cualquier texto y seguramente con mayor detalle. Aquí solo se trabajará con los archivos de salida obtenidos desde un diseño sencillo que solo busca testear los diferentes periféricos de la placa \ac{PHR}.
 
Primero se debe contar con los drivers de la placa OOCDLink instalados en el \ac{SO}. Luego conectamos la placa OOCDLink al puerto JTAG de la plataforma \ac{PHR} de un extremo, y del otro (puerto USB) nos conectamos a la computadora.
 
Como se comentó la sección \ref{sec:install-xc3sprog}, para correr el programa xc3sprog, en un terminal del sistema GNU/Linux nos cambiamos de directorio hasta donde hayamos compilado nuestra versión del xc3sprog. Una vez ahí, y ya con el \textsl{hardware} conectado correctamente, lanzamos el primer comando para escanear el \textsl{interface} JTAG.
\begin{lstlisting}
luis@luis-laptop:build$ ./xc3sprog -c ftdiphr
XC3SPROG (c) 2004-2011 xc3sprog project $Rev: 231 $ OS: Linux
Free software: If you contribute nothing, expect nothing!
Feedback on success/failure/enhancement requests:
	http://sourceforge.net/mail/?group_id=170565 
Check Sourceforge for updates:
	http://sourceforge.net/projects/xc3sprog/develop
 
Using Libftdi, 
JTAG loc.:   0  IDCODE: 0x02218093  Desc:                       XC3S200A Rev: A  IR length:  6
JTAG loc.:   1  IDCODE: 0xd5045093  Desc:                         XCF02S Rev: M  IR length:  8
\end{lstlisting}
Utilizando la configuración \texttt{ftdiphr} para el \textsl{interface} OOCDLink. Se puede ver que xc3sprog encontró dos dispositivos conectados a la cadena JTAG. El primero, ubicado en la posición 0, es la FPGA XC3S200A. Mientras que el segundo dispositivo, en la posición 1, es la memoria PROM XCF02S.
 
\subsubsection{Programación de la FPGA}
\label{sec:prog-phr-fpga}
Para programar directamente sobre la FPGA se debe correr el comando,
\begin{lstlisting}
luis@luis-laptop:build$ ./xc3sprog -v -c ftdiphr -p 0 /media/datos3/temp/xilinx_projects/PHRprojects/test1/test1_top.bit:w:0:BIT
XC3SPROG (c) 2004-2011 xc3sprog project $Rev: 231 $ OS: Linux
Free software: If you contribute nothing, expect nothing!
Feedback on success/failure/enhancement requests:
	http://sourceforge.net/mail/?group_id=170565 
Check Sourceforge for updates:
	http://sourceforge.net/projects/xc3sprog/develop
 
Using devlist.txt
Using cablelist.txt
Cable ftdiphr type ftdi VID 0x0403 PID 0x6010 dbus data 00 enable 0b cbus data 00 data 00
Using Libftdi, Using JTAG frequency   6.000 MHz from undivided clock
JTAG chainpos: 0 Device IDCODE = 0x02218093	Desc: XC3S200A
Created from NCD file: test1_top.ncd;UserID=0xFFFFFFFF
Target device: 3s200avq100
Created: 2014/03/19 18:31:15
Bitstream length: 1196128 bits
DNA is 0x95cde80efb9ba0fe
done. Programming time 288.0 ms
USB transactions: Write 83 read 9 retries 18
\end{lstlisting}
En comparación con el comando que escanea el puerto JTAG, solo le agregamos la posición del dispositivo al que nos queremos referir y luego una acción concreta que es el de escribir el dispositivo con el dato del archivo \texttt{test\_1.bit}\footnote{No es necesario que el archivo se encuentre en el directorio \texttt{build} donde se compiló el xc3sprog. Se puede indicar un archivo que se encuentre en otro directorio, éste puede ser invocado en forma absoluta o relativa.}. Los demás atributos son propios de la acción como ser, \texttt{w} que borarrá todo el dispositivo PROM y no se le asignará ningún \textsl{offset}.
 
\subsubsection{Programación de la memoria PROM}
\label{sec:prog-phr-prom}
Para el caso de la memoria PROM se debe trabajar un poco más con el \textsl{software} ISE Xilinx para realizar la conversión del archivo de salida \texttt{.bit} a un formato para las memorias XCFxxS/P. Esto se explicará en otra documentación, pero si se deja en claro que debe obtenerse una archivo configurado para este tipo de memorias. Una vez que se tenga este archivo \texttt{.MCS} se debe correr el comando 
\begin{lstlisting}
luis@luis-laptop:build$ ./xc3sprog -v -c  ftdiphr -p 1 /media/datos3/temp/xilinx_projects/PHRprojects/test1/output/Untitled.mcs:w:0:IHEX
XC3SPROG (c) 2004-2011 xc3sprog project $Rev: 231 $ OS: Linux
Free software: If you contribute nothing, expect nothing!
Feedback on success/failure/enhancement requests:
	http://sourceforge.net/mail/?group_id=170565 
Check Sourceforge for updates:
	http://sourceforge.net/projects/xc3sprog/develop
 
Using devlist.txt
Using cablelist.txt
Cable ftdiphr type ftdi VID 0x0403 PID 0x6010 dbus data 00 enable 0b cbus data 00 data 00
Using Libftdi, Using JTAG frequency   6.000 MHz from undivided clock
JTAG chainpos: 1 Device IDCODE = 0xd5045093	Desc: XCF02S
Erasing......done
Erase time 3158.5 ms
Programming does not end at block boundary (nbits = 1196432), padding
Programming block    292/   293 at XCF frame 0x2480.done
Programming time 3236.6 ms
Verify block    292/   293 at XCF frame 0x2480
Success! Verify time 938.0 ms
USB transactions: Write 903 read 890 retries 2040
\end{lstlisting}
 
\subsection{Programación del \ac{CPLD}}
 
 
\section{Documentación}
La documentación resulta fundamental en ésta etapa del desarrollo. Si bien se quiere lograr el correcto funcionamiento de las placas, la documentación sirve para realizar correciones a las versiones futuras de cada placa. Otro objetivo es documentar el funcionamiento de cada dispositivo que sirvan al reporte final como así también a los usuarios de la \emph{Plataforma de Hardware Reconfigurable}.
 
\begin{thebibliography}{}
  \bibitem{2012-SSE-FIUBA-NT01-00} Sebastián García, ``Entorno de desarrollo de firmware sobre arquitectura ARM Cortex-M3, basado en herramientas libres'', 31 de Julio del 2013, Versión 0
  \bibitem{openocd-manual-autoprobing} \ac{openocd}, ``\ac{openocd} User's Guide'', 25 de Noviembre del 2012, 10.7~Autoprobing, 58~p., Versión 0.7.0-dev
\end{thebibliography}
 
\newpage{}
 
\appendix{}
 
\section{Acrónimos}
\begin{acronym}
  \acro{PHR}[PHR]{Plataforma de Hardware Reconfigurable}
  \acro{openocd}[OpenOCD]{\textsl{Open On-Chip Debugger}}
  \acro{jtag}[JTAG]{\textsl{Joint Test Action Group}}
  \acro{TAP}[TAP]{\textsl{Test Access Port}}
  \acro{SVF}[SVF]{\textsl{Serial Vector Format}}
  \acro{CPLD}[CPLD]{\textsl{Complex Programmable Logical Device}}
  \acro{FPGA}[FPGA]{\textsl{Field Programmable Gate Array}}
  \acro{PROM}[PROM]{\textsl{Programmable Read-Only Memory}}
  \acro{SO}[SO]{sistema operativo}
  \acro{GPL}[GPL]{\textsl{General Public License}}
  \acro{UTN-FRC}{Universidad Tecnológica Nacional -- Facultad Regional Córdoba}
\end{acronym}
 
\section{Repositorio de proyecto}
 
El proyecto se encuentra alojado en los servidores de \emph{OpenCores}. Por lo que se puede acceder a los repositorios mediante el siguiente link, \texttt{http://opencores.org/project,phr}
De todas formas se pueden comunicar por correo, \texttt{guanucoluis@gmail.com}.
 
\end{document}