Copyright (c) 2005 Salvador E. Tropea <salvador en inti gov ar>
Copyright (c) 2005 Instituto Nacional de Tecnologa Industrial

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; version 2.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
 02111-1307, USA


Introduccin:
-------------

Este script es un "lint" extremadamente estpido (baka) para VHDL.
La idea es que se le ingresa un fuente VHDL y el programa debe verificar que
el mismo cumpla con las normas de codificacin especificadas.
Esta implementacin no pretende:

1) Ser exacta, se basa en un parser heurstico y por lo tanto puede
equivocarse al analizar el fuente.
2) Ser configurable. La idea es que verifique nuestros criterios, si algn
da se le agrega configuracin mejor, pero por ahora la idea es que las
reglas sean fijas y esten en el cdigo.
3) Verificar cosas demasiado avanzadas.
4) Verificar que el cdigo sea correcto, se asume que compila a la
perfeccin.

Actualmente debera ser capaz de verificar las siguientes reglas:

* Las signals, variables, ports, types, subtypes, etc. deben ser en
minsculas.
* Las constantes y generics deben ser en maysculas.
* Las entities, architectures y packages deben ser con maysculas y
minsculas (pueden ser 100% maysculas, pero no 100% minsculas).
* Los port deben tener un sufijo _i, _o o _io que denote su direccin.
* Los labels tienen que ir en lneas separadas de lo que marcan salvo el caso
de la instanciacin de componentes.
* Los end deben ser autodocumentados indicando que es lo que terminan.
* Los ports tipo buffer estan prohibidos.
* Las estructuras tipo "entity xxxx is" tienen que estar contenidas en una
misma lnea.
* No debe haber ms de una estructura en cada lnea.

Adicionalmente invoca a la herramienta check_vhdl_head.pl que verifica los
siguientes detalles del encabezado:

* Dependencias.
* Versin de las herramientas de sntesis (utiliza un path muy especfico,
pero puede ser deshabilitado).

Para ms informacin consultar los "guidelines" del proyecto fpgalibre.


Uso:
----

Para usar bakalint es necesario indicarle el nombre del archivo a verificar.
Esto se hace con la opcin --input o su abreviatura -i. Por ejemplo:

$ bakalint.pl -i test.vhdl

El programa nos informar acerca de warnings y errores utilizando el formato
de errores usado por todas las herramientas GNU:

archivo:lnea:descripcin

La descripcin siempre comienza con "warning - ", "error - " o
"information - "para indicar la severidad del problema.
De ser posible bakalint nos ofrecer una versin corregida del fuente cuyo
nombre es el mismo que el que especificamos pero con ".lint.vhdl" agregado.

Si bakalint realiz substituciones en los nombres de seales, entidades, etc.
crear un archivo con igual nombre al indicado pero agregando ".lint.txt"
conteniendo los reemplazos llevados a cabo.
Es importante tener en cuenta que cuando bakalint realiza los reemplazos
puede cometer errores si existen elementos de distinto tipo que tienen el
mismo nombre. Por ejemplo: entidad llamada test y seal llamada test.

Nota: Se recomienda correr bakalint slo despus de haber verificado que
nuestro fuente compila perfectamente.


Opciones de lnea de comandos:
------------------------------

Todas las opciones de lnea de comandos pueden abreviarse. La abreviatura
debe ser tal que el programa no la confunda con otra opcin. En casi todos
los casos basta con especificar slo la primer letra de la opcin.

--help               Muestra el texto de ayuda explicando las opciones
                     disponibles.

--depends=file       Esta opcin se usa en archivos del tipo make para que en
                     caso de fallar la verificacin bakalint elimine algn
                     archivo que fuerce al usuario a volver a correr bakalint
                     en la prxima corrida. El caso ms comn es borrar la
                     versin compilada del VHDL.

--head-out=file      Indica el nombre del archivo a ser generado por la
                     herramienta check_vhdl_head.pl

--keep-output        Cuando se especifica no se borran los archivos de salida
                     an cuando bakalint no los considere tiles. Esto puede
                     servir cuando sabemos que nuestro fuente es correcto
                     pero deseamos que bakalint slo corrija el indentado.

--max-sig-len=n      Especifica el largo mximo que admitimos para los
                     nombres de las seales. El valor por defecto es 15.

--no-header          No utiliza check_vhdl_head.pl

--no-indent          No corrije el indentado.

--no-warn-case       No informa warnings acerca de palabras reservadas que
                     fueron escritas usando maysculas/minsculas en forma
                     incorrecta. Esto no implica que no sean tenidos en
                     cuenta, simplemente no se muestran para evitar que la
                     lista de mensajes sea excesivamente larga.

--no-xilinx          Desabilita el chequeo de la versin de las herramientas
                     de sntesis realizado por check_vhdl_head.pl

--output=file        Especifica un nombre para el archivo sugerido como
                     correccin.

--over-head          Esta opcin hace que check_vhdl_head.pl sobreescriba el
                     archivo original.

--replace=file       Indica el nombre del archivo usado para guardar los
                     reemplazos realizados. Esta opcin es muy til cuando
                     queremos que bakalint aplique reemplazos aprendidos en
                     un fuente a otros fuentes. Si al usar bakalint con
                     varios fuentes distintos especificamos un nico archivo
                     de reemplazos los mismos seran propagados.

--stack-debug        Esta opcin se usa para depurar bakalint. Habilita la
                     impresin de informacin sobre la pila interna.

--wishbone           Se debe usar cuando nuestro proyecto usa seales del
                     bus wishbone y deseamos que aplique los reemplazos
                     necesarios sobre las mismas.


Contacto:
---------

Ante dudas, reportes de errores, comentarios, sugerencias, mejoras, etc. por
favor contctese con el proyecto FPGA libre:

http://fpgalibre.sf.net/
http://sf.net/projects/fpgalibre

