Mce cmd

Related topics:

► Communication

▼ Commanding‎ (3 P)

  MCE commands

  Mce cmd

  STOP Command

Related topics:

► MAS

▼ MAS Applications‎ (8 P)

  Dsp cmd

  Dsp status

  Mas param

  Mas var

  Maslog

  Mce cmd

  Mce status

  Psc status

mce_cmd provides an interface between a Linux shell and the MCE. The application can run interactively (accepting commands from a user and issuing responses to stdout), or can be used to execute scripts containing mce_cmd instructions.

Running mce_cmd

Usage summary

mce_cmd [options] [-x cmd...]

 -i                     interactive mode, don't exit on errors
 -q                     quiet mode, only print errors or output data
 -p                     prefix-supression, don't print line number
 -e                     echo mode, print each command as well as response
 -r                     don't use readline on stdin (faster input in scripts)

 -n <card number>       use the specified fibre card (Multicard MAS only)
 -c <file>              choose a particular mce config file (mce.cfg)
 -m <file>              choose a particular MAS config file (mas.cfg)
 -f <batch file>        run commands from file instead of stdin
 -X "cmd string"        execute this command and exit (these can be stacked)
 -o <directory>         data file path

 -x <command>           execute remainder of line as an mce_cmd command
                        The -X command may be more useful as it allows multiple
                        commands to be executed, e.g.
                             mce_cmd -X "acq_config test_1 rc1" -X "acq_go 100"

 -v                     print version string and exit

Interactive mode

When invoked with the '-i' option, mce_cmd can be used interactively. A session command history (similar to the one in bash) can be accessed with the up and down arrow keys, and line editing is possible using emacs-based key-mappings.

mce_cmd -i

After displaying a version message, mce_cmd will be ready to accept input. There is no user prompt.

Single command execution

A single command can be issued using the '-x' option:

mce_cmd -x rb cc fw_rev

The application will execute the command, display any output, and exit.

Multiple commands may be executed with the '-X' option. The commands are executed in order, in the same context. The command must be passed as a single shell argument (put it in quotes...):

mce_cmd -X "wb rc1 data_mode 4" -X "wb rca servo_mode 1"

Script execution

The '-f' option tell mce_cmd to read lines from the specified file and attempt to execute them. The '-q' option suppresses unnecessary output.

mce_cmd -q -f my_script.scr

When redirecting commands to mce_cmd, the '-r' option should be used to disable the command history/line editing features of mce_cmd and decrease the execution time.

cat my_script.scr | mce_cmd -q -r

If a script command fails, mce_cmd will exit. To suppress that behaviour (and continue attempting commands even after one of them has failed), pass the '-i' option.

Commands

We can break the mce_cmd command set into several broad categories:

• Special hardware commands, used to reset the MCE or DSP program
• Special driver access commands, used to manipulate the kernel driver state
• Scripting and output formatting commands, which control the behaviour of mce_cmd itself, rather than the MCE
• MCE data block commands, used to read or write MCE parameters
• MCE data acquisition commands, used to control a data acquisition
• Voluntary lock-out commands, to prevent multiple agents from accessing the MCE at the same time

It also provides access to various low-level functionality:

• Low-level MCE commands, MCE commands which are typically abstracted by higher-level commanding
• Raw commands, unformatted commands which bypass the MCE command description (mce.cfg)

Special hardware commands

MCE_RESET: reset the MCE firmware using special character override

The mce_reset command causes the PCI card to transmit a special character (0x0b) over the fibre-optic connection to the MCE. This command was originally invented to clear the cmd/reply path when either of fibre or backplane communication is frozen. A tiny sniffer block in clock-card of the MCE detects this special character and asserts the mce_bclr line, which subsequently resets (only) the firmware on each MCE card.

Upon firmware reset, all state machines go to idle, register-based variables are reset to 0, but RAM-based variables stay unchanged. A firmware reset does not refresh the DAC outputs. Note that after an mce_reset, not all of the DAC outputs are set to zero.

