............................Contents


1. Introduction	1
..Introduction to This Guide	1
....Audience	1
....Organization	1
....Code Examples	3
....Conventions Used	3
....Other Documentation	4
2. Overview of STREAMS	5
..What Is STREAMS?	5
..Basic Streams Operations	9
..STREAMS Components	12
....Queues	12
....Messages	13
....Modules	16
....Drivers	18


..Multiplexing	18
..Benefits of STREAMS	23
....Standardized Service Interfaces	23
....Manipulating Modules	24
3. STREAMS Mechanism	29
..STREAMS Mechanism Overview	29
....STREAMS System Calls	30
..Stream Construction	30
....Opening a STREAMS Device File	33
....Creating a STREAMS-based Pipe	34
....Adding and Removing Modules	35
....Closing the Stream	35
....Stream Construction Example	36
4. STREAMS Processing Routines	43
..Put and Service Procedures	43
....Put Procedure	44
....Service Procedure	45
..An Asynchronous Protocol Stream Example	46
....Read-Side Processing	49
....Write-Side Processing	52
....Analysis	52
5. Messages	53
..Message Overview	53
....Message Types	53


....Expedited Data	55
..Message Structure	56
....Sending/Receiving Messages	59
....Control of Stream Head Processing	64
..Message Queues and Message Priority	66
....The queue Structure	70
....Message Processing	75
..Service Interfaces	82
....Service Interface Benefits	83
....Service Interface Library Example	86
..Message Allocation and Freeing	99
....Recovering From No Buffers	102
....Releasing Callback Requests	105
..Extended STREAMS Buffers	105
.... esballoc Example	108
6. Polling and Signaling	111
..Input/Output Polling	111
....Synchronous Input/Output	112
....Asynchronous Input/Output	116
....Signals	118
..Stream as a Controlling Terminal	119
....Job Control	119
....Allocation and Deallocation	122
....Hungup Streams	122


....Hangup Signals	122
....Accessing the Controlling Terminal	123
7. Overview of Modules and Drivers	125
..Module and Driver Environment	125
....Module and Driver Declarations	126
..Module and Driver ioctls	130
....General ioctl Processing	132
....I_STR ioctl Processing	134
....Transparent ioctl Processing	135
....Transparent ioctl Messages	138
....Transparent ioctl Examples	139
....I_LIST ioctl	151
..Flush Handling	153
....Flushing Priority Bands	156
....Device Driver Interface and Driver-Kernel Interface	158
....STREAMS Interface	159
..Configuring the System for STREAMS Drivers and Modules .	160
..Design Guidelines	160
....Data Structures	165
8. Modules	167
..Module Overview	167
....STREAMS Module Configuration	167
....Module Procedures	168
....Filter Module Example	172


..Flow Control	176
..Design Guidelines	179
9. Drivers	181
..Device Drivers	181
.....Overview of Drivers	181
.....Driver Classification	182
.....Writing a Driver	182
..STREAMS Drivers	184
.....STREAMS Driver Configuration	184
.....STREAMS Entry Points	185
..Printer Driver Example	187
.....Driver Flush Handling	190
..... Driver Interrupt	192
.....Driver Close	194
.....Driver Flow Control	194
..Cloning	195
.....Loop-Around Driver	198
..Design Guidelines	209
10. Multiplexing	211
..Overview of Multiplexing	211
.....Building a Multiplexer	212
.....Dismantling a Multiplexer	220
.....Routing Data Through a Multiplexer	222
..Connecting / Disconnecting Lower Streams	222


.....Connecting Lower Streams	223
.....Disconnecting Lower Streams	224
..Multiplexer Construction Example	225
..Multiplexing Driver	228
.....Upper Write Put Procedure	232
.....Upper Write Service Procedure	236
.....Lower Write Service Procedure	237
.....Lower Read Put Procedure	237
..Persistent Links	240
..Design Guidelines	244
11. STREAMS-Based Pipes and FIFOS	247
..Overview of Pipes and FIFOs	247
..Creating and Opening Pipes and FIFOs	248
.....Accessing Pipes and FIFOs	249
.....Flushing Pipes and FIFOs	252
.....Named Streams	252
.....Unique Connections	256
12. STREAMS-Based Terminal Subsystem	261
..Overview of Terminal Subsystem	261
.....Line-Discipline Module	263
.....Hardware Emulation Module	270
..STREAMS-based Pseudo-Terminal Subsystem	272
.....Line-Discipline Module	273
.....Pseudo-TTY Emulation Module - PTEM	274


.....Remote Mode	278
.....Packet Mode	278
.....Pseudo-TTY Drivers - ptm and pts	279
13. Multi-Threaded STREAMS	285
..MT STREAMS Overview	285
..MT STREAMS Framework	286
.....STREAMS Framework Integrity	287
.....Message Ordering	287
..Your MT Options	288
.....MT SAFE modules	288
.....MT UNSAFE modules	289
..Preparing to Port	289
.....Porting to SunOS 5.x	291
..MT SAFE Modules	292
.....MT STREAMS perimeters	292
.....Perimeter options	294
.....MT configuration	295
.....qprocson()/qprocsoff()	295
.....qtimeout()/qbufcall()	296
.....qwriter()	296
.....qwait()	297
.....Asynchronous Callbacks	297
.....Close Race Conditions	298
.....Module unloading and esballoc	298


