[Gb-ccb] Updated documentation and CCB code/firmware/documentation hierarchy
Martin Shepherd
mcs at astro.caltech.edu
Thu Nov 3 02:21:41 EST 2005
In addition to finishing a major update of the CCB documentation
(which I'll summarize shortly), I have now finished rationalizing the
CCB hierarchy. The CCB code, documentation and firmware all live under
a top-level CCB directory, which now also holds a single configure
script and the makefile that is used to build and install the CCB
libraries, programs and, optionally, the CCB documentation. A tar-file
of this hierarchy can be found in my home directory at Green Bank, and
is called:
~mshepher/ccb.tar.gz
It can also be downloaded using a link in the following web page:
http://www.astro.caltech.edu/~mcs/GBT/index.html
I untarred this to create the ~mshepher/CCB/ directory, and built and
installed everything in subdirectories of my home directory. For
reference I did this as follows:
# I went into my home directory and unpacked the CCB hierarchy there.
# This created ~mshepher/CCB/
cd ~mshepher
tar xzfp ccb.tar.gz # Unpack the CCB hierarchy
# I then created a temporary build directory in my home directory
# and went into that directory.
mkdir build
cd build
# Next I ran the CCB configuration script from within the build directory
# telling the configure script that I wanted the executables, libraries,
# include files, etc to be installed in subdirectories of my home
# directory, rather than subdirectories of /usr/local/.
../CCB/configure --prefix=/users/mshepher
# Next I compiled the libraries and the programs.
make
# The following statement installed the executables, etc into pertinent
# subdirectories of my home directory, as instructed above, when the
# configure script was run.
make install
# Next I performed the optional step of using LaTeX to create PDF files
# of all of the documentation.
make pdf
# Since the installation procedure doesn't know where to install PDF files,
# I then copied the files into ~mshepher/doc/.
cp *.pdf ~/doc/
# Finally I returned to the home directory, and deleted the redundant
# build directory.
cd
\rm -rf build
Now onto the documentation changes. There are now the following documents:
ccb_network_interface.pdf - (Heavily updated)
Documentation of all aspects of installation and usage of the
network interfacing libraries of the CCB, now including not only
the manager and server interface libraries, but also the dump-mode
client, and diagnostic client libraries.
ccb_diagnostic_programs.pdf - (A new document)
Documentation of the CCB diagnostic programs.
ccb_fpga_design.pdf - (Unchanged)
Documentation of the CCB firmware.
ccb_epp_driver.pdf - (A new document)
Documentation of the EPP device-driver that controls the CCB
firmware.
ccb_gpio_driver.pdf - (A new document)
Documentation of the I/O card driver that monitors the general
status of the CCB, and drives the front-panel LEDs.
ccb_external_hardware_interfaces.pdf - (Unchanged)
Documentation of the goals and rational behind the eventual
design of the external hardware interfaces of the CCB, intermixed
with the description of an early potential implementation, of
which only a few parts were actually used.
As indicated above, PDF versions of these documents can be found in
the ~mshepher/doc/ directory at Green Bank. I have also placed links
to network copies in the following web page.
http://www.astro.caltech.edu/~mcs/GBT/index.html
There have been a lot of changes to the ccb_network_interfaces.pdf
document. The following are the main changes:
Newly documented functions:
ccb_parse_CCBConfig() - Read a human-readable configuration
specification from a string (this is used
the diagnostic programs).
ccb_read_CCBConfig() - Read a human-readable configuration
specification from a text file.
ccb_print_CCBConfig() - Print the current CCB configuration to
the terminal.
ccb_write_CCBConfig() - Print the current CCB configuration to a
file.
ccb_zero_timestamp() - Zero-initialize a CCBTimeStamp object.
ccb_timestamp_to_time() - Convert the contents of a CCBTimeStamp
object to a standard UNIX time_t value.
ccb_calibrate_monitor_data() - Given a CCBRawMonitorData object containing
monitoring information in ADC counts,
from the GPIO card, convert the ADC counts
to appropriate physical units
(eg. PSU voltages), and record them in
a specified CCBMonitorData object.
ccb_display_monitor_data() - Display the contents of a CCBMonitorData
object, to the terminal, in the format that
is displayed by the ccb_monitor_status
program.
ccb_compute_led_states() - Given a CCBRawMonitorData object, compute the
states that the front-panel LEDs should
be given.
ccb_queue_set_dacs_cmd() - Queue a set-dacs command to be sent to the
CCB server. The set-dacs command can be used
to set the count values of the miscellaneous
digital-to-analog converters of the GPIO card.
ccb_parse_CCBPhaseSwitches() - Read a human-readable phase-switch
specification from a string.
ccb_render_CCBPhaseSwitches() - Write a human-readable phase-switch
specification to a string.
ccb_parse_CCBCalDiodes() - Read a human-readable cal-diode
specification from a string.
ccb_render_CCBCalDiodes() - Write a human-readable cal-diode
specification to a string.
ccb_queue_dump_frame_msg() - The server uses this to queue a dump-frame
message to be sent a remote dump-mode client.
ccb_phase_switch_sequence() - Return the current phase-switching pattern.
ccb_zero_integ_frame() - Zero-initialize a CCBIntegFrame variable.
ccb_zero_dump_frame() - Zero-initialize a CCBDumpFrame variable.
new_CCBDumpReader() - Open a passive connection to the dump-mode
port the CCB server.
ccb_get_CCBDumpReader_fd() - Enquire the file-descriptor that is used
by a given CCBDumpReader object, for use
by select().
ccb_read_dump_frame() - Read a single dump-mode frame from the
CCB server.
del_CCBDumpReader() - Disconnect and delete the resources of
a connection to the dump-mode port of
the CCB server.
new_CCBTestClient() - Create the resources needed by a
diagnostic client.
ccb_tst_connect_client() - Connect a diagnostic client to the
control, telemetry and dump-mode
ports of the CCB server.
ccb_tst_disconnect_client() - Disconnect a diagnostic client from the
CCB server.
del_CCBTestClient() - Disconnect and delete the resources of
a diagnostic client.
ccb_tst_update_conf() - Set the base-configuration of subsequent
scans requested by a diagnostic client.
ccb_tst_start_scan() - Start a new integration-mode scan for
a diagnostic client.
ccb_tst_read_integ_frame() - Read an integration-mode frame for a
diagnostic client.
ccb_tst_start_dump() - Start a new dump-mode scan for
a diagnostic client.
ccb_tst_read_dump_frame() - Read a dump-mode frame for a
diagnostic client.
ccb_tst_mean_of_dump() - Compute the mean and RMS noise of the
samples in a dump-mode frame.
ccb_tst_get_config() - Get the current scan-configuration of
a diagnostic client.
ccb_tst_set_dacs() - Set the analog outputs of the GPIO card
for a diagnostic client.
ccb_fake_integrations() - Compute the expected per-bin integrated
values of fake samples, pertaining to a
given scan-configuration.
Modified server functions:
new_CCBServerDriver() - This now takes an extra argument (set_dacs).
ccb_queue_monitor_msg() - This now has an CCBRawMonitorData argument
instead of an array of monitor points
and a corresponding number of values.
ccb_queue_integ_msg() - This now takes a CCBIntegFrame arg instead
of the details of the integration frame
being split into separate arguments.
New DataTypes:
CCBSetDacsFn - The server driver-callback that responds
to the new set-dacs command.
CCBRawMonitorData - The structure that encapsulates monitoring
data received from the GPIO driver.
CCBRawFpgaMonitorData - The structure that encapsulates fpga-specific
parts of the monitoring data that are
received from the GPIO driver.
CCBPanelLed - An enumeration of the front-panel LEDs.
CCBIntegFrame - The structure that encapsulates the details
of a frame of integrated data.
CCBDumpFrame - The structure that encapsulates the details
of a frame of dump-mode data.
CCBDumpReader - The object that encapsulates the resources
that are used by passive dump-mode clients
to receive data from the dump-mode port of
the CCB server.
CCBTestClient - The object that encapsulates the resources
that are used by diagnostic clients to talk
to the CCB server.
CCBSetDacsCmd - The network object of the set-dacs command.
Modified Data-types:
CCBDrvDumpScan - This no longer has a 'frames' member, since
the job of limitating the number of frames that
are sent to clients has been moved out of the
server-driver level, to the CCB dump-mode server
module.
CCBControlCommandType - This has a new CCB_SET_DACS_CMD enumerator, used
to identify network messages that contain set-dacs
commands.
CCBControlCommand - This has a new set_dacs member.
New function macros:
CCB_SET_DACS_FN() - The macro that declares the server-driver-callbacks
that implement the set-dacs command.
CCB_DUMP_PHASE_A() - This macro calculates the state of phase-switch A
for a given sample within a dump-mode frame.
CCB_DUMP_PHASE_B() - This macro calculates the state of phase-switch B
for a given sample within a dump-mode frame.
CCB_NEXT_FAKE_SAMPLE() - This macro implements the recurrence relation that
computes the next value in the sequence of fake
samples.
New constant macros:
CCB_NUM_SLAVE - The number of CCB slave FPGAs.
CCB_NUM_FPGA - The total number of CCB FPGAs.
CCB_ADC_SAMPLE_SIZE - The number of bits per ADC sample.
CCB_ADC_OVERFLOW_MASK - A bit-mask that selects the overflow
bit of a dump-mode sample.
CCB_ADC_SAMPLE_MASK - A bit-mask that selects the data-bits
of a dump-mode sample.
CCB_FAKE_CYCLE_LENGTH - The number of fake samples before the
sequence of fake samples repeats.
CCB_FIRST_FAKE_SAMPLE - The value of the first fake sample of
a new integration period.
CCB_SATURATED_INTEGRATION - The value that signifies that the value
in an integration bin overflowed.
CCB_MAX_SAMP_PER_STATE - The maximum value of the samp_per_state
configuration parameter.
CCB_MAX_PHASE_SWITCH_DT - The maximum value of the phase_switch_dt
configuration parameter.
CCB_MAX_DIODE_FALL_DT - The maximum value of the diode_fall_dt
configuration parameter.
CCB_MAX_DIODE_RISE_DT - The maximum value of the diode_rise_dt
configuration parameter.
CCB_MAX_INTEG_PERIOD - The maximum value of the integ_period
configuration parameter.
CCB_MAX_ROUNDTRIP_DT - The maximum value of the roundtrip_dt
configuration parameter.
CCB_MAX_HOLDOFF_DT - The maximum value of the holdoff_dt
configuration parameter.
CCB_MAX_ADC_DELAY - The maximum value of the adc_delay
configuration parameter.
CCB_MIN_INTEG_DT - The minimum value of the integ_dt
configuration parameter.
CCB_MIN_DIFF_INPUT - The most negative differential input
voltage that can be presented at any CCB
input port.
CCB_MAX_DIFF_INPUT - The most positive differential input
voltage that can be presented at any CCB
input port.
CCB_MAX_LOGID - The maximum ID currently used by any
logging statement in the CCB libraries.
Modified macros:
CCB_DUMP_MAX_SAMPLES - This now holds the actual maximum number
of dump-mode samples, rather than implying
this with the value zero.
Removed macros:
CCB_BASE_LOGID - This macro is now superfluous, because the scripts
that assign IDs to log statements now assign the
actual numbers, rather than numbers that had to
subsequently be offset by this macro. This change
was made to make it possible to grep for a given
logging statement number, without having to remember
to first subtract this offset number. The ID assignment
scripts now take care of ensuring that no ID is assigned
below the lower limit that this macro previously
contained.
Added modules:
libccbdump - This library is used by programs that want to receive
dump-mode data from the CCB server.
libccbtestclient - This library is used by diagnostic clients to control
and receive integration and dump-mode data from the
CCB server.
libccbcommon - Functions that were previously duplicated in the
libccbserverlink and libccbclientlink libraries have
been moved into this common library. This library
is automatically linked in whenever any of the other
libraries are requested at link time.
Installation:
There is now a single configure script and makefile for the code and
documentation. This lives in the top-level CCB directory. See the
installation section of the ccb_network_interfaces document for
details.
Titles of new tables:
3.1 "Textual configuration parameters and their values."
3.2 "The numeric labelling of the phase-switch bins."
4.1 "The ID numbers of the CCB cables."
4.2 "The ordering of the integrate data."
More information about the gb-ccb
mailing list