Skip to content

F
FMC ADC 100M 14b 4cha - Software
Commit c05f4525 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: port to Shpinx 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 856497c1
Hide whitespace changes
Inline Side-by-side
Showing with 1239 additions and 57 deletions
doc/.gitignore
View file @ c05f4525
......@@ -15,3 +15,4 @@
*.tp
/*.txt
*.vr
_build
doc/Makefile
View file @ c05f4525
# Minimal makefile for Sphinx documentation
#
# 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 = $(wildcard *.in)
TEXI = $(INPUT:.in=.texi)
INFO = $(INPUT:.in=.info)
HTML = $(INPUT:.in=.html)
TXT = $(INPUT:.in=.txt)
PDF = $(INPUT:.in=.pdf)
ALL = $(INFO) $(HTML) $(TXT) $(PDF)
MAKEINFO ?= makeinfo
RELEASE=$(shell git describe --always --dirty)
%.texi: %.in
@rm -f $@
sed s/__RELEASE_GIT_ID__/$(RELEASE)/ $< | sed -f ./infofilter > $@
emacs -batch --no-site-file -l fixinfo $@
chmod -w $@
%.pdf: %.texi
texi2pdf --batch $<
%.info: %.texi
$(MAKEINFO) $< -o $@
%.html: %.texi
$(MAKEINFO) --html --no-split -o $@ $<
%.txt: %.texi
$(MAKEINFO) --no-headers $< > $@
##############################################
.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 *~
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = FMCADC100M14bit4Channel
SOURCEDIR = .
BUILDDIR = _build
clean: terse
rm -f $(ALL) $(TEXI)
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
install:
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
doc/conf.py 0 → 100644
View file @ c05f4525
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# FMC ADC 100M 14 bit 4 Channel documentation build configuration file, created by
# sphinx-quickstart on Thu Jan 25 09:54:50 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.graphviz',]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'FMC ADC 100M 14 bit 4 Channel'
copyright = '2018, Federico Vaga <federico.vaga@cern.ch>'
author = 'Federico Vaga <federico.vaga@cern.ch>'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '5.0'
# The full version, including alpha/beta/rc tags.
release = '5.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
#html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'FMCADC100M14bit4Channeldoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'FMCADC100M14bit4Channel.tex', 'FMC ADC 100M 14 bit 4 Channel Documentation',
'Federico Vaga \\textless{}federico.vaga@cern.ch\\textgreater{}', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'fmcadc100m14bit4channel', 'FMC ADC 100M 14 bit 4 Channel Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'FMCADC100M14bit4Channel', 'FMC ADC 100M 14 bit 4 Channel Documentation',
author, 'FMCADC100M14bit4Channel', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
smart_quotes = False
doc/driver-devel.rst 0 → 100644
View file @ c05f4525
The Driver Development Guide
============================
.. warning:: TODO describe the internals
doc/driver-tools.rst 0 → 100644
View file @ c05f4525
Tools
=====
The driver is distributed with a few tools living in the ``tools/``
subdirectory and they do not use any dedicated library, instead
they do raw accesses to the driver. The programs are meant to provide
examples about the use of the driver interface.
The generic library `adc-lib`_ supports this driver, so you may want to
consider to use the generic tools from that library.
.. _`adc-lib`: http://www.ohwr.org/projects/adc-lib
Trigger Configuration
---------------------
The program ``fau-trg-config`` configures the FMC ADC trigger. The tool
offers command line parameters to configure every register exported by
the driver. The help screen for the program summarizes the options::
# ./tools/fau-trg-config --help
fau-trg-config [OPTIONS] <DEVICE>
<DEVICE>: ZIO name of the device to use
--pre|-p <value>: number of pre samples
--post|-P <value>: number of pre samples
--nshots|-n <value>: number of trigger shots
--delay|-d <value>: set the ticks delay of the trigger
--threshold|-t <value>: set internal trigger threshold
--channel|-c <value>: select the internal channel as trigger
--external: set to external trigger. The default is the internal trigger.
--negative-edge: set internal trigger polarity to negative edge. The default
is positive edge.
--enable-sw-trg: enable the software trigger. By default is disabled.
--disable-hw-trg: disable the hardware trigger. By default is enabled
--force: force all attribute to the program default
--help|-h: show this help
NOTE: The software trigger works only if also hardware trigger is enabled
The tool gets the configuration values from the user and it writes them
to the corresponding sysfs attributes for the specified device. or
example, if you want to configure the board for the external trigger and
3 shots of 10 pre-samples and 100 post-samples, this is the associated
command line::
# ./tools/fau-trg-config --external --pre 10 --post 100 --re-enable 2 \
adc-100m14b-0200
As shown, the nshot parameter is passed as a number of re-enables,
because the trigger is initially automatically enabled. This may change
in the future, for better naming consistency with hardware documentation
and across tools.
Acquisition Time
----------------
The program fau-acq-time retrieves the timestamps associated with the
acquisition. This is the help screen of the program::
./tools/fau-acq-time --help
fau-acq-time [OPTIONS] <DEVICE>
<DEVICE>: ZIO name of the device to use
--last|-l : time between the last trigger and the acquisition end
--full|-f : time between the acquisition start and the acquisition end
--help|-h: show this help
The program can return two different *types* of acquisition time. The
value returned by **last** represent the time elapsed between the last
trigger event and the acquire-end event; this is the time spent during
the last capture.
The value returned by **full** is the time elapsed between the
acquisition start event and the acquisition end event, i.e. the total
time spent waiting for all trigger events and the time spent acquiring
all samples.
Channel Configuration
---------------------
The program ``tools/fau-config-if`` is a simple graphic tool that allow to
select offset and range for the four channels, activate termination and
see the current value of each channel, every 500ms.
The program open one window for each detected card, and configures it by
writing to sysfs. Such writes are also reported to stdout (in the
terminal where you invoked the program), so you can easily copy the
pathnames in your shell commands.
The figure below shows two instances of the tool, running on the same card
with device_id 0x200 (your window decorations will be different, according
to your choice of window manager or desktop environment).
The first one (at the left) is running under Tk-8.5; the second one shows
the graphic appearance of Tk-8.4 (and earlier versions). If you prefer the
older one, run *wish8.4 tools/fau-config-if* instead of
``tools/fau-config-if`` (or set the previous version as default Tk interpreter).
.. figure:: img/config-if.gif
:alt: Two snapshots of fa-config-if
:align: center
Parallel Port Burst
-------------------
If you have a Parallel Port you can use it to generate bursts of pulses
with a software program. This may be useful to test the external
trigger; you can connect the parallel port to the external trigger of
the FMC ADC and generate your trigger events with this program
The program parport-burst, part of this package, generates a burst
according to three command line parameters: the I/O port of the data
byte of the parallel port, the repeat count and the duration of each
period. This example makes 1000 pulses of 100 usec each, using the
physical address of my parallel port (if yours is part of the
motherboard, the address is ``378``)::
./tools/parport-burst dd00 1000 100
doc/driver-user.rst 0 → 100644
View file @ c05f4525
The Driver Interface For Users
==============================
Installation
------------
This driver depends on two other drivers, as well as the Linux kernel.
Also, it must talk to a specific FPGA binary file running in the carrier
card.
Gateware
''''''''
The driver does not support all the gateware version; each gateware
main release need a new driver release which typically is not backward
compatible. So the latest version of the driver supports only the
latest version of the gateware
.. note:: On 2018-02 driver v5.0 supports gateware v5.0
On the ohwr `wiki page`_ you can find other details about all the past
releases.
.. _`wiki page`: http://www.ohwr.org/projects/fmc-adc-100m14b4cha-sw/wiki/Releases
To install the FPGA image in the target system, you need to place the
.bin file within ``/lib/firmware/``, where the system can find it.
The default gateware depends on the carrier in use. On a SVEC carrier
the default gateware is *fmc/spec-fmc-adc-100m14b.bin*; on a SPEC carrier
the default gateware is *fmc/spec-fmc-adc-100m14b.bin*
Anyway, you can use a different name for your gateware file and you can load
it by specifying the module parameter ``gateware=`` as described in the
`Module Parameters`_ section.
.. NOTE this can change in the future if we drop the fmc-bus
Software
''''''''
The kernel versions used during development are 3.2 and 3.6.
The driver is base on the `ZIO framework`_. The exact commit being used
for development is also used as a git submodule of this package, so it is
automatically built.
.. note:: On 2018-02 driver v5.0 used ZIO *zio-1.2-24-g0765fa5*
The driver is also based on the `fmc-bus`_. This bus manages FMC carriers
and mezzanines, identification and so on.
.. note:: On 2018-02 driver v5.0 used FMC-bus *fmc-bus-v2017-06*
.. note:: The fmc-bus support can be dropped in the future in favor of
a platform device
For the particular case of the SVEC carrier, in order to be able to use
the DMA operations, we need the header files of `SVEC`_ and the VME bus.
.. note:: On 2018-02 driver v5.0 used SVEC *svec-sw-v2014-04-hotfixes-44-gbdbc36c*
.. warning:: The VME bus used for this driver is the one developed at CERN
by the BE-CO-HT section. This is not publicly available, it means that
the SVEC support is limited to CERN users.
The versions mentioned above are the one used during the development. You may
want to use different version of those dependencis to include bugfixes or
improvements.
Now that you have the dependencies you can start building the driver.
The building process needs to know the location of the different dependencies.
``LINUX``
The top-level directory of the Linux kernel you are compiling
against. If not set, the default may work if you compile in the
same host where you expect to run the driver.
``ZIO``, ``FMC_BUS``
The top-level directory of the repository checkouts for the pacakges.
If unset, the top-level Makefile refers to the submodules of this package.
``CONFIG_FMC_ADC_SVEC``
It enables the `SVEC`_ support when its value is ``y``.
``SVEC_SW``, ``VMEBUS``
The top-level directory of the repository checkouts for the pacakges.
These are necessary only if you need the `SVEC`_ support.
When you have the necessary environment variables you can the ``make`` command::
make
sudo make install
.. _`ZIO framework`: http://www.ohwr.org/projects/zio
.. _`fmc-bus`: http://www.ohwr.org/projects/fmc-bus
.. _`SVEC`: https://www.ohwr.org/projects/svec-sw
.. _`SPEC`: https://www.ohwr.org/projects/spec-sw
Module Parameters
-----------------
The driver accepts a few load-time parameters for configuration. You can
pass them to insmod directly, or write them in ``/etc/modules.conf`` or
the proper file in ``/etc/modutils/``.
The following parameters are used:
gateware=PATH[, PATH]
The binary file to use to reprogram the FPGA. The default value for
this parameter is ``fmc/adc-100m14b.bin`` as seen in Gateware
Installation. The name is a relative pathname from
``/lib/firmware``, and it will be used for each and every card.
In combination with the busid, you can provide different file for
different card.
enable_test_data=[0, 1]
This is for testing purpose. When set to 1, this option enables the
testing data, so the ADC doesn't store samples, but fills memory with
sequential numbers. The 64 bit data vector is filled with sequential
values from a free-running 25 bit counter: channel 0 sweeps the full
range, channel 1 goes from 0 to 511, other channel always report 0.
Trigger detection is unaffected by use of test data.
busid=NUMBER[,NUMBER]
Restrict loading the driver to only a few mezzanine cards. If you
have several SPEC cards, most likely not all of them host an ADC
card; by specifying the list of bus identifiers you restrict the
module to only drive those cards. This option will remain, but is
going to be mostly obsoleted by use of eeprom-based identification
of the cards.
Device Abstraction
------------------
This driver is based on the ZIO framework and the fmc-bus. It supports
initial setup of the board; it allows users to manually configure the
board, to start and stop acquisitions, to force trigger, to read
acquisition time-stamps and to read acquired samples.
The driver is designed as a ZIO driver. ZIO is a framework for
input/output hosted on http://www.ohwr.org/projects/zio.
ZIO devices are organized as csets (channel sets), and each of them
includes channels. This device offers one cset and four channels.
However, the device can only stores interleaved data for all four
channels.
The current approach to this is defining 5 channels: channels 0 to 3 are
the actual input connectors, and their software counterpart is used to
configure the channels; the last channel is called *i*, and is the
interleave channel where data is retrieved.
The Overall Device
''''''''''''''''''
As said, the device has 1 cset with 4+1 channels. Channels from 0 to 3
represent che physical channels 1 to 4. The 5th channel *chani* represent
a virtual channel created automatically by the ZIO framework; this
channel represent the interleave acquisition on the cset.
.. graphviz::
:align: center
graph layers {
node [shape=box];
adc [label="FMC ADC 100M4B4CHA"];
adc -- cset0;
cset0 -- chan0;
cset0 -- chan1;
cset0 -- chan2;
cset0 -- chan3;
cset0 -- chani;
}
The ADC registers can be accessed in the proper sysfs directory. For a
card in slot 0 of bus 2 (like shown above), the directory is
*/sys/bus/zio/devices/adc-100m14b-0200*.
The overall device (*adc-100m14b*) does not offer configuration items
besides its own temperature (read-only) because configuration is
specific of the cset and the trigger, or the individual channel.
The Channel Set
'''''''''''''''
The ADC has 1 Channel Set named ``cset0``. Its attributes are used to
control the ADC state machine, the channel parameters and so on.
Some attributes are channel-specific, and one may thing they should live
at channel-level. Unfortunately, ZIO currently lacks the mechanisms to
convey channel attributes in the meta-data associated with an
interleaved acquisition (where several channels coexist), and for this
reason we chose to put them all at cset level. This may change in future
releases, but the library implementation will follow, so there will be
no effect on API users.
The description of attributes that follows is mainly useful for the
shell user, to diagnose the system and hack around with parameters.
Channel-specific Cset Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The cset includes three attributes for each channel, as follows:
chN-50ohm-term
The read-write attribute accepts values 0 or 1. By writing 1, you
turn on the termination resistor. Default is 0.
chN-offset
The user offset is an integer value in the range [-5000,5000], and
it represents millivolts. The offset represents the center-scale
of conversion for the input channel. Internally, a DAC is used to
generate the requested voltage, which is then subtracted from the
input signal. DAC values are corrected according to the
calibration values retrieved from the FMC EEPROM. For this reason,
the offset may saturate at values less than +/- 5V.
chN-vref
The "voltage reference" used for conversion. This attribute may be
renamed to "range" in the future (again, with no effect on API
users). Changing the range does not reset the user offset, which
is automatically adjusted according to the new calibration values.
The attribute accepts three values: 35 represents the 100mV range
(-50mV to +50mV); 17 represents 1V range; 69 represents 10V range
(-5V to +5V); 0 detaches the input connector from the ADC. The
numbers used here derive from hardware values, and the attributes
refuses any other value.
cnN-saturation
The user saturation level in the range [0, 32767]. Users can use
this value to configure their own saturation level. The hardware
applies this value symmetrically on the negative side. By default
is setted at the maximum value.
Generic Cset Attributes
~~~~~~~~~~~~~~~~~~~~~~~
This section lists the attributes that are defined by this driver;
ZIO-wide attributes (current_buffer, enable and so on) are not
described.
fsm-auto-start
This attribute can be set to 1 or 0. It is 0 by default. If set
to 1, the acquisition state-machine is automatically restarted
after the previous run is complete. Thus, for example, a card
configured for external trigger, after the first acquisition will
continue aquiring and storing blocks to the ZIO buffer every time a
new trigger event is detected. Applications can read such blocks
from the char device.
fsm-command
Write-only: start (1) or stop (2) the state machine. The values
used reflects the hardware registers. Stopping the state machine
aborts any ongoing acquisition. Starting the state machine is
required in order to run an acquisition (the library manages this
internally). The green LED ACQ on the front panel reflect the fact
that the state machine has started. Restarting a running state
machine is equivalent to first stopping it.
fsm-state
Read-only current state of the FSM. Useful for diagnostics in
strange situation. Please refer to the firmware manual (or to
source code) about the various states.
resolution-bits
This read-only attribute returns 14, the number of valid bits in
the ADC data stream.
rst-ch-offset
This write-only attributes zeroes all offset DACs when written,
independently of the value being written. The driver applies the
current calibration values, instead of writing 0 directly to the
hardware.
undersample
The ADC always acquires at 100MSamples/s and this value cannot be
changed (it actually can, but it is not currently supported nor
even tested). If you need less samples you can tell the card to
decimate (or under-sample) the data stream. The attribute accepts
an integer value, 1 to 65536; it means to pick one sample every
that many. Thus, but writing 100 you get a 1Ms data stream, and by
writing 2 you get a 50Ms data stream.
sample-frequency
This read-only attributes returns the measured sampling frequency
sample-counter
Number of samples acquired on each channel during the last
acquisition. If queried while the acquisition is running you will
get the number of samples acquired till that moment. It can be
used to evaluate the progress of a slow acquisition.
max-sample-mshot
Maximum number of samples that can be stored in the FPGA memory in
multi-shot mode
Timestamp Cset Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~
The ADC mark with a timestamp all these events: state machine start,
state machine stop and acquisition end. The device split each timestamp
in 3 attributes named: second (s), ticks (t) and bins (b).
Seconds represents (by default) the number of second since the epoch;
ticks is the number of clocks at 125Mhz, the value is between 0 and
125000000 and it increments seconds when it overflow. At the moment, the
bins register is unused.
For example, to read the entire timestamp of the state machine start
event you should do::
cat /sys/bus/zio/devices/adc-100m14b-0200/cset0/tstamp-acq-str-s
cat /sys/bus/zio/devices/adc-100m14b-0200/cset0/tstamp-acq-str-t
cat /sys/bus/zio/devices/adc-100m14b-0200/cset0/tstamp-acq-str-b
The driver export 4 time stamps:
tstamp-acq-str-{s|t|b}
this is the time stamp of the last acquisition start command
execution
tstamp-acq-end-{s|t|b}
it is the time of last sample acquired
tstamp-acq-stop-{s|t|b}
this is the time stamp of the last acquisition stop command
execution
tstamp-trg-lst-{s|t|b}
this is the time stamp of the last trigger fire. Please bear in
mind that in multi-shot acquisition you have several trigger fire,
so this time stamp refers only to the last one. If you need the
time stamp for each trigger fire you have to get it from the
zio_control of the associated acquisition block.
By default these time stamps represent (more or less) the time since the
epoch. The user can change this and configure a different timing base.
The attributes tstamp-base-s and tstamp-base-t are ment for this
purpose.
The Channels
''''''''''''
The ADC has 4 input channels. Each channel features one attribute, other
attributes in the directory are defined by the kernel or by ZIO.
current-value
the current value is a 16 bit number, resulting from the 14 bit ADC
value and calibration correction. The value is reported as unsigned,
even if it actually represents a signed 16-bit integer. (This because
ZIO manages 32-bit attributes and the value shown comes directly from
the hardware)
The Trigger
'''''''''''
In ZIO, the trigger is a separate software module, that can be replaced
at run time. This driver includes its own ZIO trigger type, that is
selected by default when the driver is initialized. You can change
trigger type (for example use the timer ZIO trigger) but this is not the
typical use case for this board.
The name of the ADC trigger is adc-100m14b. Like all other ZIO objects,
each instance of the trigger has a sysfs directory with its own
attributes:
The ADC has its own zio_trigger_type and it can not work with any other
ZIO's trigger. The ADC trigger is called fmc-adc-trg. We advise you
against replacing the trigger with another one.
The trigger supports four operating modes: the external trigger is
driven by a specific LEMO connector on the front panel of the card. The
internal trigger activates on data threshold in one of the four input
channels - either positive-going or negative-going. The timer trigger
that fires a trigger a given time. The software trigger is activated by
simply writing to a register.
This is the list of attributes (excluding kernel-generic and ZIO-generic
ones):
source-triggered
It is a bitmask where only one bit is set and it identifies the trigger
type that triggered the last acquisition. Look at the header file, or
the gateware document, for the meaning of each bit.
source
It is a bitmask that enable (1) or disable (0) the available triggers.
It supports multi-triggers, so you can enable more than one trigger at
the same time. Look at the header file, or the gateware document, for
the meaning of each bit.
polarity
It is a bitmask that set the trigger polarity to positive (0) on
negative (1) for each trigger that supports it. Look at the header file,
or the gateware document, for the meaning of each bit.
chN-threshold
These attributes choose the value of the data thresold (as a signed
16-bit value).
chN-hysteresis
These attributes choose the value of hysteresis associated to the
threshold.
chN-delay, ext-delay
The delay attribute tells how many samples to delay actual
acquisition since the trigger fired. Being sample-based, the
resolution is 10ns. By default delay is 0. The undersampling
does not have effect.
enable
This is a standard zio attribute, and the code uses it to enable or
disable the hardware trigger (i.e. internal and external). By
default the trigger is enabled.
int-channel, int-threshold
If the internal trigger is selected, these attributes choose the
channel being monitored (range is 0..3) and the value of the data
thresold (as a signed 16-bit value).
nshots
Number of trigger shots. The state machine acquires all trigger
events to internal on-board memory, and performs DMA only at the
end. In single-shot, the acquisition can be as long ad 32Msamples
(on-board memory is 256MB), but in multi-shot acquisition is first
done to in-FPGA memory, and thus each shot can only acquire 2048
samples.
post-samples, pre-samples
Number of samples to acquire. The pre-samples are acquired before
the actual trigger event (plus its optional delay). The post
samples start from the trigger-sample itself. The total number of
samples acquired corresponds to the sum of the two numbers. For
multi-shot acquisition, each shot acquires that many sample, but
pre + post must be at most 2048.
sw-trg-fire
To use the software trigger, you must first enable it (writing 1)
to sw-trg-enable. When enabled, by writing any values to
sw-trg-file you can force a trigger event. This is expected to be
used only for diagnostic reasons.
tstamp-trg-lst-b, tstamp-trg-lst-s, tstamp-trg-lst-t
To be verified and documented.
The Buffer
''''''''''
In ZIO, buffers are separate objects. The framework offers two buffer
types: kmalloc and vmalloc. The former uses the kmalloc function to
allocate each block, the latter uses vmalloc to allocate the whole data
area. While the kmalloc buffer is linked with the core ZIO kernel
module, vmalloc is a separate module. The driver currently prefers
kmalloc, but even when it preferred vmalloc (up to mid June 2013), if
the respective module wad not loaded, ZIO would instantiate kmalloc.
You can change the buffer type, while not acquiring, by writing its name
to the proper attribute. For example::
echo vmalloc > /sys/bus/zio/devices/adc-100m14b-0200/cset0/current_buffer
The disadvantage of kmalloc is that each block is limited in size.
usually 128kB (but current kernels allows up to 4MB blocks). The bigger
the block the more likely allocation fails. If you make a multi-shot
acquisition you need to ensure the buffer can fit enough blocks, and the
buffer size is defined for each buffer instance, i.e. for each channel.
In this case we acquire only from the interleaved channel, so before
making a 1000-long multishot acquisition you can do::
export DEV=/sys/bus/zio/devices/adc-100m14b-0200
echo 1000 > $DEV/cset0/chani/buffer/max-buffer-len
The vmalloc buffer allows mmap support, so when using vmalloc you can
save a copy of your data (actually, you save it automatically if you use
the library calls to allocate and fill the user-space buffer). However,
a vmalloc buffer allocates the whole data space at the beginning, which
may be unsuitable if you have several cards and acquire from one of them
at a time.
The vmalloc buffer type starts off with a size of 128kB, but you can
change it (while not aquiring), by writing to the associated attribute
of the interleaved channel. For example this sets it to 10MB::
export DEV=/sys/bus/zio/devices/adc-100m14b-0200
echo 10000 > $DEV/cset0/chani/buffer/max-buffer-kb
Summary of Attributes
'''''''''''''''''''''
The following table lists all attributes related to this driver. All
values are 32-bit that ZIO framework can handle only 32bit unsigned
integer.
.. list-table:: FMC ADC 100M 4B 4 C Attributes Summary
:header-rows: 1
:widths: 1 1 1 1 1 2
* - Context
- Name
- Permission
- Default
- Values
- Comments
* - device
- temperature
- ro
- --
-
- The temperature is in millidegree
* - cset
- enable
- rw
- 1
- [0, 1]
-
* - cset
- chN-50ohm-term
- rw
- 0
- [0, 1]
- N = 0..3
* - cset
- chN-offset
- rw
- 0
- [-5000; 5000]
- N = 0..3
* - cset
- chN-vref
- rw
- 17
- [0, 17, 35, 69]
- N = 0..3
* - cset
- chN-saturation
- rw
- 32767
- [0;32767]
- N = 0..3
* - cset
- fsm-auto-start
- rw
- 0
- [0, 1]
-
* - cset
- fsm-command
- wo
-
- [1, 2]
- 1: start, 2: stop
* - cset
- fsm-state
- ro
-
-
- hw values
* - cset
- max-sample-mshot
- ro
-
-
- hw value
* - cset
- resolution-bits
- ro
- 14
-
-
* - cset
- rst-ch-offset
- wo
-
- any
-
* - cset
- sample-decimation
- rw
- 1
-
-
* - cset
- sample-frequency
- ro
-
-
-
* - cset
- sample-counter
- ro
-
-
-
* - cset
- tstamp-acq-str-s
- ro
-
-
-
* - cset
- tstamp-acq-str-t
- ro
-
-
-
* - cset
- tstamp-acq-str-b
- ro
-
-
-
* - cset
- tstamp-acq-stp-s
- ro
-
-
-
* - cset
- tstamp-acq-stp-t
- ro
-
-
-
* - cset
- tstamp-acq-stp-b
- ro
-
-
-
* - cset
- tstamp-acq-end-s
- ro
-
-
-
* - cset
- tstamp-acq-end-t
- ro
-
-
-
* - cset
- tstamp-acq-end-b
- ro
-
-
-
* - chan
- current-value
- ro
-
-
-
* - trigger
- delay
- rw
- 0
- [0; ]
-
* - trigger
- enable
- rw
- 1
- [0, 1]
-
* - trigger
- external
- rw
- 1
- [0, 1]
-
* - trigger
- int-channel
- rw
- 0
- [0; 3]
-
* - trigger
- int-threshold
- rw
- 0
- [0; 65535]
- datum after offset/calibration
* - trigger
- nshots
- rw
- 1
- [0; 65535]
-
* - trigger
- polarity
- rw
- 0
- [0, 1]
- 0: raising, 1: falling
* - trigger
- post-samples
- rw
- 0
- Any
- max 2K if multishot
* - trigger
- pre-samples
- rw
- 0
- Any
- max 2K if multishot
* - trigger
- sw-trg-enable
- rw
- 0
- [0, 1]
-
* - trigger
- sw-trg-fire
- wo
- -
- Any
-
* - trigger
- tstamp-trg-s
- ro
-
-
-
* - trigger
- tstamp-trg-t
- ro
-
-
-
* - trigger
- tstamp-trg-b
- ro
-
-
-
Reading Data with Char Devices
------------------------------
To read data from user-space, applications should use the ZIO char
device interface. ZIO creates 2 char devices for each channel (as
documented in ZIO documentation). The ADC acquires only interleaved
samples, so ZIO creates two char device, as shown below::
$ ls -l /dev/zio/
total 0
crw------- 1 root root 250, 8 Aug 23 22:21 adc-100m14b-0200-0-i-ctrl
crw------- 1 root root 250, 9 Aug 23 22:21 adc-100m14b-0200-0-i-data
The actual pathnames depend on the version of udev you are running. The
fmc-adc library tries both names (the new one shown above, and the older
one, without a ``zio`` subdirectory). Also, please note that a still-newer
version of udev obeys device permissions, so you'll have read-only and
write-only device files (in this case they are both read-only).
If more than one board is probed for, you'll have two or more similar
pairs of devices, differing in the dev_id field, i.e. the ``0200`` shown
above. The dev_id field is built using the PCI bus and the devfn octet;
the example above refers to slot 0 of bus 2. (Most of the time each
PCI-E physical slot is mapped as a bus, so the slot number is usually
zero).
The ADC hardware does not allow to read data from a specific channel;
data is only transferred as an interleaved block of samples. Neither the
ZIO core nor the driver split interleaved data into 4 different buffers,
because that task is computationally intensive, and is better left to
the application (which may or may not need to do it). Thus, the driver
returns to user-space a block of interleaved samples.
To read this interleaved block you can read directly the interleaved
data char device adc-100m14b-0200-0-i-data using any program, for
example cat or hexdump::
$ hexdump -n 8 -e '"" 1/2 "%x\n"' /dev/zio/adc-100m14b-0200-0-i-data
fffc
e474
8034
8084
The ADC hardware always interleaves all 4 channels, and you cannot
acquire a subset of the channels. The acquired stream, thus, follows
this format:
.. figure:: img/interleaved.pdf
:alt: ADC interleaved data
The char-device model of ZIO is documented in the ZIO manual; basically,
the ctrl device returns metadata dna thr data device returns data. Items
in there are strictly ordered, so you can read metadata and then the
associated data, or read only data blocks and discard the associated
metadata.
The ``zio-dump`` tool, part of the ZIO distribution, turns metadata and data
into a meaningful grep-friendly text stream.
User Header Files
-----------------
Internally the driver uses the header file ``fmc-adc-100m14b4cha.h`` for the
declaration of all the functions, constants and structures. Some of these are
also available for the user-space programs; especially the constants to be
used to properly interpret the ``zio_control`` attributes, or the bitmask
fields definitions.
Troubleshooting
---------------
This chapter lists a few errors that may happen and how to deal with
them.
Installation issue with modules_install
'''''''''''''''''''''''''''''''''''''''
The command ``sudo make modules_install`` may place the modules in the wrong
directory or fail with an error like::
make: *** /lib/modules/<kernel-version>/build: No such file or directory.
This happens when you compiled by setting ``LINUX=`` and your sudo is not
propagating the environment to its child processes. In this case, you
should run this command instead::
sudo make modules_install LINUX=$LINUX
doc/index.rst 0 → 100644
View file @ c05f4525
Welcome to FMC ADC 100M 14 bit 4 Channel's documentation!
=========================================================
This is the user manual of the driver for the `FMC ADC 100M 14b 4cha`_
board developed on the `Open Hardware Repository`_. FMC is the form
factor of the card, ADC is its role, 100M means it can acquire
100Msample per second, 14b is the numbers of meaningful bits and 4cha
states it has 4 input channels (plus a trigger input).
The project has been splitted in sub-projects, one for each development
domain: `hardware`_, `gateware`_ and `software`_.
.. _`Open Hardware Repository`: http://www.ohwr.org/
.. _`FMC ADC 100M 14b 4cha`: http://www.ohwr.org/projects/fmc-adc-100m14b4cha
.. _`hardware`: https://www.ohwr.org/projects/fmc-adc-100m14b4cha-hw
.. _`gateware`: https://www.ohwr.org/projects/fmc-adc-100m14b4cha-gw
.. _`software`: https://www.ohwr.org/projects/fmc-adc-100m14b4cha-sw
.. toctree::
:maxdepth: 2
:caption: Contents:
driver-user
driver-devel
driver-tools
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
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