com.serialpundit.ioctl

Class SerialComIOCTLExecutor

java.lang.Object

com.serialpundit.ioctl.SerialComIOCTLExecutor

public final class SerialComIOCTLExecutor
extends Object

Executes device-specific input/output operations and other operations which cannot be executed using regular system calls.

Application is expected to consult appropriate document to supply valid values to the methods as arguments and should understand what to expect by executing that particular IOCTL call. The IOCTL number (operation code) are unique to each driver and must be obtained from them.

Following are typical use cases:

• Access to GPIO pins in USB-UART, USB-HID, USB-I2C etc converters. It provide access to UART registers in the chip for example for reading the value at a particular port latch. The operating standard API for serial port communication provided by operating system generally does not have provision to explore modern facilities in USB-UART chip. The IOCTL calls helps in reading and writing to registers inside chip for example to configure a GPIO pin as digital output.

  It should be noted that the USB-UART bridge generally have one time programmable memory and therefore configuration/customization settings must be done thoughtfully either programmatically or through vendor provided utility.

Author:

Rishi Gupta

Constructor Summary

Constructors

Constructor and Description
SerialComIOCTLExecutor(String libDirectory, String loadedLibName) Allocates a new SerialComIOCTLExecutor object and load/link native libraries if required.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	ioctlExecuteOperation(long handle, long operationCode) Executes the requested operation on the specified handle.
long	ioctlGetValue(long handle, long operationCode) Executes the requested operation on the specified handle.
boolean	ioctlSetValue(long handle, long operationCode, long value) Executes the requested operation on the specified handle passing the given value to operation.
boolean	ioctlSetValueCharArray(long handle, long operationCode, byte[] values) Executes the requested operation on the specified handle passing the given value to operation.
boolean	ioctlSetValueIntArray(long handle, long operationCode, int[] values) Executes the requested operation on the specified handle passing the given value to operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialComIOCTLExecutor

public SerialComIOCTLExecutor(String libDirectory,
                      String loadedLibName)
                       throws SecurityException,
                              IOException

Allocates a new SerialComIOCTLExecutor object and load/link native libraries if required.

Throws:

SecurityException

IOException

Method Detail

ioctlExecuteOperation

public boolean ioctlExecuteOperation(long handle,
                            long operationCode)
                              throws com.serialpundit.core.SerialComException

Executes the requested operation on the specified handle.

Parameters:

handle - handle of the port on which to execute this ioctl operation.

operationCode - unique ioctl operation code (device/driver specific).

Returns:

true if operation executed successfully.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed as requested.

ioctlSetValue

public boolean ioctlSetValue(long handle,
                    long operationCode,
                    long value)
                      throws com.serialpundit.core.SerialComException

Executes the requested operation on the specified handle passing the given value to operation.

This may be used to toggle GPIO pins present on some state-of-art USB to UART bridges. For example for Silicon labs CP210X series using 'CP210x VCP Linux 3.0 Driver Kit' the GPIO 0 pin can be toggled as shown below:

Turn on : ioctlSetValue(handle, 0x8001, 0x00010001)

Turn off : ioctlSetValue(handle, 0x8001, 0x00000001)

Modern USB-UART bridge generally have user-configurable GPIO pins for status and control information. Each of these GPIO pins may be used as inputs, open-drain outputs, or push-pull outputs. Care must be taken to correctly interface these GPIO pins for required amount of current.

Further GPIO pins may have multiplexed functionality. For example a particular GPIO Pin may be configured as GPIO to control external peripheral or may be configured as RTS modem line. It is advised to consult datasheet. GPIO pins may also be configured at power-up so that they can be tailored to fit the needs of the application design.

This method can be used to write to UART registers in a USB-UART device for example EXAR XR22801/802/804 etc.

Parameters:

handle - handle of the port on which to execute this ioctl operation.

operationCode - unique ioctl operation code.

value - the value to be passed to the IOCTL operation.

Returns:

true if operation executed successfully.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed as requested.

ioctlGetValue

public long ioctlGetValue(long handle,
                 long operationCode)
                   throws com.serialpundit.core.SerialComException

Executes the requested operation on the specified handle. This operation returns a numerical value. This method can be used to read a register in chip. For example to get the status of GPIOs pins on CP210X series from Silicon labs using 'CP210x VCP Linux 3.0 Driver Kit' the following call can be made:

long value = ioctlSetValue(handle, 0x8000)

This method can be used to read UART registers in a USB-UART device for example EXAR XR21B1420/1422/1424 family etc.

Parameters:

handle - handle of the port on which to execute this ioctl operation.

operationCode - unique ioctl operation code.

Returns:

value requested.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed as requested.

ioctlSetValueIntArray

public boolean ioctlSetValueIntArray(long handle,
                            long operationCode,
                            int[] values)
                              throws com.serialpundit.core.SerialComException

Executes the requested operation on the specified handle passing the given value to operation.

Parameters:

handle - handle of the port on which to execute this ioctl operation.

operationCode - unique ioctl operation code.

values - the value to be passed to the IOCTL operation.

Returns:

true if operation executed successfully.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed as requested.

ioctlSetValueCharArray

public boolean ioctlSetValueCharArray(long handle,
                             long operationCode,
                             byte[] values)
                               throws com.serialpundit.core.SerialComException

Executes the requested operation on the specified handle passing the given value to operation.

Although values argument is of type byte however this method can be also used if native ioctl requires argument to be of type unsigned char (C language).

Parameters:

handle - handle of the port on which to execute this ioctl operation.

operationCode - unique ioctl operation code.

values - the value to be passed to the IOCTL operation.

Returns:

true if operation executed successfully.

Throws:

com.serialpundit.core.SerialComException - if the operation can not be completed as requested.