system_configuration(3K) SDK R4.11 system_configuration(3K)
NAME
systemconfiguration: fssubmitdevrequest,
fssubmitdevlongrequest, ioaddtoregisterlist,
ioallocatedevicenumber, iodeallocatedevicenumber,
iomapdevicenumber, ioregisterdeviceinfo,
ioderegisterdeviceinfo, iogetdeviceinfo, iocheckdevicespec,
ioforgetdevicespec, iodofirstshortboardaccess,
iodofirstlongboardaccess, ioparsedevicespec,
ioparsedevicespecwithclass, ioparseandconfiguredeviceclass,
iotranslatedeviceclassaddress,
ioincrementdeviceclassrefcount,
iodecrementdeviceclassrefcount, ioperformreset - set up,
configure, and deconfigure a device
SYNOPSIS
#include "/usr/src/uts/aviion/ii/ifs.h"
void fssubmitdevrequest (devrequestptr)
fsdevrequestptrtype devrequestptr; /*READ ONLY*/
void fssubmitdevlongrequest (devrequestptr)
fsdevlongrequestptrtype devrequestptr; /*READ ONLY*/
#include "/usr/src/uts/aviion/ii/iio.h"
void ioaddtoregisterlist (devicenumber)
iodevicenumbertype devicenumber; /*READ ONLY*/
statustype ioallocatedevicenumber (major, handle, unit, minorptr)
iomajordevicenumbertype major; /*READ ONLY*/
bit32etype handle; /*READ ONLY*/
uint16type unit; /*READ ONLY*/
iominordevicenumberptrtype minorptr; /*WRITE ONLY*/
void iodeallocatedevicenumber (devicenumber)
iodevicenumbertype devicenumber; /*READ ONLY*/
statustype iomapdevicenumber (devicenumber, handleptr,
unitptr)
iodevicenumbertype devicenumber; /*READ ONLY*/
bit32eptrtype handleptr; /*WRITE ONLY*/
uint16ptrtype unitptr; /*WRITE ONLY*/
statustype ioregisterdeviceinfo (devcode, devclass, infoptr)
iodevicecodetype dev_code; /*READ ONLY*/
ucdeviceclassenumtype dev_class; /*READ ONLY*/
pointertoanytype info_ptr; /*READ ONLY*/
void ioderegisterdeviceinfo (devcode, devclass)
iodevicecodetype devcode; /*READ ONLY*/
ucdeviceclassenumtype devclass; /*READ ONLY*/
statustype iogetdeviceinfo (devcode, devclass,
interrupthandler, ditentryptr)
iodevicecodetype devcode; /*READ ONLY*/
ucdeviceclassenumtype devclass; /*READ ONLY*/
ioserviceinterruptroutineptrtype interrupthandler;/*READ ONLY*/
pointertoanyptrtype ditentryptr; /*WRITE ONLY*/
statustype iocheckdevicespec (deviceaddress, devicecode)
opaqueptrtype deviceaddress; /*READ ONLY*/
ucdeviceclassenumtype deviceclass; /*READ ONLY*/
iodevicecodetype devicecode; /*READ ONLY*/
statustype ioforgetdevicespec (deviceaddress, devicecode)
opaqueptrtype deviceaddress; /*READ ONLY*/
ucdeviceclassenumtype deviceclass; /*READ ONLY*/
iodevicecodetype devicecode; /*READ ONLY*/
statustype iodofirstshortboardaccess (registerptr,
registercontentsptr, writetoregister)
bit16eptrtype registerptr; /*READ/WRITE*/
bit16eptrtype registercontentsptr; /*READ/WRITE*/
booleantype writetoregister; /*READ ONLY*/
statustype iodofirstlongboardaccess (registerptr,
registercontentsptr, writetoregister)
bit32eptrtype registerptr; /*READ/WRITE*/
bit32eptrtype registercontentsptr; /*READ/WRITE*/
booleantype writetoregister; /*READ ONLY*/
booleantype ioparsedevicespec (specptr, devadaptinfoptr,
specsizeptr)
charptrtype specptr; /*READ ONLY*/
iodevadaptinfoptrtype devadaptinfoptr; /*WRITE ONLY*/
int32ptrtype specsizeptr; /*WRITE ONLY*/
statustype ioparsedevicespecwithclass (specptr, infoptr,
formatptr, abbrevtable, defaultclassspec,
deviceclassptr)
charptrtype specptr; /*READONLY*/
iodevicespecinfoptrtype infoptr; /*WRITEONLY*/
iodevicespecformatptrtype formatptr; /*READONLY*/
iodevicespecabbrevptrtype abbrevtable; /*READONLY*/
charptrtype defaultclassspec; /*READONLY*/
ucdeviceclassenumptrtype deviceclassptr; /*WRITEONLY*/
statustype ioparseandconfiguredeviceclass (specptr,
devicemnemonic, defaultclassspec)
charptrtype specptr; /*READONLY*/
charptrtype devicemnemonic; /*READONLY*/
charptrtype defaultclassspec; /*READONLY*/
statustype iotranslatedeviceclassaddress (deviceclass,
physicaladdress, xlatedaddressptr)
ucdeviceclassenumtype deviceclass; /*READONLY*/
physicaladdresstype physicaladdress; /*READONLY*/
physicaladdressptrtype xlatedaddressptr; /*WRITEONLY*/
void ioincrementdeviceclassrefcount (deviceclass)
ucdeviceclassenumtype deviceclass; /*READONLY*/
void iodecrementdeviceclassrefcount (deviceclass)
ucdeviceclassenumtype deviceclass; /*READONLY*/
void ioperformreset (resetvariety) ucresetenumtype
resettype; /*READ ONLY*/
where:
abbrevtable Pointer to a structure containing information on
how device name short-integer defaults map to
full-blown device address parameters.
defaultclassspec The name of the default parent bus device (i.e.,
the device identified with the default device
class), usually "vme(0)".
devadaptinfoptr Pointer to a structure where the pointers to the
parsed string are to be returned.
devclass The device class of a particular device.
devcode The device code of a particular device.
devrequestptr 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.
deviceaddress Address of the primary registers for the device.
deviceclassptr Will be filled in with the device class parsed
from specptr.
devicecode The device code for the device.
devicemnemonic The mnemonic string that identifies the device
driver.
devicenumber The major and minor device numbers of a device.
ditentryptr A pointer to where the device information pointer
is to be returned.
formatptr 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.
handleptr Pointer to location where device handle is re
turned.
infoptr 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.
interrupthandler 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.
minorptr A pointer to the location where the allocated mi
nor device number is returned.
physicaladdress A physical address jumpered onto a VME controller.
registercontentsptr
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.
registerptr Pointer to register on the board to be accessed.
resetvariety An enumeration specifying which type of reset is
to be done.
specptr Pointer to a null terminated device or adapter
specification string.
specsizeptr 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.
unitptr A pointer to the location where the unit number is
returned.
writetoregister A boolean value indicating whether a routine is
reading from or writing to a register. TRUE indi
cates write; FALSE indicates read.
xlatedaddressptr 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:
fssubmitdevrequest Create or delete /dev entry
fssubmitdevlongrequest Create or delete an extended /dev en
try
ioaddtoregisterlist Add device to disk registration list
ioallocatedevicenumber Assign device a minor device number
iodeallocatedevicenumber Deallocate minor device number
iomapdevicenumber Translate major and minor device num
bers to device handle and unit number
ioregisterdeviceinfo Register device code and device class
ioderegisterdeviceinfo Remove interrupt handler and device
information
iogetdeviceinfo Retrieve device information
iocheckdevicespec Check address and device code's nonuse
within a device class
ioforgetdevicespec Release a device specification
iodofirstshortboardaccess Check 16-bit-register board's presence
iodofirstlongboardaccess Check 32-bit-register board's presence
ioparsedevicespec Parse device or adapter specification
ioparsedevicespecwithclass
Parse device or adapter specification
that includes name of parent VME chan
nel device class.
ioparseandconfiguredeviceclass
Parse a device specification string
that may contain an embedded device
class spec as its "hidden" parameter,
and configure that device class.
iotranslatedeviceclassaddress
Translate a jumpered physical address
to the physical address that it maps
to under the given device class.
ioincrementdeviceclassrefcount
Tell a device class that it now has
one more device configured in it.
iodecrementdeviceclassrefcount
Tell a device class that it now has
one fewer device configured in it.
ioperformreset 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 xxxconfigure). 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 xxxconfigure routine for each device
of the driver's type in that list. The initialization code passes
xxxconfigure a pointer to the device's device specification and its
major number. The specification should be in the standard format
shown below:
devicemnemonic [@devicecode]([parameters])
At a minimum, each driver's xxxconfigure 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 ioparsedevicespec or ioparsedevicespecwithclass (for VME
devices). The ioparsedevicespec routine returns the device name,
device code, and parameters embedded in the specification. The
ioparsedevicespecwithclass 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 memoryallocation(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 iodofirstlongboardaccess for 32-bit regis
ters or iodofirstshortboardaccess for 16-bit registers. If ver
ification is successful, the driver can use iocheckdevicespec 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, iocheckdevicespec 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 ioregisterdeviceinfo. Once
ioregisterdeviceinfo 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 iogetdeviceinfo.
The system passes xxxconfigure 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 ioallocatedevicenumber. 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
iomapdevicenumber with the major and minor device number as param
eters. Disk drivers may also call ioaddtoregisterlist 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
fssubmitdevrequest or fssubmitdevlongrequest 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
xxxdeconfigure routine or if the device fails any portion of the
configuration process. Examples are: iodeallocatedevicenumber,
ioderegisterdeviceinfo, and ioforgetdevicespec.
New routines--vpunspecifymaxtimeouts, described in
eventcounters(3K), and iounspecifymaxdemonmessages and
iounspecifymaxgenericdemonmessages, described in serv
ermessages(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.
fsdevrequesttype
typedef struct
{
fsdevrequestoperationenumtype operation;
chartype dirname[33];
chartype filename[33];
union {
fsdevcreaterequesttype create;
}
op;
}
fsdevrequesttype;
fsdevlongrequesttype
typedef struct {
fsdevrequestoperationenumtype operation;
chartype dirname[MAXNAMELEN];
chartype filename[MAXNAMELEN];
union {
fsdevlongcreaterequesttype create;
}
op;
}
fsdevlongrequesttype;
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 FSNULLCHAR.
filename The filename of the node.
op The information necessary for the operation requested.
fsdevrequestoperationenumtype
typedef enum
{
FsDevRequestOperationCreate,
FsDevRequestOperationDelete
}
fsdevrequestoperationenumtype;
This enum type contains the valid operations supported by the /dev
manager. The fields in this structure are as follows:
FsDevRequestOperationCreate Request to create a node in /dev.
See fsdevcreaterequesttype.
FsDevRequestOperationDelete Request to delete a node from
/dev.
fsdevcreaterequesttype
typedef struct
{
iodevicenumbertype device;
dffilemodetype modebits;
}
fsdevcreaterequesttype;
fsdevlongcreaterequesttype
typedef struct {
iodevicenumbertype device;
dffilemodetype modebits;
uint16type userid;
uint16type groupid;
}
fsdevlongcreaterequesttype;
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.
modebits The initial mode bits of the node. This includes the
file type information.
userid The user ID to be assigned to the node.
groupid The group ID to be assigned to the node.
iodevadaptinfotype
typedef struct
{
charptrtype name;
iodevicecodetype devicecode;
charptrtype params[IODEVADAPTMAXPARAMS];
char devicespec[IODEVADAPTMAXSPECSIZE];
}
iodevadaptinfotype ;
This structure provides a method to pass data back from the
ioparsedevicespec routine. The fields in this structure are as
follows:
name A pointer to the null terminated string of a device
or adapter name.
devicecode The device code.
params An array of pointers to null-terminated strings for
each of the parameters.
devicespec A copy of the device specification where the name,
and params pointers will point.
iodevicespecabbrevtype
typedef struct
{
iodevicecodetype devicecode;
uint32type params [IODEVADAPTMAXPARAMS];
}
iodevicespecabbrevtype ;
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
ioparsedevicespecwithclass() 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
ioparsedevicespecwithclass(). 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:
devicecode The replacement device code.
params The replacement parameter values.
iodevicespecformattype
typedef struct
{
charptrtype mnemonic;
booleantype isparamnumeric [IODEVADAPTMAXPARAMS];
}
iodevicespecformattype ;
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
ioparsedevicespecwithclass() 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.
isparamnumeric
A flag that indicates whether the specific parameter
in that array position should be interpreted as a
hexadecimal number.
ucdeviceclassenumtype
typedef enum
{
UcIntegratedDeviceClass = 0,
UcVmebusDeviceClass = 1,
UcInvalidDeviceClass = 2,
}
ucdeviceclassenumtype ;
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 iuc.h (in /usr/src/uts/aviion/ii) include file for
the latest supported classes.
ucdevicecodetype
typedef uint32type ucdevicecodetype;
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 ioregisterdeviceinfo). 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 iuc.h (in /usr/src/uts/aviion/ii) include file
for the latest definitions.
UCSYSTEMERRORDEVICECODE
UCSYSTEMTIMERDEVICECODE
UCKEYBOARDDEVICECODE
UC DUART0DEVICECODE
UCDUART1DEVICECODE
UCPARALLELPORTDEVICECODE
UCETHERNET0DEVICECODE
UCETHERNET1DEVICECODE
UCSCSI0DEVICECODE
UCDMATERMINALCOUNTDEVICECODE
UCGRAPHICSCARDDEVICECODE
UCCROSSINTERRUPTDEVICECODE
UCPERJPTIMERDEVICECODE
UCDUARTTIMERDEVICECODE
UCSIGHPDEVICECODE
UCLOCATIONMONITORDEVICECODE
UCPOWERFAILDEVICECODE
UCZBUFFERDEVICECODE
UCSCSI1DEVICECODE
UCSYNC0DEVICECODE
UCSYNC1DEVICECODE
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.
ucresetenumtype
typedef enum
{
UcResetScsi = 0,
UcResetEthernet = 1,
UcResetAsync = 2,
UcResetKeyboard = 3,
UcResetVme = 4,
UcResetSync = 5
} ucresetenumtype ;
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.
fssubmitdevrequest
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.
fssubmitdevlongrequest
This routine is an extended form of fssubmitdevrequest 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.
ioaddtoregisterlist
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.
ioallocatedevicenumber
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.
iocheckdevicespec
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.
iodeallocatedevicenumber
This routine terminates the association between the device and its
minor device number.
ioderegisterdeviceinfo
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 ioregisterdeviceinfo. 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.
iodofirstlongboardaccess
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.
iodofirstshortboardaccess
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.
ioforgetdevicespec
This routine releases (that is, forgets) a device specification that
was claimed as the result of a previous call to the
iocheckdevicespec routine.
When a device is deconfigured, the deviceaddress claimed for the de
vice must be freed by calling this routine. If you do not free the
device address, future calls to iocheckdevicespec using this de
vice address will fail.
iogetdeviceinfo
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 ioregisterdeviceinfo) 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.
iomapdevicenumber
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.
ioparsedevicespec
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
specsizeptr.
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 devadaptinfo
structure must be assumed to be invalid.
ioparsedevicespecwithclass
This routine parses a device or adapter specification string (null-
terminated) for the positions of all specification components in a
manner similar to ioparsedevicespec. 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.
ioparseandconfiguredeviceclass
This routine splits specptr into two parts: the device class spec
which may be present as the first parameter (with defaultclassspec
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 devicemnemonic. If so, an
attempt is made to configure the device class spec.
ioincrementdeviceclassrefcount
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.
iotranslatedeviceclassaddress
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.
iodecrementdeviceclassrefcount
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.
ioperformreset
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).
ioregisterdeviceinfo
This routine associates a pointer given in infoptr 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 ioallocatedevicenumber:
OK No errors were discovered, so all returned arguments
are valid.
IOENXIOALLMINORNUMBERSINUSE
The minor device number table for this major device
number contains no unused slots and has grown to the
maximum size.
For iocheckdevicespec:
OK The address and device code are not already in use.
IOENXIODEVICEISALREADYCONFIGURED
The address or device code are already in use.
For iodofirstlongboardaccess:
OK The register was accessed successfully.
IOENXIODEVICEDOESNOTEXIST
The board is not accessible.
For iodofirstshortboardaccess:
OK The register was accessed successfully.
IOENXIODEVICEDOESNOTEXIST
The board is not accessible.
For ioforgetdevicespec:
OK The address/device code pair is freed.
IOENXIODEVICEISNOTCONFIGURED
The address/device code to be freed were not found.
For iogetdeviceinfo:
OK The device information pointer was successfully re
turned.
IOENXIODEVICECODEOUTOFRANGE
The supplied device code is not supported on this sys
tem.
IOENXIODEVICEISNOTCONFIGURED
No device information pointer was found for the device
code or the device code does not belong to the re
quester.
For iomapdevicenumber:
OK No errors occurred.
IOENXIODEVICEISNOTCONFIGURED
An attempt was made to map a device that is not config
ured.
For ioparsedevicespec:
TRUE The specification was successfully parsed.
FALSE The parsing failed and the state of the specptr string
and the devadaptinfoptr structure elements are un
known.
For ioparsedevicespecwithclass:
OK The specification was successfully parsed and recog
nized by the driver.
IOENXIODEVICENAMENOTRECOGNIZED
The parsing failed or the driver did not claim to rec
ognize the device spec. The state of the infoptr
structure elements and the deviceclassptr value are
unknown.
For ioparseandconfiguredeviceclass:
OK The specification was successfully parsed and recog
nized by the driver.
IOENXIODEVICENAMENOTRECOGNIZED
The parsing failed or the driver did not claim to rec
ognize the device spec.
For iotranslatedeviceclassaddress:
OK The physical address was successfully translated.
IOENXIOINVALIDDEVICECLASS
An invalid or unregistered device class was passed in
as input.
For ioregisterdeviceinfo:
OK The deviceinfo was successfully registered.
IOENXIODEVICECODEOUTOFRANGE
The supplied device code is not supported on this sys
tem. The deviceinfo is not registered.
IOENXIODEVICECODEALREADYASSIGNED
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 iodeallocatedevicenumber, halt may be invoked with the follow
ing halt codes:
IOPANICMAJORNUMBEREXCEEDSMAX
An invalid major device number was used.
IOPANICDEVICEISNOTCONFIGURED
An attempt was made to deallocate a device which was
not configured.
IOPANICDEVICEISNOTCONFIGURED2
An active entry in the minor device number table does
not exist at the offset specified by the minor device
number argument.
For ioderegisterdeviceinfo, halt may be invoked with the following
halt code:
IOPANICILLEGALDEREGISTERDEVICEINFO
An attempt was made to deregister a device on a device
code that did not have information registered.
For iomapdevicenumber, halt may be invoked with the following halt
code:
IOPANICMAJORNUMBEREXCEEDSMAX
The major device number argument exceeds the maximum
specified by cfiodevicedrivercount.
IOPANICMAJORNUMBEREXCEEDSMAX2
The major device number argument exceeds the maximum
specified by cfiomajornumbercount.
For ioperformreset, halt may be invoked with the following halt
codes:
IOPANICBADRESETTYPE
The parameter passed is not recognizable.
For the other routines: none.
SEE ALSO
eventcounters(3K), memoryallocation(3K), servermessages(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)