ProgAddedum - IOCtls

Programming Guide and Reference Addendum
About this book DosDebug Commands Device Helper (DevHlp) Services and Function Codes Control Program Functions Raw File System APIs IOCtls Network APIs Windows Functions APIs Supporting High Memory Objects Notices

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation This chapter contains the following IOCtl commands.

Category	Function	Description
08h	69h	Logical Volume Management
80h	0Eh	Query HardDrive Geometry and Physical Parameters

Logical Volume Management DSK_LVMMGMT (69h)

Purpose

This IOCtl may be used with any logical volume to which a drive letter has been assigned. This function will be used by FORMAT and will also be of use to those writing disk utilities for OS/2.

Parameter Packet Format

Field	Length	C Datatype
Command Information	BYTE	UCHAR
Drive Unit	BYTE	UCHAR
Table Number	WORD	USHORT
LSN	4 BYTES	ULONG

Command Information

Command information may be:

• 0 Identify Volume Type
• 1 Enable Bad Block Relocation
• 2 Disable Bad Block Relocation
• 3 Get Bad Block Information
• 4 Get Table Size
• 5 Get Relocated Sector List
• 6 Get Relocated Data
• 7 Remove Relocation Table Entry
• 8 Clear Relocation Table
• 9 Get Drive Name

The Identify Volume Type command provides a way to determine whether a volume is a Compatibility or LVM Volume.

The Enable Bad Block Relocation command enables bad block relocation on the specified volume if that volume supports it.

The Disable Bad Block Relocation command disables bad block relocation on the specified volume.

Get Bad Block Information returns the total number of bad block relocations which are currently in effect for the specified volume, as well as the number of relocation tables being used to perform bad block relocation for the specified volume. There is one bad block relocation table per physical disk partition, so, for LVM volumes employing drive linking, there may be several such tables.

Get Table Size returns the number of active entries in the specified bad block relocation table, as well as the maximum number of entries that the table can hold. The size of a bad block relocation table is dependent upon the size of the partition it is supporting. Larger partitions have larger relocation tables, while smaller partitions have smaller relocation tables.

Get Relocated Sector List returns an array of Logical Sector Numbers (LSN). Each LSN in the array is a sector whose data had to be relocated because of a problem writing to that sector. The array returned is specific to a Relocation Table. The user-supplied buffer must be large enough to hold the entire array. The size of the array can be determined by using the Get Table Size command to find the number of active entries in the table, and then multiplying that value by the size of a Logical Sector Number (currently, 4 bytes).

Get Relocated Data returns the data associated with a sector that appears in a relocation table for the specified volume. The user-supplied buffer must be at least 512 bytes in length, because 512 bytes are returned.

Remove Relocation Table Entry removes the specified LSN from the relocation tables on the specified volume. This function is typically used by utilities which adjust the file system on a volume so that all LSNs requiring relocation are removed from use. Since the file system will never use these LSNs again, they can be safely removed from the relocation tables for the volume, thereby freeing those entries to be used again.

Clear Relocation Table is used to remove all of the entries in a relocation table in a single operation. This function is intended to be used by FORMAT immediately before a long format is performed. Typically, FORMAT will disable bad block relocation and clear the bad block relocation tables prior to a long format so that all bad sectors may be detected by FORMAT. FORMAT will place any bad sectors detected into the bad block list for the appropriate file system.

Get Drive Name is used to return the user-defined name associated with the physical drive on which the specified relocation table resides. This function can be used to identify which physical drive contains a specific relocation table associated with a volume. The name returned will not exceed 20 characters.

Drive Unit is used only when the IOCtl is issued without using a previously allocated file handle. In this case, the IOCtl must be issued with a file handle of 1. Drive Unit values are 0=A, 1=B, 2=C, etc.

Table Number is the number of the relocation table to operate on. This field is not used for commands 0, 3, and 6-8.

LSN is the logical sector number of the sector requiring relocation. This field is used only by commands 6 and 7.

Data Packet Format

Field	Length	C Datatype
Return Value	BYTE	UCHAR
Buffer	4 BYTEs	void*

Return Value

Return Value is set by every command that this IOCtl accepts. The specific meaning of the value it is set to is dependent upon the command issued.

Buffer

Buffer is a pointer to an area of memory large enough to hold any return value associated with the command issued. Some commands do not make use of Buffer. For these commands, Buffer should be NULL.

Values Returned

Command Information and possible return values are:

Command Information	Return Value	Buffer
0	1 = Compatibility V 2 = Logical Volume	Unused
1	0 = Success 1 = Failure	Unused
2	0 = Success 1 = Failure	Unused
3	0 = Success 1 = Failure	typedef struct_BadBlockInf ULONG Total_Relocations; ULONG Total_Tables; }BadBlockInfo;
4	0 = Success 1 = Failure	typedef struct_BadBlackInf ULONG Active_Relocations; ULONG Max_Relocations; }BadBlockTableInfo;
5	0 = Success 1 = Failure	Array of LSNs. Each entry in array is sector requiring relocatio
6	0 = Success 1 = Failure	Data written to specified sector
7	0 = Success 1 = Failure	Unused
8	0 = Success 1 = Failure	Unused
9	0 = Success 1 = Failure	Text of name being returned by this function. Name will be null terminat

Returns

Possible values are shown in the following list:

• 0 NO_ERROR
• 6 ERROR_INVALID_HANDLE
• 15 ERROR_INVALID_DRIVE
• 31 ERROR_GEN_FAILURE
• 87 ERROR_INVALID_PARAMETER

Query Hard Drive Geometry and Physical Parameters OEMHLP_QUERYDISKINFO (0Eh)

Purpose

This function returns geometry and physical parameters about the specified physical hard disk, if available. This information is acquired from BIOS via INT 13h function 48h at system boot.

Parameter Packet Format

Field	Length
Drive Number	BYTE

Drive Number

The BIOS drive number for which geometry and physical parameters are requested. The value must be 80h or greater.

Data Packet Format

Field	Length
Reserved	WORD
Information Flags	WORD
Number of Physical Cylinders	DWORD
Number of Physical Heads	DWORD
Number of Sectors Per Track	DWORD
Number of Physical Sectors	QWORD
Number of Bytes in a Sector	WORD
Reserved	DWORD
I/O Port Base Address	WORD
Control Port Address	WORD
Head Register Upper Nibble	BYTE
Reserved	BYTE
IRQ Information	BYTE
Block Count for ATA R/W Multiple	BYTE
DMA Information	BYTE
PIO Information	BYTE
BIOS Selected Hardware Option Flags	WORD
Reserved	WORD
DPT Extension Revision	BYTE

Information Flags

Bits are defined as follows:

• Bit 0: DMA boundary errors are handled transparently
• Bit 1: The geometry returned in bytes 4-15 is valid
• Bit 2: Media is removable. Bits 4-6 are not valid if this bit is 0
• Bit 3: Device supports write verify
• Bit 4: Device has media change notification
• Bit 5: Media is lockable
• Bit 6: Device geometry is set to maximum and no media is present when this bit is set to 1
• Bit 7-15: Reserved

Number of Physical Cylinders

The number of physical cylinders on the physical drive. This field is valid only if BIT 1 of the information flags is set to 1.

Number of Physical Heads

The number of physical heads on the physical drive. This field is valid only if BIT 1 of the information flags is set to 1.

Number of Sectors Per Track

The number of sectors per track on the physical drive. This field is valid only if BIT 1 of the information flags is set to 1.

Number of Physical Sectors

The number of physical sectors on the physical drive.

Number of Bytes in a Sector

The number of bytes per sector on the physical drive.

I/O Port Base Address

This word is the address of the data register in ATA Command Block.

Control Port Address

This word is the address of the ATA Control Block Register.

Head Register Upper Nibble

The upper nibble of this byte is logically ORed with the head number, or upper 4 bits of the LBA, each time the disk is accessed.

Bits are defined as follows:

• Bit 0-3: 0
• Bit 4: ATA DEV bit
• Bit 5: 1
• Bit 6: LBA enabled (1 = enabled)
• Bit 7: 1

IRQ Information

Bits are defined as follows:

• Bit 0-3: IRQ for this drive
• Bit 4-7: 0

Block Count for ATA R/W Multiple

If the hard disk was configured to use the READ/WRITE MULTIPLE command, then this field contains the block size of the transfer in sectors.

DMA Information

If the BIOS has configured the system to perform multi-word DMA transfers in place of the normal PIO transfers, this field specifies the DMA mode in the upper nibble, as per the ATA-2 or later definition, and the DMA Channel in the lower nibble. ATA Channels which conform to SFF-8038i set the DMA channel to 0. Note that the DMA Type field does not follow the format of the data returned by the drive. The value of the DMA mode is not limited to 2.

Bits are defined as follows:

• Bit 0-3: DMA Channel
• Bit 4-7: DMA Type

PIO Information

If the BIOS has configured the system to perform PIO data transfers other than mode 0, this field specifies the PIO mode as per the ATA-2 or later definition.

Bits are defined as follows:

• Bit 0-3: PIO Type
• Bit 4-7: 0

BIOS Selected Hardware Option Flags

Bits are defined as follows:

• Bit 0: Fast PIO accessing enabled
• Bit 1: DMA accessing enabled
• Bit 2: ATA READ/WRITE MULTIPLE accessing enabled
• Bit 3: CHS translation enabled
• Bit 4: LBA translation enabled
• Bit 5: Removable media
• Bit 6: ATAPI device
• Bit 7: 32-bit transfer mode
• Bit 8: ATAPI device uses command packet interrupt
• Bit 9-10: Translation type
  • 00: Bit-shift translation
  • 01: LBA assisted translation
  • 10: Reserved
  • 11: Vendor-specific translation
• Bit 11: Ultra DMA accessing enabled
• Bit 12-15: Reserved

DPT Extension Revision

Revision of DPT Extension provided by BIOS.

Returns

Possible values are shown in the following list:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER

Remarks

Information in the data packet will be filled in, if BIOS supports INT 13h Function 48h and if BIOS can access the entire hardfile through INT 13h Function 42h and Function 43h. If either condition is not met, all fields in the data packet will be 0.