1srv(9E) Driver Entry Points srv(9E)
2
6 srv - service queued messages
7
9 #include <sys/types.h>
10 #include <sys/stream.h>
11 #include <sys/stropts.h>
12 #include <sys/ddi.h>
13 #include <sys/sunddi.h>
14 intprefixrsrv(queue_t *q/* read side */
18 intprefixwsrv(queue_t *q/* write side */
21
24 Architecture independent level 1 (DDI/DKI). This entry point is
25 required for STREAMS.
26
28 q Pointer to the queue(9S) structure.
29
32 The optional service srv() routine may be included in a STREAMS module
33 or driver for many possible reasons, including:
34 o to provide greater control over the flow of messages in a
36 stream;
37 o to make it possible to defer the processing of some messages
39 to avoid depleting system resources;
40 o to combine small messages into larger ones, or break large
42 messages into smaller ones;
43 o to recover from resource allocation failure. A module's or
45 driver's put(9E) routine can test for the availability of a
46 resource, and if it is not available, enqueue the message
47 for later processing by the srv() routine.
48 A message is first passed to a module's or driver's put(9E) routine,
51 which may or may not do some processing. It must then either:
52 o Pass the message to the next stream component with put‐
54 next(9F).
55 o If a srv() routine has been included, it may call putq(9F)
57 to place the message on the queue.
58 Once a message has been enqueued, the STREAMS scheduler controls the
61 service routine's invocation. The scheduler calls the service routines
62 in FIFO order. The scheduler cannot guarantee a maximum delay srv()
63 routine to be called except that it will happen before any user level
64 process are run.
65 Every stream component (stream head, module or driver) has limit values
68 it uses to implement flow control. Each component should check the tun‐
69 able high and low water marks to stop and restart the flow of message
70 processing. Flow control limits apply only between two adjacent compo‐
71 nents with srv() routines.
72 STREAMS messages can be defined to have up to 256 different priorities
75 to support requirements for multiple bands of data flow. At a minimum,
76 a stream must distinguish between normal (priority zero) messages and
77 high priority messages (such as M_IOCACK). High priority messages are
78 always placed at the head of the srv() routine's queue, after any other
79 enqueued high priority messages. Next are messages from all included
80 priority bands, which are enqueued in decreasing order of priority.
81 Each priority band has its own flow control limits. If a flow con‐
82 trolled band is stopped, all lower priority bands are also stopped.
83 Once the STREAMS scheduler calls a srv() routine, it must process all
86 messages on its queue. The following steps are general guidelines for
87 processing messages. Keep in mind that many of the details of how a
88 srv() routine should be written depend of the implementation, the
89 direction of flow (upstream or downstream), and whether it is for a
90 module or a driver.
91 1. Use getq(9F) to get the next enqueued message.
93 2. If the message is high priority, process (if appropriate)
95 and pass to the next stream component with putnext(9F).
96 3. If it is not a high priority message (and therefore subject
98 to flow control), attempt to send it to the next stream com‐
99 ponent with a srv() routine. Use bcanputnext(9F) to deter‐
100 mine if this can be done.
101 4. If the message cannot be passed, put it back on the queue
103 with putbq(9F). If it can be passed, process (if appropri‐
104 ate) and pass with putnext().
105
107 Ignored.
108
110 put(9E), bcanput(9F), bcanputnext(9F), canput(9F), canputnext(9F),
111 getq(9F), nulldev(9F), putbq(9F), putnext(9F), putq(9F), qinit(9S),
112 queue(9S)
113 Writing Device Drivers
116 STREAMS Programming Guide
119
121 Each stream module must specify a read and a write service srv() rou‐
122 tine. If a service routine is not needed (because the put() routine
123 processes all messages), a NULL pointer should be placed in module's
124 qinit(9S) structure. Do not use nulldev(9F) instead of the NULL
125 pointer. Use ofnulldev(9F) for a srv() routine can result in flow con‐
126 trol errors.
127SunOS 5.11 12 Nov 1992 srv(9E)