NetWare Loadable Module Programming HOWTO
  Martin Hinner, <mhi@penguin.cz>
  Vertaald door Ellen Bokhorst, <bokkie@nl.linux.org>
  Versie 0.2, 04 augustus 2000

  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 Novell, Inc.
  ______________________________________________________________________

  Inhoudsopgave






















































  1. Introductie

     1.1 C++ Ontwikkeling
     1.2 Gerelateerde documentatie
     1.3 Kopiëren

  2. Instellen van je Linux box en NetWare Server

     2.1 Novell NetWare Server
     2.2 Linux Box met IPX/NCPFS
     2.3 GNU C Compiler
     2.4 nlmconv(1) uit GNU binutils
     2.5 Het nlm-kit Package
     2.6 Include Files en Documentatie van de NDK
     2.7 Toegang tot de NetWare Server (Xconsole of rconsole)

  3. Eerste Stap: Hello world

     3.1 hello.c - Bronbestand
     3.2 hello.def - NLM header file
     3.3 Makefile
     3.4 GCC problems
     3.5 Testen van de Module

  4. NLM Header bestand

     4.1 AUTOUNLOAD
     4.2 CHECK
     4.3 CODESTART
     4.4 COPYRIGHT
     4.5 CUSTOM
     4.6 DATASTART
     4.7 DATE
     4.8 DEBUG
     4.9 DESCRIPTION
     4.10 EXIT
     4.11 EXPORT
     4.12 FLAG_OFF
     4.13 FLAG_ON
     4.14 HELP
     4.15 IMPORT
     4.16 INPUT
     4.17 MAP
     4.18 MESSAGES
     4.19 MODULE
     4.20 MULTIPLE
     4.21 NAMELEN
     4.22 OS_DOMAIN
     4.23 OUTPUT
     4.24 PATH
     4.25 PSEUDOPREEMPTION
     4.26 REENTRANT
     4.27 SCREENNAME
     4.28 SHARELIB
     4.29 STACK
     4.30 STACKSIZE
     4.31 STAMPEDDATA
     4.32 START
     4.33 SYNCHRONIZE
     4.34 THREADNAME
     4.35 TYPE
     4.36 VERSION
     4.37 XDCDATA

  5. Message files

  6. Helpbestanden

  7. XDC Data Files

  8. Headerbestanden (.h)

  9. Importbestanden (.imp)

     9.1 Met nlmimp(1) importbestanden genereren


  ______________________________________________________________________

  1.  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:


  ·  Watcom C/C++

  ·  Metrowerks Codewarrior voor NetWare (zie
     <http://www.metrowerks.com/>)

  ·  EPC C/C++ (zie  <http://www.epc.com>)

  ·  Novell NLMLINK.EXE

  (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
  <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.
  <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
  <http://www.linuxdoc.org/>.

  1.1.  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.

  1.2.  Gerelateerde documentatie


  Andere documenten die van nut kunnen zijn:


  ·  De IPX-HOWTO, waarin de details worden beschreven hoe het IPX
     protocol onder Linux te configureren.
  ·  De Linux GCC HOWTO, 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.

  ·  De Assembly HOWTO, 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.

  ·  De Creating NLMs on Linux x86,
     <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.
     :(

  1.3.  Kopiëren

  Copyright (c) 2000 Martin Hinner, <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.

  2.  Instellen van je Linux box en NetWare Server

  Je moet het volgende installeren en configureren voor NLM
  ontwikkeling:


  ·  Linux box met IPX en NCPFS geconfigureerd

  ·  GNU C compiler (gcc) voor elf-i386 (het is in bijna alle i386 Linux
     Distributies opgenomen)

  ·  GNU binutils met het nlmconv(1) programma

  ·  Mijn nlm-kit package

  ·  Novell Developer Kit - NDK (met de bestanden en documentatie)

  ·  DOSemu (met rconsole) of X11 server voor het draaien van NetWare
     Xconsole.

  ·

  Wellicht dat je ook het package met nlm-voorbeelden vanaf mijn FTP-
  site wilt downloaden: <ftp://ftp.penguin.cz/pub/users/mhi/nlm/> of
  <ftp://ftp.funet.fi/pub/mirrors/ftp.penguin.cz/pub/users/mhi/nlm/>.

  2.1.  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).

  2.2.  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:


  ______________________________________________________________________
  #!/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
  ______________________________________________________________________



  Zie de IPX-HOWO voor meer informatie over het configureren van IPX en
  NCPFS.

  2.3.  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.

  2.4.  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.

  2.5.  Het nlm-kit Package

  Mijn nlm-kit package is beschikbaar vanaf
  <ftp://ftp.penguin.cz/pub/users/mhi/nlm/>. Het bevat de benodigde
  bestanden voor NLM ontwikkeling. Extraheer het en start "make all" en
  "make install".  Er zal een directory /usr/nwsdk/ worden aangemaakt en
  alle importbestanden, objectbestanden en het nlmimp(1) utility zullen
  worden geïnstalleerd.

  2.6.  Include Files en Documentatie van de NDK


  Er is eenvoudig aan de NDK te komen:

  ·  Download het van  <http://developer.novell.com/ndk/>.

  ·  Bestel twee NDK CD's bij Novell.

  ·  Haal deze CD's gratis op bij BrainShare, Novell Developer Workshop
     of bij andere Novell Developer events.

  Je hebt de volgende bestanden uit de NDK nodig (allen zijn online
  beschikbaar op) <http://developer.novell.com/ndk/clib.htm>:

  ·  C language header en importbestanden
     (cdrom:\files\download\clib.exe)

  ·  C language API documentatie (cdrom:\files\download\clib_doc.exe)

  ·  C language voorbeelden (optioneel)
     (cdrom:\files\download\clib_sample.exe)

  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 /usr/nwsdk/include/ 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.

  2.7.  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).

  3.  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
  <ftp://ftp.penguin.cz/pub/users/mhi/nlm/>.

  3.1.  hello.c - Bronbestand


  ______________________________________________________________________
  #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 */
  }
  ______________________________________________________________________





  3.2.  hello.def - NLM header file


  ______________________________________________________________________
  #
  # 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
  ______________________________________________________________________



  3.3.  Makefile


  ______________________________________________________________________
  # 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
  ______________________________________________________________________



  3.4.  GCC problems

  Je moet de volgende argumenten aan gcc doorgeven:


  ·  -fno-builtin: GCC's snelle ingebouwde functies zorgen er soms voor
     dat de server down gaat, dus we zullen ze niet gebruiken.

  ·  -nostdinc: Alleen include bestanden in /usr/nwsdk/include zijn voor
     NLM's van toepassing (vergeet niet ook -I/usr/nwsdk/include te
     gebruiken).

  ·  -fpack-struct: 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.



  3.5.  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".

  4.  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.

  4.1.  AUTOUNLOAD

  Syntax:

  AUTOUNLOAD

  4.2.  CHECK

  Syntax:

  CHECK <check procedure name>

  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:

  ______________________________________________________________________
  CHECK CheckUnload
  ______________________________________________________________________



  4.3.  CODESTART

  Syntax:

  CODESTART <map file code start offset>

  Map file start offset kan decimaal zijn of in Xhex.

  4.4.  COPYRIGHT

  Syntax:

  COPYRIGHT ["Copyright string"]

  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:

  ______________________________________________________________________
  COPYRIGHT "Copyright (c) 1998 ABC Inc."
  ______________________________________________________________________


  4.5.  CUSTOM

  Syntax:

  CUSTOM <custom data file path>

  4.6.  DATASTART

  Syntax:

  DATASTART <map file data start offset>

  Map file data start offset kan decimaal zijn of in Xhex.

  4.7.  DATE

  Syntax:

  DATE <maand, dag, jaar>

  4.8.  DEBUG

  Syntax:

  DEBUG

  Deze directive vertelt de nlmconv(1) debugging informatie in het NLM
  bestand op te nemen.

  Voorbeeld:

  ______________________________________________________________________
  DEBUG
  ______________________________________________________________________



  4.9.  DESCRIPTION

  Syntax:

  DESCRIPTION "NLM Description String"

  4.10.  EXIT

  Syntax:

  EXIT <exit procedure name>

  4.11.  EXPORT

  Syntax:

  EXPORT <symbol list>

  EXPORT @<symbol list file>

  4.12.  FLAG_OFF

  Syntax:

  FLAG_OFF <decimaal getal>




  4.13.  FLAG_ON

  Syntax:

  FLAG_ON <decimaal getal>

  4.14.  HELP

  Syntax:

  HELP <pad naar helpbestand>

  4.15.  IMPORT

  Syntax:

  IMPORT <symbol list>

  IMPORT @<symbol list file>

  4.16.  INPUT

  Syntax:

  INPUT <object file> [, <object file> [, ...] ]

  INPUT @<object list file>

  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:


  ______________________________________________________________________
  INPUT @objectfiles.txt
  INPUT main.o
  INPUT /usr/nwsdk/lib/prelude.o
  ______________________________________________________________________



  4.17.  MAP

  Syntax:

  MAP [map file name]

  4.18.  MESSAGES

  Syntax:

  MESSAGES <message file path>

  4.19.  MODULE

  Syntax:

  MODULE <autoload NLM list>

  4.20.  MULTIPLE

  Syntax:


  MULTIPLE

  4.21.  NAMELEN

  Syntax:

  NAMELEN <decimaal getal>

  Standaard is 31. Nul wil zeggen geen limiet.

  4.22.  OS_DOMAIN

  Syntax:

  OS_DOMAIN

  4.23.  OUTPUT

  Syntax:

  OUTPUT <naam van doelbestand>

  4.24.  PATH

  Syntax:

  PATH  [zoekpad;...]

  voor het volgende CUSTOM, HELP, INPUT, MESSAGES, SHARELIB, STAMPEDDATA
  en XDCDATA.

  4.25.  PSEUDOPREEMPTION

  Syntax:

  PSEUDOPREEMPTION

  4.26.  REENTRANT

  Syntax:

  REENTRANT

  4.27.  SCREENNAME

  Syntax:

  SCREENNAME "Initial Screen Name (CLIB)"

  4.28.  SHARELIB

  Syntax:

  SHARELIB <shared library path>

  4.29.  STACK

  Syntax:

  STACK <stack size>

  4.30.  STACKSIZE

  Syntax:


  STACKSIZE <stack size>

  4.31.  STAMPEDDATA

  Syntax:

  STAMPEDDATA "Stamp" <data file path>

  Stamp is 8 max. tekens

  4.32.  START

  Syntax:

  START <start procedure name>

  Standaard is _Prelude.

  4.33.  SYNCHRONIZE

  Syntax:

  SYNCHRONIZE

  4.34.  THREADNAME

  Syntax:

  THREADNAME "Initial Process Name (CLIB)"

  4.35.  TYPE

  Syntax:

   TYPE <versie>

  Deze directive specificeert het formaat (NLM, LAN, DSK, NAM) van het
  NLM bestand dat wordt gegenereerd. Geldige waarden zijn:


  ·  0 - NLM

  ·  1 - LAN

  ·  2 - DSK

  ·  3 - NAM

  Voorbeeld::


  ______________________________________________________________________
  TYPE 0
  ______________________________________________________________________



  4.36.  VERSION

  Syntax:

  VERSION <major versie>, <minor versie> [, <revisie>]

  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.  De version
  directive is vereist.

  Voorbeeld:


  ______________________________________________________________________
  VERSION 1,5
  ______________________________________________________________________



  4.37.  XDCDATA

  Syntax:

  XDCDATA <XDC data file path>

  5.  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. :-(

  6.  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.

  7.  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).

  8.  Headerbestanden (.h)

  (nog te doen)

  9.  Importbestanden (.imp)

  (nog te doen)

  9.1.  Met nlmimp(1) importbestanden genereren

  Het programma nlmimp(1) maakt onderdeel uit van mijn nlm-kit package.
  (te doen)