Contents:

Purpose/Objective

Documentation Change Requests

Intended Audience

Developer's Toolkit Documentation

Development Process Overview

Graphics Drivers - Development and Test Instructions

Network Drivers - Development and Test Instructions

ISDN Drivers - Test Instructions

Deliverables

SCO Driver Hand Off Processing

Check List Template

File Verification Template

Driver README Template

Change Description Template

Supplements

Glossary

Purpose/Objective

While this new paradigm releases us from meeting Media Kit release deadlines, there is still an acceptance criteria which must be met for each new/updated driver received.  The purpose of this document is to define the high level requirements which comprise a hand off that will meet the acceptance criteria.  Technology Partners will be kept apprised of SCO's Media Kit releases and any specific requirements which are not covered in this document via email from their appropriate SCO liaison (i.e., Vendor Manager.)

This document does not address requirements for other driver certification programs within SCO, i.e., Test and Certified Program, Vendor Contributed Program, etc.

Documentation Change Requests

kathryna@sco.com.

Intended Audience

Developer's Toolkit Documentation

Hardware Developers Kit (HDK)
 

To familiarize yourself with the latest information on driver development, review the following documentation from the developer's toolkit.

• Test Documentation
• Driver architecture guidelines and man pages (i.e.,  the MDI Guidelines and man pages for network drivers and the NFB Guidelines and man pages for graphics drivers)
• For a list of online topics of interest to driver developers see Using the HDK documentation set located at: http://www.sco.com/su pport/docs/ -> UnixWare 8 -> Hardware and Driver Development. Search for Using the HDK documentation set.

---

Development Process Overview

1. Unless otherwise instructed by your SCO liaison, install the following SCO Software:
• The latest shipping version of the Enterprise OS and Development System software for the appropriate platform on your build machine
• The appropriate build tree from the developer's toolkit (i.e., HDK) on your build machine
. If you are not provided a special build tree from SCO, you should install the ndsample package on UnixWare 7 or the O5ndsample package on OpenServer Release 5 and build your driver according to the instructions contained within the appropriate network driver sample package. Typically, SCO will not provide a build tree other than the network driver sample packages.
• The latest shipping version of the Enterprise OS on your test machine(s)
• The appropriate test suite from the developer's toolkit (i.e., HDK) on your test machine
2. Create a working directory for your driver in the build tree on the build machine, develop and compile the driver and make an installable floppy of the driver
3. Install the floppy on the test machine using custom or pkgadd
4. Execute the appropriate Test Plan and prepare the Test Results Report
5. Provide the deliverables defined below to SCO

Graphics Drivers - Development and Test Instructions

UnixWare 7 Graphics Driver Development

To implement autodetection of your graphics adapter, create the following files listed below. ddd is the manufacturers directory name and xxx is the model name of the video adapter.

 

• /usr/lib/vidconf/AOF/UNIQUE/ddd/xxx

The unique file is used to uniquely detect which video adapter is installed in the system. The Video Configuration Manager executes /usr/lib/vidconf/AOF/bin/grafdetect to autodetect the video adapter in the system. To create a unique file, copy one from another directory as a starting template and modify it.

The unique file has the following structure:

set ADAPTER(matrox.millennium_1) {
        {UNIQUE_ID {PCI_SLOT 
OEM_STRING BIOS_STR SAFE_EXEC}}
        {PCI_SLOT 
{102b0519000000}}
        {OEM_STRING {Matrox 
Graphics Inc.}}
        {BIOS_STR 
{{MATROX/MILLENNIUM}}}
        {SAFE_EXEC 
{/usr/X11R6.1/lib/vidconf/scripts/milpci}}
        {GRAFINFO 
{matrox/milpci.xgi}}
}

 
• ADAPTER is a unique string that represents your video adapter. It is usually of the form ddd.xxx.misc.
• UNIQUE_ID is a list of ID's that should be verified to determine if this video adapter is uniquely detected.
• PCI_SLOT is your video adapter's PCI ID string returned by running /usr/lib/vidconf/AOF/bin/pcislot
• OEM_STRING is your video adapter's OEM STRING returned by running /usr/lib/vidconf/AOF/bin/vesa -v
• BIOS_STR is a string in the video bios that helps further uniquely identify your video adapter. Run /usr/lib/vidconf/AOF/bin/vrom | strings | more and pick a string (or substring) that uniquely identifies your video adapter.
• GRAFINFO is the grafinfo file the Video Configuration Manager uses if the video adapter is uniquely identified.

 

• /usr/lib/vidconf/scripts/xxx

The Video Setup script is executed by the Video Configuration Manager to create a grafinfo file that includes I/O and Memory addresses for the Video Adapter. The script runs sed on a grafinfo template .tmpl file and updates the grafinfo .xgi file with new information. The exit status is 0 for success and 1 for failure. The script file may also be executed by the unique file to determine if the card is found in the system. Copy a script file as a starting template and modify it.

 

• /usr/lib/vidconf/AOF/ID/ddd/xxx

The AOF/ID file was used in OpenServer Release 5 for autodetection of graphics adapters. AOF/ID files are not used in UnixWare 7.

 

• /usr/lib/grafinfo/ddd/xxx.xgi and /usr/lib/grafinfo/ddd/xxx.tmpl

The grafinfo .xgi and template .tmpl files contain configuration information for your video adapter. The grafinfo .xgi file is read by the Video Configuration Manager during resolution/mode selection. If:

VIDSETUP = "/usr/lib/vidconf/scripts/xxx";

