4.4 Serial I/O Control Codes

The following summarizes the I/O control codes handled by serial drivers.

IOCTL_SERIAL_GET_STATS

Operation

Returns the current values of the performance statistics for the device. The statistics include the number of characters transmitted, the number of characters received, and various errors. The values increase until they are explicitly reset with SERIAL_IOCTL_CLEAR_STATS.

If a driver does not implement this IOCTL, it should return an error and not modify the output buffer. If the modem driver is involved in processing the I/O, it will adjust the return value from error to success but only return zeros for the counter values.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIALPERF_STATS).

Output

The driver returns data to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIALPERF_STATS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero if the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_CLEAR_STATS

Operation

Resets the performance statistics for the device.

Input

None.

Output

None

I/O Status Block

The Information field is set to zero and the Status field is set to STATUS_SUCCESS.

IOCTL_SERIAL_GET_PROPERTIES

Operation

Returns information about the characteristics of the attached communication device.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_COMMPROP).

Output

The driver returns the information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_COMMPROP) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_GET_MODEMSTATUS

Operation

Returns a bitmask indicating the status.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).

Output

The driver returns the bitmask to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_GET_COMMSTATUS

Operation

Returns general status information, including how many Errors and HoldReasons have occurred, how much data is in the driver’s buffers as indicated by the AmountInInQueue and AmountInOutQueue values, and whether EofReceived and WaitForImmediate are set.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_STATUS).

Output

The driver returns information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_STATUS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_RESET_DEVICE

Operation

Sets the device to a known state.

Input

None

Output

None

I/O Status Block

The Status field is set to STATUS_SUCCESS and the Information field is set to zero.

IOCTL_SERIAL_PURGE

Operation

Purges the specified operation(s) or queues: one or more of the current and all pending writes, the current and all pending reads, the transmit buffer if one exists, and the receive buffer if one exists.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains a bitmask of type ULONG, indicating what to purge.

Output

None

I/O Status Block

The Information field is set to zero, and the Status field is set to STATUS_SUCCESS or possibly to STATUS_PENDING, STATUS_CANCELLED, or STATUS_INVALID_PARAMETER.

IOCTL_SERIAL_LSRMST_INSERT

Operation

Enables or disables insertion of the line status or modem status into the RX stream at the behest of a user-mode application.While this state is enabled, the serial driver inserts the caller-supplied escape character, together with one of the following, into the data stream being read from the device:

• SERIAL_LSRMST_LSR_DATA, indicating that a line-status change occurred. Immediately following this, the driver inserts the value of the line status register and the character present in the receive hardware when the line-status change was processed.

• SERIAL_LSRMST_LSR_NODATA, indicating that a line-status change occurred but that no data was available in the receive buffer. Immediately following this, the driver inserts the value of the line status register when the line-status change was processed.

• SERIAL_LSRMST_MST, indicating that a modem-status change occurred. Immediately following this, the driver inserts the value of the modem status register when the modem-status change was processed.

• SERIAL_LSRMST_ESCAPE, indicating that the next character in the stream, which was received from the device, is identical to the caller-supplied escape character.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains a value of type UCHAR, indicating whether to enable LSRMST-insertion mode. A value of zero indicates the driver should disable LSRMST-insertion mode. A nonzero value is the caller-supplied escape character.

Output

None

I/O Status Block

The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER if the input escape character is the same as the current XOFF or XON character, or if handflow error replacement is enabled.

IOCTL_SERIAL_GET_BAUD_RATE

Operation

Returns the current baud-rate setting.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_BAUD_RATE).

Output

The driver returns the data to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_BAUD_RATE) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_BAUD_RATE

Operation

Sets the speed at which characters are sent over the serial line.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_BAUD_RATE)) of the buffer at
Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_INVALID_PARAMETER or STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_QUEUE_SIZE

Operation

Resizes the driver’s internal typeahead and input buffers. The driver can allocate buffers larger than the requested sizes and can refuse to allocate buffers larger than its capacity.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_QUEUE_SIZE)) of the buffer at Irp->AssociatedIrp.SystemBuffer, containing the InSize and OutSize specifications.

Output

None

I/O Status Block

The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INSUFFICIENT_RESOURCES if the driver cannot satisfy the request by allocating more memory.

IOCTL_SERIAL_GET_HANDFLOW

Operation

Returns the current values for the flow control and handshaking.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_HANDFLOW).

Output

The driver returns the information to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_HANDFLOW) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_HANDFLOW

Operation

Sets up flow control and handshaking for subsequent operations.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_HANDFLOW)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the values to be set.

Output

None

