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, MDIO, or SPI bus in a high speed environment. All of the SDF files are located in the Sequence subdirectory. When the PC-I2C software is started, all of the SDF files are read and the information is used to generate the supported Sequence list in the PC-I2C software. In order to add a sequence to the PC-I2C 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 PC-I2C 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 PC-I2C. 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 PC-I2C. 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 PC-I2C. 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 PC-I2C. 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. With SPI, the MEM token specifies byte addressing and the REG token specifies word addressing. This is only applicable when the Memory Width is greater than 1.
2.5 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.6 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.7 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 PC-I2C. 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.8 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 PC-I2C. 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.9 Example Sequence Descriptor File
The following example is the entire file “Sequencer Demo.sdf” which uses the PCF8582C included with PC-I2C-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 PC-I2C
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