server_messages(3K) DG/UX R4.11MU05 server_messages(3K)
NAME
server_messages: io_queue_message_to_driver_demon,
io_specify_max_demon_messages, io_unspecify_max_demon_messages,
io_queue_message_to_generic_demon,
io_specify_max_generic_demon_messages,
io_unspecify_max_generic_demon_messages, io_err_log_error - send
messages to driver and generic servers and to error logger
SYNOPSIS
#include "/usr/src/uts/aviion/ii/i_io.h"
#include "/usr/src/uts/aviion/ii/i_sc.h"
boolean_type io_err_log_error (priority, format, value_00, value_01,
value_02, value_03, value_04, value_05, value_06,
value_07, value_08, value_09, value_10, value_11,
value_12, value_13, value_14, value_15, value_16,
value_17)
uint32e_type priority; /* READ ONLY */
char_ptr_type format; /* READ ONLY */
bit32e_type value_00; /* READ ONLY */
bit32e_type value_01; /* READ ONLY */
bit32e_type value_02; /* READ ONLY */
bit32e_type value_03; /* READ ONLY */
bit32e_type value_04; /* READ ONLY */
bit32e_type value_05; /* READ ONLY */
bit32e_type value_06; /* READ ONLY */
bit32e_type value_07; /* READ ONLY */
bit32e_type value_08; /* READ ONLY */
bit32e_type value_09; /* READ ONLY */
bit32e_type value_10; /* READ ONLY */
bit32e_type value_11; /* READ ONLY */
bit32e_type value_12; /* READ ONLY */
bit32e_type value_13; /* READ ONLY */
bit32e_type value_14; /* READ ONLY */
bit32e_type value_15; /* READ ONLY */
bit32e_type value_16; /* READ ONLY */
bit32e_type value_17; /* READ ONLY */
vp_ec_ptr_type io_queue_message_to_driver_demon
(completion_routine_ptr, data, do_advance)
io_completion_routine_ptr_type completion_routine_ptr; /*READ ONLY*/
bit32e_type data; /*READ ONLY*/
boolean_type do_advance; /*READ ONLY*/
vp_ec_ptr_type io_queue_message_to_generic_demon
(completion_routine_ptr, data, do_advance)
io_completion_routine_ptr_type completion_routine_ptr; /*READ ONLY*/
bit32e_type data; /*READ ONLY*/
boolean_type do_advance; /*READ ONLY*/
void io_specify_max_demon_messages (count)
uint32_type count; /*READ ONLY*/
void io_specify_max_generic_demon_messages (count)
uint32_type count; /*READ ONLY*/
void io_unspecify_max_demon_messages (count)
uint32_type count /*READ ONLY*/
void io_unspecify_max_generic_demon_messages (count)
uint32_type count /*READ ONLY*/
where:
completion_routine_ptr
A pointer to the value to go in the completion_routine
field of the message. When the server dequeues this
message, it calls the routine pointed to by the
completion_routine_ptr 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.
do_advance A boolean indicating whether to advance the server
eventcounter. See io_queue_message_to_driver_demon and
io_queue_message_to_generic_demon 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.
value_00-17 Parameters to be substituted into the printf string
format.
DESCRIPTION
The following routines are described in this man page:
io_queue_message_to_driver_demon Queue message to I/O Driver Server
io_specify_max_demon_messages Set maximum number of messages that
calling driver can have in server's
queue simultaneously
io_unspecify_max_demon_messages Release previously allocated server
messages
io_queue_message_to_generic_demon Queue message to Generic Server
io_specify_max_generic_demon_messages
Inform Generic Server of maximum
number of messages that calling
driver will have in server's queue
io_unspecify_max_generic_demon_messages
Remove specified number of messages
from generic server's free list
io_err_log_error 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
io_queue_message_to_driver_demon or
io_queue_message_to_generic_demon. 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
io_specify_max_demon_messages (for driver server messages) and/or
io_specify_max_generic_demon_messages (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.
io_err_log_error
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.
io_queue_message_to_driver_demon
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 do_advance is TRUE and the queue is empty, the null eventcounter
pointer is returned and the server eventcounter will be advanced by
one.
If do_advance 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 do_advance 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.
io_queue_message_to_generic_demon
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 do_advance 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 do_advance 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 do_advance 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.
io_specify_max_demon_messages
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.
io_specify_max_generic_demon_messages
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.
io_unspecify_max_demon_messages
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.
io_unspecify_max_generic_demon_messages
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 io_specify_max_generic_demon_messages 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 io_err_log_error:
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 io_queue_message_to_driver_demon, the system may be halted with
the following halt code:
IO_PANIC_DEMON_FREE_LIST_EMPTY
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 io_specify_max_demon_messages.
For io_queue_message_to_generic_demon, the system may be halted with
the following halt code:
IO_PANIC_GENERIC_DEMON_FREE_LIST_EMPTY
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)