I/O Status Block

The Information field is set to zero, and the Status field can be set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER.

IOCTL_SERIAL_GET_LINE_CONTROL

Operation

Returns the current values of the stop-bits, parity, and word-length parameters for the device.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_LINE_CONTROL).

Output

The driver returns data to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_LINE_CONTROL) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero if the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_LINE_CONTROL

Operation

Resets the stop-bits, parity, and word-length parameters for the device.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_LINE_CONTROL)) of the buffer at Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER.

IOCTL_SERIAL_SET_BREAK_ON

Operation

Causes a break condition to be transmitted by the UART.

Input

None

Output

None

I/O Status Block

The Status field is set to STATUS_SUCCESS and the Information field is set to zero.

IOCTL_SERIAL_SET_BREAK_OFF

Operation

Disables the transmission of break conditions by the UART.

Input

None

Output

None

I/O Status Block

The Status field is set to STATUS_SUCCESS and the Information field is set to zero.

IOCTL_SERIAL_GET_TIMEOUTS

Operation

Returns the current settings for read and write time-outs on the device.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_TIMEOUTS).

Output

The driver returns information to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_TIMEOUTS) when the Status field is set to STATUS_SUCCESS. The Information field is set to zero when the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_TIMEOUTS

Operation

Sets up time-out constraints for serial I/O operations.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_TIMEOUTS)) of the buffer at Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_IMMEDIATE_CHAR

Operation

Causes a single character to be transmitted as soon as the hardware is available.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the character to be sent. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(UCHAR).

Output

None

I/O Status Block

The Information field is set to one when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING, STATUS_CANCELLED, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER if another immediate character is already pending.

IOCTL_SERIAL_XOFF_COUNTER

Operation

Sends the specified XOFF character, sets up a timer to track the specified time-out value, and decrements the supplied count of characters for each subsequently written character until the count goes to zero or a time-out occurs. This IOCTL supports software emulation of the serial chip in certain protected subsystems.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_XOFF_COUNTER)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the data.

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS (all requested characters written) or possibly to STATUS_SERIAL_MORE_WRITES, STATUS_SERIAL_COUNTER_TIMEOUT, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER if the XoffChar specified is inconsistent with the current flow-control specification.

IOCTL_SERIAL_SET_DTR

Operation

Sets DTR (data terminal ready).

Input

None

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.

IOCTL_SERIAL_CLR_DTR

Operation

Clears DTR.

Input

None

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.

IOCTL_SERIAL_SET_RTS

Operation

Sets RTS (request to send).

Input

None

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.

IOCTL_SERIAL_CLR_RTS

Operation

Clears RTS.

Input

None

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.

IOCTL_SERIAL_GET_DTRRTS

Operation

Returns the state of the DTR and RTS lines at the time this request is processed.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).

Output

The driver returns information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. The Information field is set to zero when the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_XON

Operation

Enables emulation of receipt of characters, which the serial driver might already have in its internal buffers.

Input

None

Output

None

I/O Status Block

The Status field is set to STATUS_SUCCESS and the Information field is set to zero.

IOCTL_SERIAL_SET_XOFF

Operation

Disables emulation of receipt of characters.

Input

None

Output

None

I/O Status Block

The Status field is set to STATUS_SUCCESS and the Information field is set to zero.

IOCTL_SERIAL_GET_WAIT_MASK

Operation

Returns the current value of the event wait mask.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).

Output

The driver returns the information to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING, STATUS_CANCELLED, or STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_WAIT_MASK

Operation

Causes the driver to track the specified events, or, if the specified value is zero, to complete pending waits.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(ULONG)) of the bitmask at Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_PENDING, STATUS_CANCELLED, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER.

IOCTL_SERIAL_WAIT_ON_MASK

Operation

Returns information about which events have occurred among those that the caller was waiting on.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes (must be >= sizeof(ULONG)) of the buffer.

Output

The driver returns a bitmask with bits set for events that occurred (or with a value of zero if the preceding set-waitmask request specified zero) to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING or STATUS_INVALID_PARAMETER if a wait is already pending.

IOCTL_SERIAL_GET_CHARS

Operation

Returns the current values for the special characters used by the driver.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_CHARS).

Output

The driver returns the information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to sizeof(SERIAL_CHARS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_SERIAL_SET_CHARS

Operation

Sets special characters (EofChar, ErrorChar, BreakChar, EventChar, XonChar, and XoffChar) used by the driver.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_CHARS)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the values to the used.

Output

None

I/O Status Block

The Information field is set to zero, and the Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER if the specified values for XonChar and XoffChar are identical.