STREAMS Modules and Drivers 0890426-020 February 1998 Copyright 1998 by Concurrent Computer Corporation. All rights reserved. This publication or any part thereof is intended for use with Concurrent products by Concurrent personnel, customers, and end–users. It may not be repro- duced in any form without the written permission of the publisher. The information contained in this document is believed to be correct at the time of publication. It is subject to change without notice. Concurrent Computer Corporation makes no warranties, expressed or implied, concerning the infor- mation contained in this document. To report an error or comment on a specific portion of the manual, photocopy the page in question and mark the cor- rection or comment on the copy. Mail the copy (and any additional comments) to Concurrent Computer Corporation, 2101 W. Cypress Creek Road, Ft. Lauderdale, FL 33309–1892. Mark the envelope “Attention: Publications Department.” This publication may not be reproduced for any other reason in any form without written permission of the publisher. This document is based on copyrighted documentation from Novell, Inc. and is reproduced with permission. Ethernet is a registered trademark of Xerox Corporation. UNIX is a registered trademark, licensed exclusively by X/Open Company Ltd. Printed in U. S. A. Revision History: Level: Effective With: Original Release -- August 1994 000 PowerMAX OS 1.1 Previous Release-- February 1997 010 PowerMAX OS 4.1 Current Release -- February 1998 020 PowerMAX OS 4.2 Preface Scope of Manual This manual provides a programming guide for the PowerMAX OS STREAMS facility. It contains reference information and procedures for developing operating system communi- cation services. Structure of Manual This manual consists of eleven chapters, a glossary, and an index. A brief description of the chapters is presented as follows: • Chapter 1 provides an introduction to the manual and an overview of the STREAMS facility. It describes STREAMS components and highlights the main benefits of STREAMS. • Chapter 2 explains the STREAMS-related system call interface. • Chapter 3 provides additional information on the STREAMS I/O structure and data flow and contrasts it with the conventional character I/O mecha- nism. • Chapter 4 describes the put and service procedures and provides an asynchronous protocol Stream example. • Chapter 5 describes the STREAMS message structure and message queues and priorities. It explains the procedures and interfaces for sending mes- sages. • Chapter 6 provides an overview of STREAMS modules and drivers, explains the ioctl mechanism, and describes the device driver/driver-ker- nel interfaces (DDI/DKI) and the STREAMS interface. It also explains how to configure the system for STREAMS modules and drivers. • Chapter 7 explains how to develop STREAMS modules. • Chapter 8 explains how to develop STREAMS drivers. • Chapter 9 explains how STREAMS multiplexing configurations are cre- ated and discusses multiplexing drivers. • Chapter 10 describes the STREAMS-based Transport Provider Interface (TPI). • Chapter 11 describes the STREAMS-based Data Link Provider Interface (DLPI). The glossary contains definitions of technical terms that are important to understanding the concepts presented in this book. iii STREAMS Modules and Drivers The index contains an alphabetical reference to key terms and concepts and numbers of pages where they occur in text. Syntax Notation The following notation is used throughout this guide: italic Books, reference cards, and items that the user must specify appear in italic type. Special terms may also appear in italic. list bold User input appears in list bold type and must be entered exactly as shown. Names of directories, files, commands, options and man page references also appear in list bold type. list Operating system and program output such as prompts and mes- sages and listings of files and programs appears in list type. [] Brackets enclose command options and arguments that are optional. You do not type the brackets if you choose to specify such option or arguments Referenced Publications The following publications are referenced in this document: 0890425 Device Driver Programming On line Command Reference On line Operating System API Reference On line System Files and Devices Reference On line Device Driver Reference iv Contents Chapter 1 Introduction to STREAMS Introduction . 1-1 References . 1-1 Notation Conventions . 1-2 Overview of STREAMS . 1-3 Basic Stream Operations . 1-5 STREAMS components. 1-7 Queues . 1-7 Messages. 1-8 Message Types . 1-8 Message Queuing Priority. 1-9 Modules . 1-10 Drivers . 1-12 Multiplexing . 1-12 Benefits of STREAMS . 1-17 Standardized Service Interfaces . 1-17 Manipulating Modules . 1-17 Protocol Portability . 1-18 Protocol Substitution. 1-18 Protocol Migration . 1-18 Module Reusability . 1-19 Chapter 2 STREAMS System Calls Introduction . 2-1 STREAMS System Calls . 2-1 getmsg and putmsg . 2-2 poll. 2-2 STREAM Construction . 2-2 Opening a STREAMS Device File. 2-4 Creating a STREAMS-based Pipe . 2-7 Adding and Removing Modules. 2-8 Closing the Stream . 2-9 Stream Construction Example . 2-9 Inserting Modules . 2-10 Module and Driver Control . 2-11 Chapter 3 STREAMS Input/Output Introduction . 3-1 The STREAMS Subsystem . 3-1 Modularity. 3-2 Messages . 3-2 Message Contents Type . 3-2 Message Priority. 3-3 v STREAMS Modules and Drivers Message Structure. 3-3 Structure Declarations . 3-3 STREAMS Entry Points . 3-4 Open Routine . 3-4 The CLONE Driver . 3-5 Message Processing . 3-6 put Routine . 3-6 put Routine: Switch on Message Type . 3-7 put Routine: Flush Handling . 3-7 put Routine: I/O Control Commands. 3-7 put Routine: Data Output. 3-8 put Routine: Error Detection . 3-8 Service Routine. 3-9 Service Routine: Retrieve Message . 3-9 Service Routine: Check for Blocking . 3-9 Service Routine: Return Message to Queue . 3-9 Service Routine: Forward Message . 3-10 Close Routine . 3-10 Chapter 4 STREAMS Processing Routines Introduction . 4-1 Put Procedure . 4-1 Service Procedure . 4-2 Asynchronous Protocol Stream Example . 4-3 Read-Side Processing . ..