Home page

vhdl-sphinx-domain (VSD) is a Sphinx domain extension that can be used to create rich VHDL project documentation by combining the flexibility of the Sphinx documentation system with a VHDL parser that can automatically extract the structure and documentation from the VHDL source code.

Features:

• Extracts header comments and trailing comments and associates them with their elements

• Automatically document entities, with their generic and port lists

• Allow integrating any comment block in the VHDL source files, including markdown tables

• Supports VHDL2008 using the robust VHDL parser that is embedded in the vhdl-style-guide package (currently using the forked version at https://github.com/jfcliche/vhdl-style-guide.git).

Installation

To install this package:

pip install git+https://github.com/jfcliche/vhdl-sphinx-domain.git

Documentation

Online documentation can be found at https://jfcliche.github.io/vhdl-sphinx-domain/

To build the docs:

git clone https://github.com/jfcliche/vhdl-sphinx-domain.git
pip install -e vhdl-sphinx-domain
cd vhdl-sphinx-domain/docs
make html

Then open vhdl-sphinx-domain/docs/build/html/index.html in a browser.

Usage

Configure your sphinx conf.py file to include this extension and specify the root path to the VHDL code:

extensions = ['vhdl_sphinx_domain']
vhdl_root = os.path.abspath('.')

The VHDL domain then provides the following directives:

• :vhdl:parse:: <filename>: Parses the specified VHDL file and store its contents in the internal project object

• :vhdl:autoentity:: <entity_name>: Inserts the documentation and list of ports and generics for the specified entity

• :vhdl:include-docs:: <entity_name>: Inserts the comment lines from the file that defined the specified entity, starting and ending with the lines that matches the keywords specified as directive options.

Examples

The restructuredText source of this file contains the following directives

Autogenerated Entity documentation
**********************************

.. vhdl:parse:: GPIO.vhd

.. vhdl:autoentity:: GPIO


Memory Map extracted from a comment block
*****************************************

.. vhdl:include-docs:: GPIO
     :start-after: GPIO Module

The results are shown below.

Autogenerated Entity documentation

ENTITY GPIO

Implements general I/O common to all the devices

GENERICS
PLATFORM_ID:	INTEGER –! identifies the type of platform on which the firmware is running
COOKIE:	integer := 16#42#
PROTOCOL_VERSION:	INTEGER –! Protocol version used to determins compatibility with the python support software
NUMBER_OF_ADCS:	INTEGER –! Number of antenna processing blocks that are implemented
NUMBER_OF_CHANNELIZERS:	INTEGER –! Number of antenna processing blocks that are implemented
CHANNELIZERS_CLOCK_SOURCE:	INTEGER –! ADC channel from which the channelizers clocks are derived
NUMBER_OF_CHANNELIZERS_WITH_FFT:	INTEGER –! Number of antenna processing blocks with an FFT module
ADC_SAMPLES_PER_FRAME:	integer
ADC_SAMPLES_PER_WORD:	integer
ADC_BITS_PER_SAMPLE:	integer
NUMBER_OF_CROSSBAR_INPUTS:	integer
NUMBER_OF_CROSSBAR1_OUTPUTS:	integer
NUMBER_OF_BP_SHUFFLE_LINKS:	integer
NUMBER_OF_GPU_LINKS:	integer
NUMBER_OF_CORRELATORS:	INTEGER –! Number of correlator blocks (CH_DIST+CORR+ACC) that are implemented if IMPLEMENT_CORR=TRUE
NUMBER_OF_CHANNELIZERS_TO_CORRELATE:	INTEGER –! Number of antennas to be correlated for each frequency channel. This is hard coded for now. Determines how many antenna streams are fed to the CORR_BLOCK modules, and how many multipliers to implement in parallel in the CORR module.
NUMBER_OF_ADC_BOARDS:	integer := 1
NUMBER_OF_BUCK_SYNC_LINES:	integer :=16
BUCK_SYNC_ENABLE:	boolean := True – default state of the buck sync enable at startup
BUCK_CLK_DIVIDE_FACTOR:	INTEGER :=12 – Buck frequency is 200MHz/BUCK_CLK_DIVIDE_FACTOR/16
MAC_ADDRESS_OUI_CODE:	std_logic_vector(23 downto 0) := X"000A35" – Xilinx OUI code used to identify the first 3 bytes of the MAC address
NUMBER_OF_USER_SMA_SIGNALS:	integer := 8
IMPLEMENT_LCD:	BOOLEAN := FALSE
IMPLEMENT_SWITCHER_SYNC:	BOOLEAN := TRUE
IMPLEMENT_FAN:	BOOLEAN := TRUE
IMPLEMENT_ARM_SPI:	BOOLEAN := TRUE
SIM:	boolean := FALSE
PORTS
– Control interface
ctrl_cmd_in_dat:	in AXIS8_DAT_STRUCT – Command stream input, signals from master (Data, Valid, Last)
ctrl_cmd_in_rdy:	out AXIS8_RDY_STRUCT – Command stream input, signals to master (Ready)
ctrl_rply_out_dat:	out AXIS8_DAT_STRUCT – Reply stream output, signals to slave (Data, Valid, Last)
ctrl_rply_out_rdy:	in AXIS8_RDY_STRUCT – Reply stream output, signals from slave (Ready)
ctrl_clk:	in  std_logic
ctrl_rst:	in std_logic
– IP Port setting
HOST_FRAME_READ_RATE:	out std_logic_vector(4 downto 0)
local_mac_addr:	out std_logic_vector(47 downto 0) – UDP local Rx networking configuration
local_base_ip_addr:	out std_logic_vector(31 downto 0)
local_base_ip_port:	out std_logic_vector(15 downto 0)
local_subarray:	out std_logic_vector(1 downto 0)
remote_ip_port0:	out std_logic_vector(15 downto 0) – UDP TX channel 0 remote network configuration – MAC & IP addresses are hardwired to be those of the perviously received packet – normally set to zero to reply to the same port as the last command
remote_mac_addr1:	out std_logic_vector(47 downto 0) – UDP TX channel 1 remote network configuration
remote_ip_addr1:	out std_logic_vector(31 downto 0)
remote_ip_port1:	out std_logic_vector(15 downto 0)
– Buck control signals
buck_sync:	out std_logic_vector(0 to NUMBER_OF_BUCK_SYNC_LINES-1)
– ARM SPI interface
arm_spi_sck:	in std_logic
arm_spi_miso:	out std_logic
arm_spi_mosi:	in std_logic
arm_spi_cs_n:	in std_logic
– Various unused signals, defined for testing
arm_irq_in:	in std_logic
arm_irq_out:	out std_logic
arm_irq_oe:	out std_logic
flash_cs_in:	in std_logic
flash_cs_out:	out std_logic
flash_cs_oe:	out std_logic
gpio_irq_in:	in std_logic
gpio_irq_out:	out std_logic
gpio_irq_oe:	out std_logic – Active-high: enables GPIO reset output driver.
gpio_rst_in:	in std_logic
gpio_rst_out:	out std_logic
gpio_rst_oe:	out std_logic – Active-high: enables GPIO reset output driver.
uart_rx_in:	in std_logic
uart_rx_out:	out std_logic
uart_rx_oe:	out std_logic
uart_tx_in:	in std_logic
uart_tx_out:	out std_logic
uart_tx_oe:	out std_logic
– FAN control signals (for on-board fan found on some evaluation boards)
FAN_PWM:	out std_logic –! PWM control of the fan
FAN_TACH:	in std_logic –! Tachymeter input from the fan (two pulses per revolution). A debouncer cleans this signal before measuring the fan frequency.
FAN_TACH_DIV2:	out std_logic –! logic signal pulsing at half the fan rotation speed
– ADC mezzanine control signals
ADC_RST:	out std_logic_vector(0 to NUMBER_OF_ADC_BOARDS-1)
adc_cal_freeze:	out std_logic_vector(0 to 7)
adc_cal_frozen:	in std_logic_vector(0 to 7) := (others => '0')
adc_cal_signal_detect:	in std_logic_vector(0 to 7) := (others => '0')
adc_pll_lock:	in std_logic_vector(0 to NUMBER_OF_ADC_BOARDS-1) –! Lock signal for the ADC PLL on each mezzanine
– LCD (on some evaluation boards)
LCD_DB:	out  std_logic_vector(7 downto 4)
LCD_E:	out  std_logic
LCD_RS:	out  std_logic
LCD_RW:	out  std_logic
– Backplane signals
– Slot sensing system (measures capacitance on the sense line to identify the slot number)
slot_probe:	in std_logic_vector(1 downto 0) –! Signal used to probe the capacitance of the backplane slot-sense line
slot_sense:	in std_logic_vector( 1 downto 0) –! Returns the logic level change in response to the probe edge, which is used to determine the board capacitance.
– Backplane synchronization signal
bp_buck_sync:	inout std_logic
bp_buck_sync_mon:	out std_logic
– Backplane global interrupt line
bp_gpio_int_out:	out std_logic
bp_gpio_int_in:	in std_logic
bp_gpio_int_oe:	out std_logic
– UDP Communication link monitoring
udp_tx_frame:	in std_logic
udp_rx_frame:	in std_logic
udp_tx_overflow:	in std_logic
udp_rx_overflow:	in std_logic
sfp_status_vector:	in std_logic_vector(15 downto 0)
sfp_config_vector:	out std_logic_vector(31 downto 0)
cmd_packet_counter:	in std_logic_vector(7 downto 0)
rply_packet_counter:	in std_logic_vector(7 downto 0)
udp_stack_reset:	out std_logic
ctrl_master_reset:	out std_logic
– General signals
TRIG_ASYNC:	out std_logic
– Clocks
clk200:	in std_logic –! 200 MHz clock, used for many things
clk200_reset:	in std_logic –!
clk10:	in std_logic –! 10 MHZ reference clock, in phase for every board in the system
clk10_sel:	out std_logic
dna_clk:	in std_logic –! DNA port clock (max 97 MHz)
– External PLL control
pll_sync:	out std_logic
– PWM signal
pwm_clk:	in std_logic
pwm_ctr_en:	in std_logic – Active when the pwm counter is to be enabled.
pwm_reset:	in std_logic
pwm_out:	out std_logic
– Event (Frame) counter
event_ctr_clk:	in std_logic
event_ctr_en:	in std_logic
event_ctr_inc:	in std_logic
event_ctr_reset:	in std_logic
– User output selection
user_mux_in:	in std_logic_vector(0 to NUMBER_OF_USER_SMA_SIGNALS-1) – User selectable signals (typically PWM, 1PPS, SYNC, ?)
user_mux_out:	out std_logic_vector(0 to 3) – User selected signal
user_mux_oe:	out std_logic_vector(0 to 3)
user_bit:	out std_logic_vector(1 downto 0)
– IRIG-B time
irigb_mux_in:	in std_logic_vector(0 to 7) – IRIG-B time signals
irigb_before_target:	out std_logic
irigb_pps:	out std_logic
irigb_out:	out std_logic
irigb_delay:	out std_logic_vector(4 downto 0) – Delay to apply to the IRIG-B signals on the IOB
irigb_delay_reset:	out std_logic
– Channelizer clock source selection
CHAN_CLK_SOURCE:	out std_logic
– User-controlled global resets
USER_RESET:	out std_logic
ctrl_reset_pulse:	out std_logic
sysmon_user_reset:	out std_logic
ADCDAQ_RESET_ASYNC:	out std_logic
CHAN_CLK_RESET_ASYNC:	out std_logic
CHAN_RESET_ASYNC:	out std_logic
CORR_RESET_ASYNC:	out std_logic
BLINKER_RESET:	out std_logic

Includes

• Global data capture/injection trigger

• Global antenna reset

• Global correlator reset

• LCD Interface bits

• Buck switching supply SYNC signal generation

• FMC ADC Reset line

• Fan speed readout

• IP Port offsets for the data capture and correlator outputs

Memory Map extracted from a comment block

Page	Addr	Bit(s)	Name	Description
CONTROL	0	7	CTRL_FLAG_GLOBAL_TRIG
		6	CTRL_FLAG_BUCK_SYNC_ENABLE	Enables the generation of the Buck switcher synchronization signals. If ‘0’, all sync lines are held low to let the switcher free-run.
		5	CHAN_CLK_RESET	Resets the MMCM that generates the channelizer clocks
		4	CHAN_CLK_SOURCE	Selects the source of the channelizer clocks: 0: ADC clock, 1: 200 MHz system clock. CHAN_CLK_RESET or ADCDAQ_RESET must be asserted when doing the change to allow the MMCM to lock properly to the new clock.
		3	ADCDAQ_RESET	Resets all ADCDAQ modules. This also resets the channelizer clock MMCM, the channelizers and the correlators.
		2	(unused)
		1:0	ADC_RESET	ADC RESET line (active High) for each FMC ADC boards (bit 0 is for ADC board 0, etc)
	1	7:0	CTRL_FLAG_BUCK_CLK_DIV	System clock frequency divider ratio used to set the buck sync frequency
	2	7	LCD_E	LCD Enable
		6	LCD_RS	LCD Command/Data flag
		5	LCD_RW	LCD Read/Write flag
		4	(unused)
		3:0	LCD_DB	LCD data bus (4 bits)
	3	7	BLINKER_RESET
		6	CHAN_RESET_ASYNC	Resets all channelizers
		5	CORR_RESET_ASYNC	Resets all correlators
		4:0	(unused)
	4	7:5	(unused)
		4:0	HOST_FRAME_READ_RATE	Indicates how often the host reads its UDP buffers in order to throttle the Ethernet output data rate. The read period is 2*(2^HOST_FRAME_READ_RATE)*(1/ctrl_clk) where CTRL lk is 125 MHz
	5-12	63:0	BUCK_PHASE	Phase of each of the 16 Buck sync lines. There are 16 possible phase values for each line. Bits 3:0 is for phase 0, bits 7:4 for phase 1 etc.
	13-24		(unused)
	25-32	63:57	(unused)
		56:0	TARGET_FPGA_DNA	Target FPGA serial number: The core registers can be written via BSB commands if this target serial number matches the actual serial number of the FPGA
	33		(unused)
	34-37	31:0	pwm_offset	Number of events (frames) to delay before starting to generate the first High of the PWM output
	38-41	31:0	pwm_high_time	Number of events (frames) to keep the PWM output at High
	42-45	31:0	pwm_period	Number of events (frames) between PWM High (i.e PWM period)
	33	7	pwm_soft_reset	Software reset of the PWM module. Active high.
		7:3	(unused)
		2:0	user_mux_source	Selects which user source to send to the user output.
STATUS	0	7	USER_DATA_VALID	is ‘1’ when the ACCESS0 register data (firmware timestamp) is valid
		6:0	COOKIE	Defined as a GENERIC (default = 0x42)
	1	7:0	LOG2_FRAME_LENGTH
	2	7:0	NUMBER_OF_CHANNELIZERS	Number of antennas processing pipelines implemented in the firmware
	3	7:0	NUMBER_OF_CORRELATORS	Number of correlators implemented in the firmware
	4	7:0	NUMBER_OF_CHANNELIZERS_TO_CORRELATE	Number of antennas connected to the correlators. Only antennas 0 to N-1 will be connected. This sets the numbe rof parallel multipliers and accumulators in the correlator.
	5	7:0	NUMBER_OF_CHANNELIZERS_WITH_FFT	Indicates how many channelizers have a FFT module. Those will be channeizers 0 to N-1
	6	7:0	NUMBER_OF_GPU_LINKS	Indicates how GPU Links are implemented. If zero, the GPU module is not present at all (not even the common registers)
	7-10	31:0	firmware_timestamp	32-bit word containing the timestamp of the firmware inserted during the bitgen process
	11	7:0	PLATFORM_ID	Type of platform on which the firmware is running. 0=ML605, 1=KC705, 3=MGK7MB, 4=ZCU111
	12-19	63:57	(unused)
		56:0	FPGA_DNA	FPGA unique serial number
	20	7:0	NUMBER_OF_CROSSBAR_INPUTS	Indicates how many channelizers are connected to the crossbar inputs. Those will be channeizers 0 to N-1
	21	7:0	NUMBER_OF_CROSSBAR1_OUTPUTS	Indicates the number of crossbar1 outputs. Those outputs feed the GPU links and the FPGA correlators (if implemented).
	22-23	15:0	PROTOCOL_VERSION	16-bit value indicating the protocol version. A change in the version means that some change is needed on host control software.
	24	7:0	CHANNELIZERS_CLOCK_SOURCE	ADC channel from which the channelizer clocks are derived. Useful to know if we should expect the clock to be missing and use alternate internal clock.
	25-30		(unused)
	31	7:0	slot_sense_ctr(0)
	32	7:0	slot_sense_ctr(1)
	33	7:6	adc_pll_lock
		5:2	(unused)
		1	udp_tx_overflow
		0	udp_rx_overflow
	34	7:0	cmd_packet_counter
	35	7:0	rply_packet_counter
	36	7:0	NUMBER_OF_BP_SHUFFLE_LINKS
	37	7	(unused)
	37	7	bp_gpio_int_in
	37	6	bp_gpio_int_in
	37	5	gpio_irq_in
	37	4	flash_cs_in
	37	3	uart_tx_in
	37	2	uart_rx_in
	37	1	gpio_rst_in
	37	0	arm_irq_in

How it works

This is a summary of how the domain works:

• Tokenize the source file with a VHDL parser. We use vhdl-style-guide parser.

• Post-process the token list to extract the main language elements (entities, ports, architecture) in to a hierarchical linked list (using xml.etree.ElementTree)

• Post-process the tree to group comment consecutive comment lines into comment blocks, and move comment blocks preceding and trailing each language element into that element’s node.

• Extracts entities, interface lists etc into a easy to access hiearchical dictionary using the simple xpath search parameters to lookup elements in the tree.

• Store the intormation in the VHDL parser instance

• When directives and roles are invoked,