mce_reset may lead to misleading information from mce_status, and rb commands in general. For example, flux_fbs are stored in registers which are overwritten by zero upon mce_reset. But mce_reset does not cause a rewrite of the DAC outputs. So, after a reset, rb flux_fb will report zero even if the actual flux_fb being applied is not zero. Other registers, such as servo_mode, which get reset, do affect the operation of MCE. Registers can only reinitialised by rewriting them (via a wb command). In gerenal, a mce_reconfig is recommended after mce_reset to ensure the system is properly configured.

It is advisable to wait several microseconds following the mce_reset command before issuing other MCE commands.

Syntax:

mce_reset

DSP_RESET: reset the PCI card DSP firmware

The dsp_reset command causes the PCI card to reset.

Syntax:

dsp_reset

After the reset, the quiet RP mode parameters will be restored, if active.

Special driver access commands

FAKESTOP: cause the driver to issue a stop-frame

In some cases an acquisition can hang because it has not received as many frames as it expected, and did not see a frame with the STOP bit set. The fakestop command triggers the driver to generate one or two data frames and place them in the output buffer. The last such frame will have the STOP bit set. An mce_cmd session that is acquiring data will receive the frame, see the STOP bit, and exit.

Note that in the absence of a data consumer, this command will leave frames outstanding in the data buffer. It is prudent to issue an empty command after issuing fakestop.

Syntax:

fakestop

EMPTY: cause the driver to empty the output data buffer

In some cases, following a failed acquisition, the output data buffer of the driver may contain residual data. This can lead to the failure of subsequent acquisitions. The empty command causes the driver to update its pointers such that no data is retained.

Syntax:

empty

FRAME: set driver and PCI card frame-data size

To acquire data without an associated data handler (to write the data to disk), it is necessary to inform the driver and PCI card of the expected frame size. This is accomplished by passing the frame size, in 32-bit words, to the command frame. If data acquisition is triggered (with the low-level go command, for example), and the driver/PCI card have not been informed of the frame size, the PCI card will simply discard the data.

Syntax:

frame <int>

Scripting and output formatting

SLEEP: delay execution for some number of microseconds

Note that the delays smaller than a few milliseconds cannot be commanded reliably.

Syntax:

sleep <microseconds>

DISPLAY: change integer output base

The output from MCE read commands is displayed in decimal or hex, depending on the mce.cfg configuration. To override this, decimal (dec) or hexadecimal (hex) output can be forced with the display command. Passing def will return mce_cmd to its default behaviour.

Syntax:

display [ def | dec | hex ]

ECHO: echo commands to the terminal

In some scripting situations it may be useful to have commands echoed to the terminal along with their responses. This can be turned on and off by passing 1 or 0 to the echo command.

Syntax:

echo [ 0 | 1 ]

MCE data block commands

MCE configuration data is stored in blocks at certain card and parameter addresses (which we will call "block locations"). A typical block address is

rc2 flx_quanta4

This block consists of 41 32-bit words where the user writes the squid-1 flux quantum size for column 4 on readout card 2.

The most basic data manipulation commands are RB ("read block") and WB ("write block"). These commands read from or write to the entire range of data at the block location, starting at the beginning of the block.

The commands RRA ("read range") and WRA ("write range") can be used to read or write particular subranges of the data in a block location.

All read and write commands take a card (or virtual cards) name and a parameter name as the first two arguments.

RB: read block

The read block (rb) command returns the entire contents of a block location.

Syntax:

rb  <card> <param>

Example:

rb rc1 adc_offset0
Line   1 : ok : 10 11 9 8 12 13 14 15

WB: write block

The write block (wb) command writes the given data to the specified block location. If the number of data is smaller than block size, the remaining block elements will not be altered. If the number of data is larger than the block size, the behaviour depends on the implementation of the block location.

Syntax:

wb  <card> <param> [val0 val1 val2 ...]

Example:

wb rc1 adc_offset0 0 1 2
Line   1 : ok
rb rc1 adc_offset0
Line   2 : ok :  0 1 2 8 12 13 14 15

RRA: read range

The read range (rra) command returns <count> values from the block location, starting from the value at <start_index> (indexed from 0).

Syntax:

rra <card> <param> <start_index> <count>

Example:

rra rc1 adc_offset0 2 4
Line   1 : ok : 2 8 12 13

WRA: write range

The write range (wra) command writes the given values into the block location, starting at <start_index> (indexed from 0). Other block data (i.e. at indices lower than start_index) are not changed. (This command is implemented as a read-update-write and will usually take twice as long to execute as a wb command.)

Syntax:

wra <card> <param> <start_index> [val0 val1 val2 ...]

Example:

wra rc1 adc_offset0 4 100 200
Line   1 : ok
rb rc1 adc_offset0
Line   2 : ok :  0 1 2 8 100 200 14 15

MCE data acquisition commands

The acquisition of frame data is achieved by first configuring an output system (by specifying an output format, filename, and the target readout cards), and then by issuing acq_go commands to acquire frames.

This simplest example will acquire 1000 frames from rc2 into the file /data/cryo/current_data/test:

acq_config /data/cryo/current_data/test rc2
Line   1 : ok
acq_go 1000
Line   2 : ok

The configuration commands have mnemonics that begin with acq_config. They allow a small variety of output formats.

ACQ_CONFIG: configure simple MCE frame file

The ACQ_CONFIG command configures a single output file to receive MCE frames.

Syntax:

acq_config <filename> <readout_card>

Example:

acq_config test1.dat rc2

ACQ_CONFIG_FS: configure file-sequenced MCE frame file

The ACQ_CONFIG_FS command will result in the outputting of the frame data into a set of files whose filename contains an increasing index. The output file is changed after <change_interval> frames. The output files will be called <filename>.000, <filename>.001, etc.

Syntax:

acq_config_fs <filename> <readout_card> <change_interval>

ACQ_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS: dirfile-based acquisitions

The ACQ_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS commands behave analogously to ACQ_CONFIG and ACQ_CONFIG_FS except they acquire data to a Dirfile instead of to a MCE frame file.

Syntax:

acq_config_dirfile <dirfilename> <readout_card>

and:

acq_config_dirfile_fs <dirfilename> <readout_card> <change_interval>

ACQ_GO: acquire frame data

The ACQ_GO command causes the MCE to begin acquiring data. The frame data will be stored according to the most recent ACQ_CONFIG... command. It is not usually necessary to reconfigure the output system (i.e. perform another ACQ_CONFIG) between ACQ_GO commands. The exception to this is that if the frame structure changes (i.e. "cc num_rows_reported" is altered), then ACQ_CONFIG should be issued again so that the acquisition system can determine the frame size.

Syntax:

acq_go <frame_count>

Example:

acq_config tes_bias_ramp rc1
wb tes bias 5 5 5
acq_go 1
wb tes bias 10 10 10
acq_go 1

ACQ_PATH: set the default path for data output

The ACQ_PATH command sets the default output directory for frame data. This path is only applied if the filenames given in an ACQ_CONFIG... do not specify a relative path. The given path can be absolute, or relative to the mce_cmd's run-time working directory. The default output location can also be specified using the '-o' command line option.

Syntax:

acq_path <path>

Example:

acq_path /data/cryo/current_data
acq_config test1 rc1
acq_go 10

ACQ_LINK: turn on updating a symlink to the current acquisition

The ACQ_LINK command specifies the name of a symlink which will be created/retargeted to a current acquisition. This command only schedules the creation/retargeting of the link. The link is modified by an ACQ_CONFIG.... As a result this command must be used before an ACQ_CONFIG... for it to do anything. As with the filename specified in ACQ_CONFIG and friends, if the specified name is not an absolute path, the path specified by ACQ_PATH or the -o option will be prepended. If doing a sequencing acquisition (either ACQ_CONFIG_FS or ACQ_CONFIG_DIRFILE_FS) the link will be updated whenever a new file is started.

Syntax:

acq_link <name>

Example:

acq_path /data/cryo/current_data
acq_link mas.lnk
acq_config test1 rc1
acq_go 10

ACQ_OPTION: set various acquisition options

