We list each of the functions in libsurf here. Most functions have board-based and module-based variants. The listing is grouped by functionality.
surf_init
-- initialize libsurf
int surf_init ();
surf_init
initializes the library. Among the initialized
data structures are the mutexes for access to the module table and to the SURF boards, so it is essential that surf_init
be called before any threads
are spawned.
0 on succes, on error.
surf_mod_sel_rd
,
surf_mod_sel_wr
,
surf_mod_unsel_wr
,
surf_brd_sel_rd
,
surf_brd_sel_wr
,
surf_brd_unsel_wr
,
surf_brd_sel_wr_glob
-- select a module for reading/writing from/to the
TPCC
int surf_mod_sel_rd (const char *mod);
int surf_mod_sel_wr (const char *mod);
int surf_mod_unsel_wr (const char *mod);
int surf_brd_sel_rd (const char *brd, int chn);
int surf_brd_sel_wr (const char *brd, int chn);
int surf_brd_unsel_wr (const char *brd, int chn);
int surf_brd_sel_wr_glob (const char *brd);
The sel_rd
and sel_wr
functions select a module,
either
named mod
or plugged into channel chn
() on the
board with serial number brd
, for reading/writing from/to the
TPCC. If a module is selected for writing, the DCI stream (but not
the clock) to the
other modules is suppressed. When the module is unselected, or when the
board receives a surf_brd_sel_wr_glob
call, DCI stream
transmission to the remaining modules resumes. When a module is
selected for reading, its DTO/DTO2 stream is transmitted to the
TPCC. sel_rd
and sel_wr
calls are not independent;
unless global writing is set, the module selected for writing is the
same as the module selected for reading, and the last sel_rd
or
sel_wr
determines which module is selected.
On error surf_errno
is set and is returned. Otherwise the
number of bytes transmitted in the last data transfer over the USB is
returned.
surf_mod_get_sel_rd
,
surf_mod_get_sel_wr
,
surf_brd_get_sel_rd
,
surf_brd_get_sel_wr
-- find out which module is reading/writing from/to
the TPCC
int surf_mod_get_sel_rd (const char *mod);
int surf_mod_get_sel_wr (const char *mod);
int surf_brd_get_sel_rd (const char *brd, int chn);
int surf_brd_get_sel_wr (const char *brd, int chn);
blah blah blah
On error surf_errno
is set and is returned. If the module
indicated in the argument of get_sel_rd
is selected for reading
1 is returned; if it is not selected for reading 0 is returned. If
the module indicated in the argument of get_sel_wr
is selected
for writing 1 is returned; if it is not selected
for writing 0 is returned; if global writing is selected on the board
to which the module is connected SURF_GLOB_WRITE
is returned.
surf_mod_ena
,
surf_mod_end
,
surf_brd_ena
,
surf_brd_end
-- enable analog/digital regulators
int surf_mod_get_sel_rd (const char *mod);
int surf_mod_get_sel_wr (const char *mod);
int surf_brd_get_sel_rd (const char *brd, int chn);
int surf_brd_get_sel_wr (const char *brd, int chn);
blah blah blah
blah blah blah
surf_mod_set_anl_v
,
surf_mod_set_dig_v
-- set analog/digital regulator voltages
foo
These functions are going the way of the dodo.
surf_mod_get_anl_v
,
surf_mod_get_dig_v
-- get analog/digital sense voltages
double surf_mod_get_anl_v (const char *mod);
double surf_mod_get_dig_v (const char *mod);
These functions are here to stay. They use the ground sense to calculate their answer.
on error.
surf_brd_get_anl_v_adc
,
surf_brd_get_dig_v_adc
-- get analog/digital/ground sense voltage ADC counts
int surf_brd_get_anl_v_adc (const char *brd, int chn);
int surf_brd_get_dig_v_adc (const char *brd, int chn);
int surf_brd_get_gnd_v_adc (const char *brd, int chn);
foo
on error.
surf_mod_get_anl_i
,
surf_mod_get_dig_i
-- get analog/digital supply currents
double surf_mod_get_anl_i (const char *mod);
double surf_mod_get_dig_i (const char *mod);
These functions are way cool.
on error.
surf_mod_get_temp
- get module NTC temperature
double surf_mod_get_anl_i (const char *mod);
double surf_mod_get_dig_i (const char *mod);
These functions are way cool.
on error.
surf_load_mod_tbl
, surf_print_mods
,
surf_mod_tbl_get_mod
-- load/print the
module table; get entries from the module table
int surf_load_mod_tbl (const char *file_name);
void surf_print_mods ();
int surf_mod_tbl_get_mod (char *name, int i);
The module table is a map that says which module is plugged into which channel on which SURF board. libsurf must be given such a map before you can use any module-based libsurf functions.
libsurf provides the function surf_load_mod_tbl
to
allow the user to add entries to the module table maintained in memory
by libsurf. surf_load_mod_tbl(const char *file_name)
loads the
module entries from the file with name file_name
into the module
table, superseding existing entries if the file contains entries with
the same module serial number. The file should contain lines of the
form
board_serial_number channel module_serial_number <newline>Comments are begun by
/*
and terminated by */
. The
#
character indicates that the text to the next newline is
comment. An
example file is given in libsurf/mod.table
; it looks like this:
If libsurf encounters syntax errors in the file, it will complain; entries read before errors are encountered are added to the module table.# $Id: surf.tex,v 1.16 2004/04/01 05:37:02 jmuelmen Exp $
# The format of this file is
# <board SN> <chan> <module SN>
# modules connected to 20040LBL006:
200402LBL006 0 M510177
200402LBL006 2 M510176
200402LBL006 3 M510175
200402LBL006 1 M510174
# modules connected to 20040LBL004:
200402LBL004 0 M500174
200402LBL004 2 M500175
200402LBL004 3 M510178
200402LBL004 1 M510170
When libsurf is compiled as part of AMBUSH, i.e. with the
LIBSURF_LOG_TO_AMBUSH
defined, surf_load_mod_tbl
has an
additional effect: AMBUSH attempts to open log files in blah blah
blah.
surf_print_mods
prints the module table currently in libsurf memory.
surf_mod_tbl_get_mod
can be used to get a list of modules currently
in
surf_load_mod_tbl
, surf_print_mods
and
surf_mod_tbl_get_mod
are all thread-safe, as are the functions
libsurf uses internally when the surf_mod_
... family
of functions needs to resolve a module name.
foo bar