is specificed in the DATA section of the grafinfo file, the Video Configuration Manager executes this Video Setup script (see above) to update your .xgi file to contain I/O and MEMORY addresses for your Video Adapter. VIDSETUP is included in the initial .xgi file and in the template .tmpl file so that successive configurations work properly.

 

• Source Code Product (SCP) Requirements
  SCO ships a Source Code Product that does not contain vendor source code. However, the Source Code Product is required to cut the same product that SCO ships in our standard product. To meet this requirement, graphics vendor Imakefiles must be SCP aware. SCO has provided the environment variable SCP_PRODUCT and also SCP imake rules that check for the existence of one of your source files. Typically xxxInit.c.

  Below is a code fragment of generic SCP usage in a Graphics driver Imakefile. Change xxx to your driver prefix when adding these rules to your Imakefile.

  /*
   * @(#) Imakefile 77.1 98/09/01
   *
   * The information in this file is provided for the exclusive use of 
  the
   * licensees of SCO International, Inc.  Such users have the 
  right
   * to use, modify, and incorporate this code into other products for 
  purposes
   * authorized by the license agreement provided they include this 
  notice
   * and the associated copyright notice with any such product.  The
   * information in this file is provided "AS IS" without warranty.
   *
   *       Copyright (C) 2001 SCO International, Inc.
   *
   */
  
  ...
  
  #ifndef SCP_PRODUCT
  NormalLibraryTarget(xxx,$(OBJS))
  SharedXDriverTarget(xxx,6.0,$(OBJS),shared,..)
  #endif /* SCP_PRODUCT */
  
  DynamicObjectRuleSCP(xxx,$(DDXLIBS),xxxInit.c)
  DependTargetSCP(xxxInit.c)
  
  ...
  
  

  • To test that your driver works properly in an SCP build environment, do the following:

     

    • do a full make of your driver
    • now remove the source code (.c's and .h's) from your driver directory
    • add  #define  SCP_PRODUCT  1 to the beginning of your Imakefile
    • make Makefile
    • make Makefiles
    • make includes
    • make depend
    • make
    • make install DESTDIR=/tmp

     

  • None of the above make commands should complain that source code is missing.

UnixWare 7.0.1 Graphics Driver Development

The NFB Graphics Driver Development Kit (xlinkkit) provided in the Hardware Developers Kit will function on this release if several modifications are made.

 
• The nap(S) function call was removed from UnixWare 7.0.1 development libraries. It is required by the XServer in the xlinkkit for it to build and run correctly. Details for this fix must be obtained from SCO.

UnixWare 7.1.0 Graphics Driver Development

The NFB Graphics Driver Development Kit (xlinkkit) provided in the Hardware Developers Kit will function on this release if several modifications are made.

 
• A globals files used by the XServer in the xlinkkit must be modified for the XServer to build and run correctly. Details for this fix must be obtained from SCO.

UnixWare 7 Graphics Driver Test Plan

A.  Installation of your test machine

NOTE: You must have all required supplements installed.

Follow the installation instructions provided with UnixWare 7.

The UODK is required to build the Unisoft Test Suite

1. log in as root
2. Insert the UODK cdrom into your computer and type:
pkgadd -d cdrom1
3. Press Enter to select the udk  package set.
4. Install all of the packages or install only the X11R6 Development System
5. Select Apply
6. Enter your Development System license number
7. Select Apply
8. Select quit after the installation completes

The HDK contains the Unisoft Test Suite and the performance tests  x11perf and  xbench.

1. log in as root
2. Insert the HDK cdrom into your computer
pkgadd -d cdrom1
3. Press Enter to select the hdk  package set.
4. Install all of the packages or install only the X11R6 Graphics Test
5. Select Apply
6. Answer yes to the question  Do you want to install the Unisoft Test Suite? (default y)
7. Press Enter to install the test suites into the default directory of /usr/src/ihvkit/display/test/xsuite
8. Select quit after the installation completes

Disable scologin so it does not interfere with the test suites.

scologin disable

Use the MakeProduct script on your build machine to build your Video Driver package file. You can then install the package file on the test machine using the command:

pkgadd -d /tmp/XD.pkg

B. Video Configuration

Configure your video adapter to use the highest resolution possible on your monitor using 256 colors. Configure a second resolution on vt02 (or tty02 for OpenServer 5)using a different resolution and a different color depth. While configuring your video adapter, you will:

• verify your video adapter is automatically detected
• all of the strings in your grafinfo file are spelled correctly

1. Run the Video Configuration Manager to configure your adapter.
scoadmin video
2. Select Add Adapter
Your video adapter should be autodetected.
3. Select OK
4. Select Monitor
Select a monitor from the list (any monitor is fine). However, if the vertical refresh rate of the monitor is listed in the grafinfo file, make sure you have a monitor attached that supports that refresh rate.
5. Select Resolution
• Verify that all resolutions are syntactically correct.
• Verify that all resolutions are listed starting with the highest resolution, frequency and number of colors first. The resolutions should decrease by number of colors first, then frequency, and then resolution.
6. Configure the highest resolution supported by your monitor (at 256 colors).
7. Select OK
8. Select Assign all function keys
 

NOTE:  You just completed configuring all screens with your resolution selection. Now configure a different resolution and color depth to run on vt02/tty02. This is used to verify screen switching later.

 

Select Modify

Select OK

Select Add Resolution

Select a different resolution and a different color depth. For example, if you initially selected 1280x1024  256 colors select 1024x768  64K colors

Select Specify function keys

Select OK

Select vt02

This configures 1024x768  64K colors on screen vt02/tty02

Select OK

Select OK

Note the warning that you are removing the 1280x1024 configuration from this screen

Select OK

