Writing Loadable Kernel Servers NeXT Developer's Library NeXTstep Draw upon the library of software contained in NeXTstep to develop your applications. Integral to this development environment are the Application Kit and Display PostScript. Concepts A presentation of the principles that define NeXTstep, including user interface design, object-oriented programming, event handling, and other fundamentals. Reference, Volumes 1 and 2 Detailed, comprehensive descriptions of the NeXTstep Application Kit software. Sound, Music, and Signal Processing Let your application listen, talk, and sing by using the Sound Kit and the Music Kit. Behind these capabilities is the DSP56001 digital signal processor. Independent of sound and music, scientific applications can take advantage of the speed of the DSP. Concepts An examination of the design of the sound and music software, including chapters on the use of the DSP for other, nonaudio uses. Reference Detailed, comprehensive descriptions of each piece of the sound, music, and DSP software. ~ NeXT Development Tools A description of the tools used in developing a NeXT application, including the Edit application, the compiler and debugger, and some performance tools. ~ NeXT Operating System Software A description of NeXT's operating system, Mach. In addition, other low-level software is discussed. ~ Writing Loadable Kernel Servers How to write loadable kernel servers, such as device drivers and network protocols. ~ NeXT Technical Summaries Brief summaries of reference information related to NeXTstep, sound, music, and Mach, plus a glossary and indexes. ~ Supplemental Documentation Information about PostScript, RTF, and other file formats useful to application developers. Writing Loadable Kernel Servers We at NeXT Computer have tried to make the information contained in this manual as accurate and reliable as possible. Nevertheless, NeXT disclaims any warranty of any kind, whether express or implied, as to any matter whatsoever relating to this manual, including without limitation the merchantability or fitness for any particular purpose. NeXT will from time to time revise the software described in this manual and reserves the right to make such changes without obligation to notify the purchaser. In no event shall NeXT be liable for any indirect, special, incidental, or consequential damages arising out of purchase or use of this manual or the information contained herein. Copyright ©1990 by NeXT Computer, Inc. All Rights Reserved. [1386] The NeXT logo and NeXTstep are registered trademarks of NeXT Computer, Inc., in the U.S. and other countries. NeXT, NeXTcube, NeXTstation, NetInfo, NeXTbus, and Workspace Manager are trademarks of NeXT Computer, Inc. PostScript is a registered trademark of Adobe Systems Incorporated. UNIX is a registered trademark of AT&T. NFS is a registered trademark of Sun Mlcrosystems; Inc. All other trademarks mentioned belong to their respective owners. Notice to U.S. Government End Users: Restricted Rights Legends For civilian agencies: This software is licensed only with "Restricted Rights" and use, reproduction, or disclosure is subject to restrictions set forth in subparagraph (a) through (d) of the Commercial Computer Software-Restricted Rights clause at 52.227 -19 of the Federal Acquisition Regulations. Unpublished-rights reserved under the copyright laws of the United States and other countries. For units of the Department of Defense: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c )(l)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. NeXT Computer, Inc., 900 Chesapeake Drive, Redwood City, CA 94063. Manual written by Kathy Walrath Edited by Caroline Rose and Helen Casabona Book design by Eddie Lee Illustrations by Jeff Yaksick and Don Donoughe Production by Adrienne Wong, Jennifer Yu, and Katherine Arthurs Publications management by Cathy Novak Reorder Product #N6007B Contents Introduction 1-1 Chapter 1: Overview 1-1 Before You Start 1-1 Get the Documentation You Need 1-2 Get the Hardware You Need 1-3 Choose an Interface for Your Server 1-3 Software Support 1-3 The NeXTbus Probe 1-4 The Mach Interface Generator (MiG) 1-4 The Kernel-Server Utility (kl_util) 1-4 The Kernel-Server Log Command (kIJog) 1-4 The Kernel Debugger (KGDB) 1-4 Concepts 1-4 Loadable Kernel Servers 1-6 The Kernel-Server Loader 1-6 The Hardware 1-7 NeXTbus Address Space 1-8 The NeXTbus Interface Chip (NBIC) 2-1 Chapter 2: Designing Kernel Servers 2-1 Rules of Thumb 2-2 Testing Your Hardware 2-2 Building In Debugging Code 2-2 Displaying Debugging Information 2-2 kern_ servJogO 2-3 printfO 2-3 Checking Assumptions 2-3 ASSERTO 2-4 probeJbO 2-4 Kernel-Server Loader Requirements 2-4 The Instance Variable 2-5 Writing Routines for kernJoader to Call 2-5 Writing an Interrupt Handler 2-7 Considerations for Message-Based Kernel Servers 2-8 Considerations for UNIX-Based Kernel Servers 2-8 UNIX Entry Points 2-8 Character Device Entry Points 2-9 Block Device Entry Points 2-10 Inserting UNIX Servers into Device Switch Tables 2-11 Functions Supplied by NeXT 2-12 Communicating with the Hardware 2-12 Mapping from Physical to Virtual Memory Addresses 2-13 NeXTbus Byte Ordering 2-13 CPU Board NBIC Registers 2-14 NBIC Control Register 2-14 NeXTbus Board Registers 2-15 Identification Bytes (NBIC ID Register) 2-17 Interrupt Byte 2-18 Interrupt Mask Byte 2-18 Workaround for Intercepted NeXTbus Addresses 3-1 Chapter 3: Testing and Debugging Kernel Servers 3-1 Booting the Computer 3-1 Generating Interrupts 3-1 Generating a Non-Maskable Interrupt (NMI) 3-1 Resetting the CPU 3-2 The System Console 3-2 The NMI Mini-Monitor Window 3-2 The Panic Window 3-3 The ROM Monitor Window 3-3 The NeXTbus Probe 3-4 Other Tools 4-1 Chapter 4: Network-Related Kernel Servers 4-1 Overview 4-2 Network Objects 4-2 Network Buffers (netbufs) 4-3 Network Interfaces (netifs) 4-3 Functions You Should Implement 4-4 Callback Function 4-5 Initialization Function 4-5 Input Function 4-7 Output Function 4-8 Getbuf Function 4-9 Control Function 4-11 Notes for Specific Interfaces 4-11 Ethernet Interfaces 4-11 TCP/IP Interfaces 5-1 Chapter 5: C Functions 5-1 General Functions 5-51 Network Functions A-I Appendix A: The Kernel-Server Loader A-I Starting kernJoader A-2 Creating the Relocatable Object File A-4 Command Scripts B-1 Appendix B: The Kernel-Server Utility C-l Appendix C: The Kernel-Server Log Command D-l Appendix D: The Kernel Debugger D-2 Setting Up the Hardware D-2 Setting Up the Files D-2 Files Needed by the Slave Computer D-2 Files Needed by the Master Computer D-3 Starting Up KGDB D-5 Debugging with KGDB D-5 Ending the Debugging Session E-l Appendix E: The ROM Monitor and NMI Mini-Monitor E-I ROM Monitor Commands E-l Open Address Register E-2 Open Data Register E-2 Open Processor Register E-3 Open System Register E-3 Examine Memory Locations E-4 Open Function Code E-5 Set Input Radix E-5 NMI Mini-Monitor Commands E-5 Set or Examine Any Kernel Flag F-l Appendix F: Summary of Kernel Functions F-l General Functions F-I Time Functions F-I Memory Functions F-2 Critical Section and Synchronization Functions F-2 General Task and Thread Functions F-2 Port and Message Functions F-3 Hardware Interface Functions F-3 Logging and Debugging Functions F-4 Miscellaneous Functions F-4 Network Functions FA Netif Functions F-5 Netbuf Functions F-6 Miscellaneous Functions Index Introduction This manual describes how to write loadable kernel servers for NeXT™ computers. It's part of a collection of manuals called the NeXT Developer's Library; the illustration on the first page of this manual shows the complete set of manuals in this Library. This manual describes how to write loadable kernel servers for NeXT computers. Loadable kernel servers are the only way for third-party developers to add functionality (such as device drivers) to the NeXT Mach kernel. To write a loadable kernel server, you must be able to program in C. Depending on the kind of loadable kernel server you're writing, you probably don't need to be familiar with UNIX@ internals, but a general background in writing interrupt-driven device drivers or networking protocols is useful. Some topics aren't covered here in detail; instead, you're referred to a generally available book on the subject, or to an on-line source of the information. For example, Egan and Teixeira's Writing a UNIX Device Driver describes writing UNIX-style drivers and gives general driver-writing tips; those subjects aren't described in detail in this manual. A version of this manual is stored on-line in the NeXT Digital Library (which is described in the user's manual NeXT Applications). The Digital Library also contains Release Notes that provide last-minute information about the latest release of the software. How This Manual is Organized The first four chapters of this manual describe different aspects of developing loadable kernel servers, with Chapter 4 concentrating on network-related kernel servers. Chapter 5 provides detailed descriptions of each C function you can use inside a loadable kernel server; these functions are summarized in Appendix F. Appendices A through E explain how to use several programs, such as the KGDB kernel debugger. lntro-l Conventions Syntax Notation Where this manual shows the syntax of a function, command, or other programming element, the use of bold, italic, square brackets [ ], and ellipsis has special significance, as described here. Bold denotes words or characters that are to be taken literally (typed as they appear).