tokn Special File

Purpose

Provides access to the token-ring adapters by way of the token-ring device handler.

Description

The tokn character special file provides access to the token-ring device handler that provides access to a token-ring local area network. The device handler supports up to four token-ring adapters.

Usage Considerations

When accessing the token-ring device handler, the following should be taken into account:

Driver initialization and termination

The device handler may be loaded and unloaded. The device handler supports the configuration calls to initialize and terminate itself.

Special file support

Calls other than the open and close subroutines are discussed based on the mode in which the device handler is operating.

Subroutine Support

The token-ring device handler provides specific support for the open, close, read, write, and ioctl subroutines.

open and close Subroutines

The device handler supports the /dev/tokn special file as a character-multiplex special file. The special file must be opened for both reading and writing (O_RDWR). There are no particular considerations for closing the special file. The special file name used in an open call depends upon how the device is to be opened. The three types of special file names are:

Item Description
/dev/tokn Starts the device handler for the selected port, where the value of n is 0 <= n <= 7.
/dev/tokn/D Starts the device handler for the selected port in Diagnostic mode, where the value of n is 0 <= n <= 7.
/dev/tokn/W Starts the device handler for the selected port in Diagnostic Wrap mode, where the value of n is 0 <= n <= 7.

read Subroutine

Can take the form of a read, readx, readv, or readvx subroutine. For this call, the device handler copies the data into the buffer specified by the caller.

write Subroutine

Can take the form of a write, writex, writev, or writevx subroutine. For this call, the device handler copies the user data into a kernel buffer and transmits the data on the LAN.

ioctl Subroutine

The token-ring device handler supports the following ioctl operations:

Item Description
CIO_GET_STAT Returns current adapter and device handler status.
CIO_HALT Halts a session and removes a network ID from the network ID table.
CIO_QUERY Returns the current counter values, as defined in the /usr/include/sys/comio.h and /usr/include/sys/tokuser.h files.
CIO_START Starts a session and registers a network ID.
IOCINFO Returns a structure of device information to the user specified area. The devtype field is DD_NET_DH and the devsubtype field is DD_TR, as defined in the /usr/include/sys/devinfo.h file.
TOK_GRP_ADDR Allows the setting of the active group address for the token-ring adapter.
TOK_FUNC_ADDR Allows the setting of a functional address for the token-ring adapter.
TOK_QVPD Returns adapter vital product data.
TOK_RING_INFO Returns information about the token-ring device.

Error Conditions

The following error conditions may be returned when accessing the device handler through the dev/tokn special file:

Item Description
EACCES Indicates that permission to access the adapter is denied for one of the following reasons:
  • Device has not been configured.
  • Diagnostic mode open request denied.
  • The call is from a kernel-mode process.
EAGAIN Indicates that the transmit queue is full.
EBUSY Indicates one of the following:
  • The device is already opened in Diagnostic mode.
  • The maximum number of opens has already been reached.
  • The request is denied.
  • The device is in use.
  • The device handler cannot terminate.
EEXIST Indicates that the device is already configured or the device handler is unable to remove the device from switch table.
EFAULT Indicates that the an invalid address or parameter was specified.
EINTR Indicates that the subroutine was interrupted.
EINVAL Indicates one of the following:
  • The parameters specified were invalid.
  • The define device structure (DDS) is invalid.
  • The device handler is not in Diagnostic mode.
ENOCONNECT Indicates that the device has not been started.
ENETDOWN Indicates that the network is down and the device handler is unable to process the command.
ENOENT Indicates that there was no DDS available.
ENOMEM Indicates that the device handler was unable to allocate required memory.
ENOMSG Indicates that there was no message of desired type.
ENOSPC Indicates that the network ID table is full or the maximum number of opens was exceeded.
EADDRINUSE Indicates that the specified network ID is in use.
ENXIO Indicates that the specified minor number was not valid.
ENETUNREACH Indicates that the device handler is in Network Recovery mode and is unable to process the write operation.
EMSGSIZE Indicates that the data is too large for the supplied buffer.