Keep selecting OKuntil the Video Configuration Manager exits back to the system prompt.

 C. Grafinfo file testing

Verify all resolutions/modes listed in the grafinfo file function and display correctly

Use graftest to verify that all modes work and the X server root weave and mouse cursor appear on the screen correctly. graftest prompts you to run each resolution listed in your grafinfo file.

graftest  /usr/lib/grafinfo/ddd/xxx.xgi

ddd is the grafinfo directory name and xxx is your grafinfo file name.

graftest will use the Video Driver installed in /usr/lib/X11/dyddx. If you have created a XServer that is statically linked to your Video Driver, which is located in /tmp/Xsco, you can run it using the command:

graftest  /tmp/Xsco  /usr/lib/grafinfo/ddd/xxx.xgi

Step through all resolutions/modes and make sure the root weave and mouse cursor appear on the screen correctly.

 D. Color, Font, Window Manager and Screen Switch testing

Verify the resolution/modes configured on vt01/tty01 and vt02/tty02 display correctly

Run /usr/bin/X11/color3 to verify the correct number of colors are displayed (256, 64K, ...). Resize and move the color3 window around the screen and check for screen corruption. Run /usr/bin/X11/text2 to verify fonts are displayed correctly.

For OpenServer 5 use /xtests/color3/color3 and /xtests/fonts/text2

1. startx
2. /usr/bin/X11/color3 &  (or  /xtests/color3/color3)

NOTE:  If color3 appears solid white (or black), try resizing the window. The colorwheel will appear after doing this. If you expose a covered portion of the color3 window and it does not redraw, resize the window again. This is a problem with color3.

3. /usr/bin/X11/text2 -a &  (or  /xtests/fonts/text2 -a)

While exercising the Window Manger pmwm, verify no screen corruption occurs when pop-up menus are displayed and when windows are moved around or resized.

1. Pop-up or pull-down some menus
2. Run color3 and other windows. Move them around and resize them
3. Watch for screen corruption

1. Switch screens between vt01/tty01 and vt02/tty02 and a text screen vt03/tty03 slowly and rapidly. Use the key sequence ctrl-alt-F1, ctrl-alt-F2, ..., to switch screens.
2. Verify color3 colormap is not corrupted during screen switches
3. Watch for other screen corruption

E. Desktop Verification

Verify the resolution/modes configured on vt01/tty01 and vt02/tty02 display the Desktop correctly

1. startx
2. Closely watch the Desktop as it is starting up. Pop-up and pull-down some menus, move and resize windows.
3. Watch for screen corruption

 F.  Unisoft Test Suite (UTS)

The UTS is an automated test suite. It will find rendering errors in your XDriver and is useful for regression testing after making any changes to your XDriver. Please run the UTS at each color depth supported by your video adapter. You may have to configure additional resolution/modes/color depths on more screens using the Video Configuration Manager scoadmin video.

The UTS is provided in source form with UnixWare 7. You must first build the UTS prior to running it. Instructions to do this are provided below.

• /usr/src/ihvkit/display/test/xsuite/xtest/doc
• /usr/src/ihvkit/display/test/xsuite/tet/posix_c/doc

It is recommended that all XDriver writers read the Users Guide. This guide provides a more thorough understanding of the UTS. Print the file .../xtest/doc/userguide.{mm,ps}

• cd  /usr/src/ihvkit/display/test/xsuite
• RunTests
• Select 1   Build the test suite

This will take a while to complete. After the build completes, note the location of the build results journal file. Review the journal file and make sure the build was successful.

Note: You must have the UODK installed. See above.

• Log in as root on vt01, vt02 or another screen which has the color depth configured you wish to test
• cd  /usr/src/ihvkit/display/test/xsuite
• RunTests
• Select 2   Run the test suite
• This will take a while to complete.

• Select 3   Generate report from the most recent run
• Review the test reports. Correct any failures in your driver and then rerun the UTS.

 G. Performance Test

For performance testing, run  x11perf and  xbench.  x11perf is useful for testing the relative speed of your XDriver on a specific Video Adapter and Computer combination. You can verify incremental performance improvements when an acceleration routine is added or tuned. Both x11perf and xbench are useful for flooding the video adapter with drawing requests.

1. cd  /usr/src/ihvkit/display/Xserver/tests/x11perf  (on OpenServer 5,  cd  /xtests/xperf/x11perf.SCO)
2. RunTests
3. Results are saved in summary. Detailed information is stored in the results/ directory.
• To rebuild summary:
rm  summary*
make  -k  summary

1. cd  /usr/src/ihvkit/display/Xserver/tests/xbench
(on OpenServer 5, cd  /xtests/xperf/xbench)
2. RunTests
3. Results are saved in summary. Detailed information is stored in the results/ directory.
• To rebuild summary:
rm  summary*
make  -k  summary

I.  Completion of all tests

When your driver is complete and ready to handoff to SCO, include your test results and the archived files listed below. Note PASS or FAIL next to each test category. All FAIL test results should include a description explaining the exception or failure that occurred.

1. PASS/FAIL  graftest - all resolution/modes listed in the grafinfo file executed properly
2. PASS/FAIL  Color3, Text2, Window Manager all executed properly at all color depths listed in the grafinfo file
3. PASS/FAIL  Screen Switching executed properly
4. UTS Archived test results summary file /usr/src/ihvkit/display/test/xsuite/results
5. x11perf Archived test results summary file /usr/src/ihvkit/display/Xserver/tests/x11perf
6. xbench Archived test results summary file /usr/src/ihvkit/display/Xserver/tests/xbench

OpenServer Release 5 Graphics Drivers Development

