doc/golden: documentation for the golden bitstream

28ce4d1b · Tomasz Wlostowski · 0d030d95 · 28ce4d1b · 28ce4d1b · 28ce4d1b
Commit 28ce4d1b authored Oct 17, 2012 by Tomasz Wlostowski
5 changed files
--- a/doc/golden/Makefile
+++ b/doc/golden/Makefile
+#
+# Makefile for the documentation directory
+#
+# Copyright 1994,2000,2010,2011   Alessandro Rubini <rubini@linux.it>
+#
+#################
+
+# There is not basenames here, all *.in are considered input
+INPUT = svec-golden.in
+
+TEXI = $(INPUT:.in=.texi)
+INFO = $(INPUT:.in=.info)
+HTML = $(INPUT:.in=.html)
+TXT  = $(INPUT:.in=.txt)
+PDF  = $(INPUT:.in=.pdf)
+
+ALL    =  $(TXT) $(PDF)
+
+MAKEINFO ?= makeinfo
+
+%.texi: %.in
+	@rm -f $@
+	sed -f ./infofilter $< > $@
+	emacs -batch --no-site-file -l fixinfo $@
+	chmod -w $@
+
+
+#%.info: %.texi
+#	$(MAKEINFO) $< -o $@
+
+#%.html: %.texi
+#	$(MAKEINFO) --html --no-split -o $@ $<
+
+%.txt: %.texi
+	$(MAKEINFO) --no-headers $< > $@
+
+%.pdf: %.texi
+	texi2pdf --batch $<
+
+##############################################
+.PHONY: all images check terse clean install
+.INTERMEDIATE: $(TEXI)
+
+all: images $(ALL)
+	$(MAKE) terse
+
+images::
+	if [ -d images ]; then $(MAKE) -C images || exit 1; fi
+
+check: _err.ps
+	gs -sDEVICE=linux -r320x200x16 $<
+
+terse:
+	for n in cp fn ky pg toc tp vr aux log; do rm -f *.$$n; done
+	rm -f *~
+
+clean: terse
+	rm -f $(ALL) $(TEXI)
+
+install:
+
--- a/doc/golden/drawings/golden_block.eps
+++ b/doc/golden/drawings/golden_block.eps
--- a/doc/golden/fixinfo
+++ b/doc/golden/fixinfo
+
+;; use:
+;;     emacs -batch -l ./fixinfo.el <file>
+;; or, better:
+;;     emacs -batch --no-site-file -l ./fixinfo.el <file>
+
+(defun fixinfo (file)
+  (find-file-other-window file)
+  (message (concat "Maxing texinfo tree in " file))
+  (texinfo-all-menus-update)
+  (texinfo-every-node-update)
+  (save-buffer)
+  (kill-buffer (current-buffer))
+)
+
+;; loop over command line arguments
+(mapcar 'fixinfo command-line-args-left)
+(kill-emacs)
--- a/doc/golden/infofilter
+++ b/doc/golden/infofilter
+#! /usr/bin/sed -f
+
+# allow "%" as a comment char, but only at the beginning of the line
+s/^%/@c /
+#s/[^\\]%.*$//
+s/^\\%/%/
+
+
+#preserve blanks and braces in @example blocks
+/@example/,/@end example/ s/{/@{/g
+/@example/,/@end example/ s/}/@}/g
+/@example/,/@end example/ p
+/@example/,/@end example/ d
+/@smallexample/,/@end smallexample/ s/{/@{/g
+/@smallexample/,/@end smallexample/ s/}/@}/g
+/@smallexample/,/@end smallexample/ p
+/@smallexample/,/@end smallexample/ d
+
+# remove leading blanks
+s/^[ 	]*//
+
--- a/doc/golden/svec-golden.in
+++ b/doc/golden/svec-golden.in
+\input texinfo    @c -*-texinfo-*-
+%
+% fine-delay.in - main file for the documentation
+%
+%%%%
+
+%------------------------------------------------------------------------------
+%
+%                         NOTE FOR THE UNAWARE USER
+%                         =========================
+%
+%    This file is a texinfo source. It isn't the binary file of some strange
+%    editor of mine. If you want ASCII, you should "make fine-delay.txt".
+%
+%------------------------------------------------------------------------------
+
+%
+% This is not a conventional info file...
+% I use three extra features:
+%   - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
+%   - leading blanks are allowed (this is something I can't live without)
+%   - braces are automatically escaped when they appear in example blocks
+%
+
+@comment %**start of header
+@documentlanguage en
+@documentencoding UTF-8
+@setfilename fine-delay.info
+@settitle svec-golden
+@iftex
+@afourpaper
+@end iftex
+@paragraphindent 3
+@comment %**end of header
+
+@setchapternewpage off
+
+@set update-month October 2012
+
+@finalout
+
+@titlepage
+@title @i{Golden} bitstream for the SVEC card
+@subtitle Programmer's manual
+@author CERN BE-CO-HT / Tomasz Włostowski
+
+@end titlepage
+@headings single
+
+@iftex
+@contents
+@end iftex
+
+@c ##########################################################################
+@node Top
+@chapter Introduction
+
+The SVEC Application FPGA golden bitstream allows the SVEC device driver to:
+@itemize
+@item Query the board's serial number,
+@item Check the presence of the FMC mezzanines,
+@item Read out their @math{I^2C} identification EEPROMs.
+@end itemize
+The bitstream does not drive any of the mezzanine user/clock pins to protect from electrical damage resulting from mismatched
+I/O standards.
+
+@chapter Using the bitstream
+
+@section Block diagram
+
+The bitstream encompasses @math{I^2C}, OneWire and GPIO modules from the @code{general-cores} library. For further details, refer to the library's manual.
+
+@float Figure,fig:block
+@center @image{drawings/golden_block, 15cm,,,.pdf}
+@caption{Block diagram of the SVEC golden gateware.}
+@end float
+
+Presence detection is done by reading out the @code{PRSNT} lines (active low) through the GPIO port. EEPROM readout is performed via the two @math{I^2C} masters. Board serial number
+is equal to the serial number of the DS18B20U+ temperature sensor, accessible via the OneWire master. The clock freqency for @code{I^2C} and OneWire dividers calculation is 62.5 MHz. 
+
+@section Memory map
+
+@b{Warning:} Please do not hardcode the base addresses of the cores, query them from the SDB descriptor. The SDB address of @code{0x0} is guaranteed to stay constant.
+Only A32/A24/D32/CSR address modifiers are supported.
+
+@multitable @columnfractions .20 .10 .15 .65
+@headitem Core @tab Base address @tab Library @tab Description
+@item @code{sdb_rom} @tab @code{0x0} @tab @code{general-cores} @tab SDB descriptor.
+@item @code{xwb_i2c_master} @tab @code{0x10000} @tab @code{general-cores} @tab I2C Master for accessing FMC 1 identification EEPROM.
+@item @code{xwb_i2c_master} @tab @code{0x11000} @tab @code{general-cores} @tab I2C Master for accessing FMC 2 identification EEPROM.
+@item @code{xwb_onewire_master} @tab @code{0x12000} @tab @code{general-cores} @tab OneWire Master for accessing temperature sensor/serial ID.
+@item @code{xwb_gpio_port} @tab @code{0x13000} @tab @code{general-cores} @tab GPIO port for accessing FMC1/2 presence lines.
+@end multitable
+   
+@bye