Holger Pieper, June 2002

Introduction

1. Purpose

This document contains the user manual of the Waveform Editor Software. It mainly addresses those who deal with CCD applications within a CCD controller environment. The syntax and expressions used throughout the document were defined by the designers of FIERA, which is the name of the ESO state of the art CCD controller.

The Waveform Editor Software was designed to match the special requirements for developers in the FIERA environment. Nevertheless it is a general tool to create and visualize waveforms, a concatenation of electrical pulses, which can be used to control a hardware.

2. Scope

This manual will not give an introduction on the FIERA CCD controller. For detailed information on CCD operation and their characteristics, and for those who are not familiar with the basic FIERA architecture, [1] and [2] will be useful to read.

3. Abbreviations and acronyms

The following abbreviations and acronyms are used in this document :

4. Glossary

5. Applicable documents

1. FIERA CCD controller system requirements, VLT-SPE-ESO-13640-1315
2. FIERA CCD controller software functional specifications, VLT-SPE-ESO-13640-1315

Overview

The waveform editor has been implemented using the Tcl/Tk and [incr Tcl/Tk] programming languages, making the application most platform independent. It's GUI a common set of commands and options as well as the additional functions relevant for the process of stimuli generation which separates into two different operational environments, a textual and a graphical part. In the following chapters the different operational environments shall be explained in more detail.

Beginning with the   Setup chapter a quick tour of how to install the software is given, using the two environments MS-Windows95 and Unix (Solaris and HP-UX) running the standard VLT environment.

The   Editor chapter provides information on the editor UIF mainframe and explains the basic set of commands available from the application menu and toolbar.

The   Waveforms chapter depicts the usage of the textual and the graphical waveform formats, and the   FAQ chapter provides a list of frequently asked questions.

Caution

Since the waveform editor was implemented using an interpreted scripting language, it is obvious that the interpreter, which is sometimes referred to as a sequencer must be present at runtime. The main program loop has not been implemented using C/C++ and does not contain a main (int argc, char *argv[]) function, it is the event loop which is part of the sequencer. This implies that terminating the sequencer will cause the application to stop immediately which may result in unpleasant loss of data.

The waveform definition formats supported by the software, can be manipulated independently. An advantage of this feature is that waveforms, which have been edited manually in either format, input format or output format, can easily be imported into the WES SW. Saving the waveform selected will automatically write both waveform formats to disk, replacing the old files, therefore it is up to the user to decide which version is the most up-to-date one and shall be used for editing.

In order to avoid confusion and eventual loss of data, the user should always choose to work with the same waveform definition format.

Naturally, it cannot be denied that whenever a small change has to be made to a waveform, i.e. changing a clockspeed divider, increasing a repetition factor, it can be much faster and therefore very tempting to edit the file directly using emacs, vi or another common text editor. In case the user does not refrain from this kind of manipulation, unpredictable behaviour of the application and loss of data can occur.

Setup

PC running Windows 95 or Windows NT

VLT environment

Setup of a new project directory

To setup a new project directory proceed as follows:

1. Create a blank directory
2. Create a new board configuration file myboard.brd which shall contain the board configuration reflecting the physical detector electronics or modify an existing one.

It is essential that the project directory contains a valid board configuration. In case board conflicting board configurations are found in the project directory.

Editor

The waveform editor comprises two different working environments which are both integrated into the application mainframe.

UIF mainframe displaying the text editor panel

Additionaly a dialog will open which waits for the user to select a project directory :

Preference dialog

The project directory initially displayed in the directory entry is loaded from the initialisation file which is optionally created by the SW in the user $(HOME) directory, called .wesFieraCfg. The leading "." makes it a hidden file on UNIX systems. Pressing the browse button opens a dialog which allows to traverse the directory structure :

Directory selection

The system clock speed is assumed to be 50 MHz default, but can be modified to reflect the current HW configuration.

It is essential for a successful session to select a directory containing the detector electronics configuration. In case no entry is selected, error messages will be generated upon opening a waveform definition file, i.e pattern , usequence, or sequence file, or upon creation of a blank definition.

As described in more detail in the   Waveforms chapter, the hierarchical waveform definitions are tied to a fixed board configuration. Only SIMMs previously defined in the board configuration file are being accepted by the SW.

Menubar and toolbar

The UIF offers a menubar and a toolbar with user commands, which allow standard file handling operations as well as operations which require a valid waveform definition to be loaded into the editor.

Menubar

Toolbar

The entry which currently has the focus is displayed with inverted colors, highlighted. In the menubar figure displayed above the mouse cursor has been moved over the Help menu entry.

The five menu buttons File, Edit, Options, View and Help comprise separate sets of items which are explained in the following. Whenever the command listed is also supported as a bitmap button entry in the toolbar, the toolbar button will be displayed additionally.

1.   File   Menu

New   creates a new waveform definition (pattern, usequence, sequence). When selected the following dialog is displayed :

Create new pattern dialog

Here, you can choose the type of the waveform to create.

Pattern

USequence

Create new usequence dialog

Sequence

Create new sequence dialog

Load   loads an existing waveform definition from HD. When selected the following Open File Dialog is displayed, which allows to browse the directory structure :

File open dialog

Save   saves the current waveform to HD.

Save As   saves the current waveform with a new name. The File Save Dialog is displayed, which has the same layout as the File Open Dialog, for the user to enter a valid filename which will be used to store the waveform. In case the file already exists, a Confirmation Dialog will popup and wait for the user to confirm the requested operation.

Print   prints the current waveform. Graphically print out the currently loaded waveform definition.

Exit   exits the application. Displays a Confirmation Dialog for the user to select whether the current configuration, i.e. display configuration, and project path name, shall be saved to the files $(HOME)/.wesFieraCfg and /.wesDisplCfg.

2.   Edit   Menu

	Adjust Waveform Length adjusts the length of the current waveform (only applies to PATTERNs and USEQUENCEs). To change the length of the current waveform the new value can be entered in the entryfield. Initially, the current length is displayed.
	Insert Ticks inserts a number of ticks into the current waveform (only works with PATTERNs and USEQUENCEs). current Waveform the name of the waveform which is currently loaded. insert at tick the insertion point. number of ticks the number of ticks which shall be inserted.

3.   Options   Menu

4.   View   Menu

The View menu contains three checkbuttons which indicate the current view configuration. The UIF mainframe can contain both, the graphical and the textual editor panel, plus additionaly a display panel for diagnostic messages.

RED / checked means activated function.
BLUEVIOLET / unchecked means deactivated function.

The displayed figure above has been set to the following :

• Do not diaply the graphical waveform editor.
• Display the textual waveform editor.
• Display the diagnostic messages.

The   Refresh   command performs an update of the currently active editor panel. In text mode, the text display area is repainted, and in graphic mode the grphical display is repainted as well as the miniature display of the overall waveform (world display).

5.   Help   Menu

Textual waveform editor

In order to define a waveform textually using the hierarchical waveform definition language, at startup the   mainframe window   displays the textual environment.

For the actual format of the supported waveform types, please refer to the   Waveforms chapter.

Graphical waveform editor

The graphical editor display contains a graphical waveform display as well as additional status information on he selected waveform :

• total length of the waveform in ticks
• the current tick, which the cursor is pointing to
• the current clock frequency (only used in sequence display)
• the current SIMM under the cursor
• the name of the board which hosts the SIMM
• sequence control-statement information, only used in sequence display
• a "world display" which gives an overall view of the entire waveform
• a ruler which displays the current cursor position in ticks

Graphical editor display

Moving the cursor whithin the waveform display will update the status fields simm board, and tick automatically.

User actions

Additionally to the general operations which can be selected from the Edit Menu, some interactive commands are supported :

Waveforms

The waveform editor must support two formats used for the description of waveforms. The input format is used to define waveforms textually. WES translates this input format into the output format which serves as the input for the SPArc SW. The files SPArc are then loaded via the sequencer running on the DSP onto the detector electronics, where they are stored.

Both format types, input and output can contain three different kinds of description levels. At the lowest level there is the pattern definition. At the next level, the usequence combines a set of patterns which are executed in parallel by different boards.

Pattern

The pattern definition contains time statements to indicate when a bi-level SIMM is assigned a value. Multilevel pattern definition uses a higher level format because of the following reasons :

• When the patterns are input, the time base which is actually used when the patterns are sent to the controller, is only defined in the sequence definition.
• Say the function is exponential and it would be split into samples according to a certain time base, information on the function behaviour would be deleted and could not be retrieved again.

As mentioned before the following format is used as input to the textual editor, to the graphical editor, and it is also the format that the graphical information is converted into when the editing is finished.

Input-Format

The input format uses the following notation : Bi-Level Pattern

Syntax   :

PATTERN <board_name> <pattern_name>
{ 

     <time_step(i)> 
     <time_step(k)>
     <time_step(n)>
     . . .

}

Where i < k < n,
<board_name> must be one of the "well known" names which have been defined either in the file fixed_boards.brd or in the file clk_brds.brd.

<pattern_name> is a NON QUOTED ascii string which the pattern shall be referred by in future definitions. The name must NOT white spaces.

<time_step(i)> has the following format :   time i: <simm_name> = <value> ;

The time statement defines the relative timing when a SIMM is assigned a value. The clockspeed will be defined later in the sequence definition. The absolute time can be calculated as i times .
If i > 0 then each of the SIMMs in the pattern are initialized to zero. If only consists of the time i - label, than the last active SIMM values are copied for this step.

Bi-Level SIMMs cannot be grouped, i.e. treated as an array of SIMMS :
IP<1-3> = 001, in the current version.

Example   :

PATTERN 1 BRD_COMMBRD pixel_read_commbrd 

{ 

     time 18:

          OUT1=1; 
          WRITE_FIFO=1; 

     time 19: 

          OUT1=0; 
          WRITE_FIFO=0; 

     time 26: 

}

PATTERN BRD_VIDBRD1 pixel_read_vidbrd1

{ 

     time 0: 

          SAMPLE2=1; 

     time 3: 

          CLAMP2=1; 

     time 7: 

          DCHARGE2=1; 

     time 8: 

          O_ENABLE2=1; 

     time 12: 

          DCHARGE2=0; 

     time 15: 

          SAMPLE2=0; 
          O_ENABLE2=0; 

     time 16: 

          CLAMP2=0; 

     time 27: 

} 

Output-Format

Syntax   :

PATTERN_START   

     <pattern_step>; 
     .;
     .;
     .;

PATTERN_END

The <board_name> must be the name of a board which has been defined in one of the board configuration files *.brd.

The <pattern_name> is any ascii string which you want to refer to the patterns. This name can contain spaces (or anything else) if the name is surrounded by " ". Pattern names must be globally unique.

Each <pattern_step> has the following format :   <simm_name> = <value> <simm_name> = <value> ... ;

The <simm_name> is the name of a SIMM defined for <board_name>. The <value> is the value that SIMM should have in this pattern step. If no value is defined for a SIMM, its value will be the same as in the last pattern step (initially 0).

If the SIMM is bi-level, its value can only be set to 1 or 0.

USequence

Input-Format

Syntax   :

USEQUENCE <usequence_name>

{

     <pattern_name>;
     .;
     .;
     .;

}

<usequence_name> is the name the usequence shall be referred by in sequence definitions. It is globally unique.

<pattern_name> is the name of a valid pattern definition, stored in file <pattern_name>.wpt.

Example   :

USEQUENCE integrate 

{

     integrate_clkdrv1;
     integrate_commbrd;
     integrate_vidbrd1;

}

Output-Format

Syntax   :

USEQUENCE_START <usequence_name> 

     <pattern_name> 
     .;
     .;
     .;

USEQUENCE_END

The <useqeuence_name> is the name by which you want to refer to the usequence in sequence definitions. It is globally unique.

The <pattern_name> are the names of patterns which have been defined in one of the pattern files *.pat. Each <pattern_name> in the usequence must be confined to a different board.

Sequence

Input-Format

Syntax   :

SEQUENCE <sequence_name> 

     pixel_x = <pixel_x_dim>
     pixel_y = <pixel_y_dim> 
     pixel_order = <pixel_order_info>

{

     <sequence_statement>

     . . .

}

Where :

Output-Format

Syntax   :

SEQUENCE_START <sequence_name> 

     pixel_x <pixel_x_dim>
     pixel_y <pixel_y_dim> 
     pixel_order <pixel_order_info> 

SEQUENCE_STATEMENTS 

     <sequence_statement>

     . . .

SEQUENCE_END

Where :

Frequently asked questions