Return to README.rtf CVS log

Up to [Apple Darwin 0.x] / driverkit / Examples / loadable

Annotation of driverkit/Examples/loadable/README.rtf, revision 1.1

1.1     ! root        1: {\rtf0\ansi{\fonttbl\f0\fmodern Courier;\f1\fmodern Ohlfs;}
        !             2: \paperw13040
        !             3: \paperh9540
        !             4: \margl120
        !             5: \margr120
        !             6: {\colortbl;\red0\green0\blue0;}
        !             7: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f0\b\i0\ulnone\fs24\fc0\cf0 General Information
        !             8: \b0 \
        !             9: \
        !            10: The purpose of this example is to illustrate the technique of starting up a kernel-level driver using the user-level device configuration mechanism. The operation of this example is as follows:\
        !            11: \
        !            12: 
        !            13: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-720\li720\fc0\cf0 1)   The user-level device configuration utility, Config, starts up a user level program called myDriver, implemented in this example in the User/ subdirectory. The myDriver program is not the actual device driver; it's merely an agent which facilitates loading the kernel-level driver into the kernel and passing the device port obtained from Config down to the kernel-level driver. (Normally, Config starts up user-level drivers early in the boot process. For running this example, the configutil utility may be used to force this driver startup action to happen interactively. This procedure is described below.)\
        !            14: 
        !            15: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \
        !            16: 
        !            17: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-720\li720\fc0\cf0 2)   The myDriver executable obtains its device port from Config in the normal manner. \
        !            18: 
        !            19: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \
        !            20: 
        !            21: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-720\li720\fc0\cf0 3)   MyDriver then loads the loadable kernel server (LKS) called myHandler_reloc, implemented in the Kernel/ subdirectory of this example, into the kernel. myHandler_reloc contains two parts: one is myHandler, which is a standard loadable kernel "handler" module. The other is myDevice, which is the actual IODevice-style driver which will perform I/O to/from this device.\
        !            22: \
        !            23: 4)     MyDriver uses RPCs to pass the device port down to myHandler and to cause basic device driver initialization. \
        !            24: \
        !            25: 5)     MyHandler, since it is running in its own kernel-level task (
        !            26: \b not
        !            27: \b0  the driverkit's I/O task), uses the convertPortToIOTask() function to convert the device port obtained from myDriver into an I/O task port. The result of this is passed to myDevice, the actual IODevice-style driver. \
        !            28: \
        !            29: 6)     The initDevice() RPC is sent from myDriver (in user space) down to the myHandler, which calls myDevice's -init method. At this time, myDevice has a valid devicePort and can map in its device page and perform actual I/O. \
        !            30: \
        !            31: 
        !            32: \b Usage notes\
        !            33: \
        !            34: 
        !            35: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 [This section is highly dependent on system type, hardware configuration, and whether or not the target system contains a NeXT Laser Printer driver.]\
        !            36: 
        !            37: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-720\li720\fc0\cf0 \
        !            38: 
        !            39: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b0\fc1\cf1 To run this example, do the following:\
        !            40: \
        !            41: 
        !            42: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-720\li720\fc0\cf0 1)   Compile the whole example by typing 'make' in the directory containing this README file. \
        !            43: \
        !            44: 2)     Place a symlink in /usr/Devices called devr_0003_0100_myDriver which points to the executable of myDriver in this example. This executable is in User/m88kdebug/myDriver relative to the directory containing this README. This symlink overrides the existing printer driver. \
        !            45: \
        !            46: 3)     Use the configutil program to instruct Config to delete its knowledge of the printer driver. Type the following command as root:\
        !            47: \
        !            48: 
        !            49: \fs20\fc1\cf1  # /usr/bin/configutil t ffff0001 30000\
        !            50: 
        !            51: \fs24\fc0\cf0  \
        !            52: 4)     Kill the printer driver if it is currently running. Use ps to find the printer driver's PID, like this:\
        !            53: \
        !            54: 
        !            55: \fs20\fc1\cf1  # ps auxw | grep printer\
        !            56: 
        !            57: \fc0\cf0       root       246   1.8  0.3 1.89M  216K p2 S     0:00 grep printer\
        !            58: 
        !            59: \fc1\cf1       root       189   0.0  1.0 3.41M  656K p3 S     0:02 /usr/Devices/devr_0003_0001_printerDriver\
        !            60: 
        !            61: \fs24\fc0\cf0 \
        !            62:        Then kill the printer driver.\
        !            63:        \
        !            64: 
        !            65: \fs20\fc1\cf1  # kill 189\
        !            66: 
        !            67: \fs24\fc0\cf0  \
        !            68: 5)     Use the configutil program to instruct Config to rescan for new devices. \
        !            69: \
        !            70: 
        !            71: \fs20\fc1\cf1  # /usr/bin/configutil s\
        !            72: 
        !            73: \fs24\fc0\cf0 \
        !            74:        This will cause Config to attempt to restart a driver for the printer device. Since the symlink created in step 2 has a higher revision number (0100) than the original printer device, our example driver will be started instead of the standard printer driver. \
        !            75:        \
        !            76:        This will cause the entire mechanism described above (under "General Information" to execute. \
        !            77:        \
        !            78:        \
        !            79: 
        !            80: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0\cf0 Files
        !            81: \b0 \
        !            82: \
        !            83: user/\
        !            84: \
        !            85:     myDriver.c: Simple program which is started up by Config. This program loads\
        !            86:        in the actual driver into the kernel, obtains a device port from Config,\
        !            87:        and passes the device port down to the kernel-level driver.\
        !            88:        \
        !            89:     km_com.[mh]: Interface to libkernload, which simplifies the mechanism of loading\
        !            90:        an LKS into the kernel from a C program.\
        !            91:        \
        !            92:     m88kdebug/myHandler.h:\
        !            93:        Generated by MIG. Defines C interface to public RPCs in myHandler.m.\
        !            94: \
        !            95:     m88kdebug/myHandlerUser.c:\
        !            96:        The actual C code generated by MIG to convert function calls made by \
        !            97:        myDriver.c into mach RPCs which go to the loadable kernel server.\
        !            98:        \
        !            99:        \
        !           100: kernel/\
        !           101: \
        !           102:     myDevice.[mh]: Trivial IODevice which is to eventually perform all of the\
        !           103:        "work" associated with this device.\
        !           104:        \
        !           105:     myHandler.m: a loadable kernel "handler" module. This accepts RPCs from \
        !           106:        user level and passes along method calls to myDevice. The code in this \
        !           107:        module runs as part of the loadable kernel server task. \
        !           108:        \
        !           109:     myHandler.defs: MIG specification file which defines the RPC interface to\
        !           110:        myHandler.m.\
        !           111:        \
        !           112:     Load_Commands.sect:\
        !           113:     Load_Commands.sect:\
        !           114:        Section commands for the kl_ld utility. These define entry and exit \
        !           115:                operations for the loadable kernel module.\
        !           116:                \
        !           117:     m88krelocdebug/myHandler.h:\
        !           118:        Generated by MIG. Defines C interface to public myHandler.m RPCs.\
        !           119:        \
        !           120:     m88krelocdebug/myHandlerHandler.h:\
        !           121:        Generated by MIG. Among other things, defines the myHandler_t struct, which\
        !           122:        is used by MIG code to vector from an incoming message out to one of the\
        !           123:        public routines in myHandler.m.\
        !           124:        \
        !           125:     m88krelocdebug/myHandlerHandler.c:\
        !           126:        The actual C code generated by MIG to parse incoming messsages and to \
        !           127:        convert them into function calls to myHandler.m.\
        !           128:        \
        !           129:     m88krelocdebug/myHandler_reloc:\
        !           130:        The relocatable module which is loaded into a running kernel.\
        !           131:        
        !           132: }

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.