Understanding the DDF file

1. Device Descriptor File Overview
   1.1 The DEVICE Block
   1.2 The REGISTER Block
   1.3 The MEMORY Block
   1.4 SPI Specific MEMORY Tokens
   1.5 Example Device Descriptor File

1. Device Descriptor File Overview
The Device Descriptor File (DDF) is an ASCII text file that completely describes the registers and memory locations present in a particular device. It also specifies the protocol that is used to communicate with the device (e.g. I2C, MDIO, or SPI). All of the DDF files are located in the Devices subdirectory. When the PC-I2C software is started, all of the DDF files are read and the information is used to generate the supported Bus Protocol and Device lists in the PC-I2C software. In order to add support for new devices to the PC-I2C software, a new DDF file must be created and placed in the Devices subdirectory. This new device will show up in the supported device list the next time the PC-I2C software is started.

The DDF file consists of identifier tokens followed by their corresponding values. The identifier tokens are grouped into one of three different descriptor blocks. These blocks are the Device Block, the Register Block, and the Memory Block. There must be a single Device Block as the first descriptor block in the file. The Device block is then followed by one or more Register Blocks and possibly a single memory Block. The format of these blocks can vary depending on the type of bus protocol used to communicate with the device. These differences are notes in the sections below. Note that all tokens are enclosed in square brackets [] and the values can be a HEX value (preceded by 0x), a decimal value, or an ASCII string enclosed by double quotes.

Comments can be added to the DDF file by starting a line with two forward slashes (//). The DDF 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.

1.1 [DEVICE]
The DEVICE Block must be the first descriptor block encountered in the DDF file. It is used to define the basic characteristics of the device. These characteristics include the Device Name, the Device Description, the Device Type, and the valid Base Addresses of the device. There can be only one DEVICE Block in the DDF file.

1.1.1 [NAME]
The [NAME] token is used to define the name of the device. The ASCII string following this token will be displayed in the Device list of the PC-I2C software. This string can be up to 64 characters long and can include spaces and other special characters.

1.1.2 [DESC]
The [DESC] token is used to define a description of the device. The ASCII string following this token will be displayed below the Device list of the PC-I2C software when this device is selected. This string can be up to 64 characters long and can include spaces and other special characters.

1.1.3 [TYPE]
The [TYPE] token is used to define the bus interface protocol for this device. The ASCII string following this token will determine the bus protocol. The currently supported values are:

• I2C – This token defines a standard I2C device
• MDIO_22 – This token defines an MDIO device that adheres to IEEE 802.3 Clause 22 (old MDIO)
• MDIO_45 – This token defines an MDIO device that adheres to IEEE 802.3ae Clause 45 (10G MDIO)

1.1.4 [CS POLARITY]
The [CS POLARITY] token is used to define the value held at CS when a command is being sent for the SPI protocol. This value is ignored for all other protocols. The currently supported values are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.
• None, N/A                – This token defines the CS line as unnecessary.

1.1.5 [ADDR]
The [ADDR] token is used to define the address(es) associated with this device. Its meaning changes depending on the value of the TYPE token as follows:

• I2C – The values listed after the token are the valid Slave addresses for this device. If more than one Slave address is defined, the values are separated by commas.
• MDIO_22 – The value listed after the token is the 5 bit address of the PHY to be accessed.
• MDIO_45 – This address is the two 5 bit addresses used to address the MMD.
• SPI – Not applicable.

1.1.6 An Example Device Block
The following example is for a Philips Semiconductor PCF8582C EEPROM device. It is an I2C device with 8 possible Slave addresses.

1.2 [REGISTER]
The REGISTER block is used to define the characteristics of a single register within a device. These characteristics include the Register Name, the Register Address, the Register Size, and the Register Type. There can be as many REGISTER Blocks as needed, in the DDF file, to fully describe every register in the device.

1.2.1 [REG NAME]
The [REG NAME] token is used to define the name of the register. The ASCII string following this token will be displayed in the register list of the PC-I2C Register Dialog. This string can be up to 64 characters long.

1.2.2 [REG ADDR]
The [REG ADDR] token is used to define the address of the register. The value following this token will be displayed along with the register name in the register list of the PC-I2C Register Dialog. This is the value that will be used as the address for reading and writing to this particular register. If the register has no address (i.e. there is only one register that can be read), then N/A should be entered for this value. (See the PCF8574A.DDF for an example.)

1.2.3 [REG SIZE]
The [REG SIZE] token is used to define the data size of the register. The value following this token is the data size in bytes for this register. A value of 0x01 would correspond to an 8 bit register, a value of 0x02 would correspond to a 16 bit register, etc.

1.2.4 [REG TYPE]
The [REG TYPE] token is used to define the access type of the register. The ASCII string following this token will determine the access type. The currently supported values are:

• RW – The register can be both read and written. Both the ‘R’ and ‘W’ buttons for this register will be enabled.
• RO – The register can only be read. The ‘R’ button will be enabled and the ‘W’ button will be disabled for this register.
• WO – The register can only be written. The ‘W’ button will be enabled and the ‘R’ button will be disabled for this register.
• RSV – The register is a “Reserved” register. Both the ‘R’ and ‘W’ buttons for this register will be enabled. Also, if the “Display Reserved Registers” option is not selected on the PC-I2C main window, all registers with a type of RSV will be hidden.

1.2.5 An Example Register Block
The following example is for the Control/Status register of the Philips Semiconductor PCF8583 Clock/Calendar chip. The register is 8 bits wide and is a read/write register.

1.3 [MEMORY]
The MEMORY block is used to define the characteristics of a memory array within a device. These characteristics include the Memory Block Name, the Memory Base Address, the Memory Size, the Memory Type, the Page Write Size, and the Write Delay time. There can be only one MEMORY Block per DDF file.

1.3.1 [MEM NAME]
The [MEM NAME] token is used to define the name of the memory block. The ASCII string following this token will be displayed in the tab of the PC-I2C Memory Dialog. This string can be up to 64 characters long and can include spaces and other special characters.

1.3.2 [MEM ADDR]
The [MEM ADDR] token is used to define the base address of the memory block. The value following this token will be used as the start of the memory block and will be the first address displayed when the Memory Dialog is opened.

1.3.3 [MEM SIZE]
The [MEM SIZE] token is used to define the size (in bytes) of the memory block. The value following this token will be used to determine the amount of memory that can be displayed and modified.

1.3.4 [MEM WIDTH]
The [MEM WIDTH] token is used to define the width (in bytes) of the memory word. The value following this token will be used to determine the method to be used when reading or writing to memory. If this value is more than 1, then the entire memory array will be used for all read, write, and erase operations. Memory is only displayed in bytes.

1.3.5 [MEM TYPE]
The [MEM TYPE] token is used to define the access type of the memory block. The ASCII string following this token will determine the access type. The currently supported values are:

• RW – The memory block can be both read and written.
• RO – The memory block can only be read.

1.3.6 [MEM PAGE]
The [MEM PAGE] token is used to define the page write size for the memory block. The value following this token determines the number of bytes that can be written to memory block in a single instruction. This value is only relevant for EEPROM/FLASH type devices that utilize the page write mode. For other devices, this value can be set to the memory block size.

1.3.7 [MEM WDLY]
The [MEM WDLY] token is used to define the write delay for the memory block. The value following this token determines the amount of time (in ms) to delay after a write instruction, before the next access occurs. This prevents the overlap of operations due to excessive write times for some devices.

1.3.8 An Example Memory Block
The following example is for a Philips Semiconductor PCF8583 Clock/Calendar chip with 240 bytes or SRAM (running from address 0x10 to 0xff). The page write is set to 8 bytes and the write delay is set to 1ms. 
 

1.4 SPI Specific [MEMORY] Tokens

 These [MEMORY] Tokens are used in the DDF file for SPI only. SPI support is limited to memory devices at this time.

1.4.1 [MEM POSTWCLK]

The [MEM POSTWCLK] token is used to define the number of clocks to wait for a response after completing a write or erase command. The CS line is toggled and when the DIN line matches the value specified by [MEM POSTWPOL], PC-I2C will toggle the CS line and move on to the next command.

1.4.2 [ MEM POSTWPOL]

The [MEM POSTWPOL] token is used to define the value on the DIN line that signifies that the target device is finished writing or erasing.

1.4.3 [ MEM ENWIDTH]

The [MEM ENWIDTH] token is used to define the size (in bits) of the target device’s Enable Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM ENABLE] token.

