server_messages(3K) DG/UX R4.11MU05 server_messages(3K)
NAME
servermessages: ioqueuemessagetodriverdemon,
iospecifymaxdemonmessages, iounspecifymaxdemonmessages,
ioqueuemessagetogenericdemon,
iospecifymaxgenericdemonmessages,
iounspecifymaxgenericdemonmessages, ioerrlogerror - send
messages to driver and generic servers and to error logger
SYNOPSIS
#include "/usr/src/uts/aviion/ii/iio.h"
#include "/usr/src/uts/aviion/ii/isc.h"
booleantype ioerrlogerror (priority, format, value00, value01,
value02, value03, value04, value05, value06,
value07, value08, value09, value10, value11,
value12, value13, value14, value15, value16,
value17)
uint32etype priority; /* READ ONLY */
charptrtype format; /* READ ONLY */
bit32etype value00; /* READ ONLY */
bit32etype value01; /* READ ONLY */
bit32etype value02; /* READ ONLY */
bit32etype value03; /* READ ONLY */
bit32etype value04; /* READ ONLY */
bit32etype value05; /* READ ONLY */
bit32etype value06; /* READ ONLY */
bit32etype value07; /* READ ONLY */
bit32etype value08; /* READ ONLY */
bit32etype value09; /* READ ONLY */
bit32etype value10; /* READ ONLY */
bit32etype value11; /* READ ONLY */
bit32etype value12; /* READ ONLY */
bit32etype value13; /* READ ONLY */
bit32etype value14; /* READ ONLY */
bit32etype value15; /* READ ONLY */
bit32etype value16; /* READ ONLY */
bit32etype value17; /* READ ONLY */
vpecptrtype ioqueuemessagetodriverdemon
(completionroutineptr, data, doadvance)
iocompletionroutineptrtype completionroutineptr; /*READ ONLY*/
bit32etype data; /*READ ONLY*/
booleantype doadvance; /*READ ONLY*/
vpecptrtype ioqueuemessagetogenericdemon
(completionroutineptr, data, doadvance)
iocompletionroutineptrtype completionroutineptr; /*READ ONLY*/
bit32etype data; /*READ ONLY*/
booleantype doadvance; /*READ ONLY*/
void iospecifymaxdemonmessages (count)
uint32type count; /*READ ONLY*/
void iospecifymaxgenericdemonmessages (count)
uint32type count; /*READ ONLY*/
void iounspecifymaxdemonmessages (count)
uint32type count /*READ ONLY*/
void iounspecifymaxgenericdemonmessages (count)
uint32type count /*READ ONLY*/
where:
completionroutineptr
A pointer to the value to go in the completionroutine
field of the message. When the server dequeues this
message, it calls the routine pointed to by the
completionroutineptr field.
count A positive integer indicating the maximum number of
messages or the number of messages to be removed.
data The value to go in the data field of the message.
doadvance A boolean indicating whether to advance the server
eventcounter. See ioqueuemessagetodriverdemon and
ioqueuemessagetogenericdemon below.
format A printf format string that specifies the format to be
used for the message.
priority The priority of the error message. See syslog.h for
priority definitions.
value00-17 Parameters to be substituted into the printf string
format.
DESCRIPTION
The following routines are described in this man page:
ioqueuemessagetodriverdemon Queue message to I/O Driver Server
iospecifymaxdemonmessages Set maximum number of messages that
calling driver can have in server's
queue simultaneously
iounspecifymaxdemonmessages Release previously allocated server
messages
ioqueuemessagetogenericdemon Queue message to Generic Server
iospecifymaxgenericdemonmessages
Inform Generic Server of maximum
number of messages that calling
driver will have in server's queue
iounspecifymaxgenericdemonmessages
Remove specified number of messages
from generic server's free list
ioerrlogerror Format message and copy it into
error queue element and place on
ready queue
Overview to Driver Server and Generic Server Routines
Driver servers (daemons) and generic servers are classes of server
processes that drivers use to aid in processing asynchronous I/O
requests. They provide the recommended path for completing
asynchronous processing after the asynchronous request has been
satisfied by the device.
The two classes of server processes have exactly the same interface
and method of operation. Each class has a global queue on which
requests are placed. You put requests on these queues by calling
ioqueuemessagetodriverdemon or
ioqueuemessagetogenericdemon. A request comprises a pointer to
a routine to execute and an argument to be passed to the routine.
Server processes continually remove and process entries from the
request queue by calling the routine with the specified argument.
Because more than one server process may be removing requests from
the same queue, multiple requests may be executed in parallel on
systems with multiple processors. Each request, however, is only
executed once and by a single server. All the server processes
working off the same queue are in the same class. Note that the
requester's routine will run in the server's context not in the
requester's context.
The two classes of servers differ in what kinds of operations the
routine in the request may perform. Routines in Driver Server
requests must not perform any operation that might have to wait for
the completion of a disk I/O operation. For example, such routines
may not cause a page fault, because servicing the page fault may
require waiting for a disk I/O to complete. In addition, such
routines must not directly or indirectly send signals or perform
terminal-related operations. Because of all these restrictions, the
Driver Servers will generally only be used by disk device drivers.
Routines in Generic Server requests are allowed to wait on disk I/O,
send signals, and perform terminal-related operations. The lesser
restrictions make the Generic Servers usable by terminal-handling
code and other higher level parts of the system.
CAUTION: Disk device drivers must not use the Generic Servers
because a deadlock condition could result.
As with time-outs, the kernel needs a certain amount of space to
process server messages and this space is allocated dynamically at
run-time. You must declare the maximum space needed by calling
iospecifymaxdemonmessages (for driver server messages) and/or
iospecifymaxgenericdemonmessages (for generic server messages)
before you send any messages to the corresponding server.
Constants and Data Structures
These routines do not require special constants or data structures.
ioerrlogerror
If an error queue element is available, the indicated message is
formatted and copied into it, and the element is placed on the ready
queue.
If the error server syslogd has not opened the err pseudodevice, the
message is formatted and printed on the console. If an empty record
is available, the priority number and the message are formatted into
it. Long messages are truncated. The formatted record is placed on
the ready queue, and the eventcounter is advanced. If there are no
available records, the message is ignored.
ioqueuemessagetodriverdemon
This routine queues a message to the I/O Driver Server. A free
message is allocated from the Driver Server free list, filled in with
the arguments given, and queued to the I/O Driver Server queue.
If doadvance is TRUE and the queue is empty, the null eventcounter
pointer is returned and the server eventcounter will be advanced by
one.
If doadvance is FALSE, the server eventcounter is not advanced under
any circumstances. Rather, if the message queued is the only message
in the queue, the address of the server eventcounter is returned.
Otherwise, the null eventcounter pointer is returned.
The doadvance boolean is needed to handle timeouts. When a driver's
timeout routine queues a message to the server, the eventcounter must
not be advanced because the await table lock is already held by the
await table routine that found the timeout entry. Instead, the
eventcounter address is passed all the way back to the await table
code, which will perform the advance when the await table is
unlocked.
ioqueuemessagetogenericdemon
This routine queues a message to the Generic Server. A free message
is allocated from the Generic Server free list, is filled in with the
arguments given, and queued to the Generic Server queue.
If the doadvance boolean is TRUE, the return value will be the null
eventcounter pointer and the Generic Server eventcounter will be
advanced if the message queue is the only message in the queue.
If the doadvance boolean is FALSE, the Generic Server eventcounter
is not advanced under any circumstances. Rather, if the message
queued is the only message in the queue, the address of the server
eventcounter is returned. Otherwise, the null eventcounter pointer
is returned.
The doadvance boolean is needed to handle timeouts. When a driver's
timeout routine queues a message to the server, the eventcounter must
not be advanced because the await table lock is already held by the
await table routine that found the timeout entry. Instead, the
eventcounter address is passed all the way back to the await table
code, which will perform the advance when the await table is
unlocked.
iospecifymaxdemonmessages
This routine defines the maximum number of messages that the calling
driver can have in the server's queue simultaneously.
The routine allocates space for the specified number of messages and
adds them to the server's free queue. It must be called by each
device driver before that driver sends a message to the server. A
given driver may make this call more than once if the maximum number
of messages grows.
In general, the maximum number of messages a driver will need depends
on the number of devices it must service and on the way the driver
handles and clears interrupts from those devices.
iospecifymaxgenericdemonmessages
This routine informs the Generic Server of the maximum number of
messages that the calling driver will have in the server's queue.
The routine allocates space for the specified number of messages and
adds them to the Generic Server's free queue. It must be called by
each device driver before that driver sends a message to the Generic
Server. A given driver may make this call more than once if the
maximum number of messages grows.
In general, the maximum number of messages a driver will need depends
on the number of devices it must service and on the way the driver
handles and clears interrupts from those devices.
iounspecifymaxdemonmessages
This routine tries to release some previously allocated server
messages. The routine removes the specified number of messages from
the server's free queue and deallocates the space.
Presumably this call, which should be done by the driver's
deconfiguration routine, will have the same count as that specified
by the specify routine called from the driver's configuration
routine.
iounspecifymaxgenericdemonmessages
This routine removes a specified number of messages from the generic
server's free list.
The routine attempts to remove the specified number of messages from
the generic server's free list. The routine is designed to be a
complement to the iospecifymaxgenericdemonmessages routine.
Presumably the maximum number of messages was specified by a driver
at configuration time and this will use the same message number and
be called at deconfiguration time.
DIAGNOSTICS
Return Value
For ioerrlogerror:
TRUE If an error queue element was available.
FALSE If no error queue element was available.
For the other routines: none.
Errors
None.
Abort Conditions
For ioqueuemessagetodriverdemon, the system may be halted with
the following halt code:
IOPANICDEMONFREELISTEMPTY
A free message could not be allocated from the Driver Server
free list when needed. A device driver has used more messages
than the number of messages it requested to be allocated for
the server. See iospecifymaxdemonmessages.
For ioqueuemessagetogenericdemon, the system may be halted with
the following halt code:
IOPANICGENERICDEMONFREELISTEMPTY
A free message could not be allocated from the Generic Server
free list when needed. The device driver has used more
messages than the number of messages it requested to be
allocated for the server.
SEE ALSO
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)