See the Developer's Toolkit Documentation to develop graphics drivers on OpenServer Release 5. Additional development information is provided below.

 

To implement autodetection of your graphics adapter, create the following files listed below. ddd is the manufacturers directory name and xxx is the model name of the video adapter.

 

• /usr/lib/vidconf/AOF/UNIQUE/ddd/xxx is not used in OpenServer Release 5

 

• /usr/lib/vidconf/scripts/xxx

The Video Setup script is executed by the Video Configuration Manager to create a grafinfo file that includes I/O and Memory addresses for the Video Adapter. The script runs sed on a grafinfo template .tmpl file and updates the grafinfo .xgi file with new information. The exit status is 0 for success and 1 for failure. Copy a script file as a starting template and modify it.

 

• /usr/lib/vidconf/AOF/ID/ddd/xxx

The AOF/ID file is used in OpenServer Release 5 for autodetection of graphics adapters. Copy an existing AOF/ID file as a starting template and modify it. You will probably only have to update the fields listed below.

• Update DESCRIPTION= with your video adapter name.
• Update ID= with a comma separated list of video adapter PCI ID's.
• For each PCI ID listed in ID=, assign the PCI ID= to a video adapter name. You can obtain your video adapter's PCI ID string by running /opt/K/SCO/Vidconf/*/usr/lib/vidconf/AOF/bin/pcislot

 

• /usr/lib/grafinfo/ddd/xxx.xgi and /usr/lib/grafinfo/ddd/xxx.tmpl

The grafinfo .xgi and template .tmpl files contain configuration information for your video adapter. The grafinfo .xgi file is read by the Video Configuration Manager during resolution/mode selection. If:

VIDSETUP = "/usr/lib/vidconf/scripts/xxx";

is specificed in the DATA section of the grafinfo file, the Video Configuration Manager executes this Video Setup script (see above) to update your .xgi file to contain I/O and MEMORY addresses for your Video Adapter. VIDSETUP is included in the initial .xgi file and in the template .tmpl file so that successive configurations work properly.

OpenServer Release 5 Graphics Drivers Test Plan

Follow this test plan to verify functionality of your graphics driver. This test plan may reference sections of the UnixWare 7 test plan where similar.

A.  Installation of your test machine

Follow the installation instructions provided with OpenServer Release 5.

Follow the installation instructions provided with OpenServer Release 5. The Development System is available on the same cdrom and can be installed by running custom. It is needed by the Performance Testing which requires make to build the test results.

Instructions for running this command are similar for both Unixware 7 and OpenServer 5.

Use the MakeProduct script on your build machine to build your Video Driver media image file VOL.000.000. You can then install the media image file on the test machine using custom. Make sure your driver version/release number is later then the current shipping version of the driver on the Web or in SCO product (assuming your driver has been released previously). If it is not a later version, custom will not automatically upgrade your new driver.

 B.  Video Configuration

Instructions for running this test are similar for both Unixware 7 and OpenServer 5.

C.  Grafinfo file testing

Instructions for running this test are similar for both Unixware 7 and OpenServer 5.

D.  Color, Font, Window Manager and Screen Switch testing

Instructions for running this test are similar for both Unixware 7 and OpenServer 5.

E.  Desktop Verification

Instructions for running this test are similar for both Unixware 7 and OpenServer 5.

F.  Unisoft Test Suite (UTS)

The UTS is an automated test suite. It will find rendering errors in your XDriver and is useful for regression testing after making any changes to your XDriver. Please run the UTS at each color depth supported by your video adapter. You may have to configure additional resolution/modes/color depths on more screens using the Video Configuration Manager scoadmin video.

The UTS is provided in compiled form. You do not need to build it.

There are 19 FAILures that are in the core server and cannot be corrected.

• /unisoft/xtest/doc
• /unisoft/tet/doc/posix_c
• /unisoft/README.sco.uts

It is recommended that all XDriver writers read the Users Guide. This guide provides a more thorough understanding of the UTS. Print the file .../xtest/doc/userguide.{mm,ps}.

README.sco.uts contains specific details on how to install, configuration and initiate a UTS cycle on OpenServer 5. It is used in Configuring the UTS below

1. Complete the instructions under:
6) Set up a UTS 'configuration' and a 'scenario' file for the system to be tested.

 

2. Complete the instructions under:
RUNNING THE UTS:

 

3. Additional notes:
• The XT_FONTPATH variable is correct and should not require modification.
• Switch back to the screen running the XServer. If the test suite is running correctly, the XServer should repeatedly reset.
• To abort tcc press  ctrl  \

1. Complete the instructions under:
TEST COMPLETION

G.  Performance Test

Instructions for running this test are similar for both Unixware 7 and OpenServer 5.

Network Drivers - Development and Test Instructions

UnixWare 7 MDI Driver Development