.....Use of q_next	299
..MT SAFE Modules using Explicit Locks	299
.....Constraints when using locks	299
.....Preserving message ordering	300
..MT UNSAFE Modules	300
.....Modifying UNSAFE Drivers	301
.....Caveats	302
.....New facilities	303
..Old Facilities	303
.....spl	304
.....sleep/wakeup	304
..Sample Multi-threaded Device Driver	305
..Sample Multi-threaded Module with Outer perimeter	314
A. STREAMS Data Structures	323
..streamtab	323
..QUEUE Structures	324
..... queue	324
.....qinit	325
.....module_info	325
.....qband	326
..Message Structures	326
.....iocblk	327
.....copyreq	327
.....copyresp	328


..Other Structures	328
.....strioctl	328
.....linkblk	329
.....stroptions	329
B. Message Types	331
..Introduction	331
..Ordinary Messages	331
.....M_BREAK	331
.....M_CTL	332
.....M_DATA	332
.....M_DELAY	332
.....M_IOCTL	333
.....M_PASSFP	336
.....M_PROTO	336
.....M_RSE	337
.....M_SETOPTS	338
..High-Priority Messages	342
.....M_COPYIN	342
.....M_COPYOUT	343
.....M_ERROR	343
.....M_FLUSH	344
.....M_HANGUP	345
.....M_IOCACK	346
.....M_IOCDATA	346


.....M_IOCNAK	347
.....M_PCPROTO	348
.....M_PCRSE	348
.....M_PCSIG	348
.....M_READ	348
.....M_START and M_STOP	349
.....M_STARTI and M_STOPI	349
.....M_UNHANGUP	349
C. STREAMS Utilities	351
..Introduction	351
..Utility Descriptions	352
.....adjmsg - trim bytes in a message	352
.....allocb - allocate a message and data block	353
.....backq - get pointer to the queue behind a given queue	353
.....bcanput - test for flow control in the given priority band .	353
.....bcanputnext- test for flow control in the given priority band	353
.....bufcall - recover from failure of allocb	354
.....canput - test for room in a queue	354
.....canputnext - test for room in the next queue	355
.....copyb - copy a message block	355
.....copymsg - copy a message	355
.....datamsg - test whether message is a data message	356
.....dupb - duplicate a message block descriptor	356
.....dupmsg - duplicate a message	356


.....enableok - re-allow a queue to be scheduled for service /	357
.....esballoc - allocate message and data blocks	357
.....esbbcall - call function when buffer is available	358
.....flushband - flush the messages in a given priority band	358
.....flushq - flush a queue	358
.....freeb - free a single message block	358
.....freemsg - free all message blocks in a message	359
.....freezestr - freeze a stream	359
.....getq - get a message from a queue	359
.....insq - put a message at a specific place in a queue	360
.....linkb - concatenate two messages into one	361
.....msgdsize - get the number of data bytes in a message	361
.....msgpullup - concatenate bytes in a message	361
.....noenable - prevent a queue from being scheduled	361
.....OTHERQ - get pointer to the mate queue	361
.....pullupmsg - concatenate and align bytes in a message	362
.....put - call a STREAMS put procedure	362
.....putbq - return a message to the beginning of a queue	362
.....putctl - put a control message	363
.....putctl1 - put a control message with a one-byte parameter	363
.....putnext - put a message to the next queue	363
.....putnextctl - put a control message	363
.....putnextctl1 - put a control message	364
.....putq - put a message on a queue	364


.....qenable - enable a queue	365
.....qsize - find the number of messages on a queue	366
.....RD - get pointer to the read queue	366
.....rmvb - remove a message block from a message	366
.....rmvq - remove a message from a queue	367
.....strlog - submit messages for logging	367
.....testb - check for an available buffer	368
.....unbufcall - cancel a bufcall request	369
.....unfreezestr- unfreeze a stream	369
.....WR - get pointer to the write queue	369
..DKI Interface	369
..New MT perimeter utility routines	370
.....qbufcall - recover from failure of allocb	370
.....qunbufcall - cancel a qbufcall request	371
.....quntimeout - cancel a qtimeout request	371
.....qwait/qwait_sig -STREAMS perimeter wait routines	371
.....qwriter - asynchronous STREAMS perimeter upgrade	372
..Utility Routine Summary	373
D. Debugging	377
..Overview of Debugging Facilities	377
..Kernel Debug Printing	378
.....Console Messages	378
..STREAMS Error Logging	379
.....Error and Trace Logging	379


..Kernel Examination Tools	381
.....The crash(1M) Command	381
.....The adb(1) Command	382
.....The kadb(1M) Command	382
E. Configuration	383
..Introduction	383
..Configuring STREAMS Drivers and Modules	383
.. Data Structure Layout	384
.....modlinkage	384
.....modldrv	385
.....modlstrmod	385
.....dev_ops	385
.....cb_ops	386
.....streamtab	387
.....qinit	388
..Entry Points	388
.....pts example	388
.....STREAMS Module Configuration	394
.....Compilation	395
.....Kernel Loading	395
.....Checking module type	395
..Tunable Parameters	395
..Autopush Facility	396
.....User Interface	397


F. Manual Pages	401
......DDI/DKI Entry Points	402
......DDI/DKI Functions	403
......DDI/DKI Data Structures	405
Glossary	407
Index	I- 415

包含在

尋找其他文件

熱門支援資源

............................Contents