system_configuration(3K) SDK R4.11 system_configuration(3K)
NAME
system_configuration: fs_submit_dev_request,
fs_submit_dev_long_request, io_add_to_register_list,
io_allocate_device_number, io_deallocate_device_number,
io_map_device_number, io_register_device_info,
io_deregister_device_info, io_get_device_info, io_check_device_spec,
io_forget_device_spec, io_do_first_short_board_access,
io_do_first_long_board_access, io_parse_device_spec,
io_parse_device_spec_with_class, io_parse_and_configure_device_class,
io_translate_device_class_address,
io_increment_device_class_ref_count,
io_decrement_device_class_ref_count, io_perform_reset - set up,
configure, and deconfigure a device
SYNOPSIS
#include "/usr/src/uts/aviion/ii/i_fs.h"
void fs_submit_dev_request (dev_request_ptr)
fs_dev_request_ptr_type dev_request_ptr; /*READ ONLY*/
void fs_submit_dev_long_request (dev_request_ptr)
fs_dev_long_request_ptr_type dev_request_ptr; /*READ ONLY*/
#include "/usr/src/uts/aviion/ii/i_io.h"
void io_add_to_register_list (device_number)
io_device_number_type device_number; /*READ ONLY*/
status_type io_allocate_device_number (major, handle, unit, minor_ptr)
io_major_device_number_type major; /*READ ONLY*/
bit32e_type handle; /*READ ONLY*/
uint16_type unit; /*READ ONLY*/
io_minor_device_number_ptr_type minor_ptr; /*WRITE ONLY*/
void io_deallocate_device_number (device_number)
io_device_number_type device_number; /*READ ONLY*/
status_type io_map_device_number (device_number, handle_ptr,
unit_ptr)
io_device_number_type device_number; /*READ ONLY*/
bit32e_ptr_type handle_ptr; /*WRITE ONLY*/
uint16_ptr_type unit_ptr; /*WRITE ONLY*/
status_type io_register_device_info (dev_code, dev_class, info_ptr)
io_device_code_type dev_code; /*READ ONLY*/
uc_device_class_enum_type dev_class; /*READ ONLY*/
pointer_to_any_type info_ptr; /*READ ONLY*/
void io_deregister_device_info (dev_code, dev_class)
io_device_code_type dev_code; /*READ ONLY*/
uc_device_class_enum_type dev_class; /*READ ONLY*/
status_type io_get_device_info (dev_code, dev_class,
interrupt_handler, dit_entry_ptr)
io_device_code_type dev_code; /*READ ONLY*/
uc_device_class_enum_type dev_class; /*READ ONLY*/
io_service_interrupt_routine_ptr_type interrupt_handler;/*READ ONLY*/
pointer_to_any_ptr_type dit_entry_ptr; /*WRITE ONLY*/
status_type io_check_device_spec (device_address, device_code)
opaque_ptr_type device_address; /*READ ONLY*/
uc_device_class_enum_type device_class; /*READ ONLY*/
io_device_code_type device_code; /*READ ONLY*/
status_type io_forget_device_spec (device_address, device_code)
opaque_ptr_type device_address; /*READ ONLY*/
uc_device_class_enum_type device_class; /*READ ONLY*/
io_device_code_type device_code; /*READ ONLY*/
status_type io_do_first_short_board_access (register_ptr,
register_contents_ptr, write_to_register)
bit16e_ptr_type register_ptr; /*READ/WRITE*/
bit16e_ptr_type register_contents_ptr; /*READ/WRITE*/
boolean_type write_to_register; /*READ ONLY*/
status_type io_do_first_long_board_access (register_ptr,
register_contents_ptr, write_to_register)
bit32e_ptr_type register_ptr; /*READ/WRITE*/
bit32e_ptr_type register_contents_ptr; /*READ/WRITE*/
boolean_type write_to_register; /*READ ONLY*/
boolean_type io_parse_device_spec (spec_ptr, dev_adapt_info_ptr,
spec_size_ptr)
char_ptr_type spec_ptr; /*READ ONLY*/
io_dev_adapt_info_ptr_type dev_adapt_info_ptr; /*WRITE ONLY*/
int32_ptr_type spec_size_ptr; /*WRITE ONLY*/
status_type io_parse_device_spec_with_class (spec_ptr, info_ptr,
format_ptr, abbrev_table, default_class_spec,
device_class_ptr)
char_ptr_type spec_ptr; /*READ_ONLY*/
io_device_spec_info_ptr_type info_ptr; /*WRITE_ONLY*/
io_device_spec_format_ptr_type format_ptr; /*READ_ONLY*/
io_device_spec_abbrev_ptr_type abbrev_table; /*READ_ONLY*/
char_ptr_type default_class_spec; /*READ_ONLY*/
uc_device_class_enum_ptr_type device_class_ptr; /*WRITE_ONLY*/
status_type io_parse_and_configure_device_class (spec_ptr,
device_mnemonic, default_class_spec)
char_ptr_type spec_ptr; /*READ_ONLY*/
char_ptr_type device_mnemonic; /*READ_ONLY*/
char_ptr_type default_class_spec; /*READ_ONLY*/
status_type io_translate_device_class_address (device_class,
physical_address, xlated_address_ptr)
uc_device_class_enum_type device_class; /*READ_ONLY*/
physical_address_type physical_address; /*READ_ONLY*/
physical_address_ptr_type xlated_address_ptr; /*WRITE_ONLY*/
void io_increment_device_class_ref_count (device_class)
uc_device_class_enum_type device_class; /*READ_ONLY*/
void io_decrement_device_class_ref_count (device_class)
uc_device_class_enum_type device_class; /*READ_ONLY*/
void io_perform_reset (reset_variety) uc_reset_enum_type
reset_type; /*READ ONLY*/
where:
abbrev_table Pointer to a structure containing information on
how device name short-integer defaults map to
full-blown device address parameters.
default_class_spec The name of the default parent bus device (i.e.,
the device identified with the default device
class), usually "vme(0)".
dev_adapt_info_ptr Pointer to a structure where the pointers to the
parsed string are to be returned.
dev_class The device class of a particular device.
dev_code The device code of a particular device.
dev_request_ptr Pointer to information needed to manipulate a /dev
entry. For the create operation, this information
includes the file's major and minor device num
bers, mode bits, type (block or character), con
taining directory (for example, . or rdsk), and
the filename of the new file (for example, tty05).
For the delete operation, only the filename and
containing directory fields are required.
device_address Address of the primary registers for the device.
device_class_ptr Will be filled in with the device class parsed
from spec_ptr.
device_code The device code for the device.
device_mnemonic The mnemonic string that identifies the device
driver.
device_number The major and minor device numbers of a device.
dit_entry_ptr A pointer to where the device information pointer
is to be returned.
format_ptr A pointer to a structure that describes how the
device name is to be parsed.
handle Device handle which identifies the device to its
driver. This is usually a pointer to a structure
that contains state information about the devices.
handle_ptr Pointer to location where device handle is re
turned.
info_ptr Pointer to device information structure to be as
sociated with the specified device code. The
first field of the structure must contain a point
er to an interrupt handler, which becomes the han
dler for interrupts from the specified device
code.
interrupt_handler The service interrupt routine pointer stored at
the beginning of the device information structure.
This argument is used to ensure that the device
information pointer returned by this routine real
ly does belong to the requester.
major The device's major device number.
minor_ptr A pointer to the location where the allocated mi
nor device number is returned.
physical_address A physical address jumpered onto a VME controller.
register_contents_ptr
A pointer a one-word read/write buffer. For a
write operation, the routine writes the contents
of this buffer to the register. For a read opera
tion, the routine stores in this buffer the data
read from the register.
register_ptr Pointer to register on the board to be accessed.
reset_variety An enumeration specifying which type of reset is
to be done.
spec_ptr Pointer to a null terminated device or adapter
specification string.
spec_size_ptr Pointer to the location where the length of the
parsed device/adapter specification is returned.
This location remains unchanged on error.
unit The unit number that identifies the device to its
controller.
unit_ptr A pointer to the location where the unit number is
returned.
write_to_register A boolean value indicating whether a routine is
reading from or writing to a register. TRUE indi
cates write; FALSE indicates read.
xlated_address_ptr Pointer to a physical address to be filled in with
the device-class-specific translation of the
jumpered physical address parameter.
DESCRIPTION
The following routines are described in this man page:
fs_submit_dev_request Create or delete /dev entry
fs_submit_dev_long_request Create or delete an extended /dev en
try
io_add_to_register_list Add device to disk registration list
io_allocate_device_number Assign device a minor device number
io_deallocate_device_number Deallocate minor device number
io_map_device_number Translate major and minor device num
bers to device handle and unit number
io_register_device_info Register device code and device class
io_deregister_device_info Remove interrupt handler and device
information
io_get_device_info Retrieve device information
io_check_device_spec Check address and device code's nonuse
within a device class
io_forget_device_spec Release a device specification
io_do_first_short_board_access Check 16-bit-register board's presence
io_do_first_long_board_access Check 32-bit-register board's presence
io_parse_device_spec Parse device or adapter specification
io_parse_device_spec_with_class
Parse device or adapter specification
that includes name of parent VME chan
nel device class.
io_parse_and_configure_device_class
Parse a device specification string
that may contain an embedded device
class spec as its "hidden" parameter,
and configure that device class.
io_translate_device_class_address
Translate a jumpered physical address
to the physical address that it maps
to under the given device class.
io_increment_device_class_ref_count
Tell a device class that it now has
one more device configured in it.
io_decrement_device_class_ref_count
Tell a device class that it now has
one fewer device configured in it.
io_perform_reset Perform specified type of reset
Overview to the Configuration Process and Configuration Routines
The routines in this subsection are used to perform a number of dif
ferent configuration tasks required in your driver's configuration
routine (we'll call it xxx_configure). The system build process cre
ates a list of devices to be configured from the entries in the sys
tem file. At boot time, the system initialization code scans this
list and invokes the driver's xxx_configure routine for each device
of the driver's type in that list. The initialization code passes
xxx_configure a pointer to the device's device specification and its
major number. The specification should be in the standard format
shown below:
device_mnemonic [@device_code]([parameters])
At a minimum, each driver's xxx_configure routine should: verify that
the device specification it receives is valid; test for device exis
tence, and, if successful, register the device with various parts of
the kernel.
The driver must first verify that the device specification identifies
a device of its type. It does this by parsing the specification us
ing io_parse_device_spec or io_parse_device_spec_with_class (for VME
devices). The io_parse_device_spec routine returns the device name,
device code, and parameters embedded in the specification. The
io_parse_device_spec_with_class routine returns all that plus some
additional information such as the device class of the device.
If the device specification identifies one of the driver's devices
and it is a physical device, the driver should verify that the device
is attached and working. It is important to use the kernel-supplied
routines for the first access because if a device is not present when
an attempt is made to address it directly, a memory fault and system
halt may occur. Note that if you must map the device registers (as
described in memory_allocation(3K)), you must map them before trying
to access the device.
The driver can verify that the device exists by reading the device's
I/O registers using io_do_first_long_board_access for 32-bit regis
ters or io_do_first_short_board_access for 16-bit registers. If ver
ification is successful, the driver can use io_check_device_spec to
check that the device's address and device code are not already in
use within the given device class. If both the address and device
code are not in use in that device class, io_check_device_spec will
reserve them for the current driver.
If the device exists, the driver must perform several steps to appro
priately register it with the system. If the device generates inter
rupts, the driver must register the interrupt service routine with
the kernel. This is done by calling io_register_device_info. Once
io_register_device_info is called, any interrupt generated by the de
vice will cause the driver's interrupt service routine to be invoked.
Thus, it is important that the driver not register the device until
the driver is ready to handle interrupts. The driver can read the
device registration information by calling io_get_device_info.
The system passes xxx_configure a major number that identifies the
driver's position in the kernel's driver lookup table. The driver
must then allocate a minor number that specifies the particular de
vice's location in the kernel's device tables. The driver can allo
cate a minor number by calling io_allocate_device_number. This rou
tine returns the next available minor number and also puts a parame
ter supplied by the driver into the device table. Typically, the pa
rameter is a pointer to a data structure associated with the device.
The driver can retrieve the stored parameter by calling
io_map_device_number with the major and minor device number as param
eters. Disk drivers may also call io_add_to_register_list to have
their disk implicitly registered. Implicitly registered disks are
known to the file system even if they are not mounted.
The driver creates device nodes in the /dev directory dynamically
during system initialization. The driver can call
fs_submit_dev_request or fs_submit_dev_long_request to create a de
vice node for each device.
Most of the registration routines described above have a correspond
ing deregistration routine which should be used during the
xxx_deconfigure routine or if the device fails any portion of the
configuration process. Examples are: io_deallocate_device_number,
io_deregister_device_info, and io_forget_device_spec.
New routines--vp_unspecify_max_timeouts, described in
event_counters(3K), and io_unspecify_max_demon_messages and
io_unspecify_max_generic_demon_messages, described in serv
er_messages(3K)--have been added to allow these resources to be re
turned to the system.
Constants and Data Structures
This subsection describes constants and data structures defined in
the include files cited in the SYNOPSIS section and used by the rou
tines documented in this man page.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable defi
nitions in the appropriate include file. The best way to avoid such
dependencies is to use kernel-supplied routines to manipulate these
structures.
fs_dev_request_type
typedef struct
{
fs_dev_request_operation_enum_type operation;
char_type dirname[33];
char_type filename[33];
union {
fs_dev_create_request_type create;
}
op;
}
fs_dev_request_type;
fs_dev_long_request_type
typedef struct {
fs_dev_request_operation_enum_type operation;
char_type dirname[MAXNAMELEN];
char_type filename[MAXNAMELEN];
union {
fs_dev_long_create_request_type create;
}
op;
}
fs_dev_long_request_type;
These structures contain the information required to change a node in
/dev. The fields in the structures are as follows:
operation The type of operation requested; for example, delete or
create.
dirname The directory in which the node should reside. This
name will be appended to /dev/. For example, to create
a node in /dev/rdsk, set dirname to rdsk. If you want
the node in /dev and not a subdirectory, set dirname[0]
to FS_NULL_CHAR.
filename The filename of the node.
op The information necessary for the operation requested.
fs_dev_request_operation_enum_type
typedef enum
{
Fs_Dev_Request_Operation_Create,
Fs_Dev_Request_Operation_Delete
}
fs_dev_request_operation_enum_type;
This enum type contains the valid operations supported by the /dev
manager. The fields in this structure are as follows:
Fs_Dev_Request_Operation_Create Request to create a node in /dev.
See fs_dev_create_request_type.
Fs_Dev_Request_Operation_Delete Request to delete a node from
/dev.
fs_dev_create_request_type
typedef struct
{
io_device_number_type device;
df_file_mode_type mode_bits;
}
fs_dev_create_request_type;
fs_dev_long_create_request_type
typedef struct {
io_device_number_type device;
df_file_mode_type mode_bits;
uint16_type user_id;
uint16_type group_id;
}
fs_dev_long_create_request_type;
This structure contains the information required to create a node in
/dev. The fields in this structure are as follows:
device The device number of the node.
mode_bits The initial mode bits of the node. This includes the
file type information.
user_id The user ID to be assigned to the node.
group_id The group ID to be assigned to the node.
io_dev_adapt_info_type
typedef struct
{
char_ptr_type name;
io_device_code_type device_code;
char_ptr_type params[IO_DEV_ADAPT_MAX_PARAMS];
char device_spec[IO_DEV_ADAPT_MAX_SPEC_SIZE];
}
io_dev_adapt_info_type ;
This structure provides a method to pass data back from the
io_parse_device_spec routine. The fields in this structure are as
follows:
name A pointer to the null terminated string of a device
or adapter name.
device_code The device code.
params An array of pointers to null-terminated strings for
each of the parameters.
device_spec A copy of the device specification where the name,
and params pointers will point.
io_device_spec_abbrev_type
typedef struct
{
io_device_code_type device_code;
uint32_type params [IO_DEV_ADAPT_MAX_PARAMS];
}
io_device_spec_abbrev_type ;
This type describes an entry in a driver's device name abbreviation
table. A pointer to that table is passed in as an argument to
io_parse_device_spec_with_class() to parse the device name and expand
its abbreviations.
Each entry represents one shorthand notation which can be used in the
first parameter position of a device spec. A shorthand name will be
a small hexadecimal number string; the corresponding table entry will
be indexed on that number.
If a given device spec has as its first parameter a number string
that is less than the number of entries in the device's name abbrevi
ation table, then that device spec is eligible for expansion by
io_parse_device_spec_with_class(). The spec's first parameter value
is the first parameter value in the abbreviation table entry. The
other parameters are also examined as numeric arguments when appro
priate (the driver's spec format entry determines which ones are),
and each one that is not set (i.e., has value "") receives as its
value the corresponding entry in the abbreviation table entry. Fi
nally, if the device spec did not include an explicit device code,
that too is replaced with its counterpart form the table entry.
The fields in this structure are as follows:
device_code The replacement device code.
params The replacement parameter values.
io_device_spec_format_type
typedef struct
{
char_ptr_type mnemonic;
boolean_type is_param_numeric [IO_DEV_ADAPT_MAX_PARAMS];
}
io_device_spec_format_type ;
This type describes a device spec format for a particular driver. A
pointer to the driver's spec format is passed in as an argument to
io_parse_device_spec_with_class() to parse the device name and expand
its abbreviations.
The fields in this structure are as follows:
mnemonic A pointer to the null terminated string used a the
driver's mnemonic.
is_param_numeric
A flag that indicates whether the specific parameter
in that array position should be interpreted as a
hexadecimal number.
uc_device_class_enum_type
typedef enum
{
Uc_Integrated_Device_Class = 0,
Uc_Vmebus_Device_Class = 1,
Uc_Invalid_Device_Class = 2,
}
uc_device_class_enum_type ;
This type describes the classes of devices supported by the DG/UX
kernel. A device is uniquely identified by its device class and de
vice code.
As new classes of devices are supported, this type definition will
change. Check i_uc.h (in /usr/src/uts/aviion/ii) include file for
the latest supported classes.
uc_device_code_type
typedef uint32_type uc_device_code_type;
This type is used to describe a device code, which, along with its
associated device class, is used to identify an I/O device.
Device codes must be unique within a class, but the same value device
code can be found in multiple classes. Thus, device codes are fit to
the device class to which they apply.
The device codes for integrated devices are pre-defined and will be
the same across all architectures. Note that there is no association
between the pre-defined integrated device codes and physical hard
ware. The kernel will map the pre-assigned device code to the device
interrupt on a given machine.
Integrated Device Code Literals
This sub-subsection defines the values for the integrated device type
pre-assigned device codes. The values below apply for all machine
architectures. During driver initialization, a device's driver links
its device class and device code with an interrupt handler by regis
tering the device (by calling io_register_device_info). Use the fol
lowing literals as the device codes for integrated class devices:
As new pre-assigned device codes are supported, new literals will be
defined. Check the i_uc.h (in /usr/src/uts/aviion/ii) include file
for the latest definitions.
UC_SYSTEM_ERROR_DEVICE_CODE
UC_SYSTEM_TIMER_DEVICE_CODE
UC_KEYBOARD_DEVICE_CODE
UC_ DUART_0_DEVICE_CODE
UC_DUART_1_DEVICE_CODE
UC_PARALLEL_PORT_DEVICE_CODE
UC_ETHERNET_0_DEVICE_CODE
UC_ETHERNET_1_DEVICE_CODE
UC_SCSI_0_DEVICE_CODE
UC_DMA_TERMINAL_COUNT_DEVICE_CODE
UC_GRAPHICS_CARD_DEVICE_CODE
UC_CROSS_INTERRUPT_DEVICE_CODE
UC_PER_JP_TIMER_DEVICE_CODE
UC_DUART_TIMER_DEVICE_CODE
UC_SIGHP_DEVICE_CODE
UC_LOCATION_MONITOR_DEVICE_CODE
UC_POWER_FAIL_DEVICE_CODE
UC_ZBUFFER_DEVICE_CODE
UC_SCSI_1_DEVICE_CODE
UC_SYNC_0_DEVICE_CODE
UC_SYNC_1_DEVICE_CODE
VMEbus class devices do not have pre-assigned device codes because
the VME interrupt vector mechanism allows devices to be set up to use
any valid VME vector. In the VMEbus class, the device code is the
value of the VME vector. It is up to drivers to register device in
formation specifying the appropriate VME vector to the kernel. When
a VME class interrupt occurs, the kernel returns the VME vector of
the interrupting device.
uc_reset_enum_type
typedef enum
{
Uc_Reset_Scsi = 0,
Uc_Reset_Ethernet = 1,
Uc_Reset_Async = 2,
Uc_Reset_Keyboard = 3,
Uc_Reset_Vme = 4,
Uc_Reset_Sync = 5
} uc_reset_enum_type ;
This type describes the various reset types available. These resets
are all for integrated class devices. Resets of non-integrated class
devices is not supported. An enumeration is provided for any reset
supported by any architecture.
fs_submit_dev_request
This routine submits a request to create or delete a /dev entry. If
the root is not mounted, then the request will not be performed until
the root is mounted.
A request to manipulate a /dev entry is accepted. The request will
be processed immediately if the root has been mounted. Otherwise,
the request is added to a queue for later processing.
fs_submit_dev_long_request
This routine is an extended form of fs_submit_dev_request which al
lows you to specify a longer device node name as well as the uid and
gid to be placed on the device node.
io_add_to_register_list
This routine adds the specified device to the list of disks that will
be implicitly registered as part of system initialization. This rou
tine is optional and is used only with disks.
Registration makes a physical disk known to the file system and the
virtual disk manager. Thus, implicitly registered disks are known to
the file system without being specifically mounted.
io_allocate_device_number
This routine assigns the device a minor device number. The major de
vice number identifies the family of devices to which the device be
longs.
io_check_device_spec
This routine checks that the address and device code specified for
the device are not already in use within the specified device class.
Such address and device code validation will not prevent overlap of
registers or RAM areas. It does help avoid the most common user er
rors in device specification. Only the first address for a device is
checked.
io_deallocate_device_number
This routine terminates the association between the device and its
minor device number.
io_deregister_device_info
This routine deregisters the device by removing its current interrupt
handler and device information structure from the kernel device in
formation table.
This routine reverses the effect of io_register_device_info. After
this call completes, future interrupts on the specified device code
will be directed to the system supplied interrupt handler. If you
make this call on a device code that does not currently have an in
terrupt handler, a halt will occur.
io_do_first_long_board_access
This routine tests for the existence of the board at a particular
memory-mapped I/O address. Use this routine for boards with long
(32-bit) registers.
Do the first access to a long board register such that if a board is
not present, the system will not hang or halt. The board should not
be accessed again if IO_ENXIO_DEVICE_DOES_NOT_EXIST is returned.
This routine assumes that the register is a long register.
io_do_first_short_board_access
This routine tests for the existence of the board at a particular
memory-mapped I/O address. Use this routine for boards with short
(16-bit) registers.
Do the first access to a board register such that if a board is not
present, the system will not hang or halt. The board should not be
accessed again if IO_ENXIO_DEVICE_DOES_NOT_EXIST is returned. This
routine assumes that the register is a short register.
io_forget_device_spec
This routine releases (that is, forgets) a device specification that
was claimed as the result of a previous call to the
io_check_device_spec routine.
When a device is deconfigured, the device_address claimed for the de
vice must be freed by calling this routine. If you do not free the
device address, future calls to io_check_device_spec using this de
vice address will fail.
io_get_device_info
This routine retrieves the device information pointer associated with
the device specified by the device code and device class.
The device information pointer registered with the specified device
(by an earlier call to io_register_device_info) is retrieved. If the
specified device code has no device information registered to it, or
if the service interrupt routine pointer in the device information
structure does not match the service interrupt routine pointer sup
plied as an argument to this call, then an error status is returned
and the returned device information pointer is undefined.
io_map_device_number
This routine translates the previously allocated major and minor de
vice numbers to device handle and unit number.
This routine is typically called by a driver's open routine to map
the major and minor device numbers to a specific device.
io_parse_device_spec
This routine parses a device or adapter specification string (null-
terminated) for the positions of all specification components. The
components parsed for are the device name, device code, and up to
IO_DEV_ADAPT_MAX_PARAMS parameters. The parse leaves the original
string intact. If a given component was not present, its pointer
will point to a null character. Upon successful parsing, the length,
in bytes, of the parsed specification will be returned in
spec_size_ptr.
At a minimum the device specification must consist of a sequence of
characters followed by an open and a close parenthesis. If a device
code is present it must be prefixed with an
IO_DEV_ADAPT_DEVICE_CODE_DELIMITER (at-sign, @), consist of one or
two hexadecimal characters, and occupy the space immediately in front
of the open parenthesis. Any number of parameters up to
IO_DEV_ADAPT_MAX_PARAMS may be present, but they must be separated by
commas. For more detailed information about the device and adapter
specification, refer to Programming in the DG/UX Kernel Environment.
If the parsing fails, then all information within the dev_adapt_info
structure must be assumed to be invalid.
io_parse_device_spec_with_class
This routine parses a device or adapter specification string (null-
terminated) for the positions of all specification components in a
manner similar to io_parse_device_spec. It also extracts the de
vice's class (based on its parent bus device) and expands short-
number device abbreviations out into full device code and address pa
rameter values.
io_parse_and_configure_device_class
This routine splits spec_ptr into two parts: the device class spec
which may be present as the first parameter (with default_class_spec
used if one was not present there), and the "normal" device spec
which is the result of removing the device class spec and its follow
ing comma. The routine then verifies that the "normal" spec has a
valid syntax and that its mnemonic matchs device_mnemonic. If so, an
attempt is made to configure the device class spec.
io_increment_device_class_ref_count
This routine tells a device class device (such as a VME channel) that
it now has one more child device connected to it. The parent device
will not be able to be deconfigured until its reference count drops
to zero.
io_translate_device_class_address
This routine translates a jumpered physical address to the physical
address that it maps to under the given device class. This routine
is needed for determining the address of control registers of VME de
vices on secondary VME channels.
io_decrement_device_class_ref_count
This routine tells a device class device (such as a VME channel) that
it now has one fewer child device connected to it. The parent device
will not be able to be deconfigured until its reference count drops
to zero.
io_perform_reset
This routine performs the specified type of reset. It uses the clock
and await mechanisms, so it should not be used in an environment
where this is not possible (for example, during shutdown or after re
set).
io_register_device_info
This routine associates a pointer given in info_ptr with the device
specified by the device code and device class. This process estab
lishes an interrupt handler for the given device code.
This routine creates an entry in the appropriate device class device
interrupt table (DIT) for the device code. If the slot in the DIT is
already occupied or if the device code is larger than the maximum de
vice code supported on this system, then an error is returned and the
association between the device code and device information structure
is not established.
DIAGNOSTICS
Return Value
For io_allocate_device_number:
OK No errors were discovered, so all returned arguments
are valid.
IO_ENXIO_ALL_MINOR_NUMBERS_IN_USE
The minor device number table for this major device
number contains no unused slots and has grown to the
maximum size.
For io_check_device_spec:
OK The address and device code are not already in use.
IO_ENXIO_DEVICE_IS_ALREADY_CONFIGURED
The address or device code are already in use.
For io_do_first_long_board_access:
OK The register was accessed successfully.
IO_ENXIO_DEVICE_DOES_NOT_EXIST
The board is not accessible.
For io_do_first_short_board_access:
OK The register was accessed successfully.
IO_ENXIO_DEVICE_DOES_NOT_EXIST
The board is not accessible.
For io_forget_device_spec:
OK The address/device code pair is freed.
IO_ENXIO_DEVICE_IS_NOT_CONFIGURED
The address/device code to be freed were not found.
For io_get_device_info:
OK The device information pointer was successfully re
turned.
IO_ENXIO_DEVICE_CODE_OUT_OF_RANGE
The supplied device code is not supported on this sys
tem.
IO_ENXIO_DEVICE_IS_NOT_CONFIGURED
No device information pointer was found for the device
code or the device code does not belong to the re
quester.
For io_map_device_number:
OK No errors occurred.
IO_ENXIO_DEVICE_IS_NOT_CONFIGURED
An attempt was made to map a device that is not config
ured.
For io_parse_device_spec:
TRUE The specification was successfully parsed.
FALSE The parsing failed and the state of the spec_ptr string
and the dev_adapt_info_ptr structure elements are un
known.
For io_parse_device_spec_with_class:
OK The specification was successfully parsed and recog
nized by the driver.
IO_ENXIO_DEVICE_NAME_NOT_RECOGNIZED
The parsing failed or the driver did not claim to rec
ognize the device spec. The state of the info_ptr
structure elements and the device_class_ptr value are
unknown.
For io_parse_and_configure_device_class:
OK The specification was successfully parsed and recog
nized by the driver.
IO_ENXIO_DEVICE_NAME_NOT_RECOGNIZED
The parsing failed or the driver did not claim to rec
ognize the device spec.
For io_translate_device_class_address:
OK The physical address was successfully translated.
IO_ENXIO_INVALID_DEVICE_CLASS
An invalid or unregistered device class was passed in
as input.
For io_register_device_info:
OK The device_info was successfully registered.
IO_ENXIO_DEVICE_CODE_OUT_OF_RANGE
The supplied device code is not supported on this sys
tem. The device_info is not registered.
IO_ENXIO_DEVICE_CODE_ALREADY_ASSIGNED
An attempt was made to configure a device on a device
code that is already assigned.
For the other routines: none.
Errors
None.
Abort Conditions
For io_deallocate_device_number, halt may be invoked with the follow
ing halt codes:
IO_PANIC_MAJOR_NUMBER_EXCEEDS_MAX
An invalid major device number was used.
IO_PANIC_DEVICE_IS_NOT_CONFIGURED
An attempt was made to deallocate a device which was
not configured.
IO_PANIC_DEVICE_IS_NOT_CONFIGURED2
An active entry in the minor device number table does
not exist at the offset specified by the minor device
number argument.
For io_deregister_device_info, halt may be invoked with the following
halt code:
IO_PANIC_ILLEGAL_DEREGISTER_DEVICE_INFO
An attempt was made to deregister a device on a device
code that did not have information registered.
For io_map_device_number, halt may be invoked with the following halt
code:
IO_PANIC_MAJOR_NUMBER_EXCEEDS_MAX
The major device number argument exceeds the maximum
specified by cf_io_device_driver_count.
IO_PANIC_MAJOR_NUMBER_EXCEEDS_MAX2
The major device number argument exceeds the maximum
specified by cf_io_major_number_count.
For io_perform_reset, halt may be invoked with the following halt
codes:
IO_PANIC_BAD_RESET_TYPE
The parameter passed is not recognizable.
For the other routines: none.
SEE ALSO
event_counters(3K), memory_allocation(3K), server_messages(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)