Netware

From Lazarus wiki

The compiler supports two different tragets for netware. Both targets are using the same compiler and binutils but different runtime libraries.


Target Netware

As of fpc 2.5.1 (Mar 27, 2011), the internal linker will be used to generate netware loadable modules. Currently only the clib target is implemented. This means binutils for netware are no longer required. Due to the fact that fpc currently only supports reading coff objects in the internal linker, the object format for netware has been changed to coff. Because nlmconv for binutils only supports coff, linking with binutils does no longer work. I plan to switch back to elf as soon as internal support for elf is available in fpc.

This target is based on the classic netware c-library (clib.nlm). The nlm should work on netware versions from 4.00 on. It will not work on 3.x (mainly because the rtl auto loads nlms from the modular clib, i.e. threads.nlm). You are free to change that in the runtime library. The resulting nlm is a uni-processor nlm (no xdc-data support). There are some netware specific support modules included in the rtl:

aio Serial port support, aio.h in ndk

nwnit Definitions from the following ndk-files: nwaccntg.h, nwafp.h, nwbindry.h, nwdatamg.h, nwdir.h, nwenvrn.h, nwenvrn1.h, nwextatt.h, nwmsg.h, nwnit.h, nwqueue.h, nwserial.h, nwservst.h, nwsync.h, nwtts.h

nwprot netware server protocol library (streams and tli)

nwserv Contains definitions from the follwing header files: string.h dirent.h errno.h fcntl.h limits.h locale.h nwaudnlm.h nwbitops.h nwcntask.h nwconio.h nwconn.h nwdebug.h nwdfs.h nwdos.h nwerrno.h nwfattr.h nwfileio.h nwfileng.h nwfinfo.h nwfshook.h nwipx.h nwlib.h nwlocale.h nwmalloc.h nwncpx.h nwnspace.h nwproc.h nwsemaph.h nwserv.h nwsignal.h nwstring.h nwtoolib.h stdio.h stdlib.h unistd.h time.h utime.h nwthread.h nwmediam.h ioctl.h sys/socket.h sys/time.h sys/filio.h syys/ioctl.h sys/stat.h sys/time.h sys/timeval.h sys/uio.h sys/utsname.h

nwsnut Netware utility text interface (same as in ndk)

winsock Netware winsock2 interface

Target Netwlibc

This target is based on the modern netware libc (libc.nlm). The nlm should work on netware versions from 5.10 on (current service packs and libc fixes may be needed). Older versions of netware are not supported because no libc is available on these versions. Threads within the generated nlm can run on any cpu by default (xdc-data is generated by the compiler). There are some netware specific support modules included in the rtl:

libc Interface to netware libc

winsock Netware winsock2 interface

nwsnut Netware utility text interface (same as in ndk)


Compiler Switches for Netware

{$Description TEXT} Sets the NLM Description displayed while loading the NLM

{$Copyright TEXT} Sets the NLM copyright displayed while loading the NLM

{$Version x,y,z} Sets the nlm version to x.y.z, x,y, and z has to be numeric, z=1 will be interpreted as rev a, z=1 as rev b ...

{$Screenname} Sets the clib screenname, the following special Screennames will be supported by netware:

default no own screen, stdout and errout are active on console for Netware < 6.0, Logger Screen on newer Versions

none No screen and no stdout/errout at all. You should not use this mode with FreePascal because in case a runtime error will be generated, FreePascal prints the error to stdout and that will fail and generate another runtime error (and so on ...) This will result in a nice abend (even when loaded protected)

{$Threadname} Sets the thread name. Make sure the names are not to long for netware because this will prevent your nlm from loading.

{$Memory Stacksize} {$Memory Stacksize,Heapsize} Specifies the stacksize, the heapsize will be ignored.


Defines for Netware

The compiler defines the symbol NETWARE for both targets, netware and netwlibc. For netware the additional symbol NETWARE_CLIB is defined, for netwlibc, NETWLIBC and NETWARE_LIBC are defined.

begin
 {$if defined(netware)}
 writeln ('Running on netware');
   {$if defined(netware_libc)}
    writeln ('on libc target');
   {$endif}
   {$if defined(netware_clib)}
    writeln ('on clib target');
   {$endif}
 {$endif}
end.


Importing functions

Importing functions are be supported with or without auto loading required nlms:

FUNCTION rmdir (path : PCHAR) : LONGINT; CDECL; EXTERNAL 'nlmlib.nlm' NAME 'rmdir';

This will import "rmdir" from nlmlib.nlm and adds nlmlib.nlm to the list of autoloaded nlm's. If the name of the external library will begin with !, the autoload will not be added to the generated nlm as in the following example:

FUNCTION rmdir (path : PCHAR) : LONGINT; CDECL; EXTERNAL '!nlmlib.nlm' NAME 'rmdir';

The internal linker do not need .imp files. (Except for nwpre.pp that will be automatically included)

Exporting functions

Exports are handled like in win32: procedure bla; CDECL; EXPORT; begin end; exports bla name 'bla';

Linker Specials

The internal linker supports options via the -k command line options. Multiple options can be separated by ; or can be saved to a separate file.

fpc -Tnetware -k"CUSTOM custfile.dat;OS_DOMAIN;REENTRANT" fpc -Tnetware -k"@linkeroptionsfile.txt"

The second sample reads options from an external file. The following options are supported:

AUTOUNLOAD The nlm will be unloaded if none of the exported symbols are in use.

COPYRIGHT Specifies the copyright string that will be shown when the nlm is loaded. The text must be enclosed in double quotation marks ("). This is the same that can be specified with {$Copyright TEXT}. The linker option will override the text specified by $Copyright. The option is only useful within a linker options file, example: COPYRIGHT "(c) 2011 the free pascal team"

CUSTOM Specifies a custom data file that will be included in the nlm image.

DATE Secifies the nlm date that will be displayed while the nlm is loaded. The default is the system date. Month, day and year have to be separated by at least one space. example: DATE 27 3 2011

DEBUG Will be ignored

DESCRIPTION Specifies the copyright string (up to 127 chars) that will be shown when the nlm is loaded. The text must be enclosed in double quotation marks ("). This is the same that can be specified with {$Description TEXT}. The linker option will override the text specified by $Description. The option is only useful within a linker options file, example: DESCRIPTION "test nlm for free pascal"

FLAG Sets or clears the flag in the nlm header. ON or OFF and the decimal value has to be specified. examples FLAG ON 1 FLAG OFF 2

HELP Specifies the path to the help file that contains the default help screens for the NLM. The helpfile will be included in the nlm file.

MESSAGES Specifies the path to the message file that contains the default messages for the NLM. The file will be included in the nlm file.

MULTIPLE Sets a flag in the NLM header indicating that this NLM can be loaded more than once times.

OS_DOMAIN Sets a flag in the NLM header indicating that this NLM must be loaded in the memory space of the operating system. This prevent the NLM from being loaded into a protected address space.

PSEUDOPREEMPTION Sets a flag in the NLM header indicating that the NetWare operating system can force the NLM to relinquish control if it does not do so on its own often enough.

REENTRANT Sets a flag in the NLM header indicating that this NLM is reentrant. If an NLM is reentrant, when it is loaded by the LOAD command more than once, the NLM is not loaded again, but the NLM can now be executed concurrently by multiple threads. In this case, only one copy of the NLM is in memory.

SCREENNAME Specifies the name of the first screen (max 71 chars) of an NLM, which is created when the NLM is loaded and to which stdin, stdout, and stderr are wired. This is the same that can be specified with {$Screenname TEXT}. The linker option will override the name specified by $Screenname.

STACK or STACKSIZE Specifies the stacksize in bytes.

SYNCHRONIZE Sets a flag in the NLM header indicating that when this NLM is loaded, the load process goes to sleep until the NLM calls SynchronizeStart. This prevents other console commands (particularly LOAD) from being processed while the NLM is loading.

THREADNAME Specifies a prefix for NetWare to use to name the threads of the NLM. For example, if the prefix was FPC, then threads created in the NLM would be named “FPC1,” “FPC2,” and so on. Thread names can be displayed in the internal debugger with the .P command. The prefix should be 12 chars or less.

TYPE Specifies the numerical type of the nlm. The types are defined as follows: 0 Generic module (default and the most common one) 1 LAN driver 2 Disk driver 3 Name space module 4 NLM utility application 5 Mirror server link module 6 OS module 7 Paged high OS module 8 Host adapter module 9 Custom device module 10 File system module 11 Real mode module 12 Ghost module 13 Normal SMP module 14 NIOS module 15 CIOS CAD module 16 CIOS CLS module 20..32 NICI modules

VERSION Specifies the version displayed while loading the nlm. This overrides the version specified by {$version}. The version consist of 3 numerical valued separated by at least one space. (major minor and revision) Major can be any positive number (31 bits), Minmor has to be in the range of 0 to 99 and revision in the range from 0 to 26. example version 12 2 1

XDCDATA Specifies a path to a file containing Remote Procedure Call (RPC) descriptions for functions in the NLM. XDC data can be used to create an MT-safe NLM, funnel functions to processor 0, declare an NLM as MT unsafe, and mark an NLM as preemptible. The data will be generated by novells mpkxdc tool.


--Armin 18:30, 27 Mar 2011 (CET)