Display Tuple Utility
DTPL.EXE is a tool designed for interpreting the tuples on a PC Card.
This tool is intended to help you design or verify card information structure (CIS) for use with future Microsoft implementations of PCMCIA support in the Microsoft® Windows®95 operating system. For more information on these implementations, see the Windows 95 DDK.
DTPL runs in real mode on MS-DOS® using real-mode Card Services and Socket Services implementations. It is intended to be run on PC Cards that have not been configured by a Card Services client or enabler. Therefore, Card Services clients and PC Card enablers should not be loaded or active when using this tool.
This tool displays information derived from the tuples on the PC Card. This includes the Plug and Play device ID, the Plug and Play logical configurations, and a display of each tuple on the card.
Usage:
DTPL [-d[c] [# Bytes]] [-f filename] [-a] [-i] [-l] [-r] [-t] [Socket#]
Display tuple data for PC Cards.
-a Displays the alternate Plug and Play device IDs for the PC Card.
-d Displays attribute memory bytes.
-dc Displays common memory bytes.
# Bytes Displays an optional number of memory bytes; otherwise, 256 bytes will be displayed.
-f Defines a filename to take the tuple input from instead of calling Card Services.
-i Displays the Plug and Play device IDs for the PC Card.
-l Displays the Plug and Play logical configurations for the PC Card.
-r Displays raw tuple data bytes, formatted for input file.
-t Displays all the tuples on the PC Card.
Socket# Displays an optional socket; otherwise, all sockets will be displayed.
The -f option allows the tuple input to be taken from a file. This allows tuples to be interpreted without the need for a real-mode Card Servicesdriver and also allows tuples to be tested before they are placed on a PC Card.
The tuples in this file must be defined in an ASCII HEX format. Each hex value must have two digits. The parser for this is very simple.
Comments can be placed in the tuple file using a semicolon (;) character.
For example, the following tuple is a configuration entry tuple for a COM port.
; This is a COM1 port
1B 11 ; Config entry and link values.
E0 01 1D 48 D5 02 1D FC
14 A0 60 F8 03 07 30 3C 00The optional Socket# is ignored when the -f option is used, and the socket for the tuples will be set to 0xFF.
The -i option displays the Plug and Play device ID for the PC Card. The Plug and Play device ID is the ID that will be generated by the PCMCIA bus enumerator for the device and used by the Plug and Play system. This ID should be used when generating the INF file for a device.
The device ID is created from the manufacturer name string, the product name string, and a 16-bit CRC of a set of tuples. The ID is created by concatinating the PCMCIA prefix, the manufacturer name string, the product name string, and a 16-bit CRC. The device ID has the following format:
PCMCIA\Manuf_name-Prod_name-Crc
The Manuf_name and Prod_name are obtained from the CISTPL_VERS_1 tuple. If the CISTPL_VERS_1 tuple is not available or if the manufacturer name is NULL, then the string UNKNOWN_MANUFACTURER will be included in its place.
The CRC will be created from the following tuple data.
CISTPL_DEVICE
CISTPL_VERS_1
CISTPL_CONFIG
CISTPL_CFTABLE_ENTRY
CISTPL_MANFIDOnly the first two strings in the CISTPL_VERS_1 tuple -- the manufacturer name string and the product name string -- are included in the CRC. This is because serial numbers are occasionally placed in the additional strings of this tuple. These serial numbers would cause the CRC to be different for each card even though they are the same.
The tuples are not parsed during this CRC computation to determine the length, so the link value is used as the length of each tuple's data to include in the CRC. The length is reduced if the configuration registers are located in the address range skipped by the link. The offset of the configuration registers is determined from the CISTPL_CONFIG tuple. The offset of each tuple and its existence in attribute memory is determined from the Card Services flags and CIS offset values in the GetTupleData packet. Since these fields are implementation-specific in Card Services, this check is not done in this DTPL tool. As a result, the CRC value created by DTPL may differ from that created by Windows. This rarely occurs; however, the ID created by Windows should be used if they differ.
The total length of the device ID string is limited to 128 characters, including the null terminator. The manufacturer and product name will be truncated to maintain this length restriction in the ID string.
The characters in the manufacturer and product name strings that are greater than or equal to a space (0x20) or less than (0x7F) will be copied into the name string. Any other characters outside this range will be skipped. This makes it easier to include these characters in the INF files for the device.
Spaces and commas in the device ID will be converted to underscores (_).
The -a option displays the alternate Plug and Play device ID for the PC Card. An alternate device ID is created that contains the manufacturer ID values in place of the CRC. This alternate device ID has the following format:
PCMCIA\Manuf_name-Prod_name-Manf-Card
The Manuf_name and Prod_name are the same as defined in the original device ID. The Manf and Card values are obtained from the CISTPL_MANFID tuple and are displayed as two 16-bit hex values.
The purpose of the alternate ID is to allow card manufacturers to modify the configuration tuples on the card without changing the device ID for the card. This will allow the same INF file to be used for cards with minor updates. Any time the card is modified in such a way that the INF file would require changes, the card portion of the manufacturer ID must be changed.
For more information on the use of this alternate device ID, see PC Card Standard and Windows 95: A Developer's Update on www.microsoft.com.
The -l option displays the Plug and Play logical configurations for the PC Card. The Plug and Play logical configurations are generated by the PCMCIA bus enumerator from the configuration and configuration entry tuples. The display of these configurations is intended to provide some feedback on the interpretation of the configuration tuples on the PC Card. The logical configuration will be used by the Plug and Play configuration manager to determine the configuration for the PC Card. The information displayed includes I/O, IRQ, and memory resource data, along with the contents of a Card Services RequestConfiguration argument structure.
The -r option displays each tuple as its raw data bytes. This is in a format that can be easily edited and used with the DTPL tool as an input file using the -f option. Notice that any strings that are not data bytes must be commented out with a semicolon (;) or removed from the input file.
The -t option displays each tuple in a more readable format. Many of the tuples are interpreted and displayed in an expanded form. For example, this is done for the configuration entry tuples, which are difficult to understand without such expansion. Following the expanded information for each tuple is a dump of the tuple data bytes in an ASCII HEX format, followed by an ASCII dump of each byte in the tuple. Non-printable bytes are diplayed as a period (.) in the ASCII dump. Tuples that are not expanded are displayed in an ASCII HEX format only.
Note: This tool has been tested using the SystemSoft and Phoenix Card Services drivers. If it fails to work on other Card Services implementations, try using the -f option, which reads the tuple data from a file.
Changes in current version (Version 6.02.26):
- Added alternate device ID and multifunction child device ID.
- Added multifunction logical configurations and tuple dumps.
- Added display of custom interface ID from the CISTPL_CONF tuple.
- Added support for access to indirect tuple memory.
|
|