White Paper on NetBIOS Applications Interoperability

1.0 NetBIOS Applications Interoperability
NetBIOS applications including IBM's LAN Server, Data Base, etc., can run over OEM LM10 protocols. OEM LM10 protocols such as IPX, DECNet, ATTISO, AILANBIO can be used instead of IBM's NetBIOS (NETBEUI) protocol to run NetBIOS applications.

The IBM NetBIOS NB30* (NETBIOS.OS2), LAN Server (HPFS386.IFS) and LAN Redirector (NETWKSTA.200) use the NetBIOS LM10 interface. We will refer to these three (NetBIOS.OS2, HPFS386.IFS and NETWKSTA.200) as LM10 applications hereafter. During initialization, each one of the LM10 application performs a standard DosDevIoctl to the LM10 NetBIOS driver to get the far address of the direct I/O routing. This routine is analogous to a real mode INT 5C handler, i.e., it gets called with a pointer to a Network Control Block (NCB). This pointer to NCB can be a physical address or a virtual address. Each of the LM10 application drivers provides two standardized routines. PhysNCBDone and VirtNCBDone for handling NCB completion. Based on the type of NCB (physical or virtual) address, the LM10 NetBIOS driver returns to PhysNCBDone or VirtlNCBDone on completion.

Even though the LM10 protocol driver returns to only one callback routine, all of the three drivers (NETBIOS NB30, NETWKSTA.200 and HPFS386.IFS) can coexist. HPFS386.IFS first gets the completion NCB and determines whether that ncb belongs to HPFS386.IFS. If not, it passes it to NETWKSTA.200. NETWKSTA.200 passes it to NETBIOS.OS2 if it does not belong to NETWKSTA.200.

LM10 NetBIOS drivers never get a synchronous NCB, and therefore, they need not process synchronous or asynchronous NetBIOS options. The drivers just call a PhysNCBDone or a VirtNCBDone routine when processing is complete.

The NB30 NetBIOS takes the responsibility of locking all the NCBs and the buffers passed in the NCBs for ring3 and locking all the buffers passed in the NCBs for ring0 NB30 NetBIOS applications. Whereas LAN Server and Requester take the responsibility of locking all the NCBs and the buffers passed in from their NCBs (for example from the LAN Server NetBiosSubmit API). A convention has been defined to support OEM-defined NCBs such that the NB30 NetBIOS, LAN Server and Requester can still perform the appropriate locking and other actions for their extended NCBs.

Configuration
LM10 NetBIOS drivers are installed by inserting a DEVICE= statement in the CONFIG.SYS file. All LM10 NetBIOS drivers must be installed before the IBM supplied NETWKSTA.200 driver.

Each LM10 NetBIOS driver controls one or more NetBIOS networks and a single system may have multiple LM10 NetBIOS drivers installed. All the three LM10 application drivers (NETBIOS, NETWKSTA.200 and HPFS386.IFS) support multiple LM10 NetBIOS drivers using different logical adapter numbers.

Each LM10 NetBIOS driver is described to the NB30 NetBIOS driver by NETBIOS section in PROTOCOL.INI configuration file. The format of each LM10 NetBIOS driver under NETBIOS section is:  = , where,
 * :is the OS/2 driver name for the LM10 NetBIOS driver.
 * :is the LAN adapter number for the NetBIOS network represented by this statement. Default is 0.

Each LM10 NetBIOS driver is described to LAN Server and LAN Redirector by a statement under the [network] section in the IBMLAN.INI configuration file. Each entry in the [network] section represents a "virtual network" adapter. The format of each LMl0 NetBIOS network definition is: =, , , <#sessions>, <#ncbs>, <#name>; where,
 * :is the OS/2 driver name for the NetBIOS driver.
 * :is the LAN adapter number for the NetBI0S network represented by this statement. Default is 0.
 * :is the type of the NetBIOS driver. For NetBIOS drivers that support the interface described in this document, the type field must be LM10 1. Default is LM10. NB30, the other valid value for this field, is not described in this document.
 * <#sessions>:is the number of session resources that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.
 * <#ncbs>:is the number of NetBIOS Network Control Blocks (NCBs) that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.
 * <#names>:is the number of name resources that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.

The requester uses the virtual networks specified on the WRKNETS line of the [requester] section of the IBMLAN.INI file to determine which networks to use when establishing sessions to remote servers. The server uses the virtual networks specified on the SRVNETS line in the [server] section of the IBMLAN.INI file to determine on which virtual networks to listen for incoming connections. For example configuring "SRVNETS=NET1, NET2" would request that the server listen for incoming requests on the adapter and driver specified by NET1 as well as the adapter and driver specified on the NET2 line.

The configuration information provided under the LM10 NetBIOS (NETBEUI) driver section in PROTOCOL.INI file is used to initialize the LM10 NetBIOS driver. This is the total pool of resources that NB30 NetBIOS.OS2, LAN Server and Requestor share. LAN Server and Requestor get their resources based on the configuration in the virtual network statements (net#) in IBMLAN.INI file. The remaining pool of resources is given to the NB30 NetBIOS driver to distribute to standard NetBIOS applications.

The adapter# statements under the NETBIOS section in the PROTOCOL.INI and the net# statements in IBMLAN.INI file allow applications to open LM10 NetBIOS drivers by logical network name, independent of the actual driver name and LANA number.

Initialization
LM10 NetBIOS drivers should perform device initialization at load time just like any other OS/2 device driver. In addition to supporting the standard driver initialization sequence, LM10 NetBIOS drivers must also support the DosDevIoctl command that is issued by each of the LM10 applications during system initialization. The LM10 NetBIOS driver initialization sequence is:
 * 1) Respond to the device Init command at driver load time by allocating packet buffers, setting up tables, and running start-up diagnostics as appropriate.
 * 2) Respond to the sequence DosOpen, DosDevIoctl: NetBIOSLinkage, DosClose. Each of the LM10 NetBIOS applications use this mechanism to pass the entry points of their PhysNCBDone and VirtNCBDone routines and other configuration parameters. The LM10 NetBIOS driver is responsible for filling in a table of parameters that the LM10 NetBIOS application needs.

LM10 NetBIOS drivers must be prepared to respond to multiple initialization sequences of DosOpen/DosDevIoctl: NetBIOSLinkage/DosClose. For a driver supporting multiple LANAs, this would happen once for each LANA defined in the subset of LANAs defined in the NETBIOS section of PROTOCOL.INI and the [networks] section of IBMLAN.INI file.

NetBIOS Linkage
Shown below is the format of the Ioctl request packet that the LM10 NetBIOS driver will recruit as the result of one of the LM10 NetBIOS application performing the DosDevIoctl: NetBIOSLinkage call.

Note that the GDT selectors allocated via the AllocGDTSelector Device Help are not valid to use during initialization. Any access to memory that normally would be done via an allocated GDT selector must be done via PhysToVirt.

The LM10 NetBIOS driver will only have to respond to DosOpen and DosClose if bit 11 of the Device Attribute field in the Device Driver Header is set.

PhysNCBDone and VirtNCBDone addresses that are passed to the LM10 NetBIOS driver are only valid after completion of CONFIG.SYS processing by OS/2.

LM10 NetBIOS drivers should determine if the given version of NB30 NetBIOS or NETWKSTA.200 or HPFS386.IFS software supports the VirtNCBDone entry point by checking the Parameter Packet length. If the length is less than 14 bytes, the VirtNCBDone entry point is not available.

LM10 NetBIOS drivers should determine if the given version of LM10 NetBIOS application is capable of providing virtual buffer addresses in NCBs by checking the Parameter Packet length and by examining the bit 0 of the Parameter Packet word at offset 15. If the length is less than 16 bytes, OR if bit 0 or the Parameter Packet word at offset 15 is set to 0, then the LM10 NetBIOS application will not provide virtual buffer addresses in NCBs.

LM10 NetBIOS driver should complete the Ioctl request by filling in the NetBIOSLinkage structure whose address is conveyed in the Ioctl request packet. The format of the NetBIOSLinkage structure is shown below:

Command descriptor bits: The OEMExtTable is an optional table that can have zero entries. It defines NCB commands that are OEM-defined extensions to the standard NetBIOS interface. The CmdInfo parameter describes the extended NCB's usage of buffers and asynchronous notification. It also indicates whether the command is cancellable and whether the requesting ring 3 application needs to have opened the NetBIOS driver in privileged or exclusive mode to issue the command. The LAN Redirector software that supports ring 3 NetBIOS applications needs this information to provide correct addressing and protection in making application-level buffers available to the LM10 NetBIOS driver in physical address form.

NCB Handler
One of the LM10 NetBIOS application obtains the address of the NetBIOS NCB handler at system initialization time using the NetBIOSLinkage DosDevIoctl described earlier. The NetBIOS NCB handler is entered via a far call. The calling conventions are essentially identical to those for real-mode INT 5C, except that ES:BX is the virtual address of the NCB to be executed. The virtual address of the NCB (passed in ES:BX and TOS+4) is always a GDT address and is accessible by the NetBIOS driver (both at task time and interrupt time) until the driver has completed the NCB (or rejected it via the immediate return code).

Parameters are passed both in registers and on the stack. The NTCB handler must preserve BP and always exit via a far return with parameter removed from the stack and with immediate NCB return code in AX. These conventions allow the handler to be coded in high level languages.

Note that if the immediate result code is non-zero, the NCB is considered to be complete and an NCBDone routine must NOT be called.

The addresses within the NCB contained in the NCB_BUFFER and NCB_CALLNAME fields are physical addresses that are guaranteed to be valid until the invocation of PhysNCBDone or VirtNCBDone.

The LAN Redirector software also provides virtual buffer addresses in the NCB_NAME field for the following NetBIOS commands: NCB.CHAIN.SEND, NCB.CHAIN.SEND.NO.ACK, NCB.SEND. NCB.SEND.NO.ACK, NCB.RECEIVE and NCB.RECEIVE.ANY. For commands that carry a single buffer, the virtual address of the buffer is conveyed in the first four bytes of the NCB.NAME. For commands that carry two buffers addresses (e.g., NCB.CHAIN.SEND), the virtual addresses are contained one after the other in the first eight bytes of the NCB_NAME field. LAN Redirector or LAN Server software may not always supply the virtual address within the NCB. In these cases, the SELECTOR portion of the virtual addresses in the NCB_NAME field will be zero. Therefore, NetBIOS drivers should only attempt to use the supplied virtual address if the address SELECTOR field is non-zero. LM10 NetBIOS drivers should use the information passed at NetBIOSLinkage time to determine if the given software is capable of supplying virtual addresses in NCBs.

The values of NCB_POST and NCB_CMD_CPLT fields are reserved and must not be modified during the course of NCB processing.

The LM10 NetBIOS NCB handler should not distinguish between synchronous and asynchronous NCBs. It need just start the necessary I/O and return. NCB completion and synchronization is handled by the NCBDone routine.

[Note] The NCB handler MUST NOT block at any time.

NCB Completion
The LM10 NetBIOS driver must issue a far call to either PhysNCBDone or VirtNCBDone upon completing processing of an NCB (usually at interrupt time). The far addresses of PhysNCBDone and VirtNCBDone are passed to the driver at initialization time via the NetBIOSLinkage DosDevloctl. The address of the NCB being completed must be passed to the given NCBDone on the stack.

The LM10 NetBIOS driver must satisfy the following conditions when calling PhysNCBDone or VirtNCBDone:
 * 1) The LM10 NetBIOS driver must always call the given NCBDone routine in protected mode.
 * 2) The stack segment at the time of the call must be the same stack segment on which the driver was entered (either at interrupt time or at task time). If the NetBIOS driver uses the Device Help GoProt in an interrupt handler, then the driver should use the stack segment that was resumed from GoProt.
 * 3) The stack should be set up as follows:
 * 4) The NCB_RETCODE field must have been completed with a suitable return code value.
 * 5) NCBs_POST and NCB_CMD_CPLT fields must contain the values that they had at NCB submission time.
 * 6) All NetBI0S processing of this NCB must be complete. The internals of NCBDone reserve the right to modify the NCB in any way.
 * 7) Common Problems, Hints and Suggestions
 * 8) *It is recommended that LM10 NetBIOS drivers for LAN Redirector, LAN Server and NB30 NetBIOS support a configurable "call" time-out. This parameter specifies the maximum amount of time that the driver will wait for a response from the remote machine when handling NCB.CALL, NCB.ADD.NAME and NCB.ADD.GROUP.NAME commands. The parameter should be settable via system configuration files.
 * 9) *When transferring blocks of data using the REP instruction, a maximum size of 2K is allowed. Please refer to the OS/2 Device driver guidelines.
 * 10) *For performance reasons, it is recommended that PhysToGDT be used whenever possible instead of PhysToVirt.
 * 11) *The NCB handler MUST NOT block at any time.
 * 12) *When a session is aborted (as opposed to hung-up), the driver should return the error code 18H (Session Ended Abnormally). The error code OAH (Session closed) should only be resumed when either end hangs up the session.
 * 13) *LAN Server or LAN Redirector or NETBIOS NB30 driver needs this information for its session handling.
 * 14) *The virtual address passed (on the stack) to the VirtNCBDone must be the SAME address that was passed to the LM1O driver's NCB handler in ES:BX (and on the stack).
 * 15) *The LM10 NetBIOS driver may use either PhysNCBDone or VirtINCBDone, but must only call ONE of the routines for any given NCB.
 * 16) *For performance reasons, the LM1O NetBIOS driver should:
 * 17) ** use the virtual address supplied in the NCB_NAME field when provided
 * 18) ** support interrupt time submission of NCBs

NetBIOS Command Descriptions

 * NCB.ADD.GROUP.NAME:Same as LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.ADD.NAME:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * This NCB is also used to request Name#1.
 * To request Name#1, NCB_NAME+0 must be 0x00 and NCB_NAME+1 must be 0x2A(*).


 * NCB.CALL:Same as LAN Technical Reference for OS/2DD interface, minus supplied field of NCB_POST@
 * plus supplied field of NCB_FLAGS
 * If bit 0x08 is off, PiggyBackAck is requested.
 * If bit 0x08 is on, no PiggyBackAck is requested.


 * NCB.CANCEL:Same As LAN Technical Reference for OS/2 DD interface,
 * NCB.CHAIN.SEND:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.CHAIN.SEND.NO.ACK:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCBDELETE.NAME:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * This NCB is also used to request Name#1.
 * To request Name#1, NCB_NAME+0 must be 0x00 and NCB_NAME+1 must be 0x2A(*).


 * NCB.FIND.NAME:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.HANG.UP:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB_BUFF@ is set to 0xFFFFFFFF when an ncb.hang.up is issued as a result ncb.reset.


 * NCB.LAN.STATUS.ALERT:Same As LAN Technical Reference for OS?2 DD interface, minus supplied field of NCB_POST@
 * NCB.LISTEN:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * plus supplied field of NCB_FLAGS
 * If bit 0x08 is off, PiggyBackAck is requested.
 * If bit 0x08 is on, no PiggyBackAck is requested.


 * NCB.RECEIVE:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.RECEIVE.ANY:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.RECEIVE.BROADCAST.DATAGRAM:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.RECEIVE.DATAGRAM:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.RESET:Supplied fields are
 * NCB_ADPTR_NUM
 * Returned fields are
 * LOAD_SESSIONS at NCB_NAME+8 (1 byte field) The number of commands defined at LM10 load time.
 * LOAD_COMMANDS at NCB_NAME+9 (1 byte field) The number of commands defined at LM10 load time.
 * LOAD_NAMES at NCB_NAME + 10(1 byte field) The number of names defined at LM10 load time.
 * This Number includes Name #1.
 * Note: These are the only fields required for NCB.RESET.


 * NCB.SEND:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.SEND.BROADCAST.DATAGRAM:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.SEND.DATAGRAM:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.SEND.NO.ACK:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.SESSIONS.STATUS:Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
 * NCB.TRACE:Not supported

DDID Support for LM10 Protocol Driver
IBM NetBIOS Netbeui LM10 protocol driver adds this DDID support. The LM10 interface specification does not include a Device Driver Identification Number concept (DDID). The NB30 NetBIOS driver identifies its applications with this DDID. The LM10 protocol stack assumes that only one application is running. Hence a NetBIOS application using LMl0 stack may end up getting another NetBIOS application's data when it uses NCB.RECEIVE.ANY for any name or NCB.RECEIVE.DATAGRAM for any name.

DDID is also associated with NetBIOS Group Name, so the same application cannot add the same group name twice. IBMs LM10 protocol stack Netbeui and TCPbeui have been enhanced to include the DDID concept. Netbeui identifies names, with DDID, so NetBIOS applications using netbeui or TCPbeui are guaranteed to get their own data. Any NetBIOS application running over OEM LM10 stack may not get the correct data if it uses NCB.RECEIVE.ANY for any name or NCB.RECEIVE.DATAGRAM for any name if LM10 stack does not use DDID concept.

Resource Consideration
Since the LM10 interface does not specify any NetBIOS resource related information in the NETBIOS LINKAGE structure, NB30 NetBIOS and LAN Redirector depend on the values configured in protocol.ini file. If an OEM LM10 protocol does not add a protocol section in protocol.ini, then the default values assigned by these drivers (NB30 NetBIOS, LAN Server and LAN Redirector) will be used for NetBIOS resources.

Implementation Specific Information
NetBIOS.OS2 driver uses some of the bytes in the NCB's reserve field. So LM10 protocol drivers are expected to preserve this field. WORD PTR ncb_reserve + 0 WORD PTR ncb_reserve + 6 WORD PTR ncb_reserve + 8 WORD PTR ncb_reserve + 12 The first two bytes of the reserve field, four bytes starting from offset reserve + 6 and two bytes starting from offset reserve + 12 need to be preserved.

Reserved NCB Command Codes
The following NetBIOS Command Block codes are reserved by IBM:
 * NB30 NetBIOS supports the ATTACHDD Device Driver Interface defined in the IBM Local Area Network Technical Reference Manual.

Notices
August 1994

Issued by:

IBM Corporation

Personal Software Products

11400 Burnet Road

Austin, Texas 78758

First Edition (August 1994)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Copyright Notices
© '''Copyright International Business Machines Corporation 1994. All rights reserved.'''

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.

Trademarks
The following terms, denoted by an asterisk (*) in this publication, are trademarks of the IBM Corporation in the United States and/or other countries:
 * IBM
 * OS/2
 * AT
 * Micro Channel
 * Operating System/2
 * LAN Server 2.0
 * Extended Services
 * LAN Adapter and Protocol Support