NetWare Loadable Module Programming HOWTO <author>Martin Hinner, <<htmlurl url="mailto:mhi@penguin.cz" name="mhi@penguin.cz">><newline> Vertaald door Ellen Bokhorst, <<htmlurl url="mailto:bokkie@nl.linux.org" name="bokkie@nl.linux.org">> <date>Versie 0.2, 04 augustus 2000 <abstract> In dit document wordt beschreven hoe Netware Loadable Modules met behulp van GNU CC en nlmconv(1) uit de GNU binutils onder Linux te ontwikkelen. Dit is geen officieel Novell document; ik schreef dit zonder enige hulp of in samenwerking met <htmlurl url="http://www.novell.com/" name="Novell, Inc."> <toc> <sect>Introductie NetWare Loadable Modules (NLMs) zijn programma's die onder een Novell NetWare server draaien. NLM's maken onderdeel uit van het NetWare OS. Je kunt NLM's laden en uit het geheugen verwijderen onderwijl de server draait. "Officiële" compilers voor NLM's zijn: <itemize> <item> Watcom C/C++ <item> Metrowerks Codewarrior voor NetWare (zie <url url="http://www.metrowerks.com/">) <item> EPC C/C++ (zie <url url="http://www.epc.com">) <item> Novell NLMLINK.EXE </itemize> (Even terzijde, Netware 5 kan ook 32bit DLL's laden, welke kunnen worden gebouwd met Microsoft Visual C++, Borland C++ en andere Windows compilers. Zie voor meer informatie <url url="http://developer.novell.com/ndk/dllcomp.htm">) In dit document wordt beschreven hoe van start te gaan met NLM ontwikkeling onder Linux (en mogelijk andere Unices). Dit project bevindt zich in een zeer vroeg stadium van ontwikkeling, dus veel werkt wellicht niet zoals je zou verwachten. Voor dit document wordt ervan uitgegaan dat je bekend bent met Novell NetWare, en dat je op z'n minst beschikt over wat basiskennis in het schrijven van NLM's. Zie de ontwikkelaarssite van Novell voor meer informatie over het schrijven van NLM's. <url url="http://developer.novell.com/">. Er wordt ook van je verwacht dat je ervaring hebt met Unix en C/C++ programmeren met GNU CC. Je kunt heel veel informatie over dit onderwerp vinden op <url url="http://www.linuxdoc.org/">. <sect1>C++ Ontwikkeling Zover ik weet, is C++ ontwikkeling met gcc thans onmogelijk, totdat iemand op z'n minst de libstdc++ en libgcc library's uit het gcc package port. <sect1>Gerelateerde documentatie Andere documenten die van nut kunnen zijn: <itemize> <item>De <bf>IPX-HOWTO</bf>, waarin de details worden beschreven hoe het IPX protocol onder Linux te configureren. <item>De <bf>Linux GCC HOWTO</bf>, waarin wordt behandeld hoe de GNU C compiler en ontwikkelaarslibrary's onder Linux in te stellen en waarin een overzicht wordt verstrekt over het compileren, linken, uitvoeren en debuggen van programma's. <item>De <bf>Assembly HOWTO</bf>, waarin wordt beschreven hoe in assembleertaal te programmeren met behulp van vrij verkrijgbare programmeertools, gericht op de ontwikkeling voor of onder het Linux Besturingssysteem op het i386 platform. <item>De <bf>Creating NLMs on Linux x86</bf>, <url url="http://home.sch.bme.hu/~keresztg/novell/howto/NLM-Linux-HOWTO.html">, by Gabor Keresztvalvi <keresztg@mail.com>. Op zijn pagina wordt hetzelfde beschreven als in mijn HOWTO. Ik vond Gabor's pagina tien dagen na het uitgeven van 0.1 van dit document. :( </itemize> <sect1>Kopiëren Copyright (c) 2000 Martin Hinner, <<htmlurl url="mailto:mhi@penguin.cz" name="mhi@penguin.cz">>. Deze HOWTO is vrije documentatie;je kunt het herdistribueren en/of aanpassen onder de voorwaarden van de GNU General Public Licentie zoals gepubliceerd door de Free Software Foundation; óf versie 2 van de Licentie, of (naar keuze) enige latere versie. Dit document wordt gedistribueerd in de hoop dat het van nut zal zijn, maar zonder enige garantie; zelfs zonder de impliciete garantie van verkoopbaarheid of geschiktheid voor een bepaald doel. Zie de GNU General Public Licentie voor meer details. Je kunt een kopie verkrijgen van de GNU General Public Licentie door te schrijven naar de Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. <sect>Instellen van je Linux box en NetWare Server Je moet het volgende installeren en configureren voor NLM ontwikkeling: <itemize> <item> Linux box met IPX en NCPFS geconfigureerd <item> GNU C compiler (gcc) voor elf-i386 (het is in bijna alle i386 Linux Distributies opgenomen) <item> GNU binutils met het nlmconv(1) programma <item> Mijn nlm-kit package <item> Novell Developer Kit - NDK (met de bestanden en documentatie) <item> DOSemu (met rconsole) of X11 server voor het draaien van NetWare Xconsole. <item> ... en als laatste, NetWare server :-) </itemize> Wellicht dat je ook het package met nlm-voorbeelden vanaf mijn FTP-site wilt downloaden: <url url="ftp://ftp.penguin.cz/pub/users/mhi/nlm/"> of <url url="ftp://ftp.funet.fi/pub/mirrors/ftp.penguin.cz/pub/users/mhi/nlm/">. <sect1>Novell NetWare Server Laten we beginnen met de NetWare server. Je kunt gebruik maken van NetWare versie 3.X, 4.X of 5.X. De "demo" versie van NetWare 5 (of 5.1) voor drie gebruikers kan voor een paar dollar worden besteld bij Novell Inc.. Laat je niet in de war brengen door het woord "demo", het is een volledige functionele NetWare, behalve dat het beperkt is tot drie gebruikers. Tussen twee haakjes, deze licentie kan online, zonder kosten, tot vijf gebruikers worden bijgewerkt. Je zou ook kunnen proberen je lokale Novell partner om demo CD's te vragen (wellicht kosten deze niks). <sect1>Linux Box met IPX/NCPFS Je moet je kernel opnieuw compileren met "IPX protocol" en de "NCP file system support" opties geactiveerd. Vergeet niet YES te antwoorden op "NDS authentication support" als je gebruik maakt van NDS. Vervolgens moet je het IPX protocol configureren en je NetWare servervolumes configureren. Zorg dat je het ncpfs package hebt geïnstalleerd! Ik gebruik dit script: <code> #!/bin/sh ipx_interface delall ipx_interface add -p eth0 802.2 120 # Frame Ethernet_802.2, ipx net num 120 insmod ncpfs # Ik heb NCPfs als module gecompileerd ncpmount -U admin -S elf -P XYZ /nw # mount alle ELF's volumes als /nw </code> Zie de IPX-HOWO voor meer informatie over het configureren van IPX en NCPFS. <sect1>GNU C Compiler Ik denk dat in alle moderne Linux distributies voor de Intel X86 gcc is opgenomen, waarmee ELF32/i386 objectbestanden worden gegenereerd. Als je een oudere Linux distributie hebt, kan het zijn dat het a.out formaat wordt gebruikt in plaats van ELF. Als je Linux geen gebruik maakt van ELF, haal dan een nieuwer gcc op en installeer dat. <sect1>nlmconv(1) uit GNU binutils Het nlmconv(1) utility linkt objectbestanden naar het NLM formaat. Het maakt standaard onderdeel uit van GNU binutils, maar helaas is het niet in de huidige distributies (RedHat, SuSE, Debian, ...) opgenomen. Haal de binutils sources op van ftp.gnu.org, en compileer ze, of gebruik eenvoudigweg de voorgecompileerde nlmconv vanuit mijn nlm-kit package. <sect1>Het nlm-kit Package Mijn nlm-kit package is beschikbaar vanaf <url url="ftp://ftp.penguin.cz/pub/users/mhi/nlm/">. Het bevat de benodigde bestanden voor NLM ontwikkeling. Extraheer het en start <tt>"make all"</tt> en <tt>"make install"</tt>. Er zal een directory <tt>/usr/nwsdk/</tt> worden aangemaakt en alle importbestanden, objectbestanden en het nlmimp(1) utility zullen worden geïnstalleerd. <sect1>Include Files en Documentatie van de NDK Er is eenvoudig aan de NDK te komen: <itemize> <item> Download het van <url url="http://developer.novell.com/ndk/">. <item> Bestel twee NDK CD's bij Novell. <item> Haal deze CD's gratis op bij BrainShare, Novell Developer Workshop of bij andere Novell Developer events. </itemize> Je hebt de volgende bestanden uit de NDK nodig (allen zijn online beschikbaar op) <url url="http://developer.novell.com/ndk/clib.htm">: <itemize> <item> C language header en importbestanden (cdrom:\files\download\clib.exe) <item> C language API documentatie (cdrom:\files\download\clib_doc.exe) <item> C language voorbeelden (optioneel) (cdrom:\files\download\clib_sample.exe) </itemize> Het is jammer dat alle bestanden die hier zijn genoemd InstallShield Win32 uitvoerbare bestanden zijn. Je moet een Windows computer zien te vinden om ze te extraheren en de include bestanden vervolgens kopiëren naar <tt>/usr/nwsdk/include/</tt> en documentation/samples naar waar je ook maar wilt. De Novell Licentie staat me niet toe include bestanden of documentatie met de nlm-kit te distribueren. Omdat de NDK include bestanden onder Linux niet werken, moet je er handmatig een patch op toepassen door te typen "make install-include" in de nlm-kit-X.Y/ directory. <sect1>Toegang tot de NetWare Server (Xconsole of rconsole) Je kunt de NetWare serverconsole direct benaderen (toetsenbord en monitor), door gebruik te maken van rconsole.exe (van dosemu), of door gebruik van telnetd.nlm/Xconsole (je hebt hier een X-server voor nodig). <sect>Eerste Stap: Hello world Zoals gewoonlijk zullen we beginnen met het befaamde "Hello world" programma. De broncode voor hello.nlm is beschikbaar in het nlm-samples packages. Je kunt het downloaden vanaf <url url="ftp://ftp.penguin.cz/pub/users/mhi/nlm/">. <sect1>hello.c - Bronbestand <code> #define N_PLAT_NLM /* Definieer doelplatform */ #include <nwconio.h> /* ConsolePrintf */ int main (int argc, char **argv) { int i; ConsolePrintf ("\rHello world!\n\n"); /* geef weer op systeemconsole */ ConsolePrintf("Argumenten:\n"); /* alle argumenten */ for (i=0;i<argc;i++) ConsolePrintf("argv[%u]=\"%s\"\n",i, argv[i]); return 0; /* exit NLM */ } </code> <sect1>hello.def - NLM header file <code> # # hello.def - NLM Header definitie bestand voor nlmconv(1) # Copyright (c) 2000 Martin Hinner <mhi@penguin.cz> # # definieer opstart objectbestanden INPUT hello.o INPUT /usr/nwsdk/lib/prelude.o # clib opstartcode # all imported functions and import lists IMPORT @/usr/nwsdk/imports/clib.imp # Functies in CLIB.NLM IMPORT @/usr/nwsdk/imports/threads.imp # Functies in THREADS.NLM # NLM header... OUTPUT hello.nlm # uitvoerbestand TYPE 0 # Gewone NLM VERSION 1,0,0 # Versie 1.0 COPYRIGHT "Copyright (c) 2000 Martin Hinner <mhi@penguin.cz>" # (c) ... DESCRIPTION "Simpel 'Hello world' NLM module." # titel van nlm SCREENNAME "Systeem Console" # Standaard schermnaam MODULE CLIB,THREADS # vereist modules </code> <sect1>Makefile <code> # makefile voor "hello world" NLM CC = gcc CFLAGS = -Wall -O2 -g -I/usr/nwsdk/include/ -nostdinc -fno-builtin -fpack-struct hello.nlm: hello.o hello.def nlmconv --output-target=nlm32-i386 -T hello.def hello.o: hello.c $(CC) $(CFLAGS) -c hello.c </code> <sect1>GCC problems Je moet de volgende argumenten aan gcc doorgeven: <itemize> <item> <bf>-fno-builtin</bf>: GCC's snelle ingebouwde functies zorgen er soms voor dat de server down gaat, dus we zullen ze niet gebruiken. <item> <bf>-nostdinc</bf>: Alleen include bestanden in /usr/nwsdk/include zijn voor NLM's van toepassing (vergeet niet ook -I/usr/nwsdk/include te gebruiken). <item> <bf>-fpack-struct</bf>: GCC's struct packing methode is niet geldig voor Novell NetWare, dus we zullen het niet gebruiken. Met dank aan Gabor Keresztvalvi voor deze informatie. </itemize> <sect1>Testen van de Module Kopieer hello.nlm naar de SYS:\SYSTEM directory op je NetWare server. Typ onder de systeemconsole vervolgens "load hello.nlm". Als dit goed ging, zou je de NLM versie informatie te zien moeten krijgen, een copyright melding en "Hello world". <sect>NLM Header bestand De NLM header bevat informatie voor nlmconv(1). Op iedere regel staat een optie of directive; alles achter een "#" is commentaar. In dit hoofdstuk worden alle opties en directives beschreven. Sorry, maar dit hoofdstuk is nog niet af. <sect1>AUTOUNLOAD Syntax: <bf>AUTOUNLOAD</bf> <sect1>CHECK Syntax: <bf>CHECK <check procedure name></bf> Deze directive specificeert de functie die moet worden uitgevoerd wanneer de NLM uit het geheugen wordt verwijderd met behulp van de UNLOAD Server console opdracht. Als deze functie nul retourneert, dan kan de NLM uit het geheugen worden verwijderd, anders is de NLM nog niet zover om uit het geheugen verwijderd te worden. Voorbeeld: <code> CHECK CheckUnload </code> <sect1>CODESTART Syntax: <bf>CODESTART <map file code start offset></bf> Map file start offset kan decimaal zijn of in Xhex. <sect1>COPYRIGHT Syntax: <bf>COPYRIGHT ["Copyright string"]</bf> De copyright string wordt op het scherm van de serverconsole weergegeven wannneer de NLM is geladen. Als deze optie niet is gebruikt, zal er geen copyright informatie worden weergegeven. Voorbeeld: <code> COPYRIGHT "Copyright (c) 1998 ABC Inc." </code> <sect1>CUSTOM Syntax: <bf>CUSTOM <custom data file path></bf> <sect1>DATASTART Syntax: <bf>DATASTART <map file data start offset></bf> Map file data start offset kan decimaal zijn of in Xhex. <sect1>DATE Syntax: <bf>DATE <maand, dag, jaar></bf> <sect1>DEBUG Syntax: <bf>DEBUG</bf> Deze directive vertelt de nlmconv(1) debugging informatie in het NLM bestand op te nemen. Voorbeeld: <code>DEBUG</code> <sect1>DESCRIPTION Syntax: <bf>DESCRIPTION "NLM Description String"</bf> <sect1>EXIT Syntax: <bf>EXIT <exit procedure name></bf> <sect1>EXPORT Syntax: <bf>EXPORT <symbol list></bf> <bf>EXPORT @<symbol list file></bf> <sect1>FLAG_OFF Syntax: <bf>FLAG_OFF <decimaal getal></bf> <sect1>FLAG_ON Syntax: <bf>FLAG_ON <decimaal getal></bf> <sect1>HELP Syntax: <bf>HELP <pad naar helpbestand></bf> <sect1>IMPORT Syntax: <bf>IMPORT <symbol list> </bf> <bf>IMPORT @<symbol list file></bf> <sect1>INPUT Syntax: <bf>INPUT <object file> [, <object file> [, ...] ]</bf> <bf>INPUT @<object list file></bf> Deze directive geeft een opsomming van de invoer ELF (.o) objectbestanden die zullen worden gelinkt. Je kunt de objectbestanden in het list-bestand ook opsommen, ieder objectbestand op één regel. Voorbeeld: <code> INPUT @objectfiles.txt INPUT main.o INPUT /usr/nwsdk/lib/prelude.o </code> <sect1>MAP Syntax: <bf>MAP [map file name]</bf> <sect1>MESSAGES Syntax: <bf>MESSAGES <message file path></bf> <sect1>MODULE Syntax: <bf>MODULE <autoload NLM list></bf> <sect1>MULTIPLE Syntax: <bf>MULTIPLE</bf> <sect1>NAMELEN Syntax: <bf>NAMELEN <decimaal getal></bf> Standaard is 31. Nul wil zeggen geen limiet. <sect1>OS_DOMAIN Syntax: <bf>OS_DOMAIN</bf> <sect1>OUTPUT Syntax: <bf>OUTPUT <naam van doelbestand></bf> <sect1>PATH Syntax: <bf>PATH [zoekpad;...]</bf> voor het volgende CUSTOM, HELP, INPUT, MESSAGES, SHARELIB, STAMPEDDATA en XDCDATA. <sect1>PSEUDOPREEMPTION Syntax: <bf>PSEUDOPREEMPTION</bf> <sect1>REENTRANT Syntax: <bf>REENTRANT</bf> <sect1>SCREENNAME Syntax: <bf>SCREENNAME "Initial Screen Name (CLIB)"</bf> <sect1>SHARELIB Syntax: <bf>SHARELIB <shared library path></bf> <sect1>STACK Syntax: <bf>STACK <stack size></bf> <sect1>STACKSIZE Syntax: <bf>STACKSIZE <stack size></bf> <sect1>STAMPEDDATA Syntax: <bf>STAMPEDDATA "Stamp" <data file path></bf> Stamp is 8 max. tekens <sect1>START Syntax: <bf>START <start procedure name></bf> Standaard is _Prelude. <sect1>SYNCHRONIZE Syntax: <bf>SYNCHRONIZE</bf> <sect1>THREADNAME Syntax: <bf>THREADNAME "Initial Process Name (CLIB)"</bf> <sect1>TYPE Syntax: <bf> TYPE <versie></bf> Deze directive specificeert het formaat (NLM, LAN, DSK, NAM) van het NLM bestand dat wordt gegenereerd. Geldige waarden zijn: <itemize> <item> 0 - NLM <item> 1 - LAN <item> 2 - DSK <item> 3 - NAM </itemize> Voorbeeld:: <code> TYPE 0 </code> <sect1>VERSION Syntax: <bf>VERSION <major versie>, <minor versie> [, <revisie>]</bf> De versie-informatie wordt op de serversysteemconsole weergegeven wanneer de NLM zichzelf laadt. De major en minor versienummers kunnen zich bevinden in de range 0 - 99. Het revisie nummer kan zich in de range 0 26 ("a" - "z") bevinden en deze is optioneel. <bf>De version directive is vereist.</bf> Voorbeeld: <code> VERSION 1,5 </code> <sect1>XDCDATA Syntax: <bf>XDCDATA <XDC data file path></bf> <sect>Message files Een message file bevat (zoals je al dacht) tekstmeldingen gegenereerd door de NLM. Je kunt het aanmaken met behulp van de DOS programma's MSGLIB.EXE en MSGMAKE.EXE. Ik ken geen vergelijkbaar utility voor Unix. Sorry, je zult hier dosemu of een DOS computer voor moeten gebruiken. :-( <sect>Helpbestanden Helpbestanden bevattten hulp voor gebruik met de NWSNUT gebruikersinterface library. Er is geen Linux utility bekend voor het aanmaken van helpbestanden. Je moet het DOS programma HELPLIB.EXE gebruiken, wat beschikbaar is vanaf de Novell developer site. <sect>XDC Data Files XDC bestanden worden door NetWare 5 (of SMP NetWare 4.x) gebruikt en hierin wordt informatie over symmetrische multiprocessing (SMP) opgeslagen. Je hebt deze waarschijnlijk niet nodig. Tenminste voor het moment. :-) Nogmaals, er is geen Unix-utility voor het aanmaken van XDC-bestanden, je zal het MPKXDC.EXE programma moeten gebruiken (ook beschikbaar op de Novell developer site). <sect>Headerbestanden (.h) (nog te doen) <sect>Importbestanden (.imp) (nog te doen) <sect1>Met nlmimp(1) importbestanden genereren Het programma nlmimp(1) maakt onderdeel uit van mijn nlm-kit package. (te doen) </article>