• Source Code Hierarchy

  For the UnixWare 7 NIC driver named "xxx", SCO expects the following as part of a handoff:

  ./xxx    <-  this is a directory
  ./xxx/file1.c  \
  ./xxx/file2.c   - Your source files, named whatever you want.
  ./xxx/file3.c  /
  ./xxx/xxx.mk   <- the makefile, puts Driver.o into xxx.cf
                              See the "Makefile guidelines" section for 
  more info
  ./xxx/xxx.cf   <- this is a directory
  ./xxx/xxx.cf/Driver.o    (mandatory)
  ./xxx/xxx.cf/Master      (mandatory)
                                 You must specify conforming interfaces 
  in
                                 the driver's Master file; do not use
                                 $interface base or $interface 
  nonconforming
  ./xxx/xxx.cf/System      (mandatory)
  ./xxx/xxx.cf/Drvmap      (mandatory)
  ./xxx/xxx.cf/Node        (mandatory)
  ./xxx/xxx.cf/xxx-bus1.bcfg (mandatory: 1 for each bus supported)
  ./xxx/xxx.cf/xxx-bus2.bcfg (mandatory: 1 for each bus supported)
  ./xxx/xxx.cf/xxx-bus3.bcfg (mandatory: 1 for each bus supported)
                                 you can have as many bcfg files as is 
  necessary
  ./xxx/xxx.cf/Space.c     (optional)
  ./xxx/xxx.cf/msg.o       (optional)
  
  If you have multiple drivers to hand off to SCO, use the above 
  template for
  each drivers directories.
  
  The following files are mandatory
  ---------------------------------
  Driver.o       - The driver that gets built from source by the "all" 
  make 
                   target.
  Drvmap         - per Drvmap(4).  New MDI drivers must:
                    - have 'Y' in autoconfiguration field
                    - have a verify routine for configuring ISA boards.
                      EISA/MCA/PCI boards do not need a verify routine.
                      If this is an ISA board then use 'Y' in the 
  verify field.
                      Having a 'V' means that the DCU will 
  always silently 
                      call your xxx_verify routine when starting when 
  it finds 
                      your boardid is recognized.  The intent is that 
  your
                      verify routine will immediately have sufficient
                      information to determine if the hardware is set 
  up correct
                      or not.  If your verify fails then the DCU 
  will
                      silently skip this card and it will not be 
  presented
                      to the user later on for the user to try other 
                      configuration parameters.
  
                      Using a 'Y' in this field allows the user to 
  press F4=Verify
                      repeatedly in the DCU to determine if the 
  hardware 
                      is at the specified address.  If you had a 'V' 
  the user 
                      would never get this far.
  
                      Leave the bcfg pathname field blank.  For 
  Example:
  
                   #ident  "@(#)Drvmap     2.1"
                   foo|Y|N|Network Interface Cards|
                   |EISA||Zoom Zoom driver 959|
                   |EISA|UNB0048|Unisys 596 EISA Card|
                   |EISA|COG9004|Cogent EM932 EISA Card|
  
                   See the "DCU Considerations" section for more on 
  this field.
  
  Master         - per Master(4).  Must have 'L' Loadable module flag. 
                   Must only have 1 driver line.  Note that ddi8 
  drivers use
                   a Master file syntax that is different from pre-ddi8
                   drivers.  Refer to the sample drivers that are 
  included
                   in the "ndsample" package for examples.
  Node           - per Node(4).   MDI drivers live in /dev/mdi and 
  start with
                   minor 0.  They are not cloning drivers.  Note that 
  ddi8
                   drivers use a Node file syntax that is different 
  from pre-ddi8
                   drivers.  MDI drivers should always use "c" in field 
  3 of
                   their Node file and they should always use "0" in 
  fields
                   5 and 6 as in the following example for a ddi8 
  driver:

