SpinCore PulseBlaster Interpreter

Sections

  1. Legal
  2. Graphical User Interface
  3. Language
  4. Interpreter Special Features
  5. Command Line
  6. PulseBlaster ESR Pro Information

For help or information about other SpinCore products, please visit us at www.spincore.com


Legal

Copyright (c) 2009 SpinCore Technologies, Inc.

This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications.

Graphical User Interface


   Upon launching the program, you will be presented with an interface for writing your PulseBlaster programs. The top white box is an editor. The bottom gray box is output that the interpreter produces. At the bottom of the window is a box to put in the frequency your board uses. This frequency will be saved each time you shutdown the program and then reloaded the next time you launch. On the bottom right, you will notice Line # and Column # output. This tells you where the cursor is inside of the edit box for fixing errors and such.

    At the top of the window is the menu bar and 5 buttons. The buttons perform many of the same functions that can be found on the menu bar but are provided as a convenience. Starting from left to right:

Open File
This button opens a file. You will be prompted to save any changes to the contents of the current file.

Save File
This button saves the file you are currently editing.

Load Board
This button loads the program that currently resides in the edit box onto the board. The file does not have to be saved beforehand. The program will take the contents of the edit box and interpret them. The output of this operation will be displayed in the output box. Upon success, a message will be displayed saying the board was successfully loaded. If this message is not displayed, it means that some error occurred and a message telling you the error should be the last thing displayed.

Start
This button starts execution of the program currently in the board's memory.

Stop
This button stops execution of the program current in the board's memory.

    The menu bar is just above the 5 buttons. Starting from left to right:

File->New
This will erase the current contents of the edit box. You will be prompted to save changes to the
current file.

File->Open
Same as the Open File button.

File->Save
Same as the Save File button.

File->Exit
This will exit the program. You will be prompted to save changes to the current file.

Interpreter->Show Debug Information
This turns debug information from the interpreter on and off. This might provide some insight into an error that you might not be able to resolve. The debug information will be shown next time the board is loaded.

Interpreter->Save Output
This saves the contents of the output box to a text file.

Interpreter->Clear Output
This clears the contents of the output box.

Board->Load
Same as Load Board button.

Board->Start
Same as Start button.

Board->Stop
Same as Stop button.

Help->Read Me
Opens this document in a web browser.

Help->About
This displays information about the program.

Language

The language of the interpreter is very similar in appearance to that of an assembly language. Every line represents a single instruction. White space, such as tabs and spaces, is discarded. The language is case-insensitive. The following are instructions on the contents of a given line.

Labels

    Labels come at the beginning of a line and are denoted by a : at the end. For instance:

Start: 0xFFFFFF, 200 ms

    This line is labeled Start. Since the language is case insensitive though, the label is equal to any form of the word Start. Labels are optional and do not have to be contained on any line.

Output Pattern

    This is the first required part for a given line. This field must exist on all lines or the interpreter will fail while programming the board. This field represents the pattern that the board will output for this instruction. This pattern may be represented in Hex, Binary, or simply Integer format. All output fields must begin with a number no matter what format they are represented in. This usually only matters for Hex and Binary representations. Hex and Binary representations should start with a 0 followed by an 'x' or a 'b'. The following are examples of valid output patterns for all bits on:

Hex: 0xFFFFFF
Binary: 0b1111 1111 1111 1111 1111 1111
Integer: 16777215

    Notice how Hex and Binary begin with "0x" and "0b". The x or the b must be there otherwise the interpreter will fail while trying to program the board. Also notice that the binary output pattern contains white space. This is allowed. You may also use white space inside of hex values:

0x FF FF FF

The output pattern is read until a comma is reached. All white space is thrown away during the read.

Time Field

    The time field consists of two parts, time value and time units. Time value can be any decimal number. Time units must be one of four options:
s
 seconds
ms
 milliseconds
us
 microseconds
ns
 nanoseconds
*PulseBlaster ESR-Pro 400MHz users: please see special note here

Examples of valid time fields are as follows:

500 ms
500ms
500.0 ms
500.0ms
White space is permitted inside of a time field.

Command Field

The command field tells the board what to do after producing the output pattern for the given amount of time. Valid commands are as follows:

CONTINUE or continue - Continue to next instruction
STOP or stop - Stop execution
LOOP or loop - Beginning of a loop
END_LOOP or end_loop - End of a loop
JSR or jsr - Jump to a sub routine
RTS or rts - Return from a sub routine
BRANCH or branch - Branch
LONG_DELAY or long_delay - Long delay
WAIT* or wait - Wait for a trigger
The command field is optional. If no command field is listed, the CONTINUE command will be assumed.
For more information on these commands see the SpinAPI reference.

*Pleae note that WAIT cannot be placed at the top of the program and there should be at least one instruction execution time between the start of the program and WAIT.

Data Field

The data field is also optional unless a branch or jsr command is used during an instruction. In this case, the interpreter forces you to enter a label to jump to. The data field is used for different purposes depending on the command field. If no data field is specified, a value of 0 will be assumed. For more information see the SpinAPI reference.

