Understanding the SDF

Understanding the SDF file

1. Sequence Descriptor File Overview.
2. Sequence Descriptor File Tokens.

1. Sequence Descriptor File Overview
The Sequence Description File (SDF) is an ASCII text file that describes the sequence of instructions that the user intends to send to the I2C or MDIO bus in a high speed environment. All of the SDF files are located in the Sequence subdirectory. When the USB-MPC software is started, all of the SDF files are read and the information is used to generate the supported Sequence list in the USB-MPC software. In order to add a sequence to the USB-MPC software, a new SDF file must be created and placed in the Sequence subdirectory. This new device will show up in the supported device list the next time the USB-MPC software is started.

The SDF file consists of instruction tokens followed by their corresponding values. Four description instructions are required and the file parser will ignore any sequence files without one of each. Note that all tokens are followed by at least one space or tab and the values can be a HEX value (preceded by 0x), a decimal value (with a leading 0), or an ASCII string enclosed by double quotes. Instruction lines must be limited to 255 characters total.

Comments can be added to the SDF file by starting a line with two forward slashes (//). The SDF file parser will ignore any lines that start with the comment characters. A comment is required on the first line in order to ensure that a text editor was used.

2. Sequence Descriptor File Tokens
The following section contains all of the valid tokens used in a Sequence Descriptor File. A short description follows an example of each.
Note: While specific positions of the NAME, DESC, USE, and ADDR tokens are not required, it is suggested that they occur as the first four instructions in order to minimize confusion.

2.1 NAME Token

NAME	“ASCII string representing the name of the Sequence ”

The NAME token is used to set the name that will be displayed within the Sequence list in USB-MPC. The only character that cannot be used within the quotation marks is another quotation mark. This is a required token.

2.2 DESC Token

DESC	“ASCII string representing the description of the Sequence”

The DESC token is used to set the description that will be displayed when this Sequence’s name is chosen in the Sequence list in USB-MPC. The only character that cannot be used within the quotation marks is another quotation mark. This is a required token.

2.3 USE Token

USE	“The DDF file being used for this Sequence”

The USE token is used to set the name of the DDF file that will be used when running this Sequence in USB-MPC. The characters that cannot be used within the quotation marks are another quotation mark and any character which cannot be used in file naming. This is a required token.

2.4 ADDR Token

ADDR	0xFF	0x1F
ADDR	0255

The ADDR token is used to set the address of the specific device that will be used when running this Sequence in USB-MPC. This token requires input of one address for I2C and MDIO 22, and the port address followed by the device address for MDIO 45. This is a required token.

2.5 READ Token

READ	MEM[0xFF]	DISPLAY(“Heading=”)
READ	REG[0255]	LOG(“Heading=”)

The READ token reads the specified memory(MEM) or register(REG) and displays(DISPLAY) the value or logs(LOG) it to a “.log” file with the same name as the Sequence Descriptor File and a “-##” added to the name. This was chosen in order to preserve previously logged files. The register is specified by the register number in the .ddf file while the memory is specified by the address which is to be accessed. The quotation marks can be filled with whatever the user would like to appear in front of the output value. This will always be preceded by “Line #:” and two tabs where # is the line number. The base, hex or decimal, used for specifying the register or memory specifies the base of the output. Again, the total output size, including line number, cannot exceed 255 characters.

2.6 WRITE Token

WRITE	MEM[0xFF]	0255
WRITE	REG[0255]	0xFF

The WRITE token writes the specified data, represented in hex or decimal, to the specified memory(MEM) or register(REG). The register is specified by the register number in the .ddf file while the memory is specified by the address which is to be accessed. This particular action is followed by an automatic delay of 100 milliseconds.

2.7 PAUSE Token

PAUSE	00
PAUSE	016777216
PAUSE	0x1000000

The PAUSE token signifies that the sequencer should pause execution for the specified length of time. Indefinite or user ended pauses are signified by a value of zero (00). The value entered after the PAUSE token must not exceed 0x1000000.

2.8 START_LOOP Token

START_LOOP
START_LOOP	032767
START_LOOP	0x7FFF

The START_LOOP token signifies that the next line is the beginning of a loop which will run a number of times equal to the value following the START_LOOP token. Infinite loops are signified by the absence of a value, but a warning will pop up on loading USB-MPC. If both tokens, START_LOOP and END_LOOP, specify a value for the number of loops, the value at START_LOOP takes precedence. The value entered after the START_LOOP token must not exceed 0x7FFF.

2.9 END_LOOP Token

END_LOOP
END_LOOP	032767
END_LOOP	0x7FFF

The END_LOOP token signifies the end of a loop which will run a number of times equal to the value following the END_LOOP token. Infinite loops are signified by the absence of a value, but a warning will pop up on loading USB-MPC. On an infinite loop, a dialog will pop up every 10,000 loops asking whether or not to continue looping. If “No” is chosen, the sequencer will continue past the END_LOOP token. If both tokens, START_LOOP and END_LOOP, specify a value for the number of loops, the value at START_LOOP takes precedence. The value entered after the END_LOOP token must not exceed 0x7FFF.

2.10 Example Sequence Descriptor File

The following example is the entire file “Sequencer Demo.sdf” which uses the PCF8582C included with USB-MPC KIT to demonstrate all the commands that can be used in the sequencer.

// This is a test file for testing the sequencer

//This instruction specifies the label to be displayed in the "Sequence:" combo box in USB-MPC
NAME "Demonstration"

//This instruction specifies the description to be displayed when this sequence is selected in the "Sequence:" combo box
DESC "This is a test file for demonstrating the sequencer."

//This instruction specifies the DDF (Device Descriptor File) to be used
USE "PCF8582C.ddf"

//This instruction specifies the address of the device to be used
ADDR 0xA8

//This instruction specifies a read from memory address 0x01 to be displayed to the screen with the message "Memory at address 0x01 is"
READ MEM[0x01] DISPLAY("Memory at address 0x01 is")

//This instruction specifies a write to memory address 0x05 of a value of 0x01
WRITE MEM[0x05] 0x01

//This instruction specifies a pause for at least 598 milliseconds.
PAUSE 0598

//This instruction specifies a read from memory address 0x05 to be logged to the log file with the message "But the memory located at 0x05 is"
READ MEM[0x05] LOG("But the memory located at 0x05 is")

//This instruction specifies the start of a loop with 25 iterations
START_LOOP 25

//This instruction specifies a read from memory address 0x01 to be logged to the log file with the message "Can the Memory at 0x01 be represented in decimal like this?=>"
READ MEM[01] LOG("Can the Memory at 0x01 be represented in decimal like this?=>")

//This instruction specifies the end of a loop
END_LOOP

//This instruction specifies the start of a loop
START_LOOP

//This instruction specifies a read from memory address 0x05 to be logged to the log file with the message "Type anything you want here. Anything at all. As long as you don't exceed a total instruction length of 256 characters."
READ MEM[0x05] LOG("Type anything you want here. Anything at all. As long as you don't exceed a total instruction length of 256 characters.")

//This instruction specifies the end of a loop with 5 iterations
END_LOOP 5

//This instruction specifies the start of a loop with 25 iterations
START_LOOP 25

//This instruction specifies a write to memory address 0x15 of a value of 0x01
WRITE MEM[21] 0x01

//This instruction specifies a read from memory address 0x15 to be logged to the log file with the message "MemoryCheck="
READ MEM[0x15] LOG("MemoryCheck=")

//This instruction specifies a read from memory address 0x15 to be logged to the log file with the message "MemoryCheck="
READ MEM[21] LOG("MemoryCheck=")

//This instruction specifies the end of a loop with 4 iterations but is overidden by the Start_Loop command's number of iterations
END_LOOP 4