#ident "%W%" $maxchan 0 foo mdi/foo%i c 0 0 0 600 System - per System(4). Must not contain '$static'. Must only have 1 driver line. You must have one bcfg file for each BUS= type supported by the driver. We'll assume that our driver will transparently work for 4 bus types. The name isn't important as long as it ends in .bcfg; idinstall will copy them all to /etc/conf/bcfg.d. Pxxx.bcfg - bcfg file for PCI Exxx.bcfg - bcfg file for EISA Ixxx.bcfg - bcfg file for ISA Mxxx.bcfg - bcfg file for MCA Cxxx.bcfg - bcfg file for PCCARD If you aren't going to distribute your driver on an IHV DOS diskette then you can use longer names. Suggested names are xxx-pci.bcfg - PCI xxx-eisa.bcfg - EISA xxx-isa.bcfg - ISA xxx-mca.bcfg - MCA xxx-pccard.bcfg - PCCARD Remember that each bcfg file can support multiple topologies. That is, while BUS= in your bcfg file is single valued, TOPOLOGY= can be multi valued. The following files are optional -------------------------------- $LOCALE/msg.o - msg files for driver for a specific locale Contains localized copies of message files. Autotune - per AutoTune(4). Useful for preallocation of buffers (see esballoc(D3)) based on increased memory usage Drivers should not use esballoc because the stacks can (and will) legitimately hold on to the buffer for a long time, causing buffer starvation in your MDI driver. Mtune - per Mtune(4). Rc - per Rc(4) hardware specific startup script goes into /etc/conf/rc.d see also PRE_SCRIPT and POST_SCRIPT in bcfg(4dsp) could perform download code functionality here. You'll need a PRE_SCRIPT or POST_SCRIPT to copy any other files into the appropriate place for the rc script to use. Sd - per Sd(4) hardware specific function goes into /etc/conf/sd.d see also PRE_SCRIPT and POST_SCRIPT Space.c - per Space.c(4). Generally not necessary for MDI drivers: XXX_CNTLS is not defined for autoconfig drivers. XXX_UNITS is not defined for autoconfig drivers. XXX_attach_info not defined for autoconfig drivers. the following defines no longer exist for all minor devices and driver types (all are preceded by the driver prefix and '_'): CHAN, TYPE, VECT, SIOA, EIOA, SCMA, ECMA, IPL, intrinfo Use cm_getval routine to obtain these values instead. You may use CUSTOM parameters in the bcfg file(s) to specify xmit/recv buffer sizes. STREAMS module_info/qinit/streamtab structures should not be defined in a Space.c anymore. The min/max packet size can be a CUSTOM parameter in the bcfg or it may be declared as a variable in a Space.c file. Remember that CUSTOM IDTUNE parameters that are specified in the bcfg files are saved in the resmgr and not in the Space.c. The following files should not be necessary for a NIC DSP package ----------------------------------------------------------------- Init - per Init(4) Modstub.o - MDI drivers may not require this file since they must be DLMs. Sassign - per Sassign(4) Ftab - per Ftab(4). For statically linked drivers only Stubs.c - per Stubs.c(4) Dtune - per Dtune(4). GUI only. space.h - not permitted Space.h - not permitted *.h - not permitted
• bcfg files

  Please refer to the bcfg(4dsp) man page. Also feel free to look at and follow conventions in the bcfg files found in /etc/inst/nd/mdi/driver/*.bcfg

• Makefiles
  • Naming convention
    Makefiles must be named the same name as the driver with a ".mk" suffix. For example, if your driver name is "xxx", the directory with the source must be named "xxx" and the makefile must be named "xxx/xxx.mk".

  • Targets
    The makefile must contain the following targets:
    • all: builds xxx.cf/Driver.o if the $(SCP_SRC) file is present
    • install: dependent on the all target, uses $(IDINSTALL) -a -k to install the DSP into $(ROOT)/$(MACH)
    • clean: removes all objects that are built by the all target, but does not remove xxx.cf/Driver.o
    • clobber: dependent on the clean target; uses $(IDINSTALL) -d -k to remove the DSP from $(ROOT)/$(MACH); removes xxx.cf/Driver.o if the $(SCP_SRC) file is present
    • lintit: runs lint on source files if the $(SCP_SRC) file is present

    Verify that running "make -f xxx.mk target" with each of the targets listed above functions correctly.

  • UTSRULES
    The makefile must include $(UTSRULES) at the top, before the all inference rule:

    include $(UTSRULES)
    

  • Macros
    The makefile must define the following macros, where xxx is replaced with the driver name and xxx_mdi.c is replaced with the name of one of your source files:

    KBASE = ../../../..
    MAKEFILE = xxx.mk
    SCP_SRC = xxx_mdi.c
    

    References to header files required for compilation must be done relative to the $(KBASE) macro when the source is built with _KERNEL_HEADERS defined. Refer to the MDI driver source code that is included in the ndsample package for examples.

    The makefile may define desired macros in the "LOCALDEF" macro, for example:

    LOCALDEF = -DUNIXWARE
    

    The makefile may add local include directories to the include path with the "LOCALINC" macro, for example:

    LOCALINC = -I./inc -I.
    

  • Rules
    For lint objects, the following rule is advised:

    .c.L:
       [ -f $(SCP_SRC) ] && $(LINT) $(LINTFLAGS) $(DEFLIST) $(INCLIST) $< 
    >$@
    

  • Source Code Product Requirements
    SCO ships a Source Code Product (SCP) that does not contain vendor source code. However, the SCP is required to cut the same product that SCO ships. To meet this requirement, vendor makefiles must be SCP aware. Essentially, they must check for the existence of one of their source files before building the all, clobber, or lintit targets.

    If the $(SCP_SRC) file is not present, all can be skipped, clobber cannot remove the Driver.o, and lintit cannot be run (since there's no source). To test compliance with the SCP requirements, build your driver with the "install" target, then move the $(SCP_SRC) file to $(SCP_SRC)_orig. Verify the following:

    • Running "make -f xxx.mk clean" removes all of the object files, but does not remove xxx.cf/Driver.o
    • Running "make -f xxx.mk clobber" does not remove xxx.cf/Driver.o
    • Running "make -f xxx.mk all" does not do anything and does generate errors
    • Running "make -f xxx.mk lintit" does not do anything and does generate errors

    Now move $(SCP_SRC)_orig back to $(SCP_SRC) and verify that running "make -f xxx.mk clobber" removes xxx.cf/Driver.o

    Below is an example Makefile that conforms to the SCP requirements:

    #ident "%W%"
    #
    #	Copyright (C) 2001 SCO International, Inc
    #	This Module contains Proprietary Information of
    #	SCO International, Inc, and should be treated as 
    Confidential.
    
    include $(UTSRULES)
    
    MAKEFILE = wdn.mk
    KBASE = ../../../..
    LOCALDEF = -DSCO -UM_XENIX -DUNIXWARE -D_KERNEL
    SCP_SRC = wd.c
    OBJ = wd.o
    LOBJS = wd.L
    DRV = wdn.cf/Driver.o
    
    .c.L:
    	[ -f $(SCP_SRC) ] && $(LINT) $(LINTFLAGS) $(DEFLIST) 
    $(INCLIST) $< >$@
    
    all:
    	if [ -f $(SCP_SRC) ]; then \
    		$(MAKE) -f $(MAKEFILE) $(DRV) $(MAKEARGS); \
    	fi
    
    $(DRV): $(OBJ)
    	$(LD) -r -o $@ $(OBJ)
    
    install: all
    	(cd wdn.cf; $(IDINSTALL) -R$(CONF) -M wdn)
    
    lintit:	$(LOBJS)
    
    clean: 
    	rm -f $(OBJ) $(LOBJS) tags
    
    clobber: clean
    	if [ -f $(SCP_SRC) ]; then \
    		rm -f $(DRV); \
    	fi
    	(cd wdn.cf; $(IDINSTALL) -R$(CONF) -d -e wdn)
    

• Compilation Flags

  The default kernel build rules in the SCO build environment generates objects for MPDEBUG KERNELS, but the ndsample package uts.rulefile is setup to build UPNODEBUG objects. Please verify your source builds when you build MPDEBUG objects by invoking make with arguments similar to the following:
  make -f xxx.mk DDEBUG="-DDEBUG -D_KMEM_STATS -D_KMEM_HIST -D_MEM_RESV_STATS -DDKTEST -D_MPSTATS" STATIC=

• Clean Build

  Source must build with no warnings or compilation errors.

• Language

  Drivers must be written in C Programming Language with as little supporting assembler code as possible.

• Build Environment

  The preferred way to build your driver is to install the ndsample package from the HDK onto your build system, which should be installed with the desired release of UnixWare 7 and the Universal Development Kit (UDK). Be sure to install the usoftint or "Software Packaging Tools" package). Note that the usoftint package is not selected by default when you install the UDK.

  Once the ndsample package is installed on your build machine, you can put your driver source code under directories you create in /usr/src/hdk/net/mdi. This subdirectory, along with the installed Operating System and Development Kit, is referred to as the "build tree" elsewhere in this document. Please refer to the README file included with the ndsample package in /usr/src/hdk/net/README for information on how to set necessary environment variables such as $UTSRULES, etc. when adding drivers to your build machine.

• _ndversion

  netcfg can display a version string when configuring your NIC. This comes from the _ndversion symbol in your source code. The format for this must be as follows:
  static char _ndversion[]="1.2.3";
  You can see examples of this in the HDK ndsample package which contains example source code. The _ndversion symbol must be static or else ndcfg(1M) will not allow users to configure your driver.

  Please remember to update this string each time anything in your driver changes, whether or not you hand off the driver to SCO.  The actual contents of _ndversion (here :1.2.3:) doesn't matter and can be any printable string, although it should be reasonably short.  You should update this string even if the file containing the _ndversion string is different than the file you've modified.  SCCS keywords may be helpful for this.

  The contents of this string are also displayed to the user when they install a new NICs package.

  You should also use the _ndversion string when calling mdi_printcfg(D3mdi).

  The _ndversion symbol is a powerful way to identify the release of the driver to the user before loading it or turning the Driver.o into a DLM.  And, because the version is embedded in the Driver.o symbol table it won't be removed by strip(1) or mcs(1).

• DEBUG macro

  We suggest you use a separate debug macro, such as xxx_DEBUG to enable building a debug driver independent of the DEBUG macro. If your driver gets built with DEBUG defined (-DDEBUG), you should define xxx_DEBUG to build a debug version of your driver.

UnixWare 7 MDI Drivers Testing

Required Tests

1. auto_mdi
2. auto_dlpmdi
3. auto_drvr
4. auto_util
5. auto_ncard - run with the same number of adapters as specified in the MAX_BD parameter in the bcfg file(s)
6. spm - default number of frames, submit status output for both send and receive
7. auto_tcp
8. auto_nfs
9. auto_spx
10. DDI8 hotplug drivers - your own file containing documented test results.

Automated Testing

• Create a /etc/inst/nd/mdi/<xxx> directory on the master target machine and place your DSP into this directory.  The DSP is everything under your <xxx>.cf from your built source tree.  The DSP must include:
• Driver.o
• Drvmap
• System
• Node
• Master
• One or more <xxx_prefix>*.bcfg files
 
• Test Suites - Important Notes
• Test machines must be in "init state 1" (as root type init 1) to run the first set of unit tests (nd-mdi, nd-dlpmdi, nd-ncard, and spm). These tests are executed by running the test simultaneously, after configuration, on both the test and remote test machines),
• Test machines must be in "init state 3" (the default state), and the test is started on only the test machine for the rest of the tests (nd-util, nd-spx, nd-tcp, and nd-nfs). The test machine will connect to the remote machine using rsh to start up anything necessary on the remote machine. Therefore, user equivalence for the "ndcert" user must be setup prior to executing these tests.
• Running tests in the incorrect state or failure to correctly start tests simultaneously on both the test and remote machines when required will produce unpredictable machine behaviors and may corrupt your test result files.
• When the ndtests package from the HDK is installed, it looks for any configured NIC's and autopushes a new STREAMS module named "spam" (Streams Performance Analyzer for MDI) above each previously configured NIC. This is accomplished by adding lines to /etc/ap/spam/ap. SPM can accurately measure performance of your driver under heavy load on both the sending and receiving sides. For more information about SPM, please see the README in user ndcert's home directory (usually /home/ndcert). Note that passing the SPM test is a requirement for all MDI drivers submitted to SCO for inclusion in SCO products.

Manual Testing - Pull Cable

Configure your card under TCP/IP, go into init state 3 and run "ping -s remote_machine". While the ping is happening, pull the cable out of the card. Make sure the system still functions correctly (that is, no panics, no keyboard lockups, etc.), but the ping response stops. Reinsert the cable and assure traffic is resumed.

UnixWare 7 MDI Drivers - Failover and Hotplug Support

PCI HotPlug Capable Machines for UW7.1.1 and OU8.0.0

If there is no line or switch emulator for a switch type, test it anyway. At least determine the line is getting as far as you would expect given the incompatibility.

SCO has 5ESS and NI-1 lines and can emulate an additional switch type.

Configure a second BRI line and then create enough load to make it active. If you have single link working, you can use ppptalk to configure the second line:

  ppptalk <ENTER>
        list bundle <bundle_name> | more   - you see your 
parameter settings
        bundle <bundle_name> {
           thrashtime = 30           - 30 secs of thrashing, open 2nd 
link
           bodpay = caller           - caller initiates 2nd link (not 
peer)
        }
        save                         - save your changes
        reset bundle <bundle_name>   - update the active bundle
        quit

  ppp status link                    - to verify 2B channels are 
running
                                       once you've loaded the 
connection

Configure two machines each with one PRI adapter. Then configure 23 bundles using 1 B channel per bundle. Next, run telnet to each IP address to verify each channel.

Performance Testing

Use dool to transfer 50k files over the link(s). If you do not have dool, run ftp file transfers of /stand/unix over the link(s).

Transfer rates for BRI and PRI (UnixWare to UnixWare):
• 1 link: 7.5k bytes/second
• 2 links: 15k bytes/second

Load Testing

  	EG: from machine_a, 
	telnet machine_b, log in and run
		while :
		do 
	   		cat /etc/termcap
	   		sleep 1
		done

Do the same from machine_b to machine_a.

Deliverables

SCO delivers to the Technology Partner

1. Development Environment Software
2. Test Environment Software
3. Developer's Toolkit Software
4. On an on-going basis, a complete list of open bug reports against the driver(s)
5. On an on-going basis, technical driver development memorandums
6. Source drops whenever modifications are made to the driver source by SCO

Technology Partner delivers to SCO

1. Email notification to your SCO liaison upon delivery of the driver hand off which includes a completed Hand off Checklist
2. Everything specified in the Deliverables Section of the Hand off Checklist

SCO Driver Hand Off Processing

1. Assure that the hand off is complete as specified in the Technology Partner delivers to SCO section above
2. Review Test Results Report and verify that there are no unexplained FAIL or ABORT messages - any problems such as testsuite failures must be satisfactorily explained in the REAMDE.tests file
3. Verify that source hand off is complete as specified in the Deliverables Section of the Hand off Checklist
4. Do a code review on the source received (optional)
5. Build the driver from the source received
6. Test the driver - this may include re-running portions of the Test Suite
7. Check driver into SCO source tree
8. Notify the Source Code Product Administrator that this source should not be included in SCO's Source Code Product (for new drivers)
9. Provide top-of-tree source to the Technology Partner
10. Provide installable image of the driver to the SCO BBS Administrator for BBS placement

Update the CHWP (Compatibility Hardware Web Page) as necessary

Check List Template

File Verification Template

Driver README Template

Driver Prefix Designation:         &nb sp;                       &nb sp;       ________________________ _

Technology Partner's Driver Version Number: _________________________

SCO Operating System and Version:          & nbsp;         __________ _______________

Supported Card Models or Chipsets: _________________________________

           &nb sp;                       &nb sp;                       &nb sp;              _________________________________

           &nb sp;                       &nb sp;                       &nb sp;              ___[list all supported cards/chipsets]___

Limitations:
[e.g., for Graphics drivers - list any standard Intel hardware modes not supported by the driver]
[e.g., for Network drivers - list any modifications made to CUSTOM parameters or Space.c files when testing the driver]

Configuration Parameters:
[List configuration parameters for each card supported by the driver, e.g., network driver hardware options]

Additional Information:
[List any additional and important information about the driver.  For example, this card requires DOS configuration software to be run and here is how the card should be configured under DOS]

Change Description Template

• [brief description of change]



• SCO Bug Identification Number: ______________________________________________



• Source files changed: __________[list all source files modified for this change]__________


            ;    ____________________________________________ ____________
            ;    ____________________________________________ ____________



• Verification testing:    ______[provide brief description of how this change was tested]____
 ________________________________________________________
 ________________________________________________________
Change 2
• [brief description of change]



• SCO Bug Identification Number: ______________________________________________



• Source files changed: __________[list all source files modified for this change]__________
            ;    ____________________________________________ ____________
            ;    ____________________________________________ ____________



• Verification testing:    ______[provide brief description of how this change was tested]____
 ________________________________________________________
 ________________________________________________________
[etc, assure all changes are described on this template]

Supplements

You must install all required supplements for your release.

• Supplements can be obtained from ftp.sco.com/pub in openserver5, openunix8 or unixware7 depending on what release you are using.
• Supplements are periodically updated or superseded.

Glossary

BRI

Basic Rate Interface (BRI) ISDN service, consisting of two 64K B-channels and one 16K D-channel.

Build Machine

A machine installed with specified SCO development environment software and used to compile and package your driver deliverable.

Build Tree

SCO provided source code hierarchy within which the Technology Partner builds the driver deliverable. Typically, this is the ndsample package for UnixWare 7, or the O5ndsample package for OpenServer Release 5.

DCU

Device Configuration Utility - see dcu(1M)

DDI7

Device Driver Interface Version 7

DDI8

Device Driver Interface Version 8

DSP

Driver Software Package

Hand off

A hand off is a set of deliverables that includes new/updated drivers from SCO's Technology Partners which meets the acceptance criteria defined in this document.

MAC

Media Access Control

MDI

MAC Driver Interface - the interfaced used by network drivers

Media Kits

A set of CD's which comprise a complete set of software for SCO product.

NIC

Network Interface Controller

NFB

No Frame Buffer - the interfaced used by accelerated graphics drivers

PPP

The Point-to-Point Protocol (PPP) is a method for transmitting datagrams over point-to-point serial links.

PRI

Primary Rate Interface (PRI) service, consisting of 23 64K B-channels and one 16K D-channel.

ISDN

Integrated Services Digital Network (ISDN).

Technology Partner

Technology Partner is a hardware company who has formed a partnership with SCO whereby their drivers are incorporated and distributed in SCO product, specifically this entails agreement to the terms and conditions set forth in the Driver Software License Agreement.

Test Machine

A machine installed with specified SCO test environment software and used to execute the test plan.

---

Authors: Rob Mills/David Wood/Kathryn Anderson/Barry Feild/Mardiros Chakalian
Start Date: 1/18/99
File Name: driverreq.html  Type: HTML