MCEWiki - User contributions [en]

Template:MCE hardware table

2022-03-23T23:34:42Z

Mhasse: Fix PDF link

<includeonly>{| class="wikitable"
! Component
! Type{{#if: {{{obsolete|}}}|/Part}}
! Doc. Id
! Technical<br/>Description<sup>&dagger;</sup>
! Block<BR/>Diagram<sup>&dagger;</sup>
! Schematics
! Rev.
! Notes
|-
| colspan="2" | [[Clock Card]]
| S581
| [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/CC_TechDescr.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/cc_bd.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Clock%20Card%20RevB/SC2-ELE-S581-101_RevB5_CC_Schematics.pdf PDF]]
| B5
|
|-
| colspan="2" rowspan="2" | [[Readout Card]]
| rowspan="2" | S582
| rowspan="2" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/SC2_ELE_S582_501_readout_card_description.pdf PDF]]
| rowspan="2" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/rc_bd.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Readout%20Card%20RevB/RO_S582_101BIss9_Schematic.pdf PDF]]
| B9
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Readout%20Card%20RevE/RC_C582_101E0_Schematic.pdf PDF]]
| E0
| Low-power RC
|-
| colspan="2" rowspan="9" | [[Bias Card]]
| rowspan="9" | S583
| rowspan="9" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/SC2_ELE_S583_501_bias_card_description.pdf PDF]]
| rowspan="9" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/bc_bd.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevD/BC_S583_101DIss6_Schematics.pdf PDF]]
| D6
| Original design
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevD/SC2-ELE-S583-101-RevDIss7&8_BiasCard_Schematics.pdf PDF]]
| D7/8
| High-current det_bias
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevD/SC2-ELE-S583-101D10_D11_BC_Schematic.PDF PDF]]
| D11
| High-current det_bias/no heater
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevE/BC_ELE_C583_101E0_Schematic.pdf PDF]]
| E0
| Multiple det_bias lines
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevF/ELE-C583-101F_BiasCard_Schematic.PDF PDF]]
| F0
| Multi det_bias & MHz-response bias lines; Low-noise bias lines turned off
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevF/ELE-C583-101F1_BiasCard_Schematic.PDF PDF]]
| F1
| Power turned off on ln_bias
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevF/ELE-C583-101F2_BiasCard_Schematic.PDF PDF]]
| F2
| Minor change in ln_bias circuit
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevF/ELE-C583-101F3_BiasCard_Schematic.PDF PDF]]
| F3
| low 1/f-noise opamp for channel 0-15
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Bias%20Card%20RevF/ELE-C583-101F4_BiasCard_Schematic.PDF PDF]]
| F4
| low 1/f-noise opamp for channel 15-31
|-
| colspan="2" rowspan="2" | [[Address Card]]
| rowspan="2" | S584
| rowspan="2" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/AC_TechDescr.pdf PDF]]
| rowspan="2" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/ac_bd.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Address%20Card%20RevC/AC_S584_101CIss4_Schematics.pdf PDF]]
| C4
|
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Address%20Card%20RevD/AC_S584_101_RevDIss0_Schematics.pdf PDF]]
| D0
|
{{#if: {{{obsolete|}}}|
{{!}}-
{{!}} rowspan="6" {{!}} [[Instrument Backplane]]
{{!}} rowspan="2" {{!}} MCEv1
{{!}} rowspan="2" {{!}} S587-101
{{!}} rowspan="6" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/instr_backplane_descr.pdf PDF]]
{{!}} rowspan="2" {{!}} —
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Instrument%20Backplane%20RevC/S587-101_Inst_Backplane_Schematics.pdf PDF]]
{{!}} C3
{{!}} Obsolete
{{!}}-
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Instrument%20Backplane%20RevC/S587-101CI5_Inst_Backplane_Schematics.pdf PDF]]
{{!}} C5
{{!}}
}}
|-
{{#if: {{{obsolete|}}}||
{{!}} rowspan="4" {{!}} [[Instrument Backplane]]
}}
| {{#if: {{{obsolete|}}}|MCEv2}} 5MDM
| C587-201
{{#if: {{{obsolete|}}}||
{{!}} rowspan="4" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/instr_backplane_descr.pdf PDF]]
}}
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_InstrumentBackplane/ELE_C587-201_RevA0_Inst_Backplane_Schematics.pdf PDF]]
| A
|
|-
| rowspan="3" | {{#if: {{{obsolete|}}}|MCEv2}} 3MDM
| rowspan="3" | C587-101
| rowspan="3" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/ELE-C580-100_MCEv2_Instrument_Bus_Block_Diagram.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_InstrumentBackplane/ELE-C587-101_RevB_Inst_Backplane_Schematic.pdf PDF]]
| B
|
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_InstrumentBackplane/ELE-C587-101_RevC1_3MDM_Inst_Backplane_Schematics.pdf PDF]]
| C1
|
|-
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_InstrumentBackplane/ELE-C587-101_RevC2_3MDM_Inst_Backplane_Schematics.pdf PDF]]
| C2
|
{{#if: {{{obsolete|}}}|
{{!}}-
{{!}} rowspan="3" {{!}} [[Bus Backplane]]
{{!}} MCEv1
{{!}} S586
{{!}} rowspan="3" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/bus_backplane_descr.pdf PDF]]
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/Firmware_block_spec/atc_blkdia/fw_blkdia/Subrack.pdf PDF]]
{{!}} —
{{!}} C
{{!}} Obsolete
}}
|-
{{#if: {{{obsolete|}}}||
{{!}} rowspan="2" {{!}} [[Bus Backplane]]
}}
| {{#if: {{{obsolete|}}}|MCEv2}} 3MDM
| C586-101
{{#if: {{{obsolete|}}}||
{{!}} rowspan="2" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/bus_backplane_descr.pdf PDF]]
}}
| rowspan="2" | —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_BusBackplane_RevD/ELE-C586-101_BusBP_Schematic%20Prints.pdf PDF]]
| A
|
|-
| {{#if: {{{obsolete|}}}|MCEv2}} 5MDM
| C586-201
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_BusBackplane_RevD/ELE-C586-201_RevD0_BusBp_Schematics.pdf PDF]]
| D
|
{{#if: {{{obsolete|}}}|
{{!}}-
{{!}} rowspan="3" {{!}} [[Filter Board]]
{{!}} MCEv1
{{!}} S587-111
{{!}} rowspan="3" {{!}} —
{{!}} rowspan="3" {{!}} —
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/Filter%20Board/FB_S587_111BIss2_Schematics.pdf PDF]]
{{!}} B2
{{!}} Obsolete
}}
|-
{{#if: {{{obsolete|}}}||
{{!}} rowspan="2" {{!}} [[Filter Board]]
}}
| {{#if: {{{obsolete|}}}|MCEv2}} 3MDM
| C587-111
{{#if: {{{obsolete|}}}||
{{!}} rowspan="2" {{!}} —
{{!}} rowspan="2" {{!}} —
}}
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_Filter_Board/ELE-C587-111_Filter_Schematic.pdf PDF]]
| A
|
|-
| {{#if: {{{obsolete|}}}|MCEv2}} 5MDM
| C587-210
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/mceV2_Filter_Board/ELE-C587-210_Filter_Schematics.pdf PDF]]
| A
|
{{#if: {{{obsolete|}}}|
{{!}}-
{{!}} rowspan="3" {{!}} [[Power Supply Assembly]]
{{!}} [[PSU]]
{{!}} S585-103
{{!}} —
{{!}} rowspan="3" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/SCUBA-2%20Power%20Supply%20Specification%20Aug-26-2005%20JM%20WH.doc DOC]]
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PowerSupplyUnit/PSU_S585_103B_20060502_schematics.pdf PDF]]
{{!}} B
{{!}} rowspan="3" {{!}} Obsolete
{{!}}-
{{!}} [[PSUC]]
{{!}} S585-102
{{!}} —
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PowerSupplyController/PSUC%20S585_102GIss8%20Schematic.pdf PDF]]
{{!}} G8
{{!}}-
{{!}} Wiring
{{!}} S585-104
{{!}} —
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/documentation/schematics_pcb/SC2-ELE-S585-104_RevB_PSA_Wiring_Diagram.pdf PDF]]
{{!}} B
}}
|}
'''<sup>&dagger;</sup>''': Not updated since early design stages.

=== External Hardware and Accessories ===
{| class="wikitable"
|-
! Component
! Part
! Doc. Id
! Technical<br/>Description<sup>&dagger;</sup>
! Block<BR/>Diagram
! Schematics
! Rev.
! Notes
|-
| colspan="2" | [[MDM Breakout Board]]
| S58H
| —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/MDM%20Pinout/SubrackIB-TestPinouts1b_Rev2.1.xls XLS]]
| B
|
|-
| colspan="2" | [[Linear Feed Card]]
| C585-104
| —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PLA/Linear_PS_MCE_Adaptor-ELE-C585-104_RevB.pdf PDF]]
| B
|
|-
| rowspan="2" | [[Vicor Power Assembly]]
| PCB
| C585-401
| rowspan="2" | —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PowerSupplyVicor/ELE_C585-401_RevC2_VicorPSU_Schematics.pdf PDF]]
| C2
|
|-
| Wiring Harness
| C584-402
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PowerSupplyVicor/ELE-C584-402_RevA_Wiring_Harness.pdf PDF]]
| A
|
|-
| rowspan="4" | [[Sync Box]]
| PCB
| S589-101
| rowspan="4" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf PDF]]
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/SyncBox/SC2-ELE-S589-101_RevA2_SyncGen_Schematics.pdf PDF]]
| A2
| Used in both Sync Box enclosures
|-
| AC-in: Internal Wiring
| S589-102
| rowspan="2" | [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/S589-001_Syncbox_Block_Diagram.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/SyncBox/S589-102_SyncBox_Wiring_Diagram.pdf PDF]]
| rowspan="2" | A2
|
|-
| AC-in: Cable Wiring
| S589-103
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/SyncBox/S589-103_SyncBox_IO_Cable_Wiring.pdf PDF]]
|
|-
| DC-in: Internal Wiring
| C589-102
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/ELE-C589-101B_DC-In_Sync_Blk_Diagram.pdf PDF]]
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/SyncBox/ELE-C589-102_Sync_Box_Connector_Pinouts.pdf PDF]]
| A
|
|-
| colspan="2" | [[PCI fibre card]]
| —
| —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/others/SDSU/250hzPCI_schematic.pdf PDF]]
| 5A
|
|-
| colspan="2" | [[Extender Card]]
| S565-008
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/ext_card_descr.pdf PDF]]
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/ExtenderCard/extender_card_sc2_ele_s58A_101B PDF]]
|
|
|-
| colspan="2" | [[IB Tester]]
| S58E-502
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/tech_description/sc2-ele-s58e-502_gpib_ib_tester_description.pdf PDF]]
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/IB%20Tester/ELE-S58E-101C_GPIB_IB_Tester_Schmatics.pdf PDF]]
| C
|
|-
| colspan="2" rowspan="2" | [[2-slot Backplane]]
| rowspan="2" | S58G
| —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/2slot_bp/SC2_ELE_S58G_101.pdf PDF]]
| A
|
|-
| —
| —
| [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/2slot_bp/2-slot_bp_SC2_ELE_S565_101_RevB0.pdf PDF]]
| B
|
{{#if: {{{obsolete|}}}|
{{!}}-
{{!}} colspan="2" {{!}} SCUBA2 24V Power Distribution
{{!}} S565-010
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/pdrdocs/24v_ps_descr.pdf PDF]]
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/board_block_diagram/24v_pwr_distr.pdf PDF]]
{{!}} —
{{!}}
{{!}} Obsolete
{{!}}-
{{!}} rowspan="3" {{!}} [[AC-DC Unit]]
{{!}} Rectifier Board
{{!}} S588-103
{{!}} rowspan="3" {{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/PowerSupplyUnit/SCUBA-2%20Power%20Supply%20Specification%20Aug-26-2005%20JM%20WH.doc DOC]]
{{!}} rowspan="3" {{!}} —
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/acdcu/S588_103A_acdcu_rect_%28051128gf%29.pdf PDF]]
{{!}} A
{{!}} rowspan="3" {{!}} Obsolete
{{!}}-
{{!}} Controller Board
{{!}} S588-104
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/acdcu/S588_104A_acdcu_cntrl_%28060719gf%29.pdf PDF]]
{{!}} A
{{!}}-
{{!}} Wiring
{{!}} S588-105
{{!}} [[http://www.phas.ubc.ca/%7Emce/mcedocs/hardware/schematics/acdcu/S588_105A_acdcu_wiring_%28060719gf%29.pdf PDF]]
{{!}} A
}}
|}
'''<sup>&dagger;</sup>''': Not updated since early design stages.</includeonly><noinclude>
This template contains the hardware document table. It comes in two flavours:

== Modern ==
{{MCE hardware table}}

is used on [[MCE hardware]] and produces:
{{MCE hardware table}}

== Legacy ==
{{MCE hardware table{{!}}obsolete=yes}}
is used on [[Old MCE Documents]] and produces:
{{MCE hardware table|obsolete=yes}}
</noinclude>

Main Page

2020-04-21T12:05:17Z

Mhasse:

This Wiki is for users of UBC's '''Multi-Channel Electronics''' (MCE), including the '''MCE Acquisition Software''' (MAS).
__NOTOC__
== MCE Overview ==
The MCE described here borrows heavily from the designs used at [http://www.nist.gov/pml/ NIST]. Changes have been made to upgrade components, achieve higher integration, and match to the specific experimental configurations.

In basic operation, one MCE [[subrack]] controls the SQUID amplifiers and multiplexer, and reads signals from one 32×41 pixel or 16×41 pixel sub-array. The system hardware is completely modular at the sub-array level. Each sub-array is connected via woven cryogenic cables to a single MCE subrack through 3 or 5 MDM connectors. Each MCE subrack is, in turn, connected by an optical fibre to a single data-acquisition PC running Linux and data-acquisition software ([[MAS]]) developed at UBC.

Each MCE consists of hybrid analog/digital hardware and firmware developed for [https://www.altera.com/ Altera] [https://www.altera.com/products/fpga/stratix-series.html Stratix FPGAs]. A subrack has up to nine cards: including 2 or 4 [[Readout card]]s each of which reads 8 output columns through 14-bit 50MHz ADCs; 1 [[address card]] to multiplex the first-stage SQUIDs biases at around 20kHz; 1 [[clock card]] to interpret commands and to synchronize all the cards using a 25MHz clock; 2 or 3 [[bias card]]s to control the SQUID series-array feedback, the second-stage SQUID bias and feedback as well as the bolometer bias and heater. During [[auto_setup|detector setup]], the MCE is used to calculate the optimal operating points for the bolometers and the SQUID amplifiers by measuring their characteristics using open and closed feedback loops. During observation, MCE uses a running PID-calculation to determine the first-stage SQUID feedback necessary to keep the whole amplification chain in a linear regime.

In conjunction with the MCEs, a [[Sync Box]] supplies data-valid pulses with serial numbers to all MCE subracks and to the telescope pointing system. This allows synchronization between the data acquisition, the pointing system, and the telescope housekeeping.

== Documentation ==

* [[ MCE hardware | MCE Hardware ]] - information on MCE hardware (and accessories)
* [[ MCE firmware | MCE Firmware ]] - firmware versions, features, and tools (including sync box and PCI card firmware)
* [[ MAS ]] - the MCE Acquisition Software - kernel driver and low-level tools
* [[ MCE script ]] - SQUID array setup programs
* [[ MCE usage ]] - practical usage and reference documents
* [[Publications]] - technical publications relating to the Multi-Channel Electronics

== Contact Info ==

The '''<code>[[mce-announce]]</code>''' e-mail list is used to communicate important firmware and software updates to the MCE user community. See the [[mce-announce]] page for details on how to subscribe.

MCE Lab: 604-822-2585
Halpern's Lab: 604-822-6709

Hardware: mandana at phas.ubc.ca, halpern at phas.ubc.ca
Firmware: mandana at phas.ubc.ca
Software: mhasselfield at flatironinstitute.org, dvw at phas.ubc.ca

Department of Physics & Astronomy
University of British Columbia
6224 Agricultural Rd, Room 204
Vancouver, BC V6T 1Z1
Canada

Sync Box Firmware Upgrade using dfu-programmer

2017-05-04T15:46:19Z

Mhasse:

{{Related|Sync Box Firmware}}
This describes how to upgrade [[Sync Box Firmware]] using the free <tt>dfu-programmer</tt> on linux. This only applies to the microprocessor; often it is also necessary to upgrade the CPLD.
__TOC__
== Installation ==
The dfu-programmer software can be installed in Ubuntu like this:
sudo apt-get install dfu-programmer

Make sure your version supports the sync box device (<tt>at89c5131</tt>):

$ dfu-programmer --version
dfu-programmer 0.6.1
$ dfu-programmer --targets
targets:
at89c51snd1c at89c51snd2c at89c5130 '''at89c5131'''
at89c5132 at90usb1287 at90usb1286 at90usb1287-4k
...

== Programming ==
See [[Sync Box firmware#Enabling reprogramming over USB|the procedure on the Sync Box firmware page]] for instructions on how to get the bootloader to enter reprogramming mode. This will cause it to present itself as a USB device to your computer. When the device is properly detected, it will show up in <tt>lsusb</tt> as something like:
$ lsusb
Bus 002 Device 049: ID 03eb:2ffd Atmel Corp. at89c5130/c5131 DFU bootloader

In some versions of dfu-programmer, you must specify the USB bus and device address (2 and 49, respectively, in this example) along with the part name. In others, you must not specify that information. So the address will either look like "at89c5131" or "at89c5131:2,49". The latter syntax is assumed below.

To prove things are working, dump the contents of the device into a file:

$ sudo dfu-programmer at89c5131:''<USB_BUS>'',''<USB_DEVNUM>'' dump > part_dump.bin

where ''<USB_BUS>'' is the bus number from <tt>lsusb</tt> and ''<USB_DEVNUM>'' is the device number from <tt>lsusb</tt>. For the example <tt>lsusb</tt> output above, this would give us:

$ sudo dfu-programmer at89c5131:2,49 dump > ./part_dump.bin

The contents of part_dump.bin can then be inspected with <tt>hexdump -C ./part_dump.bin</tt> to confirm it's the sync box code and not some other nonsense. (It's also good to keep a copy of the previous program; if the new program doesn't work, you can always revert.)

Then to program the device the syntax is:
$ sudo dfu-programmer at89c5131:''<USB_BUS>'',''<USB_DEVNUM>'' flash ./sync_box_v22_26sept2014.hex

== External links ==
* [https://dfu-programmer.github.io/ dfu-programmer on github]

[[Category:Sync Box Firmware]]

Sync Box firmware

2017-05-04T15:44:08Z

Mhasse:

{{Related|Sync Box Firmware}}
There is an Altera CPLD (EPM570T144C3) and an Atmel micro-controller (AT89C51) on in the [[Sync Box]].
* SyncBox CPLD Firmware Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_FwDescr_S589_201.pdf PDF]] (SC2-ELE-S589-201)
* SyncBox Microcontroller Software Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_SWDescr_S589_202.pdf PDF]] (SC2-ELE-S589-202)

Consequently, there are two sets of firmware:
*firmware for the CPLD part (*.pof file)
*firmware for the microcontroller (*.hex file)

== Firmware Upgrade Instructions ==
=== Downloads ===

Firmware is available from the MCE firmware repository:

* http://e-mode.phas.ubc.ca/mce_firmware/sync_box

To upgrade the Sync Box firmware, ''most times'' both the microcontroller and the CPLD firmware need to be reprogrammed.

=== CPLD programming (<tt>.pof</tt> file) ===
The CPLD firmware can be loaded using the Altera USB-Blaster that connects to the on-board P23 JTAG header, and Quartus Programmer software. A <tt>.pof</tt> file needs to be loaded. The P23 connector is not wired out to the sync box enclosure. To access it, remove the sync box cover plate.

=== Microcontroller programming (<tt>.hex</tt> file) ===
The microcontroller program is loaded over a USB cable that connects your computer to the on-board J1 (USB-B) connector. This connector is not wired out to the sync box enclosure: to access it, remove the top cover. In the past we used Atmel's [http://www.atmel.com/tools/FLIP.aspx Flip Programmer]. Now we recommend running <tt>dfu-programmer</tt> on linux. See:
* [[Sync Box Firmware Upgrade using dfu-programmer]].

==== Enabling reprogramming over USB ====
Regardless of what you use to program the sync box, you need to get the sync box bootloader to restart in reprogramming mode. To do this, the procedure is:
# Start with the sync box powered off and disconnected from USB
# Depress ''both'' the on-board RESET switch and the PS_EN switch. Both switches are located next to the USB J1 connector on the board.
# Power on the sync box. The PS_EN switch may be labeled as PRG_EN.
# Release the RESET switch
# Release the PS_EN switch
# Plug in the USB cable
If this procedure is successfully performed, the sync box will present itself as a USB device to your computer. Your computer should now detect the sync box as an Atmel AT89C5131 device. If the sync box isn't accepting USB protocol commands, turn it off and try the procedure again.

== Releases ==

=== Firmware set Rev. 31 ===
; Filename
: sync_box_v31_21Jun2016.hex
: sync_box_v31_21Jun2016.pof

; Features
: The two banks of Manchester outputs can now be configured independently. This permits up to 4 MCEs to share one timing configuration, while up to 4 other MCEs share a second timing configuration.
: The microprocessor's on-board EEPROM can be used to load and save configurations. A preferred configuration can be loaded "on startup", so there is no need for per-experiment defaults.

; Notes
: The firmware version is not reported by the serial interface. Subsequent versions will report the version, so if you see the "eeprom" menu but no version number then you're probably looking at v31!

=== Firmware set Rev. 30 ===

; Features
: The microprocessor code has been ported to the sdcc compiler. There are no changes in behaviour. This code should continue to work with CPLD code from version 1f.

=== Firmware set Rev. 22 ===
; Filename
: sync_box_v22_26sep2014.hex
: no change to cpld code

; Features
: Sync Box default values are set for ACT values: fr=38, num_rows=33, row_len=50

=== Firmware set Rev. 21 ===
; Filename
: sync_box_v21_02sep2014.pof
: no change to microcontroller code or *.hex file

; Features
: DV_FTS and DV_POL are now duplicate copies of DV_SPARE1 and DV_SPARE2, respectively. See [http://e-mode.phas.ubc.ca/mcewiki/index.php/Sync_Box_AC-in_Rack_Mount_io IO for rackmount AC-in Sync Box]

=== Firmware set Rev. 20 ===
; Filename
: sync_box_v20_22aug2013.hex

; Features
: hard-coded Spider values of fr=120, num_rows=33, row_len=53 (which translates to row_len=106 on mce front)
: firmware revision on rs232 interface now shows 20
=== Firmware set Rev. 1f ===
; Filename
: sync_box_v1f_25feb2010.pof
: sync_box_v1f_25feb2010.hex

; Features
: adds a ckd command to the rs232 interface to adjust the frequency of DV_Spare1 and DV_Spare2 by setting a 50MHz divisor through the command.
: when you turn on the sync box, the firmware revision 1f appears on the rs232 terminal

=== Firmware set Rev. 1e (6e?) ===
; Filename
: sync_box_v6e_11aug2008.pof
: sync_box_v1c_17nov2006.hex

; Features
: added a 50MHz clock on SMA output of the Sync box

; Note
: Since the microcontroller code is still 1c and that is what is reported in rs232 terminal, there is no way to identify this set from a 1c set.

=== Firmware set Rev. 1c ===
; Filename
: sync_box_v6c_19oct2006.pof
: sync_box_v1c_17nov2006.hex

; Features
original firmware

== Source code ==
The sync box source (both CPLD and Atmel code) is available in the <tt>sync_box</tt> project in the [[UBC SVN repository]]. So, something like this might work:

svn checkout --username=mceanon svn://e-mode.phas.ubc.ca/sync_box/trunk sync_box

[[Category:Sync Box Firmware| ]]

Sync Box firmware

2016-06-25T17:04:35Z

Mhasse: /* Firmware set Rev. 31 */

{{Hierarchy header}}
There is an Altera CPLD (EPM570T144C3) and an Atmel micro-controller (AT89C51) on the Sync board.
* SyncBox CPLD Firmware Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_FwDescr_S589_201.pdf PDF]] (SC2-ELE-S589-201)
* SyncBox Microcontroller Software Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_SWDescr_S589_202.pdf PDF]] (SC2-ELE-S589-202)

Consequently, there are two sets of firmware:
*firmware for the CPLD part (*.pof file)
*firmware for the microcontroller (*.hex file)

= Firmware Upgrade Instructions =
To upgrade the Sync Box firmware,''most times'' both the microcontroller and the CPLD firmware need to be reprogrammed.

The CPLD firmware can be loaded using the Altera USB-Blaster that connects to the on-board P23 JTAG header, and Quartus Programmer software. A *.pof file needs to be loaded.

The micro-controller firmware can be loaded using a USB cable that connects to the on-board J1 connector, and [http://www.atmel.com/tools/FLIP.aspx Flip] Programmer software available from Atmel website. A *.hex file needs to be loaded. Alternately, see if you can use free software dfu-programmer on linux: [[Sync Box Firmware Upgrade using dfu-programmer]].

For more details, see section 9 in: [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf Sync Box User's Guide]

''Note: I had to install Flip on 3 computers before I could get the USB driver to work!''

[http://e-mode.phas.ubc.ca/mce_firmware/ Firmware .hex & .pof Downloads]

= Revisions =

== '''Firmware set Rev. 31''' ==
; Filename
: sync_box_v31_21Jun2016.hex
: sync_box_v31_21Jun2016.pof

; Features
: The two banks of Manchester outputs can now be configured independently. This permits up to 4 MCEs to share one timing configuration, while up to 4 other MCEs share a second timing configuration.
: The microprocessor's on-board EEPROM can be used to load and save configurations. A preferred configuration can be loaded "on startup", so there is no need for per-experiment defaults.

; Notes
: The firmware version is not reported by the serial interface. Subsequent versions will report the version, so if you see the "eeprom" menu but no version number then you're probably looking at v31!

== '''Firmware set Rev. 30''' ==

; Features
: The microprocessor code has been ported to the sdcc compiler. There are no changes in behaviour. This code should continue to work with CPLD code from version 1f.

== '''Firmware set Rev. 22''' ==
; Filename
: sync_box_v22_26sep2014.hex
: no change to cpld code

; Features
: Sync Box default values are set for ACT values: fr=38, num_rows=33, row_len=50

== '''Firmware set Rev. 21''' ==
; Filename
: sync_box_v21_02sep2014.pof
: no change to microcontroller code or *.hex file

; Features
: DV_FTS and DV_POL are now duplicate copies of DV_SPARE1 and DV_SPARE2, respectively. See [http://e-mode.phas.ubc.ca/mcewiki/index.php/Sync_Box_AC-in_Rack_Mount_io IO for rackmount AC-in Sync Box]

== '''Firmware set Rev. 20''' ==
; Filename
: sync_box_v20_22aug2013.hex

; Features
: hard-coded Spider values of fr=120, num_rows=33, row_len=53 (which translates to row_len=106 on mce front)
: firmware revision on rs232 interface now shows 20
== '''Firmware set Rev. 1f''' ==
; Filename
: sync_box_v1f_25feb2010.pof
: sync_box_v1f_25feb2010.hex

; Features
: adds a ckd command to the rs232 interface to adjust the frequency of DV_Spare1 and DV_Spare2 by setting a 50MHz divisor through the command.
: when you turn on the sync box, the firmware revision 1f appears on the rs232 terminal

== '''Firmware set Rev. 1e (6e?)''' ==
; Filename
: sync_box_v6e_11aug2008.pof
: sync_box_v1c_17nov2006.hex

; Features
: added a 50MHz clock on SMA output of the Sync box

; Note
: Since the microcontroller code is still 1c and that is what is reported in rs232 terminal, there is no way to identify this set from a 1c set.

== '''Firmware set Rev. 1c''' ==
; Filename
: sync_box_v6c_19oct2006.pof
: sync_box_v1c_17nov2006.hex

; Features
original firmware

= Source code =
The sync box source (both CPLD and Atmel code) is available in the <tt>sync_box</tt> project in the [[UBC SVN repository]]. So, something like this might work:

svn checkout --username=mceanon svn://e-mode.phas.ubc.ca/sync_box/trunk sync_box

[[Category:Firmware]]

Sync Box firmware

2016-06-21T17:49:19Z

Mhasse:

{{Hierarchy header}}
There is an Altera CPLD (EPM570T144C3) and an Atmel micro-controller (AT89C51) on the Sync board.
* SyncBox CPLD Firmware Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_FwDescr_S589_201.pdf PDF]] (SC2-ELE-S589-201)
* SyncBox Microcontroller Software Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_SWDescr_S589_202.pdf PDF]] (SC2-ELE-S589-202)

Consequently, there are two sets of firmware:
*firmware for the CPLD part (*.pof file)
*firmware for the microcontroller (*.hex file)

= Firmware Upgrade Instructions =
To upgrade the Sync Box firmware,''most times'' both the microcontroller and the CPLD firmware need to be reprogrammed.

The CPLD firmware can be loaded using the Altera USB-Blaster that connects to the on-board P23 JTAG header, and Quartus Programmer software. A *.pof file needs to be loaded.

The micro-controller firmware can be loaded using a USB cable that connects to the on-board J1 connector, and [http://www.atmel.com/tools/FLIP.aspx Flip] Programmer software available from Atmel website. A *.hex file needs to be loaded. Alternately, see if you can use free software dfu-programmer on linux: [[Sync Box Firmware Upgrade using dfu-programmer]].

For more details, see section 9 in: [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf Sync Box User's Guide]

''Note: I had to install Flip on 3 computers before I could get the USB driver to work!''

[http://e-mode.phas.ubc.ca/mce_firmware/ Firmware .hex & .pof Downloads]

= Revisions =

== '''Firmware set Rev. 31''' ==
; Filename
: sync_box_v31_21Jun2016.hex
: sync_box_v31_21Jun2016.pof

; Features
: The two banks of Manchester outputs can now be configured independently. This permits up to 4 MCEs to share one timing configuration, while up to 4 other MCEs share a second timing configuration.
: The microprocessor's on-board EEPROM can be used to load and save configurations. A preferred configuration can be loaded "on startup", so there is no need for per-experiment defaults.

== '''Firmware set Rev. 30''' ==

; Features
: The microprocessor code has been ported to the sdcc compiler. There are no changes in behaviour. This code should continue to work with CPLD code from version 1f.

== '''Firmware set Rev. 22''' ==
; Filename
: sync_box_v22_26sep2014.hex
: no change to cpld code

; Features
: Sync Box default values are set for ACT values: fr=38, num_rows=33, row_len=50

== '''Firmware set Rev. 21''' ==
; Filename
: sync_box_v21_02sep2014.pof
: no change to microcontroller code or *.hex file

; Features
: DV_FTS and DV_POL are now duplicate copies of DV_SPARE1 and DV_SPARE2, respectively. See [http://e-mode.phas.ubc.ca/mcewiki/index.php/Sync_Box_AC-in_Rack_Mount_io IO for rackmount AC-in Sync Box]

== '''Firmware set Rev. 20''' ==
; Filename
: sync_box_v20_22aug2013.hex

; Features
: hard-coded Spider values of fr=120, num_rows=33, row_len=53 (which translates to row_len=106 on mce front)
: firmware revision on rs232 interface now shows 20
== '''Firmware set Rev. 1f''' ==
; Filename
: sync_box_v1f_25feb2010.pof
: sync_box_v1f_25feb2010.hex

; Features
: adds a ckd command to the rs232 interface to adjust the frequency of DV_Spare1 and DV_Spare2 by setting a 50MHz divisor through the command.
: when you turn on the sync box, the firmware revision 1f appears on the rs232 terminal

== '''Firmware set Rev. 1e (6e?)''' ==
; Filename
: sync_box_v6e_11aug2008.pof
: sync_box_v1c_17nov2006.hex

; Features
: added a 50MHz clock on SMA output of the Sync box

; Note
: Since the microcontroller code is still 1c and that is what is reported in rs232 terminal, there is no way to identify this set from a 1c set.

== '''Firmware set Rev. 1c''' ==
; Filename
: sync_box_v6c_19oct2006.pof
: sync_box_v1c_17nov2006.hex

; Features
original firmware

= Source code =
The sync box source (both CPLD and Atmel code) is available in the <tt>sync_box</tt> project in the [[UBC SVN repository]]. So, something like this might work:

svn checkout --username=mceanon svn://e-mode.phas.ubc.ca/sync_box/trunk sync_box

[[Category:Firmware]]

Mce cmd

2016-05-05T01:32:30Z

Mhasse:

{{Hierarchy header}}
'''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 {{param||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 {{param|rc|data_mode}} 4" -X "wb rca {{param|rc|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 three broad categories: MCE commands, data acquisition commands, and output formatting commands. Commands are case insensitive.

== Special hardware commands ==

<div id="MCE_RESET">
=== 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, <code>flux_fb</code>s 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 <code>servo_mode</code>, which get reset, ''do'' affect the operation of MCE. Registers can only reinitialised by rewriting them (via a '''wb''' command). In gerenal, a <code>mce_reconfig</code> 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
</div>

<div id="DSP_RESET">
=== DSP_RESET: reset the PCI card DSP firmware ===

The '''dsp_reset''' command causes the PCI card to reset.

Syntax:
dsp_reset
</div>

== Special driver access commands ==

<div id="FAKESTOP">
=== 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
</div>

<div id="EMPTY">
=== 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
</div>

<div id="FRAME">
=== 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>
</div>

== Scripting and output formatting ==

<div id="SLEEP">
=== SLEEP: delay execution for some number of microseconds ===

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

Syntax:
sleep <microseconds>
</div>

<div id="DISPLAY">
=== 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 ]
</div>

<div id="ECHO">
=== 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 ]
</div>

== 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 {{param|rc|flx_quanta0|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 card]]s) name and a parameter name as the first two arguments.

<div id="RB">
=== RB: read block ===

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

Syntax:
rb <card> <param>
Example:
rb rc1 {{param|rc|adc_offset0}}
Line 1 : ok : 10 11 9 8 12 13 14 15
</div>

<div id="WB">
=== 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 {{param|rc|adc_offset0}} 0 1 2
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 12 13 14 15
</div>

<div id="RRA">
=== 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 {{param|rc|adc_offset0}} 2 4
Line 1 : ok : 2 8 12 13
</div>

<div id="WRA">
=== 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 {{param|rc|adc_offset0}} 4 100 200
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 100 200 14 15
</div>

== 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.

<div id="ACQ_CONFIG">
=== 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
</div>

<div id="ACQ_CONFIG_FS">
=== 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>
</div>

<div id="ACQ_CONFIG_DIRFILE">
=== 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 [http://getdata.sourceforge.net/dirfile.html 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>
</div>

<div id="ACQ_GO">
=== 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 {{param|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
</div>

<div id="ACQ_PATH">
=== 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
</div>

<div id="ACQ_LINK">
=== 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
</div>

<div id="ACQ_OPTION">
=== 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 <tt>acq_type</tt> "dirfile" has any options. These are:
* <tt>'''include''' <filename></tt>: 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''')
* <tt>'''spf''' <number></tt>: sets the samples-per-frame of the fields in the dirfile to the specified value, which must be positive. Default is one.
* <tt>'''version''' <number></tt>: sets the [http://getdata.sourceforge.net/dirfile.html 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 mode]]s 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 "<tt>[[mce_status]] -d</tt>" 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
</div>

<div id="ACQ_MULTI_BEGIN">
=== 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 <tt>mce_cmd</tt> 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
</div>

== 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|ACQ_GO]]''', &c.) should be used instead of sending this command directly.

The only parameter which responds to '''GO''' is the readout card's {{param|rc|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 {{param|rc|ret_dat}} parameter.

Syntax:
stop <card> <param>

Examples:

stop rcs {{param|rc|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 [[MCE commands|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 {{param|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:
:{| class="wikitable" style="text-align: center;"
|+ Card ids
|-
! Card !! Card id !! Upper card ID<br/><span style="font-size: smaller;">[[64-row support|v6 firmware only]]</span> !! Notes
|-
| [[PSUC]] || class="code" | 0x01 || rowspan="2" | — || Obsolete.
|-
| [[Clock card]] || class="code" | 0x02 || Card id is {{param||slot_id}}.
|-
| [[Readout card]] 1 || class="code" | 0x03 || class="code" | 0x13 || rowspan=8 | Lower card IDs are {{param||slot_id}}. Upper card IDs supported only with [[64-row support|version 6 firmware]] and only for certain parameters.
|-
| [[Readout card]] 2 || class="code" | 0x04 || class="code" | 0x14
|-
| [[Readout card]] 3 || class="code" | 0x05 || class="code" | 0x15
|-
| [[Readout card]] 4 || class="code" | 0x06 || class="code" | 0x16
|-
| [[Bias card]] 1 || class="code" | 0x07 || class="code" | 0x17
|-
| [[Bias card]] 2 || class="code" | 0x08 || class="code" | 0x18
|-
| [[Bias card]] 3 || class="code" | 0x09 || class="code" | 0x19
|-
| [[Address card]] || class="code" | 0x0A || class="code" | 0x1A
|-
| rcs <span style="font-size: smaller;">(All [[RC]]s)</span> || class="code" | 0x0B || rowspan="4" | — || Use only with {{param|rc|ret_dat}}.
|-
| bcs <span style="font-size: smaller;">(All [[BC]]s)</span> || class="code" | 0x0C || rowspan="2" | Not supported by <tt>mce_cmd</tt>.
|-
| All FPGAs || class="code" | 0x0D
|-
| All cards || class="code" | 0x0E || Not supported by <tt>mce_cmd</tt>. This is ''not'' the '''sys''' multi-address physical card.
|}
The last three of these (<tt>0x0C</tt>, <tt>0x0D</tt>, <tt>0x0E</tt>) are not supported by MAS or <tt>mce_cmd</tt>. 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 {{param||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.

[[Category: Software]]

MAS PC specifications email template

2016-05-04T18:36:43Z

Mhasse:

MAS should run without difficulty on any modern PC that has a standard PCI slot and can run Ubuntu 10.04. In particular, MAS now supports 64-bit and multi-core machines. We have run MAS on fairly weak machines (1 GHz single core w/ 1GB RAM), but during detector characterization phases users will probably prefer a much more powerful desktop machine with lots of speed and graphics support.

Note also that MCE data can take up quite a bit of disk space; 1024 channels of 400 Hz will pile up at 1.6 MB/s. If your data rate is comparable to this then your system should have at least 500 GB of space for MCE data.

Again, each MCE requires a PCI slot for the fibre-optic interface board! Some new motherboards do not have standard PCI slots, as PCI-express is becoming more popular. One alternative to on-board PCI slots is to use a PCI adapter. Users have reported good results with such hardware. One such successful configuration is:
* PCIe to PCI Adapter: StarTech PCI Express to PCI Adapter Card Model PEX1PCI1
* StarTech PEX16RISER PCI Express Riser Card - x16 Left Slot Adapter
* GIGABYTE GA-H81M-DS2V LGA 1150 Motherboard.

Main Page

2016-02-03T21:09:07Z

Mhasse: /* Contact Info */

This Wiki is for users of UBC's '''Multi-Channel Electronics''' (MCE), including the '''MCE Acquisition Software''' (MAS).
__NOTOC__
== MCE Overview ==
The MCE described here borrows heavily from the designs used at [http://www.nist.gov/pml/ NIST]. Changes have been made to upgrade components, achieve higher integration, and match to the specific experimental configurations.

In basic operation, one MCE [[subrack]] controls the SQUID amplifiers and multiplexer, and reads signals from one 32×41 pixel or 16×41 pixel sub-array. The system hardware is completely modular at the sub-array level. Each sub-array is connected via woven cryogenic cables to a single MCE subrack through 3 or 5 MDM connectors. Each MCE subrack is, in turn, connected by an optical fibre to a single data-acquisition PC running Linux and data-acquisition software ([[MAS]]) developed at UBC.

Each MCE consists of hybrid analog/digital hardware and firmware developed for Altera Stratix FPGAs. A subrack has up to nine cards: including 2 or 4 [[Readout card]]s each of which reads 8 output columns through 14-bit 50MHz ADCs; 1 [[address card]] to multiplex the first-stage SQUIDs biases at around 20kHz; 1 [[clock card]] to interpret commands and to synchronize all the cards using a 25MHz clock; 2 or 3 [[bias card]]s to control the SQUID series-array feedback, the second-stage SQUID bias and feedback as well as the bolometer bias and heater. During [[auto_setup|detector setup]], the MCE is used to calculate the optimal operating points for the bolometers and the SQUID amplifiers by measuring their characteristics using open and closed feedback loops. During observation, MCE uses a running PID-calculation to determine the first-stage SQUID feedback necessary to keep the whole amplification chain in a linear regime.

In conjunction with the MCEs, a [[Sync Box]] supplies data-valid pulses with serial numbers to all MCE subracks and to the telescope pointing system. This allows synchronization between the data acquisition, the pointing system, and the telescope housekeeping.

== Documentation ==

* [[ MCE hardware | MCE Hardware ]] - information on MCE hardware (and accessories)
* [[ MCE firmware | MCE Firmware ]] - firmware versions, features, and tools (including sync box and PCI card firmware)
* [[ MAS ]] - the MCE Acquisition Software - kernel driver and low-level tools
* [[ MCE script ]] - SQUID array setup programs
* [[ MCE usage ]] - practical usage and reference documents
* [[Publications]] - technical publications relating to the Multi-Channel Electronics

== Contact Info ==

The '''<code>[[mce-announce]]</code>''' e-mail list is used to communicate important firmware and software updates to the MCE user community. See the [[mce-announce]] page for details on how to subscribe.

MCE Lab: 604-822-2585
Halpern's Lab: 604-822-6709

Hardware: mandana at phas.ubc.ca, halpern at phas.ubc.ca
Firmware: mandana at phas.ubc.ca
Software: mhasse at psu.edu, dvw at phas.ubc.ca

Department of Physics & Astronomy
University of British Columbia
6224 Agricultural Rd, Room 204
Vancouver, BC V6T 1Z1
Canada

Hybrid row select for mux11d

2015-11-13T19:24:09Z

Mhasse:

'''This document is under active development.'''

In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to the use of Bias Card (BC) flux_fb DAC lines to augment the number of addressable S1.
* Without any firmware modifications, it should be possible to multiplex any combination of AC and BC DACs, with num_rows up to 64. However, without some firmware modification, one can configure at most 58 of those channels for servo and readout. (Actually you can only read back 57 values from a register, so that's as far one should push it.)
* With some communication protocol modification, it should be possible to configure and readout any subset of 64 rows.
* Major modifications (especially to RC) are required to get more than 64 rows.

===Software modifications===

The software components affected by hybrid row select are:
* MAS low-level and mce_script -- internal code often assumes num_rows <= 41. These instances shouldn't be too hard to find and remove.
* mux_lock -- rs_servo must be able to ramp the row_select DACs.
* config script system -- must be able to map selected row_select values to correct MCE registers.

===mce.cfg considerations===

The AC and BC are set up differently for fast switching, and thus a low-level solution based on virtual card re-mappings is not feasible.
* AC accepts lists of on_bias and off_bias values, and order of their application is set by the row_order register.
* BC allows a completely arbitrary matrix of flux_fb values, which is more general than the AC model. There is no equivalent of row_order, since the matrix rows themseleves can be modified to produce the equivalent reordering of output values.

The biggest obstacle here is that the manipulation of "row_order" has very different implementations for the AC and BC. The path to a transparent low-level solution is not clear.

Otherwise, the changes to mce.cfg are straight-forward. Switches should be added to increase the effective maximum num_rows to 57/58 or 64/66. The "row select" and "row deselect" virtual targets will be eliminated in favour of a mapping described in experiment.cfg.

=== experiment.cfg ===

The config script system must be able to take care of translating values in experiment.cfg to the appropriate MCE registers. In order for that to take place, experiment.cfg must also encode a map from "row select" index into physical address lines. We define the system by example:

# Activate hybrid mode. With great power comes great complexity.
mux11d_hybrid_row_select = 1;

# Row select lines will be drawn from AC and from BC2.
mux11d_row_select_cards = ["ac", "bc2"];

# For the purposes of mux_order, AC lines are indexed by [0,...,40] and BC lines are indexed by [50,...,81].
mux11d_row_select_cards_row0 = [0, 50];

# For mux cycles where the AC is not active, use ac on_bias[39] as a DAC to idle on.
mux11d_ac_idle_row = 39;

# The muxing order will be: 32 rows from AC (corresponding to on_bias[0] through on_bias[31],
# followed by 16 rows from BC (fb_col0 to fb_col15), followed by a single AC row (on_bias[40]).
mux11d_mux_order = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10,11,12,13,14,15,16,17,18,19,
20,21,22,23,24,25,26,27,28,29,
30,31,
50,51,52,53,54,55,56,57,58,59,
60,61,62,63,64,65,
40 ];

The values for row_select and row_deselect will then be stored in MUX order (rather than physical line order), in experiment.cfg settings:
row_select = [ 999,999,999,999,999,999... ]#(49 values total)
row_deselect = [ 999,999,999,999,999,999... ]#(49 values total)

We may as well allow the user to rescale row_select and row_deselect values prior to application to the DACs. While it is more powerful to specify this on a per DAC or per MUX cycle basis, it is probably enough to specify the multiplier on a per-card basis.
# Multiplier for row_select -> MCE values.
mux11d_row_select_multipliers = [1, 0.5];

These experiment.cfg settings will produce the following MCE configuration:
* '''ac row_order''' is like:
wb ac row_order 0 1 2 3 4 5 6 7 8 9 \
10 11 12 13 14 15 16 17 18 19 \
20 21 22 23 24 25 26 27 28 29 \
30 31 39 39 39 39 39 39 39 39 \
39 39 39 39 39 39 39 39 40
* row_select and row_deselect 999 and 0, except for row 39 which is 0 and 0.
wb ac on_bias 999 999 999 .... 999 0 999
wb ac off_bias 0 0 0 ... 0 0 0
* The '''bc2 col*''' registers are set to row_deselect values (probably 0) except for:
wra bc2 col0 32 498
wra bc2 col1 33 498
wra bc2 col2 34 498
wra bc2 col3 35 498
...
wra bc2 col14 46 498
wra bc2 col15 47 498

=== mux_lock ===

The rs_servo program has to ramp the '''row select''' DACs. It will need to parse experiment.cfg to know how to do this. It should only ramp the DACs listed in mux11d_mux_order. It should properly decode mux_order and multipliers.

Hybrid row select for mux11d

2015-11-13T19:23:22Z

Mhasse:

'''This document is under active development.'''

In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to the use of Bias Card (BC) flux_fb DAC lines to augment the number of addressable S1.
* Without any firmware modifications, it should be possible to multiplex any combination of AC and BC DACs, with num_rows up to 64. However, without some firmware modification, one can configure at most 58 of those channels for servo and readout. (Actually you can only read back 57 values from a register, so that's as far one shoul
* With some communication protocol modification, it should be possible to configure and readout any subset of 64 rows.

===Software modifications===

The software components affected by hybrid row select are:
* MAS low-level and mce_script -- internal code often assumes num_rows <= 41. These instances shouldn't be too hard to find and remove.
* mux_lock -- rs_servo must be able to ramp the row_select DACs.
* config script system -- must be able to map selected row_select values to correct MCE registers.

===mce.cfg considerations===

The AC and BC are set up differently for fast switching, and thus a low-level solution based on virtual card re-mappings is not feasible.
* AC accepts lists of on_bias and off_bias values, and order of their application is set by the row_order register.
* BC allows a completely arbitrary matrix of flux_fb values, which is more general than the AC model. There is no equivalent of row_order, since the matrix rows themseleves can be modified to produce the equivalent reordering of output values.

The biggest obstacle here is that the manipulation of "row_order" has very different implementations for the AC and BC. The path to a transparent low-level solution is not clear.

Otherwise, the changes to mce.cfg are straight-forward. Switches should be added to increase the effective maximum num_rows to 57/58 or 64/66. The "row select" and "row deselect" virtual targets will be eliminated in favour of a mapping described in experiment.cfg.

=== experiment.cfg ===

The config script system must be able to take care of translating values in experiment.cfg to the appropriate MCE registers. In order for that to take place, experiment.cfg must also encode a map from "row select" index into physical address lines. We define the system by example:

# Activate hybrid mode. With great power comes great complexity.
mux11d_hybrid_row_select = 1;

# Row select lines will be drawn from AC and from BC2.
mux11d_row_select_cards = ["ac", "bc2"];

# For the purposes of mux_order, AC lines are indexed by [0,...,40] and BC lines are indexed by [50,...,81].
mux11d_row_select_cards_row0 = [0, 50];

# For mux cycles where the AC is not active, use ac on_bias[39] as a DAC to idle on.
mux11d_ac_idle_row = 39;

# The muxing order will be: 32 rows from AC (corresponding to on_bias[0] through on_bias[31],
# followed by 16 rows from BC (fb_col0 to fb_col15), followed by a single AC row (on_bias[40]).
mux11d_mux_order = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10,11,12,13,14,15,16,17,18,19,
20,21,22,23,24,25,26,27,28,29,
30,31,
50,51,52,53,54,55,56,57,58,59,
60,61,62,63,64,65,
40 ];

The values for row_select and row_deselect will then be stored in MUX order (rather than physical line order), in experiment.cfg settings:
row_select = [ 999,999,999,999,999,999... ]#(49 values total)
row_deselect = [ 999,999,999,999,999,999... ]#(49 values total)

We may as well allow the user to rescale row_select and row_deselect values prior to application to the DACs. While it is more powerful to specify this on a per DAC or per MUX cycle basis, it is probably enough to specify the multiplier on a per-card basis.
# Multiplier for row_select -> MCE values.
mux11d_row_select_multipliers = [1, 0.5];

These experiment.cfg settings will produce the following MCE configuration:
* '''ac row_order''' is like:
wb ac row_order 0 1 2 3 4 5 6 7 8 9 \
10 11 12 13 14 15 16 17 18 19 \
20 21 22 23 24 25 26 27 28 29 \
30 31 39 39 39 39 39 39 39 39 \
39 39 39 39 39 39 39 39 40
* row_select and row_deselect 999 and 0, except for row 39 which is 0 and 0.
wb ac on_bias 999 999 999 .... 999 0 999
wb ac off_bias 0 0 0 ... 0 0 0
* The '''bc2 col*''' registers are set to row_deselect values (probably 0) except for:
wra bc2 col0 32 498
wra bc2 col1 33 498
wra bc2 col2 34 498
wra bc2 col3 35 498
...
wra bc2 col14 46 498
wra bc2 col15 47 498

=== mux_lock ===

The rs_servo program has to ramp the '''row select''' DACs. It will need to parse experiment.cfg to know how to do this. It should only ramp the DACs listed in mux11d_mux_order. It should properly decode mux_order and multipliers.

Sync Box Firmware Upgrade using dfu-programmer

2015-11-04T20:42:31Z

Mhasse:

This describes how to upgrade [[Sync Box Firmware]] using the free dfu-programmer on linux. This only applies to the microprocessor; often it is also necessary to upgrade the CPLD.

The https://dfu-programmer.github.io/ software can be installed in Ubuntu like this:
sudo apt-get install dfu-programmer

Make sure your version supports the sync box device:

act@wilson:~$ dfu-programmer --version
dfu-programmer 0.6.1
act@wilson:~$ dfu-programmer --targets
targets:
at89c51snd1c at89c51snd2c at89c5130 '''at89c5131'''
at89c5132 at90usb1287 at90usb1286 at90usb1287-4k
...

Connect the sync box to the computer over USB. From [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf the manual]: "To reprogram BLJB or to get the bootloader to restart so that you can download new code, the
PSEN and RESET switches must be held down while the USB connector is inserted. Reset is
then released followed by PSEN. "

When the device is properly detected it will show up in <tt>lsusb</tt> as something like:
act@wilson:~$ lsusb
Bus 002 Device 049: ID 03eb:2ffd Atmel Corp. at89c5130/c5131 DFU bootloader

To prove things are working, dump the contents of the device into a file:

act@wilson:~$ sudo dfu-programmer at89c5131:2,49 dump > part_dump.bin

Note that we read the address '''2,49''' from the lsusb output. The contents of part_dump.bin can then be inspected with <tt>hexdump -C</tt> to confirm it's the sync box code and not some other nonsense.

Then to program the device the syntax is:
act@wilson:~$ sudo dfu-programmer at89c5131:2,49 flash sync_box_v22_26sept2014.hex

Sync Box Firmware Upgrade using dfu-programmer

2015-11-04T20:24:04Z

Mhasse:

Sync Box Firmware Upgrade using dfu-programmer

2015-11-04T20:20:59Z

Mhasse: Created page with "The https://dfu-programmer.github.io/ software can be installed in Ubuntu like this: sudo apt-get install dfu-programmer Make sure it supports the sync box device: act@wils…"

The https://dfu-programmer.github.io/ software can be installed in Ubuntu like this:
sudo apt-get install dfu-programmer

Make sure it supports the sync box device:

act@wilson:~$ dfu-programmer --targets
targets:
at89c51snd1c at89c51snd2c at89c5130 '''at89c5131'''
at89c5132 at90usb1287 at90usb1286 at90usb1287-4k
...

Connect the sync box to the computer over USB. From [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf the manual]: "To reprogram BLJB or to get the bootloader to restart so that you can download new code, the
PSEN and RESET switches must be held down while the USB connector is inserted. Reset is
then released followed by PSEN. "

When the device is properly detected it will show up in <tt>lsusb</tt> as something like:
act@wilson:~$ lsusb
Bus 002 Device 049: ID 03eb:2ffd Atmel Corp. at89c5130/c5131 DFU bootloader

To prove things are working, dump the contents of the device into a file:

act@wilson:~$ sudo dfu-programmer at89c5131:2,49 dump > part_dump.bin

Note that we read the address '''2,49''' from the lsusb output. The contents of part_dump.bin can then be inspected with <tt>hexdump -C</tt> to confirm it's the sync box code and not some other nonsense.

Sync Box firmware

2015-11-04T20:13:27Z

Mhasse: /* Firmware Upgrade Instructions */

{{Hierarchy header}}
There is an Altera CPLD (EPM570T144C3) and an Atmel micro-controller (AT89C51) on the Sync board.
* SyncBox CPLD Firmware Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_FwDescr_S589_201.pdf PDF]] (SC2-ELE-S589-201)
* SyncBox Microcontroller Software Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_SWDescr_S589_202.pdf PDF]] (SC2-ELE-S589-202)

Consequently, there are two sets of firmware:
*firmware for the CPLD part (*.pof file)
*firmware for the microcontroller (*.hex file)

= Firmware Upgrade Instructions =
To upgrade the Sync Box firmware,''most times'' both the microcontroller and the CPLD firmware need to be reprogrammed.

The CPLD firmware can be loaded using the Altera USB-Blaster that connects to the on-board P23 JTAG header, and Quartus Programmer software. A *.pof file needs to be loaded.

The micro-controller firmware can be loaded using a USB cable that connects to the on-board J1 connector, and [http://www.atmel.com/tools/FLIP.aspx Flip] Programmer software available from Atmel website. A *.hex file needs to be loaded. Alternately, see if you can use free software dfu-programmer on linux: [[Sync Box Firmware Upgrade using dfu-programmer]].

For more details, see section 9 in: [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf Sync Box User's Guide]

''Note: I had to install Flip on 3 computers before I could get the USB driver to work!''

[http://e-mode.phas.ubc.ca/mce_firmware/ Firmware .hex & .pof Downloads]

= Revisions =
== '''Firmware set Rev. 22''' ==
; Filename
: sync_box_v22_26sep2014.hex
: no change to cpld code

; Features
: Sync Box default values are set for ACT values: fr=38, num_rows=33, row_len=50

== '''Firmware set Rev. 21''' ==
; Filename
: sync_box_v21_02sep2014.pof
: no change to microcontroller code or *.hex file

; Features
: DV_FTS and DV_POL are now duplicate copies of DV_SPARE1 and DV_SPARE2, respectively. See [http://e-mode.phas.ubc.ca/mcewiki/index.php/Sync_Box_AC-in_Rack_Mount_io IO for rackmount AC-in Sync Box]

== '''Firmware set Rev. 20''' ==
; Filename
: sync_box_v20_22aug2013.hex

; Features
: hard-coded Spider values of fr=120, num_rows=33, row_len=53 (which translates to row_len=106 on mce front)
: firmware revision on rs232 interface now shows 20
== '''Firmware set Rev. 1f''' ==
; Filename
: sync_box_v1f_25feb2010.pof
: sync_box_v1f_25feb2010.hex

; Features
: adds a ckd command to the rs232 interface to adjust the frequency of DV_Spare1 and DV_Spare2 by setting a 50MHz divisor through the command.
: when you turn on the sync box, the firmware revision 1f appears on the rs232 terminal

== '''Firmware set Rev. 1e (6e?)''' ==
; Filename
: sync_box_v6e_11aug2008.pof
: sync_box_v1c_17nov2006.hex

; Features
: added a 50MHz clock on SMA output of the Sync box

; Note
: Since the microcontroller code is still 1c and that is what is reported in rs232 terminal, there is no way to identify this set from a 1c set.

== '''Firmware set Rev. 1c''' ==
; Filename
: sync_box_v6c_19oct2006.pof
: sync_box_v1c_17nov2006.hex

; Features
original firmware

= Source code =
The sync box source (both CPLD and Atmel code) is available in the <tt>sync_box</tt> project in the [[UBC SVN repository]]. So, something like this might work:

svn checkout --username=mceanon svn://e-mode.phas.ubc.ca/sync_box/trunk sync_box

[[Category:Firmware]]

Sync Box firmware

2015-10-21T19:18:29Z

Mhasse:

{{Hierarchy header}}
There is an Altera CPLD (EPM570T144C3) and an Atmel micro-controller (AT89C51) on the Sync board.
* SyncBox CPLD Firmware Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_FwDescr_S589_201.pdf PDF]] (SC2-ELE-S589-201)
* SyncBox Microcontroller Software Description [[http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/SyncBox/SyncBox_SWDescr_S589_202.pdf PDF]] (SC2-ELE-S589-202)

Consequently, there are two sets of firmware:
*firmware for the CPLD part (*.pof file)
*firmware for the microcontroller (*.hex file)

= Firmware Upgrade Instructions =
To upgrade the Sync Box firmware,''most times'' both the microcontroller and the CPLD firmware need to be reprogrammed.

The CPLD firmware can be loaded using the Altera USB-Blaster that connects to the on-board P23 JTAG header, and Quartus Programmer software. A *.pof file needs to be loaded.

The micro-controller firmware can be loaded using a USB cable that connects to the on-board J1 connector, and [http://www.atmel.com/tools/FLIP.aspx Flip] Programmer software available from Atmel website. A *.hex file needs to be loaded.

For more details, see section 9 in: [http://www.phas.ubc.ca/~mce/mcedocs/hardware/tech_description/SyncBox_UserGuide_S589_502.pdf Sync Box User's Guide]

''Note: I had to install Flip on 3 computers before I could get the USB driver to work!''

[http://e-mode.phas.ubc.ca/mce_firmware/ Firmware .hex & .pof Downloads]
= Revisions =
== '''Firmware set Rev. 22''' ==
; Filename
: sync_box_v22_26sep2014.hex
: no change to cpld code

; Features
: Sync Box default values are set for ACT values: fr=38, num_rows=33, row_len=50

== '''Firmware set Rev. 21''' ==
; Filename
: sync_box_v21_02sep2014.pof
: no change to microcontroller code or *.hex file

; Features
: DV_FTS and DV_POL are now duplicate copies of DV_SPARE1 and DV_SPARE2, respectively. See [http://e-mode.phas.ubc.ca/mcewiki/index.php/Sync_Box_AC-in_Rack_Mount_io IO for rackmount AC-in Sync Box]

== '''Firmware set Rev. 20''' ==
; Filename
: sync_box_v20_22aug2013.hex

; Features
: hard-coded Spider values of fr=120, num_rows=33, row_len=53 (which translates to row_len=106 on mce front)
: firmware revision on rs232 interface now shows 20
== '''Firmware set Rev. 1f''' ==
; Filename
: sync_box_v1f_25feb2010.pof
: sync_box_v1f_25feb2010.hex

; Features
: adds a ckd command to the rs232 interface to adjust the frequency of DV_Spare1 and DV_Spare2 by setting a 50MHz divisor through the command.
: when you turn on the sync box, the firmware revision 1f appears on the rs232 terminal

== '''Firmware set Rev. 1e (6e?)''' ==
; Filename
: sync_box_v6e_11aug2008.pof
: sync_box_v1c_17nov2006.hex

; Features
: added a 50MHz clock on SMA output of the Sync box

; Note
: Since the microcontroller code is still 1c and that is what is reported in rs232 terminal, there is no way to identify this set from a 1c set.

== '''Firmware set Rev. 1c''' ==
; Filename
: sync_box_v6c_19oct2006.pof
: sync_box_v1c_17nov2006.hex

; Features
original firmware

= Source code =
The source code for the sync box firmware is available. Ask UBC for a copy.

[[Category:Firmware]]

U0107 Series Firmware

2015-03-17T21:10:24Z

Mhasse: Created page with "This page contains some notes specific to PCI card firmware version U0107 (and friends). ===Software sources=== The main difference between U0106 and U0107 software is that the…"

This page contains some notes specific to PCI card firmware version U0107 (and friends).

===Software sources===

The main difference between U0106 and U0107 software is that the kernel device driver was completely rewritten to enable a new communication protocol and to get away from the dependence on bigphysarea. This change is largely transparent to end users.

However, the "right version" of MAS must be installed to use U0107. Instead of <tt>trunk</tt>, get <tt>branches/driver_hacking/</tt>. Efforts are underway to merge this branch into trunk so that U0106 and U0107 can exist, more or less, side-by-side.

There is no special version of mce_script for U0107; old code should work as before.

===Locking the kernel version===

Since U0107+ firmware does not require the bigphysarea patch, the driver must be rebuilt and reinstalled whenever a new Linux kernel is activated. For now, the best way to avoid this is to avoid upgrading the kernel (note that this carries certain security risks). To "lock the kernel version", open the synaptic package manager:

sudo apt-get install synaptic
sudo syntaptic

Then find "linux-generic" in the package list. Select that entry, and then go the "Package" menu and select "Lock Version". That should turn the entry red, or something.

We may eventually implement DKMS [https://help.ubuntu.com/community/DKMS] to have the driver rebuilt automatically upon kernel upgrade.

PCI card firmware

2015-03-17T20:48:31Z

Mhasse: /* U0107 (pending): alpha */

{{Hierarchy header}}
UBC-produced firmware for the ARC-64 [[PCI card]]. [[MAS]] provides a linux kernel driver for this firmware.
== Download ==

These S-record files should work with any reasonable EEPROM programmer:
* U0107 (new!) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0107_candidate_2014-05-01.s
* U0106 (recommended) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0106.s
** 8-bit checksum 6FCDCE
** Scrubber file - try writing all ones to your this to your chip first if your programmer won't let you "erase" it:
** http://e-mode.phas.ubc.ca/mce/firmware/sdsu/scrubber_RevU0106.s
* U0105 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0105.s
* U0104 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0104.s

The full source code is available in these archives (it will not compile unless you get the correct assembler and stuff):
* U0106 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0106.tar.gz
* U0105 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0105.tar.gz
* U0104 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0104.tar.gz

The subversion tree can be obtained like this (you may not have access to this repository; contact UBC);
svn checkout svn://e-mode.phas.ubc.ca/arc_pci

It is laid out roughly as follows:
/trunk main line of development
/releases tagged versions of code
/tools debugging tools
/clash stuff for making CLAS work with wine and linux
/docs useful (though maybe not to you) notes

== Firmware version notes ==

=== U0107 (pending): alpha ===

* This firmware can operate in either of two modes:
** '''U0106 compatibility mode''': the firmware will work with classic MAS driver, just like U0106 (plus some bugfixes).
** '''New Master-only mode''': when activated, uses new set of protocols for communication with the MAS driver. These have proven to be much more stable on some systems. Also, bigphysarea is no longer needed.
* This firmware/driver are in limited release; do not attempt to use them without consulting with UBC.
* Downloads:
** S-rec for release candidates here: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/
** Soft-patches for upgrading U0106 to pseudo-U0107 temporarily: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/patches/
* Some additional notes specific to U0107: [[U0107 Series Firmware]]

=== U0106 (2011-11-21): Recommended version ===

* Backward compatible with U0104 and U0105.
* Fixes bug introduced in U0105 that prevented handling of some PCI bus errors.
* Introduction of command to update PCI burst size.
* Bugs:
** Versions U0104-6 all suffer from the following issues:
*** Host interrupts use bit-test instructions, which are not interrupt safe; consequence is a race condition that can upset ongoing tasks such as FO downloads and PCI bursts. Patch for this issue, applicable to firmware versions U0104-6:
**** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash
*** Multiple simultaneous PCI bus errors are not handled properly, leading to stale bits in the error register. This is an unlikely error vector, but should be fixed.

=== U0105 (2009-06-08) ===

* Backward compatible with U0104.
* Support for MCE STOP commands and commands-on-the-fly.
* Accelerated MCE command code (along with Quiet-RP this increases commanding rate to ~6 kHz).
* Quiet-RP simplifies the protocol for MCE reply handling.
* Low-level improvements:
** CON is done as PCI burst
** Fibre-optic FIFO is emptied with timed read instead of polling.
** Hand-shaking for interrupts instead of host command to clear INTA and HC3.
** Non-interrupt context code disables interrupts when performing PCI transactions.
** Host vector interrupts are otherwise enabled, so PC doesn't have to force with HNMI bit.
* Bugs and fixes:
** Some PCI bus arbitration conditions are mis-handled. This is fixed in U0106; alternately the commands below can be issued to patch active U0105 firmware. (The patch will not survive a power cycle.):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0105_unignore_pci_errors.bash
** Also this (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

=== U0104: First version with non-realtime linux support ===

* Implements quiet transfer mode! Remains backwards compatible with A1.4.
* Fixes the 64k boundary crossing issue
* Moves parameters that enter via interrupt out of registers and into variables
* Version reporting tag-along to RDM command (sending 'VER' to RDM's vector address returns the code version).
* Maximum burst length is reduced to 64 bytes, and is configurable.
* Reset (RST) clears the fibre fifo
* Bugs:
** This (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

== U0103: Oldest UBC release ==

* Minor modifications of SCUBA2's A1.4 firmware, to improve PCI stability.
* Not compatible with non-realtime systems.

== Programming the ARC64 Flash memory ==

To program or upgrade the PCI card's firmware, it is necessary to remove the flash memory chip from the card and program it using a standard EEPROM programmer.

# Obviously you should turn off your computer and stuff first.
# The chip is a large DIP located at U5 on the PCI board. To remove the chip you may use one of the following (in increasing order of risk, and decreasing order of barbarism):
## telekinesis
## a chip removal tool
## needle-nose pliers
## a screw-driver
## thumb and finger
## fingers only
# The chip is a standard 256 Kbit electrically erasable Flash ROM. If you can't find the particular part in your EEPROM programmer software, try using one of these compatible parts:
## Fujitsu MBM28C256
## CSI (Catalyst) CAT28C256 L
## Anything else that has 28C256 in its name as long as it is a 28-pin DIP package and you are using the right socket for your programmer.
# Some programmers won't recognize this chip as erasable. You can just try programming the chip with the new firmware, or pseudo-erasing it first using a "scrubber" file (available for U0106 in the links above).
# The firmware we provide is compiled into a [ http://en.wikipedia.org/wiki/SREC_%28file_format%29 Motorola S-record format ] hex file. This is a standard format that your programmer software should be able to cope with.
# When placing the chip back in the board, the notch on the chip should be at the same end as the notch on the socket.

== Other information ==

* [[ PCI card bug list ]]
* [[ PCI card hacking ]]
* [[ PCI card code assembly on Linux ]]

[[Category:Firmware]]

MAS user setup

2015-03-12T16:59:46Z

Mhasse: /* Using mas_var */

Care must be taken when adding new users in order that

* the new user can access the MAS binaries, scripts, and IDL projects
* the new user's actions do not interfere with other users of the system

= Adding a user =

This can be done from the graphical manager, but since you're here you might as well use these commands:
MCE_USER=mce
sudo useradd -m -g $MCE_USER -s /bin/bash new_user
sudo passwd new_user

Note that the primary group of the user should be the "mce" group. This is so that temporary files can be overwritten by other users. If you want to use another username as the main MCE user, that should be fine. Adjust MCE_USER as necessary.

= Setting up the user's environment =

== Using mas_var ==

[[mas_var]] is good at figuring out what your paths should be. Assuming that MAS has been installed into /usr/mce, add the following to .bashrc:

# MCE/MAS
umask 002
eval `/usr/mce/bin/mas_var -s`

== The old way ==

Before [[mas_var]], those paths were more or less hard-coded and you needed something like the following.

Add the following lines at the end of the .bashrc file:
# MAS!
umask 002
source /usr/mce/mce_script/template/mas_env.bash

MAS/IDL users will need to add $MAS_IDL/mas to their path, e.g.
IDL_PATH="<IDL_DEFAULT>:$MAS_IDL/mas"

For additional command-line functionality, engineering users may also want to add
source $MAS_SCRIPT/mas_library.bash
source $MAS_TEMPLATE/mas_aliases.bash

----
Up to [[ MAS ]]

MAS user setup

2015-03-12T16:58:47Z

Mhasse: /* Setting up the user's environment */

Care must be taken when adding new users in order that

* the new user can access the MAS binaries, scripts, and IDL projects
* the new user's actions do not interfere with other users of the system

= Adding a user =

This can be done from the graphical manager, but since you're here you might as well use these commands:
MCE_USER=mce
sudo useradd -m -g $MCE_USER -s /bin/bash new_user
sudo passwd new_user

Note that the primary group of the user should be the "mce" group. This is so that temporary files can be overwritten by other users. If you want to use another username as the main MCE user, that should be fine. Adjust MCE_USER as necessary.

= Setting up the user's environment =

== Using mas_var ==

[[mas_var]] is good at figuring out what your paths should be. Assuming that MAS has been installed into /usr/mce, add the following to .bashrc:

# MCE/MAS
eval `/usr/mce/bin/mas_var -s`

== The old way ==

Before [[mas_var]], those paths were more or less hard-coded and you needed something like the following.

Add the following lines at the end of the .bashrc file:
# MAS!
umask 002
source /usr/mce/mce_script/template/mas_env.bash

MAS/IDL users will need to add $MAS_IDL/mas to their path, e.g.
IDL_PATH="<IDL_DEFAULT>:$MAS_IDL/mas"

For additional command-line functionality, engineering users may also want to add
source $MAS_SCRIPT/mas_library.bash
source $MAS_TEMPLATE/mas_aliases.bash

----
Up to [[ MAS ]]

Mce cmd

2015-02-09T23:56:19Z

Mhasse: /* Voluntary lock-out mechanism */

{{Hierarchy header}}
'''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 {{param||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 {{param|rc|data_mode}} 4" -X "wb rca {{param|rc|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 three broad categories: MCE commands, data acquisition commands, and output formatting commands. Commands are case insensitive.

== Special hardware commands ==

<div id="MCE_RESET">
=== 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, <code>flux_fb</code>s 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 <code>servo_mode</code>, which get reset, ''do'' affect the operation of MCE. Registers can only reinitialised by rewriting them (via a '''wb''' command). In gerenal, a <code>mce_reconfig</code> 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
</div>

<div id="DSP_RESET">
=== DSP_RESET: reset the PCI card DSP firmware ===

The '''dsp_reset''' command causes the PCI card to reset.

Syntax:
dsp_reset
</div>

== Special driver access commands ==

<div id="FAKESTOP">
=== 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
</div>

<div id="EMPTY">
=== 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
</div>

<div id="FRAME">
=== 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>
</div>

== Scripting and output formatting ==

<div id="SLEEP">
=== SLEEP: delay execution for some number of microseconds ===

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

Syntax:
sleep <microseconds>
</div>

<div id="DISPLAY">
=== 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 ]
</div>

<div id="ECHO">
=== 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 ]
</div>

== 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 {{param|rc|flx_quanta0|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 card]]s) name and a parameter name as the first two arguments.

<div id="RB">
=== RB: read block ===

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

Syntax:
rb <card> <param>
Example:
rb rc1 {{param|rc|adc_offset0}}
Line 1 : ok : 10 11 9 8 12 13 14 15
</div>

<div id="WB">
=== 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 {{param|rc|adc_offset0}} 0 1 2
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 12 13 14 15
</div>

<div id="RRA">
=== 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 {{param|rc|adc_offset0}} 2 4
Line 1 : ok : 2 8 12 13
</div>

<div id="WRA">
=== 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 {{param|rc|adc_offset0}} 4 100 200
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 100 200 14 15
</div>

== 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.

<div id="ACQ_CONFIG">
=== 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
</div>

<div id="ACQ_CONFIG_FS">
=== 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>
</div>

<div id="ACQ_CONFIG_DIRFILE">
=== 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 [http://getdata.sourceforge.net/dirfile.html 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>
</div>

<div id="ACQ_GO">
=== 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 {{param|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
</div>

<div id="ACQ_PATH">
=== 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
</div>

<div id="ACQ_LINK">
=== 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
</div>

<div id="ACQ_OPTION">
=== 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 <tt>acq_type</tt> "dirfile" has any options. These are:
* <tt>'''include''' <filename></tt>: 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''')
* <tt>'''spf''' <number></tt>: sets the samples-per-frame of the fields in the dirfile to the specified value, which must be positive. Default is one.
* <tt>'''version''' <number></tt>: sets the [http://getdata.sourceforge.net/dirfile.html 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 mode]]s 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 "<tt>[[mce_status]] -d</tt>" 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
</div>

<div id="ACQ_MULTI_BEGIN">
=== 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 <tt>mce_cmd</tt> 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
</div>

== 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|ACQ_GO]]''', &c.) should be used instead of sending this command directly.

The only parameter which responds to '''GO''' is the readout card's {{param|rc|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 {{param|rc|ret_dat}} parameter.

Syntax:
stop <card> <param>

Examples:

stop rcs {{param|rc|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 [[MCE commands|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 {{param|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 address). Raw commands can be used to access command registers which are not defined in the hardware description file ([[mce.cfg]]).

The numeric address of a physical card is its {{param||slot_id}}. The special card '''rcs''' has a numeric address of <tt>0x0B</tt>.

Syntax:
rb <card> <register> <count> [multiplier]
wb <card> <register> <datum> [val0 val1 val2 ...]

Examples:
# read one sample from the clock card {{param||led}} register
rb cc 0x99 1

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

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.

[[Category: Software]]

Mce cmd

2015-02-09T23:28:23Z

Mhasse:

{{Hierarchy header}}
'''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 {{param||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 {{param|rc|data_mode}} 4" -X "wb rca {{param|rc|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 three broad categories: MCE commands, data acquisition commands, and output formatting commands. Commands are case insensitive.

== Special hardware commands ==

<div id="MCE_RESET">
=== 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, <code>flux_fb</code>s 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 <code>servo_mode</code>, which get reset, ''do'' affect the operation of MCE. Registers can only reinitialised by rewriting them (via a '''wb''' command). In gerenal, a <code>mce_reconfig</code> 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
</div>

<div id="DSP_RESET">
=== DSP_RESET: reset the PCI card DSP firmware ===

The '''dsp_reset''' command causes the PCI card to reset.

Syntax:
dsp_reset
</div>

== Special driver access commands ==

<div id="FAKESTOP">
=== 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
</div>

<div id="EMPTY">
=== 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
</div>

<div id="FRAME">
=== 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>
</div>

== Scripting and output formatting ==

<div id="SLEEP">
=== SLEEP: delay execution for some number of microseconds ===

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

Syntax:
sleep <microseconds>
</div>

<div id="DISPLAY">
=== 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 ]
</div>

<div id="ECHO">
=== 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 ]
</div>

== 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 {{param|rc|flx_quanta0|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 card]]s) name and a parameter name as the first two arguments.

<div id="RB">
=== RB: read block ===

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

Syntax:
rb <card> <param>
Example:
rb rc1 {{param|rc|adc_offset0}}
Line 1 : ok : 10 11 9 8 12 13 14 15
</div>

<div id="WB">
=== 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 {{param|rc|adc_offset0}} 0 1 2
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 12 13 14 15
</div>

<div id="RRA">
=== 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 {{param|rc|adc_offset0}} 2 4
Line 1 : ok : 2 8 12 13
</div>

<div id="WRA">
=== 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 {{param|rc|adc_offset0}} 4 100 200
Line 1 : ok
rb rc1 {{param|rc|adc_offset0}}
Line 2 : ok : 0 1 2 8 100 200 14 15
</div>

== 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.

<div id="ACQ_CONFIG">
=== 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
</div>

<div id="ACQ_CONFIG_FS">
=== 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>
</div>

<div id="ACQ_CONFIG_DIRFILE">
=== 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 [http://getdata.sourceforge.net/dirfile.html 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>
</div>

<div id="ACQ_GO">
=== 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 {{param|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
</div>

<div id="ACQ_PATH">
=== 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
</div>

<div id="ACQ_LINK">
=== 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
</div>

<div id="ACQ_OPTION">
=== 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 <tt>acq_type</tt> "dirfile" has any options. These are:
* <tt>'''include''' <filename></tt>: 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''')
* <tt>'''spf''' <number></tt>: sets the samples-per-frame of the fields in the dirfile to the specified value, which must be positive. Default is one.
* <tt>'''version''' <number></tt>: sets the [http://getdata.sourceforge.net/dirfile.html 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 mode]]s 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 "<tt>[[mce_status]] -d</tt>" 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
</div>

<div id="ACQ_MULTI_BEGIN">
=== 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 <tt>mce_cmd</tt> 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
</div>

== Voluntary lock-out mechanism ==

== 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|ACQ_GO]]''', &c.) should be used instead of sending this command directly.

The only parameter which responds to '''GO''' is the readout card's {{param|rc|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 {{param|rc|ret_dat}} parameter.

Syntax:
stop <card> <param>

Examples:

stop rcs {{param|rc|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 [[MCE commands|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 {{param|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 address). Raw commands can be used to access command registers which are not defined in the hardware description file ([[mce.cfg]]).

The numeric address of a physical card is its {{param||slot_id}}. The special card '''rcs''' has a numeric address of <tt>0x0B</tt>.

Syntax:
rb <card> <register> <count> [multiplier]
wb <card> <register> <datum> [val0 val1 val2 ...]

Examples:
# read one sample from the clock card {{param||led}} register
rb cc 0x99 1

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

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.

[[Category: Software]]

Hybrid row select for mux11d

2015-01-09T22:07:48Z

Mhasse:

'''This document is under active development.'''

In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to the use of Bias Card (BC) flux_fb DAC lines to augment the number of addressable S1.
* Without any firmware modifications, it should be possible to multiplex any combination of AC and BC DACs, with num_rows up to 64. However, without some firmware modification, one can configure at most 58 of those channels for servo and readout.
* With some communication protocol modification, it should be possible to configure and readout any subset of 64 rows.

===Software modifications===

The software components affected by hybrid row select are:
* MAS low-level and mce_script -- internal code often assumes num_rows <= 41. These instances shouldn't be too hard to find and remove.
* mux_lock -- rs_servo must be able to ramp the row_select DACs.
* config script system -- must be able to map selected row_select values to correct MCE registers.

===mce.cfg considerations===

The AC and BC are set up differently for fast switching, and thus a low-level solution based on virtual card re-mappings is not feasible.
* AC accepts lists of on_bias and off_bias values, and order of their application is set by the row_order register.
* BC allows a completely arbitrary matrix of flux_fb values, which is more general than the AC model. There is no equivalent of row_order, since the matrix rows themseleves can be modified to produce the equivalent reordering of output values.

The biggest obstacle here is that the manipulation of "row_order" has very different implementations for the AC and BC. The path to a transparent low-level solution is not clear.

Otherwise, the changes to mce.cfg are straight-forward. Switches should be added to increase the effective maximum num_rows to 57/58 or 64/66. The "row select" and "row deselect" virtual targets will be eliminated in favour of a mapping described in experiment.cfg.

=== experiment.cfg ===

The config script system must be able to take care of translating values in experiment.cfg to the appropriate MCE registers. In order for that to take place, experiment.cfg must also encode a map from "row select" index into physical address lines. We define the system by example:

# Activate hybrid mode. With great power comes great complexity.
mux11d_hybrid_row_select = 1;

# Row select lines will be drawn from AC and from BC2.
mux11d_row_select_cards = ["ac", "bc2"];

# For the purposes of mux_order, AC lines are indexed by [0,...,40] and BC lines are indexed by [50,...,81].
mux11d_row_select_cards_row0 = [0, 50];

# For mux cycles where the AC is not active, use ac on_bias[39] as a DAC to idle on.
mux11d_ac_idle_row = 39;

# The muxing order will be: 32 rows from AC (corresponding to on_bias[0] through on_bias[31],
# followed by 16 rows from BC (fb_col0 to fb_col15), followed by a single AC row (on_bias[40]).
mux11d_mux_order = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10,11,12,13,14,15,16,17,18,19,
20,21,22,23,24,25,26,27,28,29,
30,31,
50,51,52,53,54,55,56,57,58,59,
60,61,62,63,64,65,
40 ];

The values for row_select and row_deselect will then be stored in MUX order (rather than physical line order), in experiment.cfg settings:
row_select = [ 999,999,999,999,999,999... ]#(49 values total)
row_deselect = [ 999,999,999,999,999,999... ]#(49 values total)

We may as well allow the user to rescale row_select and row_deselect values prior to application to the DACs. While it is more powerful to specify this on a per DAC or per MUX cycle basis, it is probably enough to specify the multiplier on a per-card basis.
# Multiplier for row_select -> MCE values.
mux11d_row_select_multipliers = [1, 0.5];

These experiment.cfg settings will produce the following MCE configuration:
* '''ac row_order''' is like:
wb ac row_order 0 1 2 3 4 5 6 7 8 9 \
10 11 12 13 14 15 16 17 18 19 \
20 21 22 23 24 25 26 27 28 29 \
30 31 39 39 39 39 39 39 39 39 \
39 39 39 39 39 39 39 39 40
* row_select and row_deselect 999 and 0, except for row 39 which is 0 and 0.
wb ac on_bias 999 999 999 .... 999 0 999
wb ac off_bias 0 0 0 ... 0 0 0
* The '''bc2 col*''' registers are set to row_deselect values (probably 0) except for:
wra bc2 col0 32 498
wra bc2 col1 33 498
wra bc2 col2 34 498
wra bc2 col3 35 498
...
wra bc2 col14 46 498
wra bc2 col15 47 498

=== mux_lock ===

The rs_servo program has to ramp the '''row select''' DACs. It will need to parse experiment.cfg to know how to do this. It should only ramp the DACs listed in mux11d_mux_order. It should properly decode mux_order and multipliers.

Hybrid row select for mux11d

2015-01-09T21:55:30Z

Mhasse:

'''This document is under active development.'''

In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to the use of Bias Card (BC) flux_fb DAC lines to augment the number of addressable S1.
* Without any firmware modifications, it should be possible to multiplex any combination of AC and BC DACs, with num_rows up to 64. However, without some firmware modification, one can configure at most 58 of those channels for servo and readout.
* With some communication protocol modification, it should be possible to configure and readout any subset of 64 rows.

===Software modifications===

The software components affected by hybrid row select are:
* MAS low-level and mce_script -- internal code often assumes num_rows <= 41. These instances shouldn't be too hard to find and remove.
* mux_lock -- rs_servo must be able to ramp the row_select DACs.
* config script system -- must be able to map selected row_select values to correct MCE registers.

===mce.cfg considerations===

The AC and BC are set up differently for fast switching, and thus a low-level solution based on virtual card re-mappings is not feasible.
* AC accepts lists of on_bias and off_bias values, and order of their application is set by the row_order register.
* BC allows a completely arbitrary matrix of flux_fb values, which is more general than the AC model. There is no equivalent of row_order, since the matrix rows themseleves can be modified to produce the equivalent reordering of output values.

The biggest obstacle here is that the manipulation of "row_order" has very different implementations for the AC and BC. The path to a transparent low-level solution is not clear.

Otherwise, the changes to mce.cfg are straight-forward. Switches should be added to increase the effective maximum num_rows to 57/58 or 64/66. The "row select" and "row deselect" virtual targets will be eliminated in favour of a mapping described in experiment.cfg.

=== experiment.cfg ===

The config script system must be able to take care of translating values in experiment.cfg to the appropriate MCE registers. In order for that to take place, experiment.cfg must also encode a map from "row select" index into physical address lines. We define the system by example:

# Activate hybrid mode. With great power comes great complexity.
mux11d_hybrid_row_select = 1;

# Row select lines will be drawn from AC and from BC2.
mux11d_row_select_cards = ["ac", "bc2"];

# For the purposes of mux_order, AC lines are indexed by [0,...,40] and BC lines are indexed by [50,...,81].
mux11d_row_select_cards_row0 = [0, 50];

# For mux cycles where the AC is not active, use ac on_bias[39] as a DAC to idle on.
mux11d_ac_idle_row = 39;

# The muxing order will be: 32 rows from AC (corresponding to on_bias[0] through on_bias[31],
# followed by 16 rows from BC (fb_col0 to fb_col15), followed by a single AC row (on_bias[40]).
mux11d_mux_order = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10,11,12,13,14,15,16,17,18,19,
20,21,22,23,24,25,26,27,28,29,
30,31,
50,51,52,53,54,55,56,57,58,59,
60,61,62,63,64,65,
40 ];

These experiment.cfg settings will produce the following MCE configuration:
* '''ac row_order''' is like:
wb ac row_order 0 1 2 3 4 5 6 7 8 9 \
10 11 12 13 14 15 16 17 18 19 \
20 21 22 23 24 25 26 27 28 29 \
30 31 39 39 39 39 39 39 39 39 \
39 39 39 39 39 39 39 39 40
* The '''bc2 col*''' registers are set to row_deselect values (probably 0) except for (using 999 as a dummy row select value):
wra bc2 col0 32 999
wra bc2 col1 33 999
wra bc2 col2 34 999
wra bc2 col3 35 999
...
wra bc2 col14 46 999
wra bc2 col15 47 999

Hybrid row select for mux11d

2015-01-09T21:54:31Z

Mhasse: /* experiment.cfg */

'''This document is under active development.'''

In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to the use of Bias Card (BC) flux_fb DAC lines to augment the number of addressable S1.
* Without any firmware modifications, it should be possible to multiplex any combination of AC and BC DACs, with num_rows up to 64. However, without some firmware modification, one can configure at most 58 of those channels for servo and readout.
* With some communication protocol modification, it should be possible to configure and readout any subset of 64 rows.

===Software modifications===

The software components affected by hybrid row select are:
* MAS low-level and mce_script -- internal code often assumes num_rows <= 41. These instances shouldn't be too hard to find and remove.
* mux_lock -- rs_servo must be able to ramp the row_select DACs.
* config script system -- must be able to map selected row_select values to correct MCE registers.

===mce.cfg considerations===

The AC and BC are set up differently for fast switching, and thus a low-level solution based on virtual card re-mappings is not feasible.
* AC accepts lists of on_bias and off_bias values, and order of their application is set by the row_order register.
* BC allows a completely arbitrary matrix of flux_fb values, which is more general than the AC model. There is no equivalent of row_order, since the matrix rows themseleves can be modified to produce the equivalent reordering of output values.

The biggest obstacle here is that the manipulation of "row_order" has very different implementations for the AC and BC. The path to a transparent low-level solution is not clear.

Otherwise, the changes to mce.cfg are straight-forward. Switches should be added to increase the effective maximum num_rows to 57/58 or 64/66. The "row select" and "row deselect" virtual targets will be eliminated in favour of a mapping described in experiment.cfg.

=== experiment.cfg ===

The config script system must be able to take care of translating values in experiment.cfg to the appropriate MCE registers. In order for that to take place, experiment.cfg must also encode a map from "row select" index into physical address lines. We define the system by example:

# Activate hybrid mode. With great power comes great complexity.
mux11d_hybrid_row_select = 1;

# Row select lines will be drawn from AC and from BC2.
mux11d_row_select_cards = ["ac", "bc2"];

# For the purposes of mux_order, AC lines are indexed by [0,...,40] and BC lines are indexed by [50,...,81].
mux11d_row_select_cards_row0 = [0, 50];

# For mux cycles where the AC is not active, use ac on_bias[39] as a DAC to idle on.
mux11d_ac_idle_row = 39;

# The muxing order will be: 32 rows from AC (corresponding to on_bias[0] through on_bias[31],
# followed by 16 rows from BC (fb_col0 to fb_col15), followed by a single AC row (on_bias[40]).
mux11d_mux_order = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10,11,12,13,14,15,16,17,18,19,
20,21,22,23,24,25,26,27,28,29,
30,31,
50,51,52,53,54,55,56,57,58,59,
60,61,62,63,64,65,
40 ];

These experiment.cfg settings will produce the following MCE configuration:
* '''ac row_order''' is like:
wb ac row_order 0 1 2 3 4 5 6 7 8 9 \
10 11 12 13 14 15 16 17 18 19 \
20 21 22 23 24 25 26 27 28 29 \
30 31 39 39 39 39 39 39 39 39 \
39 39 39 39 39 39 39 39 40
* The '''bc2 col*''' registers are set to row_deselect values (probably 0) except for (using 999 as a dummy row select value):
wra bc2 col0 32 999
wra bc2 col2 33 999
wra bc2 col3 34 999
wra bc2 col4 35 999
...
wra bc2 col14 45 999
wra bc2 col15 46 999

Hybrid row select for mux11d

2015-01-09T16:46:43Z

Mhasse: /* mce.cfg considerations */

Hybrid row select for mux11d

2015-01-09T16:44:15Z

Mhasse: /* mce.cfg considerations */

Hybrid row select for mux11d

2015-01-07T17:18:26Z

Mhasse: Created page with "'''This document is under active development.''' In standard mux11d, the S1 selection signals (row_select) are provided by the Adress Card (AC). "Hybrid row select" refers to t…"

MCE usage

2015-01-07T16:37:54Z

Mhasse: /* Application Notes */

{{Hierarchy header}}
== MCE commanding ==

* [[mce_cmd]] - application for commanding the MCE.
* [[ MCE Commands ]] - especially those commands supported directly by hardware/firmware
* [[Virtual cards]]
* [[Using Python to Automate MAS |Python commanding library ]]

== Application Notes ==
* [[MCE Timing Diagram]]
* SQUID array setup
** [[Array setup programs]] - software
** Characterization and Locking SQUIDs with Multi-Channel Electronics [[http://www.phas.ubc.ca/%7Emce/mcedocs/software/locking_squids.pdf PDF]] (Jun. 07, 2005)
** "Functional Description of Read-out Electronics for Time-Domain Multiplexed Bolometers for Millimeter and Sub-millimeter Astronomy" [[http://www.springerlink.com/content/m66114j06511uw68/ PDF]] (vol. 151, no. 3-4, J. Low-Temp Phys, May 2008)
** "Automated SQUID tuning procedure for kilo-pixel arrays of TES bolometers on the Atacama Cosmology Telescope" [[http://www.phas.ubc.ca/%7Emce/mcedocs/auto_tune_results/ACT_tuning_spie2008.pdf PDF]] (SPIE Astronomical Instrumentation Conf, Jun. 2008)
** Tuning Algorithm for ACT SQUIDs - poster [[http://www.phas.ubc.ca/%7Emce/mcedocs/auto_tune_results/auto_tuning_block_diagram.pdf PDF]]
** MCE-Cryostat Diagram - cartoons of squid chain setup, servo loop calculations, and word-sizes [[http://www.phas.ubc.ca/~mce/mcedocs/system/Cryo_MCE%20Block%20Diagram.pdf PDF]]

* Data acquisition
** [[ Data mode | Data Modes ]]
** [[ Digital 4-pole Butterworth Low-pass filter | Filtered Data & the Digital 4-pole Butterworth Low-pass Filter]]
** [[ Raw-mode readout | Raw 50 MHz Data ]]
** [[ Rectangle Mode Data ]] - recommended mode for high-rate acquisition
** [[ High rate acquisition | Fast Data Acquisition ]] - high-rate acquisition without rectangle mode (deprecated)
** [[ Open loop data acquisition ]] - for noise measurements of the SQUID chain.
** [[ The STOP Command ]]
** [[ Dirfile support ]] - set up MAS to write dirfiles directly
** [[Data accumulation rate]] - how much data does the MCE produce?

* Data files
** [[ Python data and runfile modules ]] - mce_data.py)
** IDL [[ mas_data.pro | data ]] and [[ mas_runfile.pro and mas_runparam.pro | runfile]] scripts
** [[ MCE flat-file format ]]
** [[ Runfile format v2 ]]

* Internal commanding
** [[ Internal Commands ]] - notes on internal command implementation.
** [[ Ramp Generator ]]
** [[ Arbitrary Waveform Generator ]] -- for maximum length sequences and complex impedance measurements (CC v5.0.3+)

* Fast switching of the SQ2 feedback
** [[ Row-specific SQ2FB (fast switching)]]
** [[ Fast SQ2 Feedback and TES Biasing with an Address Card ]]

* mux11d support
** [[ Configuration for mux11d operation ]]
** [[ MCE Signal assignment for mux11d operation ]]
** [[ Hybrid row select for mux11d ]] (to combine AC and BC for multiplexing > 41 rows)

* MCE servo control
** [[ Flux jumping | Flux Jumping]]
** [[ FSFB Clamping Commands ]] -- to prevent unlocked detectors from ramping
** [[ Flux-loop reset per detector ]]

* Misc.
** [[ Noise Calculations]]
** [[ Special SQ1 Bias Commands ]]
** [[ MCE temperature ]]
[[Category:Usage]]

Main Page

2014-11-12T17:29:33Z

Mhasse: /* Contact Info */

This Wiki is for users of UBC's '''Multi-Channel Electronics''' (MCE), including the '''MCE Acquisition Software''' (MAS).
__NOTOC__
== MCE Overview ==
The MCE described here borrows heavily from the designs used at [http://www.nist.gov/pml/ NIST]. Changes have been made to upgrade components, achieve higher integration, and match to the specific experimental configurations.

In basic operation, one MCE [[subrack]] controls the SQUID amplifiers and multiplexer, and reads signals from one 32×41 pixel or 16×41 pixel sub-array. The system hardware is completely modular at the sub-array level. Each sub-array is connected via woven cryogenic cables to a single MCE subrack through 3 or 5 MDM connectors. Each MCE subrack is, in turn, connected by an optical fibre to a single data-acquisition PC running Linux and data-acquisition software ([[MAS]]) developed at UBC.

Each MCE consists of hybrid analog/digital hardware and firmware developed for Altera Stratix FPGAs. A subrack has up to nine cards: including 2 or 4 [[Readout card]]s each of which reads 8 output columns through 14-bit 50MHz ADCs; 1 [[address card]] to multiplex the first-stage SQUIDs biases at around 20kHz; 1 [[clock card]] to interpret commands and to synchronize all the cards using a 25MHz clock; 2 or 3 [[bias card]]s to control the SQUID series-array feedback, the second-stage SQUID bias and feedback as well as the bolometer bias and heater. During [[auto_setup|detector setup]], the MCE is used to calculate the optimal operating points for the bolometers and the SQUID amplifiers by measuring their characteristics using open and closed feedback loops. During observation, MCE uses a running PID-calculation to determine the first-stage SQUID feedback necessary to keep the whole amplification chain in a linear regime.

In conjunction with the MCEs, a [[Sync Box]] supplies data-valid pulses with serial numbers to all MCE subracks and to the telescope pointing system. This allows synchronization between the data acquisition, the pointing system, and the telescope housekeeping.

== Documentation ==

* [[ MCE hardware | MCE Hardware ]] - information on MCE hardware (and accessories)
* [[ MCE firmware | MCE Firmware ]] - firmware versions, features, and tools (including sync box and PCI card firmware)
* [[ MAS ]] - the MCE Acquisition Software - kernel driver and low-level tools
* [[ MCE script ]] - SQUID array setup programs
* [[ MCE usage ]] - practical usage and reference documents

== Contact Info ==

The '''<code>mce-announce</code>''' e-mail list is used to communicate important firmware and software updates to the MCE user community. You can subscribe to it by visiting:
:https://listserver.phas.ubc.ca/mailman/listinfo/mce-announce

MCE Lab: 604-822-2585
Halpern's Lab: 604-822-6709

Hardware/firmware: mandana at phas.ubc.ca
Software: mhasse at astro.princeton.edu, dvw at phas.ubc.ca

Department of Physics & Astronomy
University of British Columbia
Hennings 204, 6224 Agricultural Rd.
Vancouver, BC V6T 1Z1
Canada

Configuration for mux11d operation

2014-08-18T17:15:24Z

Mhasse: /* Usage */

:'''This topic is undergoing active development; information on this page is more subject to change than usual!'''

== Hardware configuration ==
The following diagram shows a conceptual schematic of using the MCE hardware with mux11d SQUID chips [http://www.phas.ubc.ca/~mce/mcedocs/system/mux11d_and_mce.pdf mux11d_with_mce.pdf] (prepared by Jimmy Grayson at Stanford)

For the reference: [[File:Mux11d_bias_simple_diagram.pdf]]

Here is the proposed MCE signal assignment scheme: [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.pdf [PDF]] [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.xls [XLS]]

Note that the signals the MCE must provide to the mux11d SQUID system are:
* SA BIAS per column, constant
* SA FB per column, fast-switching
* SQ1 BIAS per column, fast-switching
* "Rowsel" feedback per row, multiplexing (one value when active, another value when not active)

== Software requirements ==

=== MAS ===

The mux11d support in MAS has been merged back into trunk and the former mux11d branch deleted. You can check out a new tree:
svn checkout svn://e-mode.phas.ubc.ca/mas/trunk mas
or "switch" an existing checked-out mux11d branch to use trunk
cd ~/code/mas
svn switch svn://e-mode.phas.ubc.ca/mas/trunk .

Then rebuild and reinstall. The only mux11d-specific features are in the "mux_lock" applications (2 new programs) and in the config2 system (mce.cfg).

=== mce_script ===

Updates for mux11d have been put right into mce_script, starting with r914. Just run "svn update" on your checked out copy. The major changes so far are:
* [[ experiment.cfg ]] has extra parameters to configure and enable fast SA feedback and fast SQ1 bias switching, and to guide the new servo applications.
* the config script generation code (script/bits) will set up the MCE for mux11d operation depending on variables in experiment.cfg

== Configuration ==

=== mce.cfg ===

When constructing [[ mce.cfg ]], start from templates/mce_v1_mux11d.cin or templates/mce_v2_mux11d.cin. These will map SQ1 bias as a per-column register, and properly expose fast switching of the SA FB and SQ1 bias. Since there is no "SQ2" in mux11d, this register is not defined.

The default mux11d configuration maps:
* SA FB to BC1 FLUX_FB
* SQ1 BIAS to BC2 FLUX_FB

There are other ways one might choose to do this mapping. The SQ1 bias card and offset, can be overridden in mce.cin by changing these variables:
/* These are only used if hw_mux11d != 0; they specify the bias card
* and offset of the flux_fb register used for the SQ1 bias. */
$mux11d_sq1_bc = "bc2";
$mux11d_sq1_offset = 0;

At the MCE command level, fast-switching on the SA FB and SQ1 BIAS is accomplished with the same bias card registers used for Fast SQ2 switching (see [[Row-specific SQ2FB (fast switching)#Firmware_requirements|firmware requirements]]). As an example, to load per-row values into the SA FB on column 5, and then enable muxing on that column, you could do the following:
wb sa fb_col5 123 432 514 451 434 653 123 ...
wra sa enbl_mux 5 1
Then to set a constant value on column 5, and disable muxing:
wra sa fb 5 400
wra sa enbl_mux 5 0

The SQ1 BIAS is exposed in a similar way. For example, the column 5 biases are exposed through:
wb sq1 bias_col5 123 432 514 451 434 653 123 ...
wra sq1 enbl_mux 5 1

In practice users don't write these MCE commands directly, and instead use the slightly higher-level of support provided by the experiment.cfg / config script system.

=== experiment.cfg ===

A number of parameters have been added to experiment.cfg to allow the config script system to set up fast-switching on the SA FB and SQ1 BIAS. These are:

* Enable:
**'''hardware_mux11d = 1;''': triggers handling of all the other mux11d specific settings.
* Row Select DAC control; these are arrays of up to 41 integers representing values for the "row select" (AC ON_BIAS) and "row deselect" (AC OFF_BIAS) DACs.
**'''row_select = [...];''': will be written to "row select" by the config script.
**'''row_deselect = [...];''': will be written to "row deselect" by the config script.
**'''default_row_select, default_row_deselect''': Eventually these will be used by the tuning to select default row_select and row_deselect values if the tuning has been instructed not to try to choose them.
* SA FB control:
** '''config_fast_sa_fb = 0;''': When set to 0, MCE will be set up for constant SA FB output, with values obtained from the setting "sa_fb". When set to 1, MCE will be set up for fast-switching of SA FB output, with values obtained from '''sa_fb_set'''.
** '''sa_fb_set = [...];''': A 1d array encoding SA FB values for each row and column. (As usual the values are arranged as the 41 values for column 0, followed by the 41 values for column 1, etc.)
* SQ1 BIAS control - these work exactly like SA FB above.
** '''config_fast_sq1_bias = 1;'''
** '''sq1_bias_set = [...];'''

For the purposes of array tuning the '''sq1_servo_*''' parameters will be used by the new '''sq1servo_sa''' program, which ramps the SQ1 FB and servos with the fast-switching SA FB (on each row independently). This may optionally be done for a series of SQ1 bias values.

A new set of servo control parameters, '''rowsel_servo_*''' (taking the same suffixes as the sq1_servo_* variables) has been introduced to control the new '''rs_servo''' program, which ramps the "row select" DACs and servos with the fast-switching SA FB (optionally at a series of SQ1 biases). In particular these parameters are:
;; rowsel_servo_gain, rowsel_servo_flux_start, rowsel_servo_flux_count, rowsel_servo_flux_step, rowsel_servo_bias_ramp, rowsel_servo_bias_start, rowsel_servo_bias_count, rowsel_servo_bias_step

== Usage ==

=== auto_setup, mux11d edition ===

The auto_setup code has been updated to support mux11d. I am uncertain as to how well-tested this code is, however.

The steps in tuning a mux11d system are:
* '''sa_ramp''' -- same as classic tuning; select SA FB (and possibly also SA BIAS).
* '''rs_servo''' -- trace out the "Row Select" V-phi curves (all rows), probably at several different S1 bias values; pick a reasonable S1 BIAS (one value per row, column) and ROWSEL/ROWDESEL feedbacks (one value per row). The algorithm for selecting ROWSEL/ROWDESEL feedback values is:
** All (row select) V-phi curves are analyzed to identify the first minimum and next maximum in the V-phi response. Each V-phi curve (bias,row,column) is flagged as valid, or not. Only valid curves are used when determining optimal biases and feedbacks for each column/row.
** '''SQ1 bias choice:''' If the SQ1 bias was ramped, an optimal SQ1 bias is chosen for each column and row by finding the bias at which the maximum peak-to-peak response is seen.
** '''ROWSEL/ROWDESEL choice''': For a given row select V-phi curve, the ROWDESEL point is the first minimum (probably near FB=0) and the ROWSEL point is the first maximum to the right of the ROWDESEL point. For each row, the ROWSEL and ROWDESEL feedback values are taken as the median of those values over all columns in the row. Only the values corresponding to the optimal SQ1 bias are considered.
* '''sq1_servo_sa''' -- trace out the S1 V-phi curves (all rows), probably at several different S1 bias values; pick final fast-switching S1 BIAS values and fast-switching SA FB set-points.
** This is probably not fully implemented.
* '''sq1_ramp''', '''sq1_ramp_check''', '''sq1_ramp_tes''' -- as in classic tuning; check your open loop response.

=== Using the new servo programs ===

This is only relevant if you're trying to run the servo programs yourself on the command line. The auto_setup should already know how to do all of this stuff correctly.

The servo programs make a lot of assumptions about the state of the MCE before beginning their job. Preparation is usually handled by the tuning code. To run these programs manually, the biggest thing to be careful of is that you have enabled (or disabled) fast-switching on the relevant stages. Here's a sequence of terminal commands which should work:

# Disable fast switching
mas_param set config_fast_sa_fb 0
mas_param set config_fast_sq1_bias 0
# Basic MCE setup and SA tuning
auto_setup --last-stage sa_ramp
mas_param set config_fast_sa_fb 1
# Recreate config script and run it to program the MCE.
mce_make_config -x
# Run the servos on RC2
sq1servo_sa 2 myservo1
rs_servo 2 myservo2

Later, once you have set up the "sq1_bias_set" values:
mas_param set config_fast_sq1_bias 1
mce_make_config -x

Configuration for mux11d operation

2014-08-15T21:46:42Z

Mhasse: /* Using the new servo programs */

:'''This topic is undergoing active development; information on this page is more subject to change than usual!'''

== Hardware configuration ==
The following diagram shows a conceptual schematic of using the MCE hardware with mux11d SQUID chips [http://www.phas.ubc.ca/~mce/mcedocs/system/mux11d_and_mce.pdf mux11d_with_mce.pdf] (prepared by Jimmy Grayson at Stanford)

For the reference: [[File:Mux11d_bias_simple_diagram.pdf]]

Here is the proposed MCE signal assignment scheme: [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.pdf [PDF]] [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.xls [XLS]]

Note that the signals the MCE must provide to the mux11d SQUID system are:
* SA BIAS per column, constant
* SA FB per column, fast-switching
* SQ1 BIAS per column, fast-switching
* "Rowsel" feedback per row, multiplexing (one value when active, another value when not active)

== Software requirements ==

=== MAS ===

The mux11d support in MAS has been merged back into trunk and the former mux11d branch deleted. You can check out a new tree:
svn checkout svn://e-mode.phas.ubc.ca/mas/trunk mas
or "switch" an existing checked-out mux11d branch to use trunk
cd ~/code/mas
svn switch svn://e-mode.phas.ubc.ca/mas/trunk .

Then rebuild and reinstall. The only mux11d-specific features are in the "mux_lock" applications (2 new programs) and in the config2 system (mce.cfg).

=== mce_script ===

Updates for mux11d have been put right into mce_script, starting with r914. Just run "svn update" on your checked out copy. The major changes so far are:
* [[ experiment.cfg ]] has extra parameters to configure and enable fast SA feedback and fast SQ1 bias switching, and to guide the new servo applications.
* the config script generation code (script/bits) will set up the MCE for mux11d operation depending on variables in experiment.cfg

== Configuration ==

=== mce.cfg ===

When constructing [[ mce.cfg ]], start from templates/mce_v1_mux11d.cin or templates/mce_v2_mux11d.cin. These will map SQ1 bias as a per-column register, and properly expose fast switching of the SA FB and SQ1 bias. Since there is no "SQ2" in mux11d, this register is not defined.

The default mux11d configuration maps:
* SA FB to BC1 FLUX_FB
* SQ1 BIAS to BC2 FLUX_FB

There are other ways one might choose to do this mapping. The SQ1 bias card and offset, can be overridden in mce.cin by changing these variables:
/* These are only used if hw_mux11d != 0; they specify the bias card
* and offset of the flux_fb register used for the SQ1 bias. */
$mux11d_sq1_bc = "bc2";
$mux11d_sq1_offset = 0;

At the MCE command level, fast-switching on the SA FB and SQ1 BIAS is accomplished with the same bias card registers used for Fast SQ2 switching (see [[Row-specific SQ2FB (fast switching)#Firmware_requirements|firmware requirements]]). As an example, to load per-row values into the SA FB on column 5, and then enable muxing on that column, you could do the following:
wb sa fb_col5 123 432 514 451 434 653 123 ...
wra sa enbl_mux 5 1
Then to set a constant value on column 5, and disable muxing:
wra sa fb 5 400
wra sa enbl_mux 5 0

The SQ1 BIAS is exposed in a similar way. For example, the column 5 biases are exposed through:
wb sq1 bias_col5 123 432 514 451 434 653 123 ...
wra sq1 enbl_mux 5 1

In practice users don't write these MCE commands directly, and instead use the slightly higher-level of support provided by the experiment.cfg / config script system.

=== experiment.cfg ===

A number of parameters have been added to experiment.cfg to allow the config script system to set up fast-switching on the SA FB and SQ1 BIAS. These are:

* Enable:
**'''hardware_mux11d = 1;''': triggers handling of all the other mux11d specific settings.
* Row Select DAC control; these are arrays of up to 41 integers representing values for the "row select" (AC ON_BIAS) and "row deselect" (AC OFF_BIAS) DACs.
**'''row_select = [...];''': will be written to "row select" by the config script.
**'''row_deselect = [...];''': will be written to "row deselect" by the config script.
**'''default_row_select, default_row_deselect''': Eventually these will be used by the tuning to select default row_select and row_deselect values if the tuning has been instructed not to try to choose them.
* SA FB control:
** '''config_fast_sa_fb = 0;''': When set to 0, MCE will be set up for constant SA FB output, with values obtained from the setting "sa_fb". When set to 1, MCE will be set up for fast-switching of SA FB output, with values obtained from '''sa_fb_set'''.
** '''sa_fb_set = [...];''': A 1d array encoding SA FB values for each row and column. (As usual the values are arranged as the 41 values for column 0, followed by the 41 values for column 1, etc.)
* SQ1 BIAS control - these work exactly like SA FB above.
** '''config_fast_sq1_bias = 1;'''
** '''sq1_bias_set = [...];'''

For the purposes of array tuning the '''sq1_servo_*''' parameters will be used by the new '''sq1servo_sa''' program, which ramps the SQ1 FB and servos with the fast-switching SA FB (on each row independently). This may optionally be done for a series of SQ1 bias values.

A new set of servo control parameters, '''rowsel_servo_*''' (taking the same suffixes as the sq1_servo_* variables) has been introduced to control the new '''rs_servo''' program, which ramps the "row select" DACs and servos with the fast-switching SA FB (optionally at a series of SQ1 biases). In particular these parameters are:
;; rowsel_servo_gain, rowsel_servo_flux_start, rowsel_servo_flux_count, rowsel_servo_flux_step, rowsel_servo_bias_ramp, rowsel_servo_bias_start, rowsel_servo_bias_count, rowsel_servo_bias_step

== Usage ==

=== auto_setup, mux11d edition ===

The auto_setup code has been updated to support mux11d. I am uncertain as to how well-tested this code is, however.

The steps in tuning a mux11d system are:
* '''sa_ramp''' -- same as classic tuning; select SA FB (and possibly also SA BIAS).
* '''rs_servo''' -- trace out the Rowsel V-phi curves (all rows), probably at several different S1 bias values; pick a reasonable S1 BIAS (one value per row, column) and ROWSEL/ROWDESEL (one value per row) values.
* '''sq1_servo_sa''' -- trace out the S1 V-phi curves (all rows), probably at several different S1 bias values; pick final fast-switching S1 BIAS values and fast-switching SA FB set-points.
* '''sq1_ramp''', '''sq1_ramp_check''', '''sq1_ramp_tes''' -- as in classic tuning; check your open loop response.

=== Using the new servo programs ===

This is only relevant if you're trying to run the servo programs yourself on the command line. The auto_setup should already know how to do all of this stuff correctly.

The servo programs make a lot of assumptions about the state of the MCE before beginning their job. Preparation is usually handled by the tuning code. To run these programs manually, the biggest thing to be careful of is that you have enabled (or disabled) fast-switching on the relevant stages. Here's a sequence of terminal commands which should work:

# Disable fast switching
mas_param set config_fast_sa_fb 0
mas_param set config_fast_sq1_bias 0
# Basic MCE setup and SA tuning
auto_setup --last-stage sa_ramp
mas_param set config_fast_sa_fb 1
# Recreate config script and run it to program the MCE.
mce_make_config -x
# Run the servos on RC2
sq1servo_sa 2 myservo1
rs_servo 2 myservo2

Later, once you have set up the "sq1_bias_set" values:
mas_param set config_fast_sq1_bias 1
mce_make_config -x

Configuration for mux11d operation

2014-08-15T21:45:52Z

Mhasse: /* Usage */

:'''This topic is undergoing active development; information on this page is more subject to change than usual!'''

== Hardware configuration ==
The following diagram shows a conceptual schematic of using the MCE hardware with mux11d SQUID chips [http://www.phas.ubc.ca/~mce/mcedocs/system/mux11d_and_mce.pdf mux11d_with_mce.pdf] (prepared by Jimmy Grayson at Stanford)

For the reference: [[File:Mux11d_bias_simple_diagram.pdf]]

Here is the proposed MCE signal assignment scheme: [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.pdf [PDF]] [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.xls [XLS]]

Note that the signals the MCE must provide to the mux11d SQUID system are:
* SA BIAS per column, constant
* SA FB per column, fast-switching
* SQ1 BIAS per column, fast-switching
* "Rowsel" feedback per row, multiplexing (one value when active, another value when not active)

== Software requirements ==

=== MAS ===

The mux11d support in MAS has been merged back into trunk and the former mux11d branch deleted. You can check out a new tree:
svn checkout svn://e-mode.phas.ubc.ca/mas/trunk mas
or "switch" an existing checked-out mux11d branch to use trunk
cd ~/code/mas
svn switch svn://e-mode.phas.ubc.ca/mas/trunk .

Then rebuild and reinstall. The only mux11d-specific features are in the "mux_lock" applications (2 new programs) and in the config2 system (mce.cfg).

=== mce_script ===

Updates for mux11d have been put right into mce_script, starting with r914. Just run "svn update" on your checked out copy. The major changes so far are:
* [[ experiment.cfg ]] has extra parameters to configure and enable fast SA feedback and fast SQ1 bias switching, and to guide the new servo applications.
* the config script generation code (script/bits) will set up the MCE for mux11d operation depending on variables in experiment.cfg

== Configuration ==

=== mce.cfg ===

When constructing [[ mce.cfg ]], start from templates/mce_v1_mux11d.cin or templates/mce_v2_mux11d.cin. These will map SQ1 bias as a per-column register, and properly expose fast switching of the SA FB and SQ1 bias. Since there is no "SQ2" in mux11d, this register is not defined.

The default mux11d configuration maps:
* SA FB to BC1 FLUX_FB
* SQ1 BIAS to BC2 FLUX_FB

There are other ways one might choose to do this mapping. The SQ1 bias card and offset, can be overridden in mce.cin by changing these variables:
/* These are only used if hw_mux11d != 0; they specify the bias card
* and offset of the flux_fb register used for the SQ1 bias. */
$mux11d_sq1_bc = "bc2";
$mux11d_sq1_offset = 0;

At the MCE command level, fast-switching on the SA FB and SQ1 BIAS is accomplished with the same bias card registers used for Fast SQ2 switching (see [[Row-specific SQ2FB (fast switching)#Firmware_requirements|firmware requirements]]). As an example, to load per-row values into the SA FB on column 5, and then enable muxing on that column, you could do the following:
wb sa fb_col5 123 432 514 451 434 653 123 ...
wra sa enbl_mux 5 1
Then to set a constant value on column 5, and disable muxing:
wra sa fb 5 400
wra sa enbl_mux 5 0

The SQ1 BIAS is exposed in a similar way. For example, the column 5 biases are exposed through:
wb sq1 bias_col5 123 432 514 451 434 653 123 ...
wra sq1 enbl_mux 5 1

In practice users don't write these MCE commands directly, and instead use the slightly higher-level of support provided by the experiment.cfg / config script system.

=== experiment.cfg ===

A number of parameters have been added to experiment.cfg to allow the config script system to set up fast-switching on the SA FB and SQ1 BIAS. These are:

* Enable:
**'''hardware_mux11d = 1;''': triggers handling of all the other mux11d specific settings.
* Row Select DAC control; these are arrays of up to 41 integers representing values for the "row select" (AC ON_BIAS) and "row deselect" (AC OFF_BIAS) DACs.
**'''row_select = [...];''': will be written to "row select" by the config script.
**'''row_deselect = [...];''': will be written to "row deselect" by the config script.
**'''default_row_select, default_row_deselect''': Eventually these will be used by the tuning to select default row_select and row_deselect values if the tuning has been instructed not to try to choose them.
* SA FB control:
** '''config_fast_sa_fb = 0;''': When set to 0, MCE will be set up for constant SA FB output, with values obtained from the setting "sa_fb". When set to 1, MCE will be set up for fast-switching of SA FB output, with values obtained from '''sa_fb_set'''.
** '''sa_fb_set = [...];''': A 1d array encoding SA FB values for each row and column. (As usual the values are arranged as the 41 values for column 0, followed by the 41 values for column 1, etc.)
* SQ1 BIAS control - these work exactly like SA FB above.
** '''config_fast_sq1_bias = 1;'''
** '''sq1_bias_set = [...];'''

For the purposes of array tuning the '''sq1_servo_*''' parameters will be used by the new '''sq1servo_sa''' program, which ramps the SQ1 FB and servos with the fast-switching SA FB (on each row independently). This may optionally be done for a series of SQ1 bias values.

A new set of servo control parameters, '''rowsel_servo_*''' (taking the same suffixes as the sq1_servo_* variables) has been introduced to control the new '''rs_servo''' program, which ramps the "row select" DACs and servos with the fast-switching SA FB (optionally at a series of SQ1 biases). In particular these parameters are:
;; rowsel_servo_gain, rowsel_servo_flux_start, rowsel_servo_flux_count, rowsel_servo_flux_step, rowsel_servo_bias_ramp, rowsel_servo_bias_start, rowsel_servo_bias_count, rowsel_servo_bias_step

== Usage ==

=== auto_setup, mux11d edition ===

The auto_setup code has been updated to support mux11d. I am uncertain as to how well-tested this code is, however.

The steps in tuning a mux11d system are:
* '''sa_ramp''' -- same as classic tuning; select SA FB (and possibly also SA BIAS).
* '''rs_servo''' -- trace out the Rowsel V-phi curves (all rows), probably at several different S1 bias values; pick a reasonable S1 BIAS (one value per row, column) and ROWSEL/ROWDESEL (one value per row) values.
* '''sq1_servo_sa''' -- trace out the S1 V-phi curves (all rows), probably at several different S1 bias values; pick final fast-switching S1 BIAS values and fast-switching SA FB set-points.
* '''sq1_ramp''', '''sq1_ramp_check''', '''sq1_ramp_tes''' -- as in classic tuning; check your open loop response.

=== Using the new servo programs ===

The servo programs make a lot of assumptions about the state of the MCE before beginning their job. Preparation is usually handled by the tuning code. To run these programs manually, the biggest thing to be careful of is that you have enabled (or disabled) fast-switching on the relevant stages. Here's a sequence of terminal commands which should work:

# Disable fast switching
mas_param set config_fast_sa_fb 0
mas_param set config_fast_sq1_bias 0
# Basic MCE setup and SA tuning
auto_setup --last-stage sa_ramp
mas_param set config_fast_sa_fb 1
# Recreate config script and run it to program the MCE.
mce_make_config -x
# Run the servos on RC2
sq1servo_sa 2 myservo1
rs_servo 2 myservo2

Later, once you have set up the "sq1_bias_set" values:
mas_param set config_fast_sq1_bias 1
mce_make_config -x

Configuration for mux11d operation

2014-08-15T21:36:33Z

Mhasse:

:'''This topic is undergoing active development; information on this page is more subject to change than usual!'''

== Hardware configuration ==
The following diagram shows a conceptual schematic of using the MCE hardware with mux11d SQUID chips [http://www.phas.ubc.ca/~mce/mcedocs/system/mux11d_and_mce.pdf mux11d_with_mce.pdf] (prepared by Jimmy Grayson at Stanford)

For the reference: [[File:Mux11d_bias_simple_diagram.pdf]]

Here is the proposed MCE signal assignment scheme: [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.pdf [PDF]] [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.xls [XLS]]

Note that the signals the MCE must provide to the mux11d SQUID system are:
* SA BIAS per column, constant
* SA FB per column, fast-switching
* SQ1 BIAS per column, fast-switching
* "Rowsel" feedback per row, multiplexing (one value when active, another value when not active)

== Software requirements ==

=== MAS ===

The mux11d support in MAS has been merged back into trunk and the former mux11d branch deleted. You can check out a new tree:
svn checkout svn://e-mode.phas.ubc.ca/mas/trunk mas
or "switch" an existing checked-out mux11d branch to use trunk
cd ~/code/mas
svn switch svn://e-mode.phas.ubc.ca/mas/trunk .

Then rebuild and reinstall. The only mux11d-specific features are in the "mux_lock" applications (2 new programs) and in the config2 system (mce.cfg).

=== mce_script ===

Updates for mux11d have been put right into mce_script, starting with r914. Just run "svn update" on your checked out copy. The major changes so far are:
* [[ experiment.cfg ]] has extra parameters to configure and enable fast SA feedback and fast SQ1 bias switching, and to guide the new servo applications.
* the config script generation code (script/bits) will set up the MCE for mux11d operation depending on variables in experiment.cfg

== Configuration ==

=== mce.cfg ===

When constructing [[ mce.cfg ]], start from templates/mce_v1_mux11d.cin or templates/mce_v2_mux11d.cin. These will map SQ1 bias as a per-column register, and properly expose fast switching of the SA FB and SQ1 bias. Since there is no "SQ2" in mux11d, this register is not defined.

The default mux11d configuration maps:
* SA FB to BC1 FLUX_FB
* SQ1 BIAS to BC2 FLUX_FB

There are other ways one might choose to do this mapping. The SQ1 bias card and offset, can be overridden in mce.cin by changing these variables:
/* These are only used if hw_mux11d != 0; they specify the bias card
* and offset of the flux_fb register used for the SQ1 bias. */
$mux11d_sq1_bc = "bc2";
$mux11d_sq1_offset = 0;

At the MCE command level, fast-switching on the SA FB and SQ1 BIAS is accomplished with the same bias card registers used for Fast SQ2 switching (see [[Row-specific SQ2FB (fast switching)#Firmware_requirements|firmware requirements]]). As an example, to load per-row values into the SA FB on column 5, and then enable muxing on that column, you could do the following:
wb sa fb_col5 123 432 514 451 434 653 123 ...
wra sa enbl_mux 5 1
Then to set a constant value on column 5, and disable muxing:
wra sa fb 5 400
wra sa enbl_mux 5 0

The SQ1 BIAS is exposed in a similar way. For example, the column 5 biases are exposed through:
wb sq1 bias_col5 123 432 514 451 434 653 123 ...
wra sq1 enbl_mux 5 1

In practice users don't write these MCE commands directly, and instead use the slightly higher-level of support provided by the experiment.cfg / config script system.

=== experiment.cfg ===

A number of parameters have been added to experiment.cfg to allow the config script system to set up fast-switching on the SA FB and SQ1 BIAS. These are:

* Enable:
**'''hardware_mux11d = 1;''': triggers handling of all the other mux11d specific settings.
* Row Select DAC control; these are arrays of up to 41 integers representing values for the "row select" (AC ON_BIAS) and "row deselect" (AC OFF_BIAS) DACs.
**'''row_select = [...];''': will be written to "row select" by the config script.
**'''row_deselect = [...];''': will be written to "row deselect" by the config script.
**'''default_row_select, default_row_deselect''': Eventually these will be used by the tuning to select default row_select and row_deselect values if the tuning has been instructed not to try to choose them.
* SA FB control:
** '''config_fast_sa_fb = 0;''': When set to 0, MCE will be set up for constant SA FB output, with values obtained from the setting "sa_fb". When set to 1, MCE will be set up for fast-switching of SA FB output, with values obtained from '''sa_fb_set'''.
** '''sa_fb_set = [...];''': A 1d array encoding SA FB values for each row and column. (As usual the values are arranged as the 41 values for column 0, followed by the 41 values for column 1, etc.)
* SQ1 BIAS control - these work exactly like SA FB above.
** '''config_fast_sq1_bias = 1;'''
** '''sq1_bias_set = [...];'''

For the purposes of array tuning the '''sq1_servo_*''' parameters will be used by the new '''sq1servo_sa''' program, which ramps the SQ1 FB and servos with the fast-switching SA FB (on each row independently). This may optionally be done for a series of SQ1 bias values.

A new set of servo control parameters, '''rowsel_servo_*''' (taking the same suffixes as the sq1_servo_* variables) has been introduced to control the new '''rs_servo''' program, which ramps the "row select" DACs and servos with the fast-switching SA FB (optionally at a series of SQ1 biases). In particular these parameters are:
;; rowsel_servo_gain, rowsel_servo_flux_start, rowsel_servo_flux_count, rowsel_servo_flux_step, rowsel_servo_bias_ramp, rowsel_servo_bias_start, rowsel_servo_bias_count, rowsel_servo_bias_step

== Usage ==

=== Using the new servo programs ===

The servo programs make a lot of assumptions about the state of the MCE before beginning their job. Preparation is usually handled by the tuning code. To run these programs manually, the biggest thing to be careful of is that you have enabled (or disabled) fast-switching on the relevant stages. Here's a sequence of terminal commands which should work:

# Disable fast switching
mas_param set config_fast_sa_fb 0
mas_param set config_fast_sq1_bias 0
# Basic MCE setup and SA tuning
auto_setup --last-stage sa_ramp
mas_param set config_fast_sa_fb 1
# Recreate config script and run it to program the MCE.
mce_make_config -x
# Run the servos on RC2
sq1servo_sa 2 myservo1
rs_servo 2 myservo2

Later, once you have set up the "sq1_bias_set" values:
mas_param set config_fast_sq1_bias 1
mce_make_config -x

Configuration for mux11d operation

2014-08-15T21:33:12Z

Mhasse: /* mce.cfg */

:'''This topic is undergoing active development; information on this page is more subject to change than usual!'''
== Hardware configuration ==
The following diagram shows a conceptual schematic of using the MCE hardware with mux11d SQUID chips [http://www.phas.ubc.ca/~mce/mcedocs/system/mux11d_and_mce.pdf mux11d_with_mce.pdf] (prepared by Jimmy Grayson at Stanford)

For the reference: [[File:Mux11d_bias_simple_diagram.pdf]]

Here is the proposed MCE signal assignment scheme: [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.pdf [PDF]] [http://www.phas.ubc.ca/~mce/mcedocs/system/mce_mdm_signal_names_and_pinouts.xls [XLS]]

== Software requirements ==

=== MAS ===

The mux11d support in MAS has been merged back into trunk and the former mux11d branch deleted. You can check out a new tree:
svn checkout svn://e-mode.phas.ubc.ca/mas/trunk mas
or "switch" an existing checked-out mux11d branch to use trunk
cd ~/code/mas
svn switch svn://e-mode.phas.ubc.ca/mas/trunk .

Then rebuild and reinstall. The only mux11d-specific features are in the "mux_lock" applications (2 new programs) and in the config2 system (mce.cfg).

=== mce_script ===

Updates for mux11d have been put right into mce_script, starting with r914. Just run "svn update" on your checked out copy. The major changes so far are:
* [[ experiment.cfg ]] has extra parameters to configure and enable fast SA feedback and fast SQ1 bias switching, and to guide the new servo applications.
* the config script generation code (script/bits) will set up the MCE for mux11d operation depending on variables in experiment.cfg

== Configuration ==

=== mce.cfg ===

When constructing [[ mce.cfg ]], start from templates/mce_v1_mux11d.cin or templates/mce_v2_mux11d.cin. These will map SQ1 bias as a per-column register, and properly expose fast switching of the SA FB and SQ1 bias. Since there is no "SQ2" in mux11d, this register is not defined.

The default mux11d configuration maps:
* SA FB to BC1 FLUX_FB
* SQ1 BIAS to BC2 FLUX_FB

There are other ways one might choose to do this mapping. The SQ1 bias card and offset, can be overridden in mce.cin by changing these variables:
/* These are only used if hw_mux11d != 0; they specify the bias card
* and offset of the flux_fb register used for the SQ1 bias. */
$mux11d_sq1_bc = "bc2";
$mux11d_sq1_offset = 0;

At the MCE command level, fast-switching on the SA FB and SQ1 BIAS is accomplished with the same bias card registers used for Fast SQ2 switching (see [[Row-specific SQ2FB (fast switching)#Firmware_requirements|firmware requirements]]). As an example, to load per-row values into the SA FB on column 5, and then enable muxing on that column, you could do the following:
wb sa fb_col5 123 432 514 451 434 653 123 ...
wra sa enbl_mux 5 1
Then to set a constant value on column 5, and disable muxing:
wra sa fb 5 400
wra sa enbl_mux 5 0

The SQ1 BIAS is exposed in a similar way. For example, the column 5 biases are exposed through:
wb sq1 bias_col5 123 432 514 451 434 653 123 ...
wra sq1 enbl_mux 5 1

In practice users don't write these MCE commands directly, and instead use the slightly higher-level of support provided by the experiment.cfg / config script system.

=== experiment.cfg ===

A number of parameters have been added to experiment.cfg to allow the config script system to set up fast-switching on the SA FB and SQ1 BIAS. These are:

* Enable:
**'''hardware_mux11d = 1;''': triggers handling of all the other mux11d specific settings.
* Row Select DAC control; these are arrays of up to 41 integers representing values for the "row select" (AC ON_BIAS) and "row deselect" (AC OFF_BIAS) DACs.
**'''row_select = [...];''': will be written to "row select" by the config script.
**'''row_deselect = [...];''': will be written to "row deselect" by the config script.
**'''default_row_select, default_row_deselect''': Eventually these will be used by the tuning to select default row_select and row_deselect values if the tuning has been instructed not to try to choose them.
* SA FB control:
** '''config_fast_sa_fb = 0;''': When set to 0, MCE will be set up for constant SA FB output, with values obtained from the setting "sa_fb". When set to 1, MCE will be set up for fast-switching of SA FB output, with values obtained from '''sa_fb_set'''.
** '''sa_fb_set = [...];''': A 1d array encoding SA FB values for each row and column. (As usual the values are arranged as the 41 values for column 0, followed by the 41 values for column 1, etc.)
* SQ1 BIAS control - these work exactly like SA FB above.
** '''config_fast_sq1_bias = 1;'''
** '''sq1_bias_set = [...];'''

For the purposes of array tuning the '''sq1_servo_*''' parameters will be used by the new '''sq1servo_sa''' program, which ramps the SQ1 FB and servos with the fast-switching SA FB (on each row independently). This may optionally be done for a series of SQ1 bias values.

A new set of servo control parameters, '''rowsel_servo_*''' (taking the same suffixes as the sq1_servo_* variables) has been introduced to control the new '''rs_servo''' program, which ramps the "row select" DACs and servos with the fast-switching SA FB (optionally at a series of SQ1 biases). In particular these parameters are:
;; rowsel_servo_gain, rowsel_servo_flux_start, rowsel_servo_flux_count, rowsel_servo_flux_step, rowsel_servo_bias_ramp, rowsel_servo_bias_start, rowsel_servo_bias_count, rowsel_servo_bias_step

== Usage ==

=== Using the new servo programs ===

The servo programs make a lot of assumptions about the state of the MCE before beginning their job. Preparation is usually handled by the tuning code. To run these programs manually, the biggest thing to be careful of is that you have enabled (or disabled) fast-switching on the relevant stages. Here's a sequence of terminal commands which should work:

# Disable fast switching
mas_param set config_fast_sa_fb 0
mas_param set config_fast_sq1_bias 0
# Basic MCE setup and SA tuning
auto_setup --last-stage sa_ramp
mas_param set config_fast_sa_fb 1
# Recreate config script and run it to program the MCE.
mce_make_config -x
# Run the servos on RC2
sq1servo_sa 2 myservo1
rs_servo 2 myservo2

Later, once you have set up the "sq1_bias_set" values:
mas_param set config_fast_sq1_bias 1
mce_make_config -x

MAS OS setup

2014-07-22T19:37:09Z

Mhasse: /* Supported operating systems */

{{Hierarchy header}}
= Supported operating systems =

We use Ubuntu.

* Supported versions:
** 14.04 (new, partial support)
** 12.04 or 10.04 (both are LTS releases)
* Formerly supported versions:
** 9.10, 9.04, 8.10, 8.04, 7.10, 6.06.
* In general, we're only willing to support LTS releases now.

= Ubuntu 14.04 =

Follow instructions for Ubuntu 12.04, but use install tools package:

wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/mce_install_ubuntu_14.04.tar.gz

= Ubuntu 12.04 =

The automated installation package is tested, but as Ubuntu tweaks its packages the install script may fall slightly out of sync. It's worth a shot though.

After installing Ubuntu 12.04, get the install tarball:

cd ~
wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/ubuntu_12.04_install.tar.gz
tar -xzf ubuntu_12.04_install.tar.gz
cd install/

== Install additional ubuntu packages ==

From that install folder, run
bash install.bash

== Bigphysarea kernel patch ==

You can either download the compiled kernels or build them from scratch.

From install folder, run EITHER
bash kernel_download.bash
or
bash kernel_build.bash

Compiled kernels currently exist for the x64 architecture.

Then when one or the other of those has succeeded, install them:
bash kernel_install.bash

You can now proceed to the section below titled "[[#Configure_the_system_for_MCE_users|Configure the system for MCE users]]".

= Ubuntu 10.04 =

The automated installation package is tested, but as Ubuntu tweaks its packages the install script may fall slightly out of sync. It's worth a shot though.

After installing Ubuntu 10.04 (desktop), get the install tarball:

cd ~
wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/ubuntu_10.04_install.tar.gz
tar -xzf ubuntu_10.04_install.tar.gz
cd install/

== Install additional ubuntu packages ==

From that install folder, run
bash install.bash

(Under 10.04, the vanilla kernel 2.6.38.8 is also supported. To use it, copy ./alternatives/sources.2.6.38.8.bash to ./sources.bash before running install.bash and kernel_build.bash .)

== Bigphysarea kernel patch ==

You can either download the compiled kernels or build them from scratch.

From install folder, run EITHER
bash kernel_download.bash
or
bash kernel_build.bash

Then when one or the other of those has succeeded, install them:
bash kernel_install.bash

You can now proceed to the section below titled "[[#Configure_the_system_for_MCE_users|Configure the system for MCE users]]".

= Ubuntu 9.10 and earlier =

See [[MAS OS setup on obsolete systems]]

= Configure the system for MCE users =

== Setup environment for MCE user ==

We tend to assume that a single user and group will have dominion over the MCE software, scripts, and data. We often assume that this user will be called "mce". But it doesn't need to be. Even if multiple users are running things through their own accounts it is likely useful to have a single group that can be used to manage access to the data.

Anyway, to set up a reasonable MCE user, see [[MAS user setup]].

All users using the MCE will need to define some environment variables to use the scripts. See the above link for lines to add to your '''.bashrc'''.

== System umask ==

You may want to set the system umask to make for a system where it's easier to share
Set the umask for all users to give write access for their group by default.

Edit /etc/profile and change the "umask 022" line to
umask 002

Edit /etc/login.defs and find the line that start "# UMASK" and change it to
UMASK 002

== Folders ==

mce_script assumes that /data/cryo/ exists and can be manipulated. To create something reasonable:

MCE_USER=mce
MCE_GROUP=mce
sudo mkdir /data
sudo chown $MCE_USER:$MCE_GROUP /data
sudo chmod g+ws /data
mkdir /data/cryo/

= Download (checkout) MAS and mce_script =

See [[MAS svn repository]].

= Compile and install MAS =

The following procedure outlines the default situation, where MAS is being installed on a computer containing only one fibre card. For information on running MAS with multiple fibre cards in one computer, see [[Multicard MAS]].

== Makefile.svn ==

MAS uses autoconf for some basic configuration stuff. After checking out MAS from the SVN repository the ''first'' time, you need to bootstrap the autoconf process. To simplify this, the Makefile.svn file will automate the process. From the MAS source folder run

make -f Makefile.svn

If successful, this will create the "./configure" script. This step is only required on fresh check-outs of the repository. If you already have a ./configure script, even if it's out of date, you can skip this step. (After having been bootstrapped the
first time, the build system is smart enough to know when it needs to regenerate itself.)

Note: this procedure requires autoconf. If it's not installed, install it with:

sudo apt-get install autoconf

== ./configure ==

Once the configure script exists, run it to generate the build system (ie. the Makefiles). The biggest thing you usually need to tell it is what the basic username and group should be for mce data. Also, there are a few options for the driver and some stupid python stuff.

From the MAS source folder, run

./configure

Some useful options:
--disable-driver suppress driver compilation/installation
--disable-bigphysarea compile driver without bigphysarea support
--disable-config2 suppress mas.cfg and mce.cfg generation/installation
--enable-multicard build a version of MAS which can drive multiple fibre cards. (See [[Multicard MAS]] for specifics.)
--with-user=USER set default MCE user
--with-group=GROUP set default MCE group
--with-kernel-dir=DIR set kernel build directory (typically automatically determined)

Run

./configure --help

for a full list. When running, configure will complain if it cannot find something, and even suggest what package you need to install.

== mce.cfg ==

After running configure, but before running make, you must specify a template file (mce.cin) which will be used to generate the hardware configuration file (mce.cfg). Full details of this procedure are given in the [[mce.cfg]] page, but briefly:

# copy an appropriate template from <code>config2/templates</code> to <code>config2/mce.cin</code>
# edit the <code>config2/mce.cin</code> file to describe your MCE.

The configuration file will be installed automatically when <code>make install</code> is run below. This entire step can be skipped if you passed --disable-config2 to configure above, but note that MAS will not function without mce.cfg and mas.cfg installed.

== make ==

This often works.

make clean; make

=== Troubleshooting ===
Sometimes after doing an SVN update <code>make</code> doesn't work but instead returns the cryptic message:

*** No rule to make target `defaults/masdefault.m4', needed by `aclocal.m4'.

In this case, it's necessary to force a rebuild of the build system manually by running

make -f Makefile.svn
./configure

See the [[#Makefile.svn|Makefile.svn section]] above for further details.

== Test the driver ==

It is wise to test that the driver does not kill your machine before installing it to load on boot. After compiling do:

cd driver
sudo ./reload

This will load the driver, which should then try to talk to the SDSU PCI card if it is installed. Note that since "reload" first unloads the driver if it is present, and then loads the driver from the current folder, it may report an "ERROR" message if the first step fails, even though the driver is successfully loaded. The definitive way to check that the driver is loaded is
cat [[/proc/mce_dsp]]

If this file does not exist, the driver isn't loaded. If the cat prints out a bunch of low-level driver information, you're in good shape.

== sudo make install ==

If you're satisfied that the driver works, install the whole thing. Go back up to the MAS base folder and run

sudo make install

This will do the following:

*install the kernel driver, <code>driver/mce_dsp.ko</code>, into <code>/lib/modules/$(uname -r)/kernel/drivers/misc/</code>, and re-scan the module dependencies.
*install the MAS binaries from <code>applications/</code> and the scripts from <code>script/</code> into <code>/usr/mce/bin</code>
*install the MAS udev ruleset <code>scripts/91-mas.rules</code> into <code>/etc/udev/rules.d/</code>. These udev rules will ensure that the mce_dsp module is loaded and the MAS device nodes are created at boot time. You can get udev to run these rules immediately, which will result in /dev being populated with the mce devices, by running:

sudo udevadm trigger

:or, else, you can make the nodes yourself by running mas_mknodes.
*install the mas logging daemon script <code>/etc/init.d/mas</code> init script. The driver can then be started/restarted as desired through this script:

/etc/init.d/mas restart

:The driver will automatically be set to load on boot. To disable this, remove the symbolic link "/etc/rc2.d/S99mas".
*install the hardware configuration file, <code>config2/mce.cfg</code>, and the MAS configuration file, <code>config2/mas.cfg</code> to <code>/etc/mce/</code>, assuming there aren't versions already there.

= Install mce_script =

Users have the option of running the MCE scripts from an svn working copy, or of running the MCE scripts from an "installed" copy. Talk to your MAS technician about which option is best for you.

== Running from an svn working copy ==

Checkout the tree directly into /usr/mce:

cd /usr/mce
svn checkout svn://e-mode.phas.ubc.ca/mce_script/trunk mce_script

== Running from an installed copy ==

Checkout the tree into your code folder; then make and install:

cd code
svn checkout svn://e-mode.phas.ubc.ca/mce_script/trunk mce_script
make
sudo make install

== .bashrc ==

Add a few lines to .bashrc to update your PATH, PYTHONPATH, and to define the MAS_* variables. The new way, using [[mas_var]], is:
eval `/usr/mce/bin/mas_var -e -s`

The old way, which will probably still work for a while:

export MAS_ROOT=/usr/mce/mce_script/
source $MAS_ROOT/template/mas_env.bash
export IDL_PATH="<IDL_DEFAULT>:$MAS_IDL/mas"

== Configuration data ==

Example configuration files (especially [[experiment.cfg]]) are kept in mce_script/template. MAS, by default, expects user configuration data to be in /usr/mce/config. Users should copy the template/ files to /usr/mce/config/, and then make configuration adjustments. From the svn working copy you can use the "export" command:

mce@ubuntu:~$ sudo mkdir /usr/mce/config
mce@ubuntu:~$ sudo chown mce: /usr/mce/config
mce@ubuntu:~$ svn export --force ~/code/mce_script/template/ /usr/mce/config

MAS OS setup

2014-07-22T19:36:48Z

Mhasse: /* Ubuntu 12.04 */

{{Hierarchy header}}
= Supported operating systems =

We use Ubuntu.

* Supported versions:
** 12.04 or 10.04 (both are LTS releases)
* Formerly supported versions:
** 9.10, 9.04, 8.10, 8.04, 7.10, 6.06.
* In general, we're only willing to support LTS releases now.

= Ubuntu 14.04 =

Follow instructions for Ubuntu 12.04, but use install tools package:

wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/mce_install_ubuntu_14.04.tar.gz

= Ubuntu 12.04 =

The automated installation package is tested, but as Ubuntu tweaks its packages the install script may fall slightly out of sync. It's worth a shot though.

After installing Ubuntu 12.04, get the install tarball:

cd ~
wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/ubuntu_12.04_install.tar.gz
tar -xzf ubuntu_12.04_install.tar.gz
cd install/

== Install additional ubuntu packages ==

From that install folder, run
bash install.bash

== Bigphysarea kernel patch ==

You can either download the compiled kernels or build them from scratch.

From install folder, run EITHER
bash kernel_download.bash
or
bash kernel_build.bash

Compiled kernels currently exist for the x64 architecture.

Then when one or the other of those has succeeded, install them:
bash kernel_install.bash

You can now proceed to the section below titled "[[#Configure_the_system_for_MCE_users|Configure the system for MCE users]]".

= Ubuntu 10.04 =

The automated installation package is tested, but as Ubuntu tweaks its packages the install script may fall slightly out of sync. It's worth a shot though.

After installing Ubuntu 10.04 (desktop), get the install tarball:

cd ~
wget http://e-mode.phas.ubc.ca/mce/pc_install/install_tools/ubuntu_10.04_install.tar.gz
tar -xzf ubuntu_10.04_install.tar.gz
cd install/

== Install additional ubuntu packages ==

From that install folder, run
bash install.bash

(Under 10.04, the vanilla kernel 2.6.38.8 is also supported. To use it, copy ./alternatives/sources.2.6.38.8.bash to ./sources.bash before running install.bash and kernel_build.bash .)

== Bigphysarea kernel patch ==

You can either download the compiled kernels or build them from scratch.

From install folder, run EITHER
bash kernel_download.bash
or
bash kernel_build.bash

Then when one or the other of those has succeeded, install them:
bash kernel_install.bash

You can now proceed to the section below titled "[[#Configure_the_system_for_MCE_users|Configure the system for MCE users]]".

= Ubuntu 9.10 and earlier =

See [[MAS OS setup on obsolete systems]]

= Configure the system for MCE users =

== Setup environment for MCE user ==

We tend to assume that a single user and group will have dominion over the MCE software, scripts, and data. We often assume that this user will be called "mce". But it doesn't need to be. Even if multiple users are running things through their own accounts it is likely useful to have a single group that can be used to manage access to the data.

Anyway, to set up a reasonable MCE user, see [[MAS user setup]].

All users using the MCE will need to define some environment variables to use the scripts. See the above link for lines to add to your '''.bashrc'''.

== System umask ==

You may want to set the system umask to make for a system where it's easier to share
Set the umask for all users to give write access for their group by default.

Edit /etc/profile and change the "umask 022" line to
umask 002

Edit /etc/login.defs and find the line that start "# UMASK" and change it to
UMASK 002

== Folders ==

mce_script assumes that /data/cryo/ exists and can be manipulated. To create something reasonable:

MCE_USER=mce
MCE_GROUP=mce
sudo mkdir /data
sudo chown $MCE_USER:$MCE_GROUP /data
sudo chmod g+ws /data
mkdir /data/cryo/

= Download (checkout) MAS and mce_script =

See [[MAS svn repository]].

= Compile and install MAS =

The following procedure outlines the default situation, where MAS is being installed on a computer containing only one fibre card. For information on running MAS with multiple fibre cards in one computer, see [[Multicard MAS]].

== Makefile.svn ==

MAS uses autoconf for some basic configuration stuff. After checking out MAS from the SVN repository the ''first'' time, you need to bootstrap the autoconf process. To simplify this, the Makefile.svn file will automate the process. From the MAS source folder run

make -f Makefile.svn

If successful, this will create the "./configure" script. This step is only required on fresh check-outs of the repository. If you already have a ./configure script, even if it's out of date, you can skip this step. (After having been bootstrapped the
first time, the build system is smart enough to know when it needs to regenerate itself.)

Note: this procedure requires autoconf. If it's not installed, install it with:

sudo apt-get install autoconf

== ./configure ==

Once the configure script exists, run it to generate the build system (ie. the Makefiles). The biggest thing you usually need to tell it is what the basic username and group should be for mce data. Also, there are a few options for the driver and some stupid python stuff.

From the MAS source folder, run

./configure

Some useful options:
--disable-driver suppress driver compilation/installation
--disable-bigphysarea compile driver without bigphysarea support
--disable-config2 suppress mas.cfg and mce.cfg generation/installation
--enable-multicard build a version of MAS which can drive multiple fibre cards. (See [[Multicard MAS]] for specifics.)
--with-user=USER set default MCE user
--with-group=GROUP set default MCE group
--with-kernel-dir=DIR set kernel build directory (typically automatically determined)

Run

./configure --help

for a full list. When running, configure will complain if it cannot find something, and even suggest what package you need to install.

== mce.cfg ==

After running configure, but before running make, you must specify a template file (mce.cin) which will be used to generate the hardware configuration file (mce.cfg). Full details of this procedure are given in the [[mce.cfg]] page, but briefly:

# copy an appropriate template from <code>config2/templates</code> to <code>config2/mce.cin</code>
# edit the <code>config2/mce.cin</code> file to describe your MCE.

The configuration file will be installed automatically when <code>make install</code> is run below. This entire step can be skipped if you passed --disable-config2 to configure above, but note that MAS will not function without mce.cfg and mas.cfg installed.

== make ==

This often works.

make clean; make

=== Troubleshooting ===
Sometimes after doing an SVN update <code>make</code> doesn't work but instead returns the cryptic message:

*** No rule to make target `defaults/masdefault.m4', needed by `aclocal.m4'.

In this case, it's necessary to force a rebuild of the build system manually by running

make -f Makefile.svn
./configure

See the [[#Makefile.svn|Makefile.svn section]] above for further details.

== Test the driver ==

It is wise to test that the driver does not kill your machine before installing it to load on boot. After compiling do:

cd driver
sudo ./reload

This will load the driver, which should then try to talk to the SDSU PCI card if it is installed. Note that since "reload" first unloads the driver if it is present, and then loads the driver from the current folder, it may report an "ERROR" message if the first step fails, even though the driver is successfully loaded. The definitive way to check that the driver is loaded is
cat [[/proc/mce_dsp]]

If this file does not exist, the driver isn't loaded. If the cat prints out a bunch of low-level driver information, you're in good shape.

== sudo make install ==

If you're satisfied that the driver works, install the whole thing. Go back up to the MAS base folder and run

sudo make install

This will do the following:

*install the kernel driver, <code>driver/mce_dsp.ko</code>, into <code>/lib/modules/$(uname -r)/kernel/drivers/misc/</code>, and re-scan the module dependencies.
*install the MAS binaries from <code>applications/</code> and the scripts from <code>script/</code> into <code>/usr/mce/bin</code>
*install the MAS udev ruleset <code>scripts/91-mas.rules</code> into <code>/etc/udev/rules.d/</code>. These udev rules will ensure that the mce_dsp module is loaded and the MAS device nodes are created at boot time. You can get udev to run these rules immediately, which will result in /dev being populated with the mce devices, by running:

sudo udevadm trigger

:or, else, you can make the nodes yourself by running mas_mknodes.
*install the mas logging daemon script <code>/etc/init.d/mas</code> init script. The driver can then be started/restarted as desired through this script:

/etc/init.d/mas restart

:The driver will automatically be set to load on boot. To disable this, remove the symbolic link "/etc/rc2.d/S99mas".
*install the hardware configuration file, <code>config2/mce.cfg</code>, and the MAS configuration file, <code>config2/mas.cfg</code> to <code>/etc/mce/</code>, assuming there aren't versions already there.

= Install mce_script =

Users have the option of running the MCE scripts from an svn working copy, or of running the MCE scripts from an "installed" copy. Talk to your MAS technician about which option is best for you.

== Running from an svn working copy ==

Checkout the tree directly into /usr/mce:

cd /usr/mce
svn checkout svn://e-mode.phas.ubc.ca/mce_script/trunk mce_script

== Running from an installed copy ==

Checkout the tree into your code folder; then make and install:

cd code
svn checkout svn://e-mode.phas.ubc.ca/mce_script/trunk mce_script
make
sudo make install

== .bashrc ==

Add a few lines to .bashrc to update your PATH, PYTHONPATH, and to define the MAS_* variables. The new way, using [[mas_var]], is:
eval `/usr/mce/bin/mas_var -e -s`

The old way, which will probably still work for a while:

export MAS_ROOT=/usr/mce/mce_script/
source $MAS_ROOT/template/mas_env.bash
export IDL_PATH="<IDL_DEFAULT>:$MAS_IDL/mas"

== Configuration data ==

Example configuration files (especially [[experiment.cfg]]) are kept in mce_script/template. MAS, by default, expects user configuration data to be in /usr/mce/config. Users should copy the template/ files to /usr/mce/config/, and then make configuration adjustments. From the svn working copy you can use the "export" command:

mce@ubuntu:~$ sudo mkdir /usr/mce/config
mce@ubuntu:~$ sudo chown mce: /usr/mce/config
mce@ubuntu:~$ svn export --force ~/code/mce_script/template/ /usr/mce/config

Digital 4-pole Butterworth Low-pass filter

2014-07-16T14:52:46Z

Mhasse: /* Code for simulations */

== Overview ==
A digital 4-pole Butterworth low-pass filter is implemented as 2 cascaded biquads (2-pole topology) in the '''Read-out card firmware''' of the MCE. The transfer function of the IIR filter is:
<math> H(z) = \frac {1+2 z^{-1}+z^{-2}}{1+b_{11} z^{-1}+b_{12} z^{-2}} . 2^{-k_2} . \frac {1+2z^{-1}+z^{-2}}{1+b_{21} z^{-1}+b_{22} z^{-2}} . {2^{-k_1}} </math>

Filter coefficients b<sub>11</sub>, b<sub>12</sub>, b<sub>21</sub> b<sub>22</sub>, and truncation factors, k<sub>1</sub> and k<sub>2</sub>, are hard coded in older firmware and just recently ('''version 5.1.0+''') they can be programmed through software.

wb rca fltr_coeff b<sub>11</sub> b<sub>12</sub> b<sub>21</sub> b<sub>22</sub> k<sub>1</sub> k<sub>2</sub>

Note that in order to accomodate the quantization effects, you have to follow the recipe prescribed [[Digital 4-pole Butterworth Low-pass filter#Filter Coefficients | here]] when specifying the coefficients and truncation factors.

There are 3 filter-related MCE parameters/commands:
* fltr_type: to determine whether filter coefficients are hard-coded or configurable
* fltr_coeff: to specify filter coefficients
* fltr_rst: to reset the filter pipeline after changing coefficients

== Filter Specification ==
Filter specification of the 4-pole Butterworth filter is determined by the filter coefficients b<sub>11</sub>, b<sub>12</sub>, b<sub>21</sub>, b<sub>22</sub>, described earlier.

Assume:

* '''f<sub>cutoff</sub>''' is the frequency at which the signal after filtering is <math>\sqrt2</math> of its maximum value (nominally the read-out rate Nyquist frequency), and
* '''f<sub>samp</sub>''' is the sampling frequency, calculated as <math>\frac{50\;\mathrm{MHz}}{\mathrm{num\_rows} \times \mathrm{row\_len}}</math>. For example 50MHz / (33 * 100) = 15151.5Hz.

''Note that the filter f<sub>3dB</sub> scales if f<sub>samp</sub> changes.''

; Type 1 (hard-coded coefficients)
: (supported in all rc _except_ 5.0.7)
: DC amplification = 1217.9148
: f<sub>cutoff</sub> / f<sub>samp</sub> = 122.226Hz / 15151Hz
: Gain @ 200Hz=0.14189148 (wrt the DC gain)

; Type 2 (hard-coded coefficients)
: (supported only in rc version 5.0.7)
: DC amplification = 2044
: f<sub>cutoff</sub> / f<sub>samp</sub> = 75Hz / 30000Hz
: A plot of the transfer function generated by simulating MCE firmware (VHDL)
[[File:mce_filter_type2_magnitude.png |150px]][[File:mce_filter_type2_phase.png|150px]]

; Type 255 (configurable coefficients)
: ''supported in rc 5.1.0+'' Filter coefficients b<sub>11</sub>, b<sub>12</sub>, b<sub>21</sub>, b<sub>22</sub> and truncation factors, k<sub>1</sub>, k<sub>2</sub> are parametrized and programmable by software.

The fitler type can be determined by reading back the MCE parameter called ''fltr_type'' (rb rc1 fltr_type). (supported in firmware 5.0.a+)

The following plot shows the magnitude and the phase of Type 1 filter.

Here is Elia's original plot [[Media:BW_filter.ps]]. Then we see the same plot with the impulse-response also added (by Joe, Nov 29, 2007):
[[Image: BW_filter2.png]]

Here is the filter response for Scuba2 setting (f<sub>samp</sub>=9.5kHz, f<sub>readout</sub>=200Hz): [[Media: Filter fs10kHz 200Hzdecimated response.ps ]]

== Filter-related Software changes ==

=== Determining the filter type ===

A ''fltr_type'' parameter is introduced starting firmware 5.0.a.
* fltr_type = 1 fcutoff / fsamp = 122.226Hz / 15151Hz
* fltr_type = 2 fcutoff / fsamp = 75Hz / 30000Hz
* fltr_type = 255 configurable coefficient

All earlier firmware revisions are set to filter type 1 by default, except version 5.0.7 which is set to filter type 2.

=== Software requirements ===

* MAS - use mas/trunk r493 or later to get access to the fltr_coeff MCE parameter.
** In [[mce.cfg]], specify $fw_rev["rc"] = $5010000 or greater.
* mce_script - use mce_script/trunk r764 or later
* In [[Mce config template system#experiment.cfg | experiment.cfg]]:
**specify one of:
config_filter = 0; # do not write filter coefficients to the MCE
config_filter = 1; # write filter coefficients to the MCE
and when config_filter = 1, the filter coefficients to be written to the MCE must be specified in the "filter_params" parameter, in the order [b<sub>11</sub> b<sub>12</sub> b<sub>21</sub> b<sub>22</sub> k<sub>1</sub> k<sub>2</sub>]. E.g.:
filter_params = [ 32092, 15750, 31238, 14895, 0, 11]; # type 1 filter, fc/fs= 122.226Hz / 15.151kHz
filter_params = [ 32295, 15915, 32568, 16188, 3, 14]; # type 2 filter, fc/fs= 75Hz / 30kHz
filter_params = [ 32295, 15915, 32568, 16188, 5, 12]; # type 2 filter with more inter-biquad dynamic range (recommended)
filter_params = [ 32297, 15934, 31683, 15320, 0, 11]; # SCUBA-2 filter after 2011-06, fc/fs = 75Hz / 12.97kHz

== Code for simulations ==

Note that as of mce_script r902, '''mce_data.py''' contains code for handling the MCE Butterworth filters. This can be used to load filter parameters from a runfile, and to get the complex frequency response of a filter. See [[mce_data.py#MCEButterworth_class]].

A smaller, quicker python example:
[[ Media: mce_filt_py.txt ]]

In this little IDL program you can find the functional form as a function of the frequency of the filter. First, Elia's original program, then as modified by Joe on November 29, 2007, then modified by Mandana on Jan. 14, 2009 for Scuba2 numbers:
* [[ Media: filter_pro.txt ]]
* [[ Media: filter_pro2.txt ]]
* [[ Media: low_pass_filter_model_pro.txt ]]

=== Digital, time domain simulation codes ===

Python-based model of a single biquad, in the time domain, for exploring digitization and dynamic range:
* [[ Media: biquad_time_domain_py.txt ]]

== Filter Coefficients ==
=== Butterworth Coefficients ===
The filter coefficients are generated using ''fdatool'' (filter-design & Analysis tool, part of DSP Toolbox) in '''Matlab/Simulink'''. These coefficients are floating numbers and in order to feed them to MCE firmware, they need to be quantized by converting to signed binary fractional (SBF) 1.14 format. You may use alternate methods<sup>*</sup> to generate coefficients. Here, we explain the method using ''fdatool''.

Once you launch the ''fdatool'', choose the following settings:

* Response Type: Low Pass
* Design Method: Butterworth
* Filter Order: 4

* Frequency Specifications:
** For Type 1: F<sub>samp</sub> = 12195 = (50000/100*41), F<sub>cutoff</sub>=100
** For Type 2: F<sub>samp</sub> = 30000 ~= (50000/50*33), F<sub>cutoff</sub>=75
** For Type 255: F<sub>ssamp</sub> = You specify (50000/row_len*num_rows), F<sub>cutoff</sub>=You specify (<F<sub>readout</sub> / 2)
** (The attenuation at F<sub>cutoff</sub> is fixed at 3dB (half the passband power))

Then click on Design Filter and you will get the following coefficients:
; Type 1
:Section 1:
::Numerator: 1 2 1
::Denominator: 1 -1.9587428340882587 0.96134553442399129
::Gain = 1/g<sub>1</sub> = 0.00065067508393319923 (not implemented)
:Section 2:
::Numerator: 1 2 1
::Denominator: 1 -1.9066292518523014 0.90916270571237567
::Gain = 1/g<sub>2</sub>= 0.00063336346501859835 (not implemented)

; Type 2
:Section 1:
::Numerator: 1 2 1
::Denominator: 1 -1.9711486088510415 0.97139181456687917
:Section 2:
::Numerator: 1 2 1
::Denominator: 1 -1.9878047097960421 0.98804997058724808
:Gain = 1/(g<sub>1</sub> * g<sub>2</sub>)= 0.0000000037280516432624239 (not implemented)

; Type 255
: Plug in your desired f<sub>s</sub> and f<sub>c</sub> in Matlab fdatool and you will get a set of coefficients:
:Section 1:
::Numerator: 1 2 1
::Denominator: 1 B11 B12
:: Gain = 1/g<sub>1</sub>
:Section 2:
::Numerator: 1 2 1
::Denominator: 1 B21 B22
::Gain = 1/g<sub>2</sub>

=== Coefficient Quantization ===
The quantization format is signed-binary fractional (SBF) 1.14 and then 2's complement to be able to account for positive and negative values.
* Multiply each of the Bxx coefficients by 2<sup>14</sup> and then if negative multiply by -1.
* k2 = 1 + floor ( log<sub>2</sub> (g<sub>1</sub>) ) the inter-stage truncation
* k1 = floor ( log<sub>2</sub> (g<sub>2</sub>) ) - 10 the output-truncation

(10 is a historical constant !!!)

For example, if we use this formula to quantize Type 1 coefficients listed above:
<br>b11 = 32092
<br>b12 = 15750
<br>b21 = 31238
<br>b22 = 14895
<br>k1 = 0
<br>k2 = 11

* k1<16 and k2<32
* Now if 32-k1+k2 >32 then you have to talk to UBC!

<br>
'''The following ONLY concerns the MCE firmware developers:'''
<br>
Prior to firmware 5.1.0, the coefficients were hardcoded in '''fsfb_calc_pack.vhd''' (FILTER_B11_COEF, FILTER_B12_COEF, FILTER_B21_COEFF, FILTER_B22_COEFF, FILTER_GAIN_WIDTH, FILTER_SCALE_LSB).

=== Calculating the DC Gain (k) ===
Note that in firmware, instead of g<sub>1</sub> and g<sub>2</sub>, an inter-biquad truncation of k<sub>2</sub> (implemented as a binary shift) and k<sub>1</sub>, number of bits dropped after the second biquad, are implemented.

Hence, the overall gain becomes <math>\frac {g_1 g_2} {2^{(k_1 + k_2)}}</math>.

(Note for firmware developers: see FILTER_GAIN_WIDTH and FILTER_SCALE_LSB in '''fsfb_calc_pack.vhd'''.)

; Type 1
:k2=11, k1=0, the filter gain is estimated at 1184, but vhdl simulation results in a gain of 1216.
; Type 2
:k2=14, k1=3, the filter gain is estimated at 2046, but vhdl simulation results in a gain of 2181.

The gain difference can be attributed to the rounding effects associated with fixed-width arithmetic.

To roughly compute the gain, including the effects from truncating the coefficients, reverse the quantization process to obtain the floating point values associated with your coefficients, and plug into the filter definition. Here is a rough python program which computes the true gain for our Type 1 filter:
from numpy import *
# Sum of k1 and k2 shifts:
k12 = 11+0
# Quantized coefficients b11, b12, b21, b22:
n = array([32092, 15750, 31238, 14895]).astype('float')
# Re-float
f = n/2**14
# Compute gain
gain = 16. / (2**k12 * (1 - f[0] + f[1]) * (1 - f[2] + f[3]))
# Answer: 1217.8583043
print gain

== Useful Links ==
http://www.phas.ubc.ca/~mce/mcedocs/hardware/Firmware_block_spec/reaout_card/fsfb_calculations.pdf

http://www.planetanalog.com/showArticle.jhtml?articleID=12802683

== Alternative to fdatool ==
If you do not have access to fdatool or do not have DSP toolbox installed, you can use the following Matlab functions (or equivalent in other packages) to get the coefficients:
* butter: is a matlab function to generate butterworth coefficients
* sos2tf: matlab function to break a transfer function to second-order sections
* bilinear: converts an s-domain (continuous) transfer function to z-domain (discrete) transfer function.
* Then run the following in matlab (or whatever syntax your tool has):
num=[1 2 1]
denum=[1 -1.9711486088510415 0.97139181456687917]
max(dbode(num, denum, 1/fs) but also look at the bode-plot to make sure it is flat, otherwise read the max from the flat portion of the plot instead of the max function.

'''Note:''' When I used coefficients generated by [a,b] = butter(2, 50/20000); [SOS,G]=tf2sos(a,b), the filter was not as robust. not sure why?!

File:Biquad time domain py.txt

2014-07-16T14:52:40Z

Mhasse:

PCI card firmware

2014-05-28T20:46:25Z

Mhasse: /* Download */

{{Hierarchy header}}
UBC-produced firmware for the ARC-64 [[PCI card]]. [[MAS]] provides a linux kernel driver for this firmware.
== Download ==

These S-record files should work with any reasonable EEPROM programmer:
* U0107 (new!) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0107_candidate_2014-05-01.s
* U0106 (recommended) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0106.s
** 8-bit checksum 6FCDCE
** Scrubber file - try writing all ones to your this to your chip first if your programmer won't let you "erase" it:
** http://e-mode.phas.ubc.ca/mce/firmware/sdsu/scrubber_RevU0106.s
* U0105 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0105.s
* U0104 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0104.s

The full source code is available in these archives (it will not compile unless you get the correct assembler and stuff):
* U0106 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0106.tar.gz
* U0105 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0105.tar.gz
* U0104 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0104.tar.gz

The subversion tree can be obtained like this (you may not have access to this repository; contact UBC);
svn checkout svn://e-mode.phas.ubc.ca/arc_pci

It is laid out roughly as follows:
/trunk main line of development
/releases tagged versions of code
/tools debugging tools
/clash stuff for making CLAS work with wine and linux
/docs useful (though maybe not to you) notes

== Firmware version notes ==

=== U0107 (pending): alpha ===

* This firmware can operate in either of two modes:
** '''U0106 compatibility mode''': the firmware will work with classic MAS driver, just like U0106 (plus some bugfixes).
** '''New Master-only mode''': when activated, uses new set of protocols for communication with the MAS driver. These have proven to be much more stable on some systems. Also, bigphysarea is no longer needed.
* This firmware/driver are in limited release; do not attempt to use them without consulting with UBC.
* Downloads:
** S-rec for release candidates here: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/
** Soft-patches for upgrading U0106 to pseudo-U0107 temporarily: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/patches/

=== U0106 (2011-11-21): Recommended version ===

* Backward compatible with U0104 and U0105.
* Fixes bug introduced in U0105 that prevented handling of some PCI bus errors.
* Introduction of command to update PCI burst size.
* Bugs:
** Versions U0104-6 all suffer from the following issues:
*** Host interrupts use bit-test instructions, which are not interrupt safe; consequence is a race condition that can upset ongoing tasks such as FO downloads and PCI bursts. Patch for this issue, applicable to firmware versions U0104-6:
**** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash
*** Multiple simultaneous PCI bus errors are not handled properly, leading to stale bits in the error register. This is an unlikely error vector, but should be fixed.

=== U0105 (2009-06-08) ===

* Backward compatible with U0104.
* Support for MCE STOP commands and commands-on-the-fly.
* Accelerated MCE command code (along with Quiet-RP this increases commanding rate to ~6 kHz).
* Quiet-RP simplifies the protocol for MCE reply handling.
* Low-level improvements:
** CON is done as PCI burst
** Fibre-optic FIFO is emptied with timed read instead of polling.
** Hand-shaking for interrupts instead of host command to clear INTA and HC3.
** Non-interrupt context code disables interrupts when performing PCI transactions.
** Host vector interrupts are otherwise enabled, so PC doesn't have to force with HNMI bit.
* Bugs and fixes:
** Some PCI bus arbitration conditions are mis-handled. This is fixed in U0106; alternately the commands below can be issued to patch active U0105 firmware. (The patch will not survive a power cycle.):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0105_unignore_pci_errors.bash
** Also this (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

=== U0104: First version with non-realtime linux support ===

* Implements quiet transfer mode! Remains backwards compatible with A1.4.
* Fixes the 64k boundary crossing issue
* Moves parameters that enter via interrupt out of registers and into variables
* Version reporting tag-along to RDM command (sending 'VER' to RDM's vector address returns the code version).
* Maximum burst length is reduced to 64 bytes, and is configurable.
* Reset (RST) clears the fibre fifo
* Bugs:
** This (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

== U0103: Oldest UBC release ==

* Minor modifications of SCUBA2's A1.4 firmware, to improve PCI stability.
* Not compatible with non-realtime systems.

== Programming the ARC64 Flash memory ==

To program or upgrade the PCI card's firmware, it is necessary to remove the flash memory chip from the card and program it using a standard EEPROM programmer.

# Obviously you should turn off your computer and stuff first.
# The chip is a large DIP located at U5 on the PCI board. To remove the chip you may use one of the following (in increasing order of risk, and decreasing order of barbarism):
## telekinesis
## a chip removal tool
## needle-nose pliers
## a screw-driver
## thumb and finger
## fingers only
# The chip is a standard 256 Kbit electrically erasable Flash ROM. If you can't find the particular part in your EEPROM programmer software, try using one of these compatible parts:
## Fujitsu MBM28C256
## CSI (Catalyst) CAT28C256 L
## Anything else that has 28C256 in its name as long as it is a 28-pin DIP package and you are using the right socket for your programmer.
# Some programmers won't recognize this chip as erasable. You can just try programming the chip with the new firmware, or pseudo-erasing it first using a "scrubber" file (available for U0106 in the links above).
# The firmware we provide is compiled into a [ http://en.wikipedia.org/wiki/SREC_%28file_format%29 Motorola S-record format ] hex file. This is a standard format that your programmer software should be able to cope with.
# When placing the chip back in the board, the notch on the chip should be at the same end as the notch on the socket.

== Other information ==

* [[ PCI card bug list ]]
* [[ PCI card hacking ]]
* [[ PCI card code assembly on Linux ]]

[[Category:Firmware]]

PCI card firmware

2014-04-26T20:16:46Z

Mhasse: /* U0107 (pending): alpha */

{{Hierarchy header}}
UBC-produced firmware for the ARC-64 [[PCI card]]. [[MAS]] provides a linux kernel driver for this firmware.
== Download ==

These S-record files should work with any reasonable EEPROM programmer:
* U0106 (recommended) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0106.s
** 8-bit checksum 6FCDCE
** Scrubber file - try writing all ones to your this to your chip first if your programmer won't let you "erase" it:
** http://e-mode.phas.ubc.ca/mce/firmware/sdsu/scrubber_RevU0106.s
* U0105 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0105.s
* U0104 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0104.s

The full source code is available in these archives (it will not compile unless you get the correct assembler and stuff):
* U0106 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0106.tar.gz
* U0105 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0105.tar.gz
* U0104 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0104.tar.gz

The subversion tree can be obtained like this (you may not have access to this repository; contact UBC);
svn checkout svn://e-mode.phas.ubc.ca/arc_pci

It is laid out roughly as follows:
/trunk main line of development
/releases tagged versions of code
/tools debugging tools
/clash stuff for making CLAS work with wine and linux
/docs useful (though maybe not to you) notes

== Firmware version notes ==

=== U0107 (pending): alpha ===

* This firmware can operate in either of two modes:
** '''U0106 compatibility mode''': the firmware will work with classic MAS driver, just like U0106 (plus some bugfixes).
** '''New Master-only mode''': when activated, uses new set of protocols for communication with the MAS driver. These have proven to be much more stable on some systems. Also, bigphysarea is no longer needed.
* This firmware/driver are in limited release; do not attempt to use them without consulting with UBC.
* Downloads:
** S-rec for release candidates here: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/
** Soft-patches for upgrading U0106 to pseudo-U0107 temporarily: http://e-mode.phas.ubc.ca/mce/firmware/sdsu/patches/

=== U0106 (2011-11-21): Recommended version ===

* Backward compatible with U0104 and U0105.
* Fixes bug introduced in U0105 that prevented handling of some PCI bus errors.
* Introduction of command to update PCI burst size.
* Bugs:
** Versions U0104-6 all suffer from the following issues:
*** Host interrupts use bit-test instructions, which are not interrupt safe; consequence is a race condition that can upset ongoing tasks such as FO downloads and PCI bursts. Patch for this issue, applicable to firmware versions U0104-6:
**** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash
*** Multiple simultaneous PCI bus errors are not handled properly, leading to stale bits in the error register. This is an unlikely error vector, but should be fixed.

=== U0105 (2009-06-08) ===

* Backward compatible with U0104.
* Support for MCE STOP commands and commands-on-the-fly.
* Accelerated MCE command code (along with Quiet-RP this increases commanding rate to ~6 kHz).
* Quiet-RP simplifies the protocol for MCE reply handling.
* Low-level improvements:
** CON is done as PCI burst
** Fibre-optic FIFO is emptied with timed read instead of polling.
** Hand-shaking for interrupts instead of host command to clear INTA and HC3.
** Non-interrupt context code disables interrupts when performing PCI transactions.
** Host vector interrupts are otherwise enabled, so PC doesn't have to force with HNMI bit.
* Bugs and fixes:
** Some PCI bus arbitration conditions are mis-handled. This is fixed in U0106; alternately the commands below can be issued to patch active U0105 firmware. (The patch will not survive a power cycle.):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0105_unignore_pci_errors.bash
** Also this (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

=== U0104: First version with non-realtime linux support ===

* Implements quiet transfer mode! Remains backwards compatible with A1.4.
* Fixes the 64k boundary crossing issue
* Moves parameters that enter via interrupt out of registers and into variables
* Version reporting tag-along to RDM command (sending 'VER' to RDM's vector address returns the code version).
* Maximum burst length is reduced to 64 bytes, and is configurable.
* Reset (RST) clears the fibre fifo
* Bugs:
** This (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

== U0103: Oldest UBC release ==

* Minor modifications of SCUBA2's A1.4 firmware, to improve PCI stability.
* Not compatible with non-realtime systems.

== Programming the ARC64 Flash memory ==

To program or upgrade the PCI card's firmware, it is necessary to remove the flash memory chip from the card and program it using a standard EEPROM programmer.

# Obviously you should turn off your computer and stuff first.
# The chip is a large DIP located at U5 on the PCI board. To remove the chip you may use one of the following (in increasing order of risk, and decreasing order of barbarism):
## telekinesis
## a chip removal tool
## needle-nose pliers
## a screw-driver
## thumb and finger
## fingers only
# The chip is a standard 256 Kbit electrically erasable Flash ROM. If you can't find the particular part in your EEPROM programmer software, try using one of these compatible parts:
## Fujitsu MBM28C256
## CSI (Catalyst) CAT28C256 L
## Anything else that has 28C256 in its name as long as it is a 28-pin DIP package and you are using the right socket for your programmer.
# Some programmers won't recognize this chip as erasable. You can just try programming the chip with the new firmware, or pseudo-erasing it first using a "scrubber" file (available for U0106 in the links above).
# The firmware we provide is compiled into a [ http://en.wikipedia.org/wiki/SREC_%28file_format%29 Motorola S-record format ] hex file. This is a standard format that your programmer software should be able to cope with.
# When placing the chip back in the board, the notch on the chip should be at the same end as the notch on the socket.

== Other information ==

* [[ PCI card bug list ]]
* [[ PCI card hacking ]]
* [[ PCI card code assembly on Linux ]]

[[Category:Firmware]]

PCI card firmware

2014-04-18T16:58:35Z

Mhasse: /* Firmware version notes */

{{Hierarchy header}}
UBC-produced firmware for the ARC-64 [[PCI card]]. [[MAS]] provides a linux kernel driver for this firmware.
== Download ==

These S-record files should work with any reasonable EEPROM programmer:
* U0106 (recommended) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0106.s
** 8-bit checksum 6FCDCE
** Scrubber file - try writing all ones to your this to your chip first if your programmer won't let you "erase" it:
** http://e-mode.phas.ubc.ca/mce/firmware/sdsu/scrubber_RevU0106.s
* U0105 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0105.s
* U0104 (deprecated) - http://e-mode.phas.ubc.ca/mce/firmware/sdsu/SDSU_RevU0104.s

The full source code is available in these archives (it will not compile unless you get the correct assembler and stuff):
* U0106 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0106.tar.gz
* U0105 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0105.tar.gz
* U0104 - http://e-mode.phas.ubc.ca/mce/arc_pci/source_code/arc_pci-U0104.tar.gz

The subversion tree can be obtained like this (you may not have access to this repository; contact UBC);
svn checkout svn://e-mode.phas.ubc.ca/arc_pci

It is laid out roughly as follows:
/trunk main line of development
/releases tagged versions of code
/tools debugging tools
/clash stuff for making CLAS work with wine and linux
/docs useful (though maybe not to you) notes

== Firmware version notes ==

=== U0107 (pending): alpha ===

* This firmware can operate in either of two modes:
** '''U0106 compatibility mode''': the firmware will work with classic MAS driver, just like U0106 (plus some bugfixes).
** '''New Master-only mode''': when activated, uses new set of protocols for communication with the MAS driver. These have proven to be much more stable on some systems. Also, bigphysarea is no longer needed.
* This firmware/driver are in limited release; do not attempt to use them without consulting with UBC. Also, see [[Master-only PCI card firmware]].

=== U0106 (2011-11-21): Recommended version ===

* Backward compatible with U0104 and U0105.
* Fixes bug introduced in U0105 that prevented handling of some PCI bus errors.
* Introduction of command to update PCI burst size.
* Bugs:
** Versions U0104-6 all suffer from the following issues:
*** Host interrupts use bit-test instructions, which are not interrupt safe; consequence is a race condition that can upset ongoing tasks such as FO downloads and PCI bursts. Patch for this issue, applicable to firmware versions U0104-6:
**** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash
*** Multiple simultaneous PCI bus errors are not handled properly, leading to stale bits in the error register. This is an unlikely error vector, but should be fixed.

=== U0105 (2009-06-08) ===

* Backward compatible with U0104.
* Support for MCE STOP commands and commands-on-the-fly.
* Accelerated MCE command code (along with Quiet-RP this increases commanding rate to ~6 kHz).
* Quiet-RP simplifies the protocol for MCE reply handling.
* Low-level improvements:
** CON is done as PCI burst
** Fibre-optic FIFO is emptied with timed read instead of polling.
** Hand-shaking for interrupts instead of host command to clear INTA and HC3.
** Non-interrupt context code disables interrupts when performing PCI transactions.
** Host vector interrupts are otherwise enabled, so PC doesn't have to force with HNMI bit.
* Bugs and fixes:
** Some PCI bus arbitration conditions are mis-handled. This is fixed in U0106; alternately the commands below can be issued to patch active U0105 firmware. (The patch will not survive a power cycle.):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0105_unignore_pci_errors.bash
** Also this (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

=== U0104: First version with non-realtime linux support ===

* Implements quiet transfer mode! Remains backwards compatible with A1.4.
* Fixes the 64k boundary crossing issue
* Moves parameters that enter via interrupt out of registers and into variables
* Version reporting tag-along to RDM command (sending 'VER' to RDM's vector address returns the code version).
* Maximum burst length is reduced to 64 bytes, and is configurable.
* Reset (RST) clears the fibre fifo
* Bugs:
** This (see description in U0106):
*** http://e-mode.phas.ubc.ca/mce/arc_pci/firmware/patches/patch_U0106_safetyize_vector_ints.bash

== U0103: Oldest UBC release ==

* Minor modifications of SCUBA2's A1.4 firmware, to improve PCI stability.
* Not compatible with non-realtime systems.

== Programming the ARC64 Flash memory ==

To program or upgrade the PCI card's firmware, it is necessary to remove the flash memory chip from the card and program it using a standard EEPROM programmer.

# Obviously you should turn off your computer and stuff first.
# The chip is a large DIP located at U5 on the PCI board. To remove the chip you may use one of the following (in increasing order of risk, and decreasing order of barbarism):
## telekinesis
## a chip removal tool
## needle-nose pliers
## a screw-driver
## thumb and finger
## fingers only
# The chip is a standard 256 Kbit electrically erasable Flash ROM. If you can't find the particular part in your EEPROM programmer software, try using one of these compatible parts:
## Fujitsu MBM28C256
## CSI (Catalyst) CAT28C256 L
## Anything else that has 28C256 in its name as long as it is a 28-pin DIP package and you are using the right socket for your programmer.
# Some programmers won't recognize this chip as erasable. You can just try programming the chip with the new firmware, or pseudo-erasing it first using a "scrubber" file (available for U0106 in the links above).
# The firmware we provide is compiled into a [ http://en.wikipedia.org/wiki/SREC_%28file_format%29 Motorola S-record format ] hex file. This is a standard format that your programmer software should be able to cope with.
# When placing the chip back in the board, the notch on the chip should be at the same end as the notch on the socket.

== Other information ==

* [[ PCI card bug list ]]
* [[ PCI card hacking ]]
* [[ PCI card code assembly on Linux ]]

[[Category:Firmware]]

Series array setup

2013-09-23T19:39:56Z

Mhasse:

Here's how to set up a series array in the python auto_tuning.

= Run the auto_setup to see if it crashes =

Without trying to make it a good one, just check that the program runs smoothly. We will tell auto_setup to only acquire an SA ramp, and not to try tuning the other SQUID stages:
auto_setup --last-stage=sa_ramp

When it's working, the auto_setup should print something like:
Tuning ctime: 1323464515

That number is the current unix time. We often refer to it as a ctime. It becomes the "tuning_id" for this tuning. You indicates that your data are headed $MAS_DATA/<tuning_id> and your analysis plots will show up in $MAS_DATA/analysis/<tuning_id>.

== First glance ==

Looking at the SA plot you will probably see one of the following:
* Signal contains V-phi curves
** Beginner's luck. Proceed to tweaking.
* Signal shows noise, but no sign of a V-phi curve
** There's hope; try increasing the ranges of biases and feedback you are probing. Proceed to tweaking.
* Signal is flat, at 0.
** Your MCE configuration is wrong somehow; do your mce.cfg and experiment.cfg agree on which readout cards are present? Are sample_num and sample_dly set to reasonable values (10, 90)? Is sample_dly less than row_len?
* Signal is noiseless and flat, at -81920 or +81910
** There's hope; you may need to adjust sa_bias_offset_ratio, as described below.
** This (esp +81910) is what tends to happen if the SA line is open circuit, though.

= Tweaking the SA ramp settings =

Your plots from your dry run above will hopefully show some signs of a series array. If they do not, first check that your ramp parameters are reasonable (try using the sensible defaults described below). If your curves look sort-of-good, but seem to be truncated at the top or bottom of their range, you may need to adjust your sa_offset_bias_ratio.

== Flux and bias ranges ==

There aren't that many settings that affect the SA ramp step of auto_setup. By default, [[experiment.cfg]] is set up to more or less span the space allowed by the bias and feedback DACs. These ranges are specified in the parameters:
# Auto-tune does a flux feedback ramp, and optionally ramps the sa bias too.
sa_ramp_bias = 1;

sa_ramp_flux_start = 0;
sa_ramp_flux_count = 100;
sa_ramp_flux_step = 640;

sa_ramp_bias_start = 15000;
sa_ramp_bias_step = 1500;
sa_ramp_bias_count = 25;

When "sa_ramp_bias" is set to 1, the auto_setup will will run a feedback (or "flux") ramp for 25 different values of the SA bias, namely: 15000, 16500, 18000, ..., 51000. This space can be narrowed to probe the relevant range for your system.

If, some hittingday, you are happy with fixing the bias values (to speed up or stabilize the tuning while you study other squid stages, for example), you can set '''sa_ramp_bias = 0''' and put your desired SA bias values into the parameter
default_sa_bias = [ 0, 0, 0, ...];

This will cause the auto_setup to set up a single set of bias values only, and then run the feedback ramp. The feedback range (sa_ramp_flux_*) might be adjusted to obtain higher resolution (for measuring the SA flux quanta, for example), or to restrict the ramp to a smaller number of phi0 in cases where the complete DAC range spans more than 2 phi0.

== SA offset bias ratio ==

[[File:series_array_ramp_clipped.png|frame|link=|SA Ramp curve showing clipping at ~82000 ADC units]]
A subtle tweak that all users will need to configure for their system is the so called [[http://e-mode.phas.ubc.ca/mcewiki/index.php/Experiment.cfg#sa_offset_bias_ratio | sa_offset_bias_ratio]]. This number basically describes to what extent the DC level of the SA output drifts upwards as the SA bias is increased. If one does not compensate for this drift by applying an offset at the input op amp, the amps and ADC will saturate. If you see your SA curves "rail" at values of -81920 or +81910, it means that your sa_offset_bias_ratio needs to be adjusted. (Note that clipping will occur at values corresponding to the product of rca sample_num (usually 10) and the ADC range, -8192 to 8191.)

If your SA curves are railing at the positive end (probably +81920), you should increase sa_offset_bias_ratio (start by increasing by 0.1; it's quite sensitive). If your SA curves hit the lower boundary of the ADC (-81920), you should decrease sa_offset_bias_ratio.

There is a script that will try to guess your ratio, but your mileage may vary:
python $MAS_PYTHON/special_ops.py measure_sa_offset_ratio

The output of that script should look something like this:
Saving current configuration...
Setting up...
Measuring SA bias response...
Restoring...
Apparent resistance ratios, by column:
0.001 0.036 0.038 0.043 0.039 0.042 0.040 0.000
0.064 0.044 0.045 0.000 0.000 0.000 0.000 0.000
The typical ratio is: 0.039
Suggested sa_offset_bias_ratios, by column:
0.106 0.084 0.084 0.090 0.087 0.097 0.093 0.000
0.112 0.091 0.092 0.000 0.000 0.000 0.000 0.000
Smallest range-filling ratio: 0.084
Recommended sa_offset_bias_ratio: 0.084

So you'd go and put 0.084 into your active experiment.cfg, and re-run the tuning to see if that helped the railing at all.

MCE config template system

2013-09-18T22:27:01Z

Mhasse:

An important component of the current MCE configuration system is the "mce_config_template" file. This file is a bash script that puts the MCE in some desired state, which usually means that it sets up the biases and locking points of the squids and series arrays to the values determined in the most recent auto-tuning.

= General structure =

In previous versions of MCE software, there was a template file called config_mce_auto_setup_<date>, with date of the form YYYYMMDD, that lived in the /data/cryo/<date> folder (which was linked to /data/cryo/current_data and was the destination for all MCE data files). When the [[ Auto-tuning IDL code | auto-tune ]] was run, certain lines of the config script were updated to reflect the biases and locking points discovered by the auto-tune code. The auto-tune code would then run the updated config script to load the values into the MCE in preparation for the next stage.

In order to create a more flexible and robust system, the auto-tune programs no longer edit the config script directly. Instead, there is configuration file, called [[ experiment.cfg ]], where the auto-tune programs can read and write values. A config script is then generated by running "mce_make_config", which creates a config script based on the values in experiment.cfg.

The auto-tune read and write is accomplished via IDL functions called "load_exp_params" and "save_exp_params". These functions are in "load_exp_params.pro", which is automatically generated by the program [[ mas_param ]] based on a template for experiment.cfg. They allow IDL to import settings from experiment.cfg as an IDL structure, manipulate them using normal IDL vector operations, and then save the structure data back to the file.

The mce_make_config script constructs a config script by combining various pre-defined blocks of bash code with a block of bash variable declarations that is generated by [[ mas_param ]] from experiment.cfg.

= experiment.cfg =

'''For a description of some of the most important configuration parameters, see [[ experiment.cfg ]].'''

The experiment.cfg file structure is that of [[libconfig]]. Here are some typical lines:

# output level and time interval for driving detectors normal.

tes_bias_idle = [0, 0, 0];
tes_bias_normal = [65000, 65000, 65000];
tes_bias_normal_time = 0.1;

# Note that each entry of flux_quanta_rc# is repeated 41 times and
# written to 'rc# flux_quanta%'

flux_quanta = [ 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0 ];

Although libconfig permits complex nested data structures, experiment.cfg is restricted to root-level simple data types (strings, floats, integers, arrays of floats, and arrays of integers).

Unfortunately, experiment.cfg contains values associated with
* very stable properties that define the hardware configuration (e.g. number of rows of squids and sync box presence/absence)
* properties that must be manipulated during auto-tuning but then should return to some experiment default (e.g. rc data_mode)
* settings that a user can manipulate to select different auto-tuning options (e.g. the list of rows for which to generate sq1 bias ramp plots)
* properties that are discovered or revised at various stages of the auto-tuning (e.g. the sq2 feedback lock points)

It is necessary to distinguish between values that will be used to generate the config script and values that should be used to generate the /final/ config script. For example "default_data_mode = 2;" tells auto-tune what data mode to set in its final config script generation; in the mean time it will change the line "data_mode = 2;" to all sorts of other values for doing ramps and servos.

There are 2 copies of experiment.cfg in use at any time. The first is the working copy, kept in $MAS_DATA, which is edited by auto-tune and used to generate the config script. The second is kept in $MAS_CONFIG, and is a clean copy where experiment parameters are recorded. The $MAS_CONFIG copy is the one that should be commented carefully, and kept under version control.

The set_directory script performs a number of tasks, including copying experiment.cfg from $MAS_CONFIG into $MAS_DATA if there is no copy there already. In particular, if set_directory decides that it is necessary to create a new daily folder (and move the current_data link to point there), then a fresh copy of experiment.cfg is copied from $MAS_CONFIG to the new $MAS_DATA folder.

Another way to replace $MAS_DATA/experiment.cfg with the $MAS_CONFIG copy is to remove it and then run set_directory.

USB Blaster

2013-05-28T14:51:32Z

Mhasse: /* Programming from the Command Line */

In order to load new firmware on the MCE cards, you need to have either an Ethernet Blaster or a USB Blaster or a ByteBlaster, all available from Altera, connected to the MCE front-panel JTAG connector. On the software side, you need to have Quartus installed (check [[ Quartus II Installation ]])

(An alternative method is to load firmware over the fibre with no need for Altera Software/Hardware, this is work in progress. but if you have the patience, we can help you get it setup once and then use it forever. )

= Updating firmware on MCE Cards =
Each MCE card has an Altera Stratix FPGA and a configuration device. All cards except low-power Readout Cards (Rev. E and beyond) have an EPC16 configuration device. FPGAs are RAM-based devices, therefore, upon power up they load their firmware from a flash-based configuration devices.

In order to load firmware temporarily, use an .sof file to directly program the Stratix FPGA. This firmware only lasts till next power cycle. In order to load firmware permanently, use a .pof file to program the EPC16 parallel configuration devices or .jic to program the EPCS64 serial configuration device on low-power readout-card.

Firmware on all cards can be upgraded by attaching a Blaster (USB-Blaster, or [[ Using Ethernet Blaster | Ethernet Blaster ]], or ByteBlaster) through the MCE front-panel connector.

Clock card is an exception because it has two configuration devices: a Factory configuration device and a application configuration device. When MCE is turned on, the Clock-Card FPGA is loaded from the Factory configuration device, but then it can switch to the firmware loaded in the application configuration device by issuing an "wb cc app_config 1" command in mas. See the next section to program the Clock-Card Factory configuration device.

# Connect a USB Blaster to a PC with Quartus software installed.
# Plug the Blaster connector into the MCE front-panel connector. Be sure that the Clock Card is powered on.
# Open Quartus II. (Note that on Linux systems, you may need to invoke Quartus from the terminal. If "quartus" is not in the path, you may be able to find it in /opt/usr/local/lib/altera/10.0/quartus/bin (which can be added to the path. Furthermore, you may need to be root user to access the USB blaster, in which case "sudo quartus" (or "sudo /path/to/quartus") should be enough.
# Select Tools -> Programmer
# Press the 'Hardware Setup' button
# Select USB Blaster from the 'Currently Selected Hardware' drop-down menu. If that option is not available, press the 'Add Hardware' button, and add a USB Blaster to the list.
# Select 'Close'
# Select the 'Auto Detect' button and after few moments you should see list of devices.
# There are two devices listed per each MCE card with the exception of the low-power Readout card which will only show as one device. The top two devices correspond to Address Card, then the next 2 devices correspond to BC1, and so on.
# In order to load temporary firmware, choose the desired EP1S device. In order to load firmware permanently, choose the EPC16 device. In both cases for low-power Readout Card, select the EP3S device.
# Firmware programming files should be downloaded from [http://e-mode.phas.ubc.ca/mce_firmware/ firmware repository]. Copy files from this repository to the programming computer hard drive. Temporary firmware (for EP1S and EP3S devices) uses .sof files. Permanent firmware will be .pof (for EPC16 devices) or .jic (for EP3S devices).
# Double-click on the 'File' entry corresponding to the device that you wish to program, and select a programming file. For .jic files, an EPCS64 device should be automatically added to the device list when you associate the .jic with the EP3S device.
# Check the box in the Program/Configure column corresponding to your device. For .jic file, check boxes for both EP3S50 and EPCS64.
# Select 'Start'. If you are loading temporary firmware, it should take about 30 seconds, if you are loading permanent firmware, then it may take up to 10 minutes.
# For .sof files, the FPGA will automatically reconfigure itself when programming is complete. For .pof or .jic files, it is necessary to power cycle the unit to get the new firmware loaded.

= Updating the Factory Configuration on Clock Card=
# You need to program the Clock Card's .pof with your USB Blaster, but via P2 on the Clock Card board itself.
# To gain access to this connector, partially eject the Clock Card from the MCE until you can see the connector.
# Plug the USB blaster into the connector so that the ribbon cable is oriented upwards (this puts pin 1 of the USB Blaster to pin 1 of the connector).
# Gently curl the ribbon cable around so that it can come out the gap between the Clock Card faceplate and the Readout Card #4 faceplate.
# Gently re-insert the Clock Card taking care not to kink the ribbon cable.
# Open Quartus and go to the programmer window, as described above.
# Now when you press 'Auto Detect' to Scan the JTAG Chain, two devices should be listed. Click on EPC16 device and select a Clock Card .pof.
# Follow the instructions above for configuring the EPC16..

= If the USB Blaster stops responding =
# Close Quartus
# Power off the MCE
# Wait for 5 seconds
# Power on the MCE
# Re-open Quartus

= Using Ethernet Blaster =

You can program the MCE remotely, if you have an Altera-supplied Ethernet Blaster. Assuming that EthernetBlaster is configured and attached to MCE:

# In Quartus, select the "Tools -> Programmer" menu.
# Click on "Hardware Setup"
# Click on "Add Hardware"
# On the drop-down menus, select/specify the following pieces of information:
#*Hardware type: EthernetBlaster
#*Port: ---
#*Baud rate: ---
#*Sever name: <IP Address of the EthernetBlaster>
#*Server port: 1309 -- Server port 1309 should be opened for the Ethernet Blaster.
#*Server password: <Password>
# Press "Auto Detect". It takes few moments to find the EthernetBlaster. Press "OK".
# Now you are back to Hardware Setup Page with the following item showing up in the list of "Available Hardware Items": Hardware: Ethernet Blaster, Server: xxxxx, Port: /dev/ebhwip
# Click on the "Currently Selected Hardware" drop-down menu and select "EthernetBlaster", and then press "Close".
# Now Press on Auto Detect and you should see the list of cards that the EthernetBlaster is connected to.

= Programming from the Command Line =

On a remote Linux machine you might only have / might only be able to run a command line programmer.

Find the path to the programmer; possibly

alias quartus_pgm='sudo /opt/altera/11.1/qprogrammer/bin/quartus_pgm'

Scan (this is a CC factory configuration device):

quartus_pgm -a
...
Info (213045): Using programming cable "USB-Blaster [4-2]"
1) USB-Blaster [4-2]
0100A0DD EPC(16|4|8)
171280DD EPM(3128A|7128AE)

Program:

quartus_pgm --mode=JTAG -o 'PV;firmware/cc_v0500000e_15may2012.pof@1'
...
Info: Command: quartus_pgm --mode=JTAG -o PV;firmware/cc_v0500000e_15may2012.pof@1
Info (213045): Using programming cable "USB-Blaster [4-2]"
Info (213011): Using programming file firmware/cc_v0500000e_15may2012.pof with checksum 0x0D7E2A22 for device EPC16@1
Info (209060): Started Programmer operation at Tue May 28 10:33:04 2013
Info (209017): Device 1 contains JTAG ID code 0x0100A0DD
Info (209018): Device 1 silicon ID is 0xB0E9
Info (209044): Erasing EPC4/8/16 configuration device(s)
Info (209023): Programming device(s)
Info (209021): Performing verification on device(s)
Info (209011): Successfully performed operation(s)
Info (209061): Ended Programmer operation at Tue May 28 10:37:25 2013
Info: Quartus II 32-bit Programmer was successful. 0 errors, 0 warnings
Info: Peak virtual memory: 111 megabytes
Info: Processing ended: Tue May 28 10:37:25 2013
Info: Elapsed time: 00:04:22
Info: Total CPU time (on all processors): 00:00:06

USB Blaster

2013-05-28T14:46:18Z

Mhasse:

Programming over Fibre

2013-04-26T15:53:54Z

Mhasse: /* Update Firmware */

{{hierarchy header}}
The procedure to update the [[MCE firmware]] over the fibre interface using a [[MAS]] PC, also known as "Remote Firmware Update", is described here.

= Introduction =

Each of the Address Card, Bias Cards, and Readout Cards of the MCE has an Altera Stratix FPGA along with a configuration device ([[MCE FPGA Types | See here]]). The Clock Card, however, has one FPGA with two configuration devices. FPGAs are RAM-based devices while configuration devices are Flash-based devices. Upon power up, each FPGA is loaded from its respective configuration device. The Clock Card FPGA is loaded from its factory configuration device upon power up, but then later, the firmware in the application configuration device can be loaded into the FPGA by issuing a command, i.e.:

mce_cmd -x rs cc config_app 1

All these programmable parts, with the exception of the factory configuration device, are on a continuous JTAG chain that can be controlled via the MCE front-panel connector with an attached USB-Blaster, ''or'' via the Clock Card FPGA, provided it is running the right firmware, and is driven through the fibre interface.

The factory configuration device, however, is not on the same JTAG chain. It is only accessible through an on-board JTAG connector and can only be programmed with a USB-Blaster attached and Quartus Programmer.

In order to load temporary firmware, an sof file can be loaded into the FPGA. This firmware will be lost upon power cycle. To load permanent firmware, a pof file (or a jic file depending on EPC16 or EPCS64) can be loaded.

= Remote Update: step by step =
This can be done in 3 steps:
# Scan JTAG chain
# Generate JAM file
# Update Firmware
== Scan JTAG Chain ==

Run '''mce_auto_detect''':
user@ubuntu:~$ mce_auto_detect
mce_scan version 1
card_scan
# card card_id card_type pcb_rev slot_id
2 0x124fb77 3 0 8
3 0x19c74de 2 0 4
4 0x1256aa5 2 0 5
7 0x19c0a93 1 6 1
8 0x19c3071 1 6 2
9 0x19c1455 1 6 3
10 0x19c6305 0 0 0
jtag_scan
# id device
1 EPC4/EPC8/EPC16
2 EP1S40
3 EPC4/EPC8/EPC16
4 EP1S40
5 EPC4/EPC8/EPC16
6 EP1S10
7 EPC4/EPC8/EPC16
8 EP1S10
9 EPC4/EPC8/EPC16
10 EP1S10
11 EPC4/EPC8/EPC16
12 EP1S10
13 EPC4/EPC8/EPC16

Note that the order of devices are cc (#1), rc2 (device #2, #3), rc1(#4, #5), bc3 (#6, #7), bc2(#8, #9), bc1(#10, #11), ac(#12, #13).

Device #1 refers to the Application configuration device on Clock Card.

If there are no devices listed below "jtag_scan", you probably have to flip a jumper on your clock card. See the section below on [[ #Hardware Requirements ]].

== Generate Jam File ==
You need to update firmware on one device type at a time, i.e., EPC only, or FPGA only, or EPCS64 only.

'''If you have access to internet:'''
# Go to MCE Firmware Canning Party webpage: http://e-mode.phas.ubc.ca/mcefcp/
# copy and paste the result of mce_auto_detect on that webpage.
# Choose the target device(s) you want to program and a drop down menu of available firmware revisions will appear.
# Choose the firmware revision and click generate.
# Save the generated file somewhere on your mas PC.

'''If you do NOT have access to internet:'''
# Install Quartus II Web Edition on Linux [[Quartus II Installation | See Instructions here]]
# make a cdf file from the output of mce_auto_detect. Here is a sample cdf file [http://www.phas.ubc.ca/~mce/mcedocs/software/sample.cdf CDF]
# generate a jam file by typing:
quartus_cpf -c <cdf_file_name> <jamfilename>

== Update Firmware==

Run '''mce_fw_update''':
Usage: /usr/mce/mce_script/script/mce_fw_update <device> <jamfilename>
device one of:
FPGA: for temporary firmware (sof)
EPC16: for permanent firmware on any card other than RC Rev. E (pof)
EPCS64: for permanent firmware on RC Rev. E (jic)
jamfilename either an absolute pathname, or a file in $MCE_JAM_DIR

If you are programming FPGA parts (temporary firmware), this step takes seconds. However, it takes minutes to program permanent firmware into EPC16 or EPCS64 devices, e.g. '''13 minutes''' to program 2 rev F. Readout Cards.

If the programming fails, you might need to mess with the programming frequencies. These are passed to mce_jam via the -f flag, as frequencies in Hz. See the mce_fw_update script, and try decreasing the frequency by a factor of 10.

Note that when programming permanent firmware, the fw_rev will not immediately be updated. The new firmware will not be loaded until the card is power cycled.

= Troubleshooting Remote Update =
== Software Requirements ==
Make sure the following are installed.
From the MAS repository:
* mce_jam : This will be installed under /usr/mce/bin/.
From the MCE script repository (trunk):
* read_idcode.jam : This should be in $MAS_TEMPLATE directory.
* $MCE_JAM_DIR is set : This is set through mas_env.bash.
* mce_auto_detect (in mce_script directory)
* mce_fw_update (in mce_script directory)
== Firmware Requirements ==
The Clock Card FPGA has to run firmware revision 5.0.7 or later. Considering that Clock Card FPGA can be loaded through either the Factory or Application configuration devices, at least one of these need to have 5.0.7+ firmware. If you are running Clock Card firmware prior to 5.0.7, which means your factory configuration device is loaded with firmware prior to 5.0.7, then attach USB-Blaster to the MCE front-panel connector. Run Quaruts Programmer, click on auto-detect, and program the second part from the bottom of the list, EPC16, with Clock Card firmware 5.0.7+.pof.

Then issue the following command:
mce_cmd -x rs cc config_app 1
to switch to the new firmware. (Read back the firmware revision to make sure the new firmware is now active.)

== Hardware Requirements ==
The buffer that controls whether the FPGA can drive the JTAG chain or not is controlled by BB_EN or SW1 dip switch setting on the Clock Card. Clock Cards shipped earlier than Dec. 2010, do not have the right settings. To check this setting on your Clock Card, turn off the MCE power and unplug the Clock Card. The SW1.P1 labeled as "BB_EN" DIP should be on OPEN position.

* Note that with DIP switch SW1.P1 set to OPEN, you can not program the FPGA(sof) from the front panel connector (USB_Blaster) anymore.
* With DIP switch set to OPEN, if CC firmware is pre-5.0.7, you can not access the JTAG chain from the front panel connector (USB_Blaster) anymore. Assuming you have 5.0.7+ in your configuration device, you need to issue: <code>mce_cmd -x rs cc config_app 1</code> to be able to access front-panel JTAG.

= Footnotes =
== Porting Remote Configuration Sofware to DAS ==
The following C-code will need to be ported to DAS to enable Remote Configuration. You will need to convert the MCE WB and RB commands in the code to use DAS libraries and compile the code with the included Makefile:
*[http://www.phas.ubc.ca/~mce/mcedocs/software/mce_jam/ MCE Jam Player -- SVN revision 16 (~/jp_25/mce_jam/trunk)].
** '''jam_mce.c''': contains low-level MCE routines used during programming
** all other files should be fine.

== Development Notes ==
* [[intmce:Remote Firmware Update]]

Rectangle Mode Data

2013-02-19T19:59:20Z

Mhasse:

"Rectangle Mode" refers to the sampling of a subset of the full array, typically at a kHz data rate. The data from the Readout Cards is packed into output frames efficiently to minimize overhead.

Rectangle mode eliminates strain on the acquisition system during fast acquisitions by eliminating read-out overhead. This means that the 'difficulty' of read-out is a fairly linear function of (sampling frequency) x (number of detectors read out) rather than depending on each.

The hardware limit on readout is roughly 4 MB/s. Since MCE data are 32-bit words, this permits 1e6 detector-samples to be read out per second.

So the maximum number of detectors that can be sampled at some frequency F is
D = (1 MHz) / F

You can't sample at 1 MHz. But you could probably do a detector or two at 250 kHz.

= Configuration =

The steps for configuring a rectangle mode acquisition are:
# Set the multiplexing rate using num_rows and row_len
# If necessary, adjust row_order to mux the channels of interest (you can only read out rows you are multiplexing...). If you do not intend to re-tune the array with the adjusted num_rows / row_order, you must also change the first entries of rc* adc_offset* to correspond to the desired rows and, for fast SQ2 switching, change row_order on the BAC/BC2.
# Identify a rectangle of detectors on the readout card to read out by setting the RC parameters
#* num_rows_reported, num_cols_reported, readout_row_index, readout_col_index
# Set the size of the readout frame by setting the CC parameters
#* num_rows_reported, num_cols_reported
# Set the CC decimation factor 'data_rate' so that the RC rectangles will stack perfectly into the CC readout frame.
#* e.g. suppose
#** RC num_rows_reported x num_cols_reported = 1x4
#** CC num_rows_reported x num_cols_reported = 33x8
#* then we set
#** CC data_rate = (33 x 8) / (1 x 4) = 66

= Readout limitations =

Rectangle mode configuration should respect the following hardware limits:
* Total data rate must not exceed 4 MB/s
* Read-out frequency must not exceed 20 kHz
* The multiplexing frame rate must not be set so fast that the MCE cannot communicate with the readout cards. This limit is probably in the 100s of kHz.
* The buffer on each RC can hold 2048 words of data. The readout frame size, per readout card, must be kept somewhat below this limit.

Other things to remember:
* num_rows >= 2 is encouraged.
* you can't sample a detector faster than it is being visited in the multiplexing cycle.
* In RC firmware prior to 5.1.7, the following condition has to be met:
(230 + 2 * cc_num_rows_reported * cc_num_cols_reported) < (num_rows * row_len)
otherwise, the data is corrupted. This problem is fixed in RC firmware 5.1.7 (See [[Readout Card firmware]])

= Checking MCE configuration using rect_check.py =

Use the utility @rect_check.py@ to verify that data will be / were acquired reasonably.

e.g. To check the state of the MCE (requires python MCE bindings), run
rect_check.py --mce

To analyze the data framing in a runfile:
rect_check.py my_data.run

(Depending on stuff, you might need to invoke rect_check as:
$MAS_PYTHON/rect_check.py
or even
python $MAS_PYTHON/rect_check.py
Sorry.)

The output looks like this:

MCE configuration:
cc_rcs ( cc, rcs_to_report_data ): 60
cc_dec ( cc, data_rate ): 256
cc_nmux ( cc, num_rows ): 33
cc_cmux ( cc, row_len ): 100
cc_nr ( cc, num_rows_reported ): 32
cc_nc ( cc, num_cols_reported ): 8
rc_nmux ( rca, num_rows ): 33
rc_cmux ( rca, row_len ): 100
rc_nr ( rca, num_rows_reported ): 1
rc_nc ( rca, num_cols_reported ): 1
rc_r0 ( rca, readout_row_index ): 0
rc_c0 ( rca, readout_col_index ): 0

Framing:
RC storage per mux cycle: 1
CC read-out per frame: 256
CC decimation: 256

Sanity Summary:
Contiguous (for high-rate readout)? yes
Complete (all-detector readout)? no
Bizarro (a bad thing)? no
Bounded (a good thing)? yes

Timing:
Mux freq: 15151.00
Mean sampling freq: 15151.00
Read-out freq: 59.00

Data volume:
Frame size (bytes/RC): 1200
Data rate (MB/s/RC): 0.07

The program has notions of what is "reasonable", and these are expressed in the lines "Contiguous?", "Complete?", "Bizarro?", and "Bounded?":
* 'Contiguous': all detectors that are read out will be read out at each multiplexing cycle
** When acquiring fast data from a subset of the detectors, at the multiplexing rate, you want "Contiguous = yes".
* 'Complete': all detectors that are multiplexed will be read out
** When acquiring normal data, you probably want "Complete = yes".
* 'Bizarro': the rectangle defined in the RC does not fit evenly into the readout frame.
** e.g. you have set up an 8x8 rectangle but you're reading CC frames that are 33x8. Don't do this. I'm not even sure what you'd get out.
* 'Bounded': the rectangle defined in the RC corresponds to detectors that are actually getting read/servoed. This basically just checks that rc? readout_row_index makes any sense at all given num_rows and num_rows_reported.
** This must be "yes" or your data could be weird.

Note that it is possible to be none of Complete, Contiguous, or Bizarro. For example, you could read out the first 33 of every 66 multiplexing cycles for 8 detectors, packing them efficiently into a 33 x 8 read-out frame. Maybe that should be called Bizarro. But right now, it isn't.

It is unlikely, but possible, to be both Contiguous and Complete.

If you are Bizarro, you are neither Contiguous nor Complete. See Euler diagram below.

[[Image:reasonable_rectangles.png]]

= Data acquisition =

Use "mce_run" in the usual way to acquire data. Note that the argument specifying the number of frames is always the number of 'read-out' frames, so for packed data the number of samples per detector will be higher.

e.g. for the above configuration
mce_run my_data 100 1

would acquire 100 read-out frames. Since the read-out frequency is 59 Hz, this would take about 2 seconds. Each readout frame contains 8 x 32 = 256 data from a single detector. So the resulting data stream contains 25600 samples.

= Data file loading =

Recent versions of mce_data.py can extract rectangle mode data from the packed frame structure. E.g. for the above case, extracting the data is as easy as
>>> d = MCEFile('my_data').Read()
>>> d.data.shape
(1, 25600)

= Rather long explanation and justification of structure, from an e-mail =

Yesterday Bryce and I were talking about paths towards a new rectangle readout mode. The following is a recommendation for the rough structure of the system that I think will be easy to manage and provide a maximum flexibility for backwards compatibility and future expansion.

The current rectangle mode is simpler than the planned one because the clock card and readout card need only agree on the number of data to readout, and no addditional waiting/synchronization is required between the clock card and readout card. The readout frame data sizes, internally and externally, are the same for everyone. The new mode is much more complex, because now the readout card has to accumulate several samples from each pixel into its internal buffer before sending the data to the clock card, and the clock card needs to ask for the right amount of data, which is probably some multiple of the rectangle size and is not necessarily a multiple of 8 or the number of multiplexing rows.

Anyway, the point is that here is a simple and flexible way to parametrize the new mode parameters and manage synchronization, and to provide flexibility and backwards compatibility.

1. The meaning of num_rows remains unchanged. It will always be a multiplexing parameter that all cards need to agree on.

2. The readout card has parameters (prepend "readout_" to all of these, if you want) "row_index", "num_rows", "col_index", "num_cols" that describe the rectangle of interest.

3. The clock card is programmed with a pair of numbers "readout_mult1" and "readout_mult2", that it uses to determine how many words of data to query the RCs for:
N_data = readout_mult1 * readout_mult2.
These numbers are analagous to "num_rows_reported" and "num_cols_reported", but the idea is to kill the idea of "rows" and "columns" in the readout frames because the payload size is not a simple product of n_rows * n_cols. The clock card continues to support "data rate", which indicates the period at which data queries are sent to the RCs. Software will handle the details of getting these factors right. Eventually we will only use one of mult?; the other is for backwards compat.

4. In the RC: at each mux frame, data from the desired rectangle is copied into a large buffer. The RC continues filling the buffer until the CC asks for data. When RC receives a request for N data from the CC, it returns the first N data in the buffer, and resets its write index to the start of the buffer. If the CC doesn't ask for data, and the RC buffer write index increments all the way past the end, the RC takes _no storage action_ in subsequent steps (i.e. it writes all new data to "/dev/null").

Setting up rectangle mode then proceeds as follows. Suppose the RC buffer size is 1600 and I want to readout a 4 x 33 patch of the array:

1. Software computes that 4x33 = 132 words fits into 1600 about 12 times. So it sets "cc data_rate" to 12, and the product of "mult1" and "mult2" to 12 * 132 = 1584. It also sets the readout card row and col rectangle parameters.

2. Software triggers frame acquisition. For the _first_ frame read out, the clock card and readout card may not be synchronized; i.e. the readout card's buffer almost certainly contains ancient, stale data. So the first frame is discarded. But since the first frame query sent the the buffer write index to 0, the data from subsequent frames is fresh and ordered. Because the clock card is asking for N data at the same rate that the RC can N-fill the buffer, this results in a contiguous data stream.

This scheme is simple because:
1. CC has only enough information to ask the readout cards for the right amount of data at the right times.
2. RC only needs to know the rectangle of interest, and it basically lets the CC manage the resetting of the buffer.
3. It is backwards-compatible with existing firmware; mult1 and mult2 can masquerade as num_rows_reported and "8" (num_cols_reported).

The scheme minimizes the amount of information that must be shared between the RC and CC, which provides flexiblity. With "mult" approach, the CC can remain truly ignorant as to what the RC is doing. In this scheme I have emphasized the rectangle mode features, but I also envision it being useful in raw mode firmware, since a lot of the features (such as a large, flexible RAM block in the RC) would seem useful in that context. (For raw mode you would need to add a lock to the buffer so that it could be read out with multiple queries.)

= Script Differences Between v4.x.x and v5.x.x =

This section describes the minimal configuration changes necessary to operate v5 firmware as though it were v4 firmware. If you use MAS, then stop reading now.

The differences between basic frame setup in v4.x.x and v5.x.x are described here. The data frame structure has been made more flexible. A user can read out an arbitrarily rectangular patch of the array. The patch-size is specified using new commands.

*In v4.x.x: The array patch-size is flexible in terms of the number of rows, and the row start index.
wb cc num_rows_reported 41 //power-on default = 41
wb rcs readout_row_index 0 //power-on default = 0

*In v5.x.x: The array patch-size is now also flexible in terms of the number of columns, and the column start index. Note that matching parameters on the Readout Cards and the Clock Card must be consistent.
wb cc num_rows_reported 41 //power-on default as above
wb cc num_cols_reported 8 //power-on default = 8
wb rcs num_rows_reported 41 //power-on default = 41
wb rcs num_cols_reported 8 //power-on default = 8
wb rcs readout_row_index 0 //power-on default as above
wb rcs readout_col_index 0 //power-on default = 0

Programming over Fibre

2013-01-30T22:58:45Z

Mhasse: /* Update Firmware */

{{hierarchy header}}
The procedure to update the [[MCE firmware]] over the fibre interface using a [[MAS]] PC, also known as "Remote Firmware Update", is described here.

= Introduction =

Each of the Address Card, Bias Cards, and Readout Cards of the MCE has an Altera Stratix FPGA along with a configuration device ([[MCE FPGA Types | See here]]). The Clock Card, however, has one FPGA with two configuration devices. FPGAs are RAM-based devices while configuration devices are Flash-based devices. Upon power up, each FPGA is loaded from its respective configuration device. The Clock Card FPGA is loaded from its factory configuration device upon power up, but then later, the firmware in the application configuration device can be loaded into the FPGA by issuing a command, i.e.:

mce_cmd -x rs cc config_app 1

All these programmable parts, with the exception of the factory configuration device, are on a continuous JTAG chain that can be controlled via the MCE front-panel connector with an attached USB-Blaster, ''or'' via the Clock Card FPGA, provided it is running the right firmware, and is driven through the fibre interface.

The factory configuration device, however, is not on the same JTAG chain. It is only accessible through an on-board JTAG connector and can only be programmed with a USB-Blaster attached and Quartus Programmer.

In order to load temporary firmware, an sof file can be loaded into the FPGA. This firmware will be lost upon power cycle. To load permanent firmware, a pof file (or a jic file depending on EPC16 or EPCS64) can be loaded.

= Remote Update: step by step =
This can be done in 3 steps:
# Scan JTAG chain
# Generate JAM file
# Update Firmware
== Scan JTAG Chain ==

Run '''mce_auto_detect''':
user@ubuntu:~$ mce_auto_detect
mce_scan version 1
card_scan
# card card_id card_type pcb_rev slot_id
2 0x124fb77 3 0 8
3 0x19c74de 2 0 4
4 0x1256aa5 2 0 5
7 0x19c0a93 1 6 1
8 0x19c3071 1 6 2
9 0x19c1455 1 6 3
10 0x19c6305 0 0 0
jtag_scan
# id device
1 EPC4/EPC8/EPC16
2 EP1S40
3 EPC4/EPC8/EPC16
4 EP1S40
5 EPC4/EPC8/EPC16
6 EP1S10
7 EPC4/EPC8/EPC16
8 EP1S10
9 EPC4/EPC8/EPC16
10 EP1S10
11 EPC4/EPC8/EPC16
12 EP1S10
13 EPC4/EPC8/EPC16

Note that the order of devices are cc (#1), rc2 (device #2, #3), rc1(#4, #5), bc3 (#6, #7), bc2(#8, #9), bc1(#10, #11), ac(#12, #13).

Device #1 refers to the Application configuration device on Clock Card.

If there are no devices listed below "jtag_scan", you probably have to flip a jumper on your clock card. See the section below on [[ #Hardware Requirements ]].

== Generate Jam File ==
You need to update firmware on one device type at a time, i.e., EPC only, or FPGA only, or EPCS64 only.

'''If you have access to internet:'''
# Go to MCE Firmware Canning Party webpage: http://e-mode.phas.ubc.ca/mcefcp/
# copy and paste the result of mce_auto_detect on that webpage.
# Choose the target device(s) you want to program and a drop down menu of available firmware revisions will appear.
# Choose the firmware revision and click generate.
# Save the generated file somewhere on your mas PC.

'''If you do NOT have access to internet:'''
# Install Quartus II Web Edition on Linux [[Quartus II Installation | See Instructions here]]
# make a cdf file from the output of mce_auto_detect. Here is a sample cdf file [http://www.phas.ubc.ca/~mce/mcedocs/software/sample.cdf CDF]
# generate a jam file by typing:
quartus_cpf -c <cdf_file_name> <jamfilename>

== Update Firmware==

Run '''mce_fw_update''':
Usage: /usr/mce/mce_script/script/mce_fw_update <device> <jamfilename>
device one of:
FPGA: for temporary firmware (sof)
EPC16: for permanent firmware on any card other than RC Rev. E (pof)
EPCS64: for permanent firmware on RC Rev. E (jic)
jamfilename either an absolute pathname, or a file in $MCE_JAM_DIR

If you are programming FPGA parts (temporary firmware), this step takes seconds. However, it takes minutes to program permanent firmware into EPC16 or EPCS64 devices, e.g. '''13 minutes''' to program 2 rev F. Readout Cards.

If the programming fails, you might need to mess with the programming frequencies. These are passed to mce_jam via the -f flag, as frequencies in Hz. See the mce_fw_update script, and try decreasing the frequency by a factor of 10.

= Troubleshooting Remote Update =
== Software Requirements ==
Make sure the following are installed.
From the MAS repository:
* mce_jam : This will be installed under /usr/mce/bin/.
From the MCE script repository (trunk):
* read_idcode.jam : This should be in $MAS_TEMPLATE directory.
* $MCE_JAM_DIR is set : This is set through mas_env.bash.
* mce_auto_detect (in mce_script directory)
* mce_fw_update (in mce_script directory)
== Firmware Requirements ==
The Clock Card FPGA has to run firmware revision 5.0.7 or later. Considering that Clock Card FPGA can be loaded through either the Factory or Application configuration devices, at least one of these need to have 5.0.7+ firmware. If you are running Clock Card firmware prior to 5.0.7, which means your factory configuration device is loaded with firmware prior to 5.0.7, then attach USB-Blaster to the MCE front-panel connector. Run Quaruts Programmer, click on auto-detect, and program the second part from the bottom of the list, EPC16, with Clock Card firmware 5.0.7+.pof.

Then issue the following command:
mce_cmd -x rs cc config_app 1
to switch to the new firmware. (Read back the firmware revision to make sure the new firmware is now active.)

== Hardware Requirements ==
The buffer that controls whether the FPGA can drive the JTAG chain or not is controlled by BB_EN or SW1 dip switch setting on the Clock Card. Clock Cards shipped earlier than Dec. 2010, do not have the right settings. To check this setting on your Clock Card, turn off the MCE power and unplug the Clock Card. The SW1.P1 labeled as "BB_EN" DIP should be on OPEN position.

* Note that with DIP switch SW1.P1 set to OPEN, you can not program the FPGA(sof) from the front panel connector (USB_Blaster) anymore.
* With DIP switch set to OPEN, if CC firmware is pre-5.0.7, you can not access the JTAG chain from the front panel connector (USB_Blaster) anymore. Assuming you have 5.0.7+ in your configuration device, you need to issue: <code>mce_cmd -x rs cc config_app 1</code> to be able to access front-panel JTAG.

= Footnotes =
== Porting Remote Configuration Sofware to DAS ==
The following C-code will need to be ported to DAS to enable Remote Configuration. You will need to convert the MCE WB and RB commands in the code to use DAS libraries and compile the code with the included Makefile:
*[http://www.phas.ubc.ca/~mce/mcedocs/software/mce_jam/ MCE Jam Player -- SVN revision 16 (~/jp_25/mce_jam/trunk)].
** '''jam_mce.c''': contains low-level MCE routines used during programming
** all other files should be fine.

== Development Notes ==
* [[intmce:Remote Firmware Update]]

Programming over Fibre

2013-01-30T22:55:10Z

Mhasse: /* Generate Jam File */

{{hierarchy header}}
The procedure to update the [[MCE firmware]] over the fibre interface using a [[MAS]] PC, also known as "Remote Firmware Update", is described here.

= Introduction =

Each of the Address Card, Bias Cards, and Readout Cards of the MCE has an Altera Stratix FPGA along with a configuration device ([[MCE FPGA Types | See here]]). The Clock Card, however, has one FPGA with two configuration devices. FPGAs are RAM-based devices while configuration devices are Flash-based devices. Upon power up, each FPGA is loaded from its respective configuration device. The Clock Card FPGA is loaded from its factory configuration device upon power up, but then later, the firmware in the application configuration device can be loaded into the FPGA by issuing a command, i.e.:

mce_cmd -x rs cc config_app 1

All these programmable parts, with the exception of the factory configuration device, are on a continuous JTAG chain that can be controlled via the MCE front-panel connector with an attached USB-Blaster, ''or'' via the Clock Card FPGA, provided it is running the right firmware, and is driven through the fibre interface.

The factory configuration device, however, is not on the same JTAG chain. It is only accessible through an on-board JTAG connector and can only be programmed with a USB-Blaster attached and Quartus Programmer.

In order to load temporary firmware, an sof file can be loaded into the FPGA. This firmware will be lost upon power cycle. To load permanent firmware, a pof file (or a jic file depending on EPC16 or EPCS64) can be loaded.

= Remote Update: step by step =
This can be done in 3 steps:
# Scan JTAG chain
# Generate JAM file
# Update Firmware
== Scan JTAG Chain ==

Run '''mce_auto_detect''':
user@ubuntu:~$ mce_auto_detect
mce_scan version 1
card_scan
# card card_id card_type pcb_rev slot_id
2 0x124fb77 3 0 8
3 0x19c74de 2 0 4
4 0x1256aa5 2 0 5
7 0x19c0a93 1 6 1
8 0x19c3071 1 6 2
9 0x19c1455 1 6 3
10 0x19c6305 0 0 0
jtag_scan
# id device
1 EPC4/EPC8/EPC16
2 EP1S40
3 EPC4/EPC8/EPC16
4 EP1S40
5 EPC4/EPC8/EPC16
6 EP1S10
7 EPC4/EPC8/EPC16
8 EP1S10
9 EPC4/EPC8/EPC16
10 EP1S10
11 EPC4/EPC8/EPC16
12 EP1S10
13 EPC4/EPC8/EPC16

Note that the order of devices are cc (#1), rc2 (device #2, #3), rc1(#4, #5), bc3 (#6, #7), bc2(#8, #9), bc1(#10, #11), ac(#12, #13).

Device #1 refers to the Application configuration device on Clock Card.

If there are no devices listed below "jtag_scan", you probably have to flip a jumper on your clock card. See the section below on [[ #Hardware Requirements ]].

== Generate Jam File ==
You need to update firmware on one device type at a time, i.e., EPC only, or FPGA only, or EPCS64 only.

'''If you have access to internet:'''
# Go to MCE Firmware Canning Party webpage: http://e-mode.phas.ubc.ca/mcefcp/
# copy and paste the result of mce_auto_detect on that webpage.
# Choose the target device(s) you want to program and a drop down menu of available firmware revisions will appear.
# Choose the firmware revision and click generate.
# Save the generated file somewhere on your mas PC.

'''If you do NOT have access to internet:'''
# Install Quartus II Web Edition on Linux [[Quartus II Installation | See Instructions here]]
# make a cdf file from the output of mce_auto_detect. Here is a sample cdf file [http://www.phas.ubc.ca/~mce/mcedocs/software/sample.cdf CDF]
# generate a jam file by typing:
quartus_cpf -c <cdf_file_name> <jamfilename>

== Update Firmware==
run '''mce_fw_update''':
Usage: mce_fw_update <device> <jamfilename>
device FPGA, EPC16, or EPCS64
- FPGA for temporary firmware (sof)
- EPC16 for permanent firmware on any card other than RC Rev. E (pof)
- EPCS64 for permanent firmware on RC Rev. E (jic)
jamfilename filename
- file needs to be located in $MCE_JAM_DIR

If you are programming FPGA parts (temporary firmware), this step takes seconds. However, it takes minutes to program permanent firmware into EPC16 or EPCS64 devices, e.g. '''13 minutes''' to program 2 rev F. Readout Cards.

If the programming fails, you might need to mess with the programming frequencies. These are passed to mce_jam via the -f flag, as frequencies in Hz. See the mce_fw_update script, and try decreasing the frequency by a factor of 10.

= Troubleshooting Remote Update =
== Software Requirements ==
Make sure the following are installed.
From the MAS repository:
* mce_jam : This will be installed under /usr/mce/bin/.
From the MCE script repository (trunk):
* read_idcode.jam : This should be in $MAS_TEMPLATE directory.
* $MCE_JAM_DIR is set : This is set through mas_env.bash.
* mce_auto_detect (in mce_script directory)
* mce_fw_update (in mce_script directory)
== Firmware Requirements ==
The Clock Card FPGA has to run firmware revision 5.0.7 or later. Considering that Clock Card FPGA can be loaded through either the Factory or Application configuration devices, at least one of these need to have 5.0.7+ firmware. If you are running Clock Card firmware prior to 5.0.7, which means your factory configuration device is loaded with firmware prior to 5.0.7, then attach USB-Blaster to the MCE front-panel connector. Run Quaruts Programmer, click on auto-detect, and program the second part from the bottom of the list, EPC16, with Clock Card firmware 5.0.7+.pof.

Then issue the following command:
mce_cmd -x rs cc config_app 1
to switch to the new firmware. (Read back the firmware revision to make sure the new firmware is now active.)

== Hardware Requirements ==
The buffer that controls whether the FPGA can drive the JTAG chain or not is controlled by BB_EN or SW1 dip switch setting on the Clock Card. Clock Cards shipped earlier than Dec. 2010, do not have the right settings. To check this setting on your Clock Card, turn off the MCE power and unplug the Clock Card. The SW1.P1 labeled as "BB_EN" DIP should be on OPEN position.

* Note that with DIP switch SW1.P1 set to OPEN, you can not program the FPGA(sof) from the front panel connector (USB_Blaster) anymore.
* With DIP switch set to OPEN, if CC firmware is pre-5.0.7, you can not access the JTAG chain from the front panel connector (USB_Blaster) anymore. Assuming you have 5.0.7+ in your configuration device, you need to issue: <code>mce_cmd -x rs cc config_app 1</code> to be able to access front-panel JTAG.

= Footnotes =
== Porting Remote Configuration Sofware to DAS ==
The following C-code will need to be ported to DAS to enable Remote Configuration. You will need to convert the MCE WB and RB commands in the code to use DAS libraries and compile the code with the included Makefile:
*[http://www.phas.ubc.ca/~mce/mcedocs/software/mce_jam/ MCE Jam Player -- SVN revision 16 (~/jp_25/mce_jam/trunk)].
** '''jam_mce.c''': contains low-level MCE routines used during programming
** all other files should be fine.

== Development Notes ==
* [[intmce:Remote Firmware Update]]