The ACQ_OPTION command allows you to modify various optional parameters for a particular acquisition. Options are grouped by acquisition type (either "dirfile" or "flatfile", ignoring sequencing), and vary between acquisition type. They must be specified before configuration to take effect. Options are not persistent: an ACQ_CONFIG-type command consumes and then resets all relevant options to their default value after configuration (so ACQ_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS reset the dirfile options after applying them to the acquisition it is configuring, but ACQ_CONFIG will neither reset nor use them).

Syntax:

acq_option <acq_type> <option_name> <option_value>

Currently, only acq_type "dirfile" has any options. These are:

• include <filename>: copies contents of the specified file to the output dirfile metadata. The file is copied verbatim, but the contents are not verified by MAS to see if it makes sense to use it as dirfile metadata. Default is the empty string, indicating no inclusion. If <filename> is a relative path, it will be to the current directory. (ie. it ignores both the -o option and ACQ_PATH)
• spf <number>: sets the samples-per-frame of the fields in the dirfile to the specified value, which must be positive. Default is one.
• version <number>: sets the Dirfile Standards Version used to write the dirfile metadata. This can be any integer greater than or equal to 3 (a smaller number results in the default, 7, being used), but only a few values are really of interest:
  • Versions < 7 are unable to properly extract signed bitfields from the packed MCE data. This affects data modes 4, 5, 7, and 10.
  • Versions > 4 can't be read by default builds of kst-1.x. (It is possible to build kst-1.x against a modern GetData library, making newer Dirfiles readable, although I don't think any distro shipping kst-1 has done this.)

Setting this to 4 should recover the behaviour of older versions of MAS. Also note: the dirfile formatted runfile metadata output by "mce_status -d" requires at least Version 8 to parse, but does not depend on, nor is affected by, the Version number specified here.

Example:

acq_option dirfile include /path/to/extra/format_metadata
acq_option dirfile version 4
acq_link mas.lnk
acq_config_dirfile test1 rc1
acq_go 10

ACQ_MULTI_BEGIN and ACQ_MULTI_END: manage multiple output syncs

In some cases it may be desirable to output to multiple files at the same time (e.g. to record a dirfile and a flatfile simultaneously). This is achieved my putting mce_cmd into "multisync" mode, creating a few different output configurations with an ACQ_CONFIG..., and then issuing ACQ_GO. The ACQ_MULTI_BEGIN command clears the acquisition stack and puts mce_cmd into multisync mode. The ACQ_MULTI_END command clears the acquisition stack and disables multisync mode. An ACQ_MULTI_END command is implicitly executed when mce_cmd exits, so it is not usually necessary to execute this command explicitly.

Syntax:

acq_multi_begin
acq_multi_end

Example (output to flatfile and dirfile simultaneously):

acq_multi_begin
acq_config 1234560000_flat rcs
acq_config_dirfile 1234560000_dirfile rcs
acq_go 164000

Voluntary lock-out mechanism

The driver supports a voluntary lock-out mechanism to help prevent two agents from accessing the MCE simultaneously. The MAS driver, API, and mce_cmd provide convenient access to a locking mechanism, but the user must add the appropriate calls into their acquisition scripts. The general idea is:

• An acquisition script should issue "LOCK_DOWN" to acquire The Lock for a given MCE.
• If the LOCK_DOWN fails, it is because some other process holds the lock.
• The script can release The Lock by issuing LOCK_UP.
• If mce_cmd exits while The Lock is held, The Lock will automatically be released (this is so that random crashes do not leave The Lock locked).

LOCK_DOWN: acquire lock

Issuing LOCK_DOWN causes the driver to check the lock for the target PCI card. If the lock is available, it is acquired. Subsequent attemps to LOCK_DOWN will fail, whether they come from other processes or the present process.

Syntax:

lock_down

LOCK_UP: release lock

Issuing LOCK_UP causes the lock to be released.

Syntax:

lock_up

LOCK_QUERY: check state of lock

The LOCK_QUERY command allows a script to inspect the state of the lock. The output from the command is 1 if the lock is held, and 0 if the lock is free. (We recognize that this conflicts with the usual counting strategy for semaphores.)

Note that if LOCK_QUERY returns 1, that is not a guarantee that LOCK_DOWN will succeed. But if you hurry, maybe it will.

Syntax:

lock_query

LOCK_RESET: reset state of lock

The lock can be forcefully reset (to the unlocked state) with the LOCK_RESET command. Note that using LOCK_RESET in a script is likely to defeat the point of the locking mechanism. It is mostly for hacking.

Syntax:

lock_reset

Low-level MCE commands

GO

Issuing GO sends a MCE command packet to the MCE, but with no associated additional processing. That is, even though GO causes the MCE to produce frame data, the frames will not be stored to disk and they will either accumulate in the driver's buffer or be discarded by the PCI card if they are not of the expected size. In general, the MAS acquisition system (ACQ_GO, &c.) should be used instead of sending this command directly.

The only parameter which responds to GO is the readout card's ret_dat parameter.

Syntax:

go <card> <param>

STOP

See: The STOP Command

The STOP command is intended for terminating MCE frame data acquisitions. The only parameter which responds to STOP is the readout card's ret_dat parameter.

Syntax:

stop <card> <param>

Examples:

stop rcs ret_dat

RS

The RS command is used to activate a few special command registers. Registers which use RS have the type rs in the MCE commands list. They are mostly commands which reset devices in the MCE (RS stands for reset), which means they must reply to the request before executing the command, unlike a normal WB command, which replies after execution.

Note: although the command list indicates that RS commands take a single parameter with a value of 1, this is not needed when calling the command from MAS. MAS ignores parameters passed to a RS command and will always issue the command with the 1 datum. So, don't pass any data to a RS command.

Syntax:

rs <card> <param>

Example:

rs cc config_fac

Raw commands

In addition to the formatted commanding discussed above, raw reads and writes can be issued to the MCE by specifying numeric register addresses (and, optionally, a numeric card ID). Raw commands can be used to access command registers which are not defined in the hardware description file (mce.cfg).

Numeric card IDs are given in the following table:

Card ids

Card	Card id	Upper card ID v6 firmware only	Notes
PSUC	0x01	—	Obsolete.
Clock card	0x02
Readout card 1	0x03	0x13	Upper card IDs supported only with version 6 firmware and only for certain parameters.
Readout card 2	0x04	0x14
Readout card 3	0x05	0x15
Readout card 4	0x06	0x16
Bias card 1	0x07	0x17
Bias card 2	0x08	0x18
Bias card 3	0x09	0x19
Address card	0x0A	0x1A
rcs (All RCs)	0x0B	—	Use only with ret_dat.
bcs (All BCs)	0x0C		Not supported by mce_cmd.
All FPGAs	0x0D
All cards	0x0E		Not supported by mce_cmd. This is not the sys multi-address physical card.

The last three of these (0x0C, 0x0D, 0x0E) are not supported by MAS or mce_cmd. Sending commands to them will result in strange behaviour.

Syntax:

rb <card> <register> <count> [multiplier]
wb <card> <register> val0 [val1 val2 val3 ...]
rra <card> <register> <start_index> <count>
wra <card> <register> <start_index> val0 [val1 val2 val3 ...]

Examples:

# read one sample from the clock card led register
rb cc 0x99 1

# the same, but by card ID:
rb 0x02 0x99 1

# set ac row_order, offset 12, to value 40
wra 0x0a 0x01 12 40

Because these requests bypass the command definitions in the hardware description file, a count of data to be returned must be specified with a read (RB) request. Raw commands cannot be issued to the virtual card mappings implemented by MAS (tes, sq1, sq2, &c.), nor the multi-address physical cards rca and sys.

Output formatting

Normally, mce_cmd produces a line of output following each command. The output consists of two or three parts, separated by colons. If in line prefix mode (which is the default) the output is:

Line <line number>: <success> [: data ... ]

The <success> indicator will be "ok" if the command succeeded, or "error" otherwise. Successful commands may return data (for example, an RB command). Failed commands will always return an error message as the data.

If mce_cmd is invoked with prefixes turned off ('-p'), the output format is

<success> [: data]

If mce_cmd is invoked in quiet mode ('q'), then all command responses that have no output data are suppressed. In quiet mode, "Line 12: ok" will not be displayed.