1.4.4 [MEM ENABLE]

The [MEM ENABLE] token is used to define the command that allows writing to and erasing from the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1 – The current bit is a logic 1.
• Low, Zero, 0 – The current bit is a logic 0.

1.4.5 [MEM DISWIDTH]

The [MEM DISWIDTH] token is used to define the size (in bits) of the target device’s Disable Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM DISABLE] token.

1.4.6 [MEM DISABLE]

The [MEM DISABLE] token is used to define the command that disallows writing to and erasing from the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.

1.4.7 [MEM WWIDTH]

The [MEM WWIDTH] token is used to define the size (in bits) of the target device’s Write Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM WCOM] token.

1.4.8 [MEM WCOM]

The [MEM WCOM] token is used to define the command that writes to the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.
• A#                              – The current bit is address bit # (starting with address bit 0).
• D#                              – The current bit is data bit # (starting with data bit 0).

1.4.9 [MEM RWIDTH]

The [MEM RWIDTH] token is used to define the size (in bits) of the target device’s Read Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM RCOM] token.

1.4.10 [MEM RCOM]

The [MEM RCOM] token is used to define the command that reads from the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.
• A#                            – The current bit is address bit # (starting with address bit 0).
• D#                            – The current bit is data bit # (starting with data bit 0).

1.4.11 [MEM EWIDTH]

The [MEM EWIDTH] token is used to define the size (in bits) of the target device’s Erase Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM ECOM] token.

1.4.12 [MEM ECOM]

The [MEM ECOM] token is used to define the command that erases from the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.
• A#                            – The current bit is address bit # (starting with address bit 0).

1.4.13 [MEM ERALWIDTH]

The [MEM ERALWIDTH] token is used to define the size (in bits) of the target device’s Erase All Command. The value following this token will be used to determine the width of the command. This token also determines the number of entries allowed in the [MEM ERAL] token.

1.4.14 [MEM ERAL]

The [MEM ERAL] token is used to define the command that erases all of the device. The ASCII string following this token will determine the command. The currently supported values for each bit are:

• High, One, 1            – The current bit is a logic 1.
• Low, Zero, 0            – The current bit is a logic 0.

1.4.15 An Example SPI Memory Block

The following example is for a Atmel AT93C46A EEPROM chip with 128 bytes (running from address 0x00 to 0x7f). The page write is set to 8 bytes and the write delay is set to 1ms.

1.5 Example Device Descriptor File
The following example is the entire DDF file for the Philips Semiconductor PCF8583 Clock/Calendar Chip with 240 bytes of SRAM. It demonstrates all three types of Descriptor Blocks.
  
// PCF8583.ddf  
//  
// This is the device definition file (DDF) for the Philips  
// Semiconductor PCF8583 I2C Clock Calendar Chip with 240 x 8 RAM.  
// 

Copyright © 1997-2008, Future Designs, Inc. All rights reserved.
Send all questions and comments regarding this site to: