BSCV2 SUPPORT FOR WINDOWS (June 96) DEVELOPMENT NOTES
-----------------------------------------------------
Copyright (c) 1996 Sangoma Technologies Inc.
This 'readme' file is a supplement to the BSC Support for MS-DOS
Operations Manual.
CONTENTS
--------
1. Development Distribution Files
2. Introduction to NAPI
3. SDLA Configuration and Downloading of BSC Code
4. SDLA Driver Installation and the SDLA.INI File
5. BSC Application Development Notes
6. NAPI User Functions
1. Development Distribution Files
---------------------------------
The following files are part of this development toolkit:
Windows 3.1:
SDLA .DRV - Sangoma S502A/E/S503 SDLA card driver
OEMSETUP.INF - Sample setup information file for SDLA driver
NAPI .DLL - Dynamic link library providing Bisync API for applications
NAPI .LIB - Import library for load-time dynamic linking of NAPI.DLL
NAPI .H - Application include file with NAPI function prototypes/defines
NAPI .HLP - NAPI function reference (use WINHELP engine to view it)
Windows 95/NT:
SDLA .SYS - Sangoma S502A/E/S503/S508/S514 SDLA card driver (Windows NT only)
NAPI32MC.DLL - Dynamic link library providing BSC API for applications
NAPI32MC.LIB - Import library for Microsoft Visual C++ applications
NAPI32MC.H - Application include file with NAPI function prototypes/defines
NAPI32IM.DEF - NAPI32MC.DLL imports list for linking with Borland C++
NAPI32 .HLP - NAPI32 function reference (use WINHELP engine to view it)
Common:
DEVELOP .TXT - This file
NAPI_M .H - Command code header file for BSC
NTEST .C - Source code for NTESTer
NTEST .RC - Resource script for NTESTer
Windows 3.1:
NTEST may be built by specifying large memory model, and Windows 16-bit .EXE
as the target. It only needs the standard runtime library linked in, as well
as the NAPI.LIB.
Windows 95/NT/2000:
NTEST may be built by specifying GUI Win32 as the target. It only needs the
standard runtime library linked in, in addition to NAPI32MC.LIB.
2. Introduction to NAPI
-----------------------
The NAPI Dynamic Link Library provides a simple but powerful interface for
the development of applications in Windows.
Instead of communicating with the board directly, as would be necessary in
DOS, the NAPI library provides a function call (NAPIControl) to copy the
control block to the mailbox and to wait for opp_flag to be reset. The
purpose of the SDLA driver is to provide a mechanism for reading from and
writing to card memory, which is used by the NAPI library to perform the
functions it provides. It is not intended for the application to access the
driver directly. In Windows 95, the driver's functions are incorporated in
the DLL and so no external driver exists.
The SDLA driver also allows for the use of multiple cards, referenced by a
logical card number. As described in section 4, a configuration entry would
appear in the SDLA.INI file for each logical card. When the driver is first
loaded by the first setup call to the NAPI library (see NAPISetup), this
configuration is read by the driver and stored internally, so that any
references to a logical card number may be resolved to access the appropriate
physical card. The logical card number is passed as a parameter when required
by the particular NAPI function call. It is also required that any
application instance using a particular logical card must register itself with
the NAPI library for the usage of that card before accessing it (see
NAPIRegisterCard).
3. SDLA Configuration and Downloading of BSC Code
-------------------------------------------------
A loader program is provided in the set of utility programs accompanying this
development kit, called WINNLOAD. It uses information provided by NCONFIG,
the Configurator utility, to locate and download the SDLA test code and BSC
code, and to download the configuration settings. There is no facility in
the NAPI library or in the SDLA driver to perform the downloading function.
However, they are both used in the downloading process by WINNLOAD to perform
low-level functions for accessing the card. The details of this procedure
are currently undocumented, and it is recommended that NCONFIG and WINNLOAD
be used wherever possible for this purpose.
It is NOT possible to load the card using the DOS BLOAD utility inside a
command shell window in Windows NT. This is because command shells operate
in their own address space and do not have direct access to the physical
memory and ports required for loading the card. You may notice this when
running DOS DEBUG, if you try to look for some particular bytes that are
normally found when running it from plain old MS-DOS. The only way to
load the card using BLOAD is to boot the system from a floppy with MS-DOS,
then run BLOAD, and then reboot Windows NT.
For more information on configuring and loading cards, read the README.TXT
file found with the utility set.
4. SDLA Driver Installation and the SDLA.INI File
-------------------------------------------------
It is highly recommended that the INSTALL program be used to install the
driver, and the NCONFIGurator program be used to make changes to the settings
in the SDLA.INI file. However, if it is necessary to perform these functions
directly, without the use of the provided utility programs, the procedure
is outlined below.
Windows 3.1/95:
---------------
The SDLA driver may be installed and configured by following these steps:
0. If the platform is Windows 95, skip to step 6.
1. Choose the "Drivers" icon in Control Panel.
2. Choose the "Add..." option in the Drivers dialog box.
3. Choose the "Unlisted or Updated Driver" entry in the list box.
4. Type the pathname of the OEMSETUP.INF file accompanying the SDLA driver.
5. The driver name should appear in the dialog. Select OK.
The driver should now be installed, and an "sdla" entry should be found in the
[drivers] section of SYSTEM.INI, and in the [Userinstallable.drivers] section
of CONTROL.INI along with a description in its [drivers.desc] section. A copy
of this driver should now be located in the system directory of Windows.
6. Copy the file SDLA.INI that accompanied the driver to the Windows directory
(e.g. C:\WINDOWS).
7. Edit the SDLA.INI file, and enter a section for each logical card being
referenced by all applications that will run on the system as follows:
[sdla<logical_card_number>]
window_segment=<segment>
window_offset=<offset>
window_size=<size>
io_port=<port>
The section header must appear as presented and is case-sensitive, so make
sure that "sdla" is typed in lower case, and that no spaces are inserted in
the header. <logical_card_number> must be a unique integer between 0 and 15.
<segment> must be a 16-bit memory segment value and may be expressed in
decimal or in hex by using the notation 0x<hex_value> where <hex_value> may be
in upper or lower case. <offset> must be a 16-bit memory offset indicating
the window position in the segment, and may again be in decimal or hex.
<size> must be a 16-bit window size value, typically being 0x2000. The 20-bit
physical address of the card is of course (<segment> * 16L) + <offset>.
The <port> base address must be specified only if the WINNLOAD program is to
be used, and follows the same notation as above.
The [NAPI] section in this SDLA.INI file is used by the NAPI.DLL, and appears
as follows:
[NAPI]
SDLA_timeout_in_seconds=<number_of_seconds_from_1_to_65535>
The timeout entry above specifies the number of seconds that are allowed to
elapse before deciding that the SDLA is not responding to a command, in which
case a Z80_TIMEOUT return code will be encountered by the application on a
call to NAPIControl.
There are some other entries normally found in SDLA.INI, such as path
specifications that are used by NCONFIG and WINNLOAD, that are not necessary
for general use of the card if already loaded and configured by some other
means.
Windows NT/2000:
-----------
The SDLA driver may be installed and configured by following these steps:
1. Copy the SDLA.SYS file to the <windir>\system32\drivers directory.
2. Run REGEDT32 found in your system32 directory.
3. Add the following key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\SDLA
4. Add the following values to this key:
ErrorControl: REG_DWORD: 0x1
Start: REG_DWORD: 0x2
Type: REG_DWORD: 0x1
5. If you wish to provide a hardware configuration for a logical card
without using NCONFIG (which is strongly unadvisable), add the subkey:
Parameters\sdla<logical_card_number>
and add the following values to this key:
window_segment: REG_DWORD: <segment>
window_offset: REG_DWORD: <offset>
window_size: REG_DWORD: <size>
io_port: REG_DWORD: <port>
6. Copy the file SDLA.INI that accompanied the driver to the Windows directory
(e.g. C:\WINNT35).
7. Edit the SDLA.INI to add the [NAPI] section as explained above.
5. BSC Application Development Notes
------------------------------------
Windows 3.1:
------------
The 16-bit NAPI.DLL was written in C, and compiled using Borland C++ 4.0 under
the large memory model with 16-bit Windows 3.1 as its target platform. The
exported functions are prototyped in NAPI.H, and the import library NAPI.LIB
is provided for linking with your projects. This NAPI.DLL file may be placed
in the system directory of Windows, or in the default startup directory of the
user application. NAPI.HLP is an on-line reference (for WINHELP viewing) for
all documented and supported functions provided by NAPI.DLL.
The NAPI.DLL is designed to handle calls from multiple application instances,
but does not keep track of which instances are using any given logical card.
It is the responsibility of the developer or the user to ensure that
protocol-level conflicts do not occur as a result of sharing the same
resource(s).
Windows 95/NT/2000:
--------------
The 32-bit NAPI32MC.DLL was written in C, and compiled using Microsoft Visual
C++ 5.0. The exported functions are prototyped in NAPI32MC.H, and the import
library NAPI32MC.LIB is provided for linking with your projects that are
compiled under Visual C++. If Borland C++ or other compiler is used, link
with NAPI32IM.DEF which contains the list of exports from the DLL in the
IMPORTS section. If other items need to be added to the module definition
file, insert the contents of NAPI32IM.DEF in the application's .DEF file.
Note that the __cdecl calling convention is used for all exported functions.
See NAPI32MC.H for more information.
The NAPI32MC.DLL file may be placed in the system directory of Windows NT
(<windir>\system32), or in the default startup directory of the user
application. NAPI32.HLP is an on-line reference (for WINHELP viewing)
for all documented and supported functions provided by NAPI32MC.DLL.
The kernel mode driver SDLA.SYS was built using Windows NT DDK.
The NAPI32MC.DLL is loaded for each new calling process, and does not keep
track of which processes (or threads) are using any given logical card. It is
the responsibility of the developer or the user to ensure that protocol-level
conflicts do not occur as a result of sharing the same resource(s).
Example:
--------
Putting the Windows-related code aside, if a program's only goal is to add
a station and send "hello" to this station (in multipoint BSC), the NAPI
calling sequence would be of the form:
.
#include "napi.h" // include typedef's and function prototypes for NAPI
or
#include "napi32mc.h" // 32-bit library
.
CBLOCK cb;
char *message = "hello";
BYTE station_number;
.
NAPISetup(); // set up DLL for another caller
NAPIRegisterCard(0); // register a usage request for logical card 0
cb.command = ADD_STATION;// set command code
cb.buffer_length = 0; // no data to follow control block
// set station address information
cb.poll_address = 0x40;
cb.select_address = 0x60;
cb.device_address = 0x40;
NAPIControl(&cb, 0); // issue command to card 0 and wait for a response
if (cb.return_code == 0) {
// successfully added the station
// record the station number for future reference
station_number = cb.station;
cb.command = BSC_WRITE;
cb.buffer_length = 5;
strcpy(cb.data, message);
// not necessary in this case, but done in general (station_number)
cb.station = station_number;
cb.misc_tx_rx_bits = 0; // not transparent and ETX
NAPIControl(&cb, 0);
if (cb.return_code == 0) {
// text message sent
} else {
// failed to send for some reason, indicated by this code
}
}
NAPIDeregisterCard(0); // use of logical card 0 no longer required
NAPICleanup(); // DLL is no longer required
.
For simplicity, this example does not illustrate the need for checking return
codes as appropriate, such as for ensuring the card registration proceeded
successfully - if not, it is likely that a Protection Fault will occur
while the driver attempts to access memory without having the corresponding
selector and memory pointer initialized.
***** WARNING: Make sure that the CBLOCK structure is packed (aligned) on
1-byte boundaries! This is a compiler option. The #pragma pack(1)
directive is included in NAPI32MC.H for Microsoft compilers.
6. NAPI User Functions
----------------------
The available functions are listed in the contents page of NAPI(32).HLP,
and each function is documented in detail in this help file.
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.