bufcall(D3)bufcall(D3)NAMEbufcall - call a function when a buffer becomes available
SYNOPSIS
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/ddi.h>
toid_t bufcall(uint_t size, int pri, void (*func)(), long arg);
Arguments
size
Number of bytes in the buffer to be allocated (from the failed
allocb(D3) request).
priPriority of the allocb allocation request.
func
Function or driver routine to be called when a buffer becomes
available.
argArgument to the function to be called when a buffer becomes available.
DESCRIPTION
When a buffer allocation request fails, the function bufcall can be used
to schedule the routine, func, to be called with the argument, arg, when
a buffer of at least size bytes becomes available. bufcall serves, in
effect, as a timeout call of indeterminate length.
Return Values
On success, bufcall returns a non-zero value that identifies the
scheduling request. On failure, bufcall returns 0.
USAGE
When func runs, all interrupts from STREAMS devices will be blocked. On
multiprocessor systems, when func runs all interrupts from STREAMS
devices will be blocked on the processor on which func is running. func
will have no user context and may not call any function that sleeps.
Even when func is called, allocb can still fail if another module or
driver had allocated the memory before func was able to call allocb.
The pri argument is no longer used but is retained for compatibility.
The non-zero identifier returned by bufcall may be passed to
unbufcall(D3) to cancel the request.
Level
Base or Interrupt.
Page 1
bufcall(D3)bufcall(D3)
Synchronization Constraints
Does not sleep.
Driver-defined basic locks, read/write locks, and sleep locks may be held
across calls to this function.
Example
The purpose of this service routine [see srv(D2)] is to add a header to
all M_DATA messages. We assume only M_DATA messages are added to its
queue. Service routines must process all messages on their queues before
returning, or arrange to be rescheduled.
While there are messages to be processed (line 19), we check to see if we
can send the message on in the stream. If not, we put the message back
on the queue (line 21) and return. The STREAMS flow control mechanism
will re-enable us later when messages can be sent. If canput(D3)
succeeded, we try to allocate a buffer large enough to hold the header
(line 24). If no buffer is available, the service routine must be
rescheduled later, when a buffer is available. We put the original
message back on the queue (line 26) and use bufcall to attempt the
rescheduling (lines 27 and 28). If bufcall succeeds, we set the m_type
field in the module's private data structure to BUFCALL. If bufcall
failed, we use itimeout(D3) to reschedule us instead (line 30). modcall
will be called in about a half second [drv_usectohz(500000)]. When the
rescheduling has been done, we return.
When modcall runs, it will set the m_type field to zero, indicating that
there is no outstanding request. Then the queue's service routine is
scheduled to run by calling qenable(D3).
If the buffer allocation is successful, we initialize the header (lines
37-39), make the message type M_PROTO (line 41), link the M_DATA message
to it (line 42), and pass it on (line 43).
See unbufcall(D3) for the other half of this example.
1 struct hdr {
2 uint_t h_size;
3 int h_version;
4 };
5 struct mod {
6 long m_id;
7 char m_type;
...
8 };
9 #define TIMEOUT 1
10 #define BUFCALL 2
...
11 modsrv(q) /* assume only M_DATA messages enqueued here */
12 queue_t *q;
13 {
14 mblk_t *bp;
Page 2
bufcall(D3)bufcall(D3)
15 mblk_t *mp;
16 struct hdr *hp;
17 struct mod *modp;
18 modp = (struct mod *)q->q_ptr;
19 while ((mp = getq(q)) != NULL) {
20 if (!canput(q->q_next)) {
21 putbq(q, mp);
22 return;
23 }
24 bp = allocb(sizeof(struct hdr), BPRI_MED);
25 if (bp == NULL) {
26 putbq(q, mp);
27 modp->m_id = bufcall(sizeof(struct hdr), BPRI_MED,
28 modcall, (long)q);
29 if (modp->m_id == 0) {
30 modp->m_id = itimeout(modcall, (long)q,
31 drv_usectohz(500000), plstr);
32 modp->m_type = TIMEOUT;
33 } else {
34 modp->m_type = BUFCALL;
35 }
36 return;
37 }
38 hp = (struct hdr *)bp->b_wptr;
39 hp->h_size = msgdsize(mp);
40 hp->h_version = 1;
41 bp->b_wptr += sizeof(struct hdr);
42 bp->b_datap->db_type = M_PROTO;
43 bp->b_cont = mp;
44 putnext(q, bp);
45 }
46 }
47 modcall(q)
48 queue_t *q;
49 {
50 struct mod *modp;
51 modp = (struct mod *)q->q_ptr;
52 modp->m_type = 0;
53 qenable(q);
54 }
REFERENCESallocb(D3), esballoc(D3), esbbcall(D3), itimeout(D3), unbufcall(D3)
Page 3