Comments

Comments start with a // and the interpreter just throws anything after that on the line away. Comments may be on a line my themselves or placed after an instruction as follows:

// Valid comment on a line by itself.
Label: 0xFFFFFF, 100 ms // Valid comment after a valid instruction
0x000000, 100 ms, branch, Label // Another valid comment

There are several example programs available. Please take a look at these.

Interpreter Special Features

The interpreter provides some special features to make your life a little simpler when writing a
PulseBlaster program.

Stop

    Stop is the only command allowed to be on a line by itself. When a line is found containing only the word stop, a program line will be generated with a 0 output pattern and a length of 0 ms. Stop is special in PulseBlaster boards in that the output pattern and the time field are ignored. It is recommended that before issuing a Stop command your output pattern be set to 0. For instance:

0xFFFFFF, 100ms
STOP

This will result in all bits remaining on after the Stop command has been executed. We recommend doing the following:

0xFFFFFF, 100ms
0x000000, 100ms
STOP

This will ensure that all bits are off when program execution stops.

Loop Matching

The interpreter will do loop matching for you. Example:

0x000000, 100ms, LOOP, 3 // Loop 3 times
0xFFFFFF, 100ms, END_LOOP // Interpreter will match END_LOOP with the LOOP on the line above
Natural Language

Natural Language allows you to specify what bits to switch on for a given instruction. Begin the output field with "0n" and then you can specify which bits to switch on. Valid ranges are 0 thru 23, and each bit is seperated by a '+'. See the examples below.

0n 1 + 3, 500ms // Bits 1 and 3 on for 500ms
0n 2 + 4, 500ms // Bits 2 and 4 on for 500ms
0n 0 + 5, 500ms // Bits 0 and 5 on for 500ms
Variables
Variables allow you to change portions of your program with ease. Variables are denoted by a leading '$' and must be assigned a value
before they are used in your program. To assign a variable a value, type the name of the variable followed by an equal sign and the value you want to assign to that variable. For example:

$var = 1234 // Assign $var 1234

Assignments must be on a line by themselves. Once a variable has been assigned, it can be used anywhere in a program line. Variables can not be used to label lines. See the following example:

$output1 = 0xFFFFFF
$time1 = 100ms
$output2 = 0x000000
$time2 = 500ms

start: $output1, $time1 // Translates to: 0xFFFFFF, 100ms
       $output2, $time2, branch, start // Translates to: 0x000000, 500ms, branch, start
Variables are just replaced with the value they are assigned before program line values are parsed. They can also be changed once they are assigned a value.

$output = 0xFFFFFF // $output will be 0xFFFFFF after this point
$output, 100ms
$output = 0x000000 // $output will be 0x000000 after this point.
$output, 100ms

Command Line

The interpreter can also be used from the command line using spbicl.exe. This is only recommended for users who are familiar with the usage of a command line and need to use the interpreter from some other program. The usage of the command line program is as follows:

Usage: spbicl <command> [file] [frequency]
Commands:
Load = Load [file] into memory using [frequency]
Start = Start execution of program currently in memory
Stop = Stop execution of program currently running

Examples:

spbicl load file.pb 100.0 Load file.pb at 100 MHz
spbicl start Start program execution
spbicl stop Stop program execution
The return value of the program is 0 if success and -1 if an error occurs.

PulseBlaster ESR Pro Information

You can use the interpreter to program your PulseBlaster ESR Pro boards, but there are some things you need to know beforehand:

I.
For 400MHz PulseBlaster ESR Pro boards, the longest allowed instruciton length is 647ns.  For longer delays, please use the LONG_DELAY option in the command field.  For example, to generate a 744ns delay, use:

your_output_pattern_here, 372 ns, LONG_DELAY, 2


This will result in two 372ns delays being created, thus producing a 744ns total delay.

II.
PulseBlaster ESR Pro boards use the upper three bits of the output pattern to determine different aspects about the output pattern. For instance, if the upper three bits of the output pattern are set to 0s, no output pattern will occur during this instruction. An upper three bits of 001 tells the board to perform the output period for 1 period. You see, the board's minimum time value is 12.5 ns. You can use the upper three bits to go lower than this value.

000 - No output pattern.
001 - Output pattern for 1 period.
010 - Output pattern for 2 periods.
011 - Output pattern for 3 periods.
100 - Output pattern for 4 periods.
101 - Output pattern for 5 periods.
110 - Output pattern uses time value.
111 - Output pattern uses time value.

Example:

0b 1010 0000 0000 0000 0000 0001, 12.5 ns // Bit 0 will be on for 5 periods.
0b 1000 0000 0000 0000 0000 0010, 12.5 ns // Bit 1 will be on for 4 periods.
0b 1110 0000 0000 0000 0000 0100, 12.5 ns // Bit 2 will be on for 12.5 ns.

last modified 05/21/2009