
                   NS486SXF Demonstration Program - README                        
                   ---------------------------------------
 
                              April 22, 1997

                     NSDEMO Version 1.7 (April 22, 1997)
____________________________________________________________________________


INTRODUCTION
------------

This directory contains a complex demonstation program for the NS486SXF
evaluation board.  The program uses or performs simple tests on most of the
NS486SXF peripherals.  Version 1.7 and newer also support the NS486SXL
adaptor board on the NS486SXF EVB.  In this document, the term NS486 refers
to either the NS486SXF or SXL as applicable.

This directory contains two prebuilt demos.  One (NSDEMO.EXE) uses the
Phar Lap ETS Lite tools to build and run.  The other (NSDEMO.OMF) uses
SSI's Link&Locate 386 Evaluation tools to build and run.  The two demos
share a common code base.  The section "FILES" below describes which files
are specific to the toolset.

OBJECTIVE
---------

The purpose of NSDEMO is two fold.  First, this code shows how to properly
use many peripherals of the NS486 as applicable to the evaluation board.
Second, many modules in this program could be used as simple "peripheral
drivers" in any C code intended to run on the NS486.  Towards the
first objective, the code is documented and demonstrates proper use
of most peripherals.  Towards the second objective, this code is somewhat
modular - the modules can be used in new code, or the program could be
modified or added to in order to use additional functionality of the
NS486.

CONTACTING THE NS486 GROUP
--------------------------

Support for NSDEMO is available through email at "ns486@arador.nsc.com", the
regular NS486 technical support email address.  Please direct suggestions or
bug reports to this address as well.  Web based information, including
software updates, is available at the URL "http://www.national.com/ns486/".
The URL "http://www.national.com/ns486/ns486sxf.html" contains a link to
the latest software release.

DISCLAIMER
----------

The documentation included with this demonstration is preliminary and
brief.  We think this code will be useful.  However, you will
probably need to consult the source code to figure out exactly how this
program works.  

FILES
-----

As delivered on the disk, this directory contains a a few different types
of files.

   common files:

     *.c        - C source code
     *.h        - C header files
     readme.txt - this file
     clean.bat  - batch file to remove output files
     cpu.asm    - a few required assembly routines
     cpu.o      - pre-assembled (MASM 6.11, .OBJ format) cpu.asm

   Phar Lap ETS Lite files:

     mscemb.bat - batch file to build NSDEMO with Microsoft Visual C++
     bcemb.bat  - batch file to build NSDEMO with Borland C/C++
     nsdemo.lnk - file used by the mscemb.bat file for linking
     nsdemo.exe - pre-built (MSVC 4.0) NSDEMO program

   SSI Link&Locate 386 Evaluation files:

     makefile   - makefile (nmake) for building NSDEMO with Microsoft
                  Visual C++, Borland C++, or Watcom C++.
     nsdemo.inc - ESP3 include file to demo code
     nsdemo.omf - pre-built (MSVC 4.0) NSDEMO program

KNOWN ISSUES
------------

  When running an image with the SSI debugger built with the Borland C++ 
  4.5 compiler, if you load the image, do a "go main" command, and then do
  a "go ret" command, it seems to run fine, but the debugger does not
  seem to regain control.  However, if you set a breakpoint at the end
  of main() and do "go", the breakpoint will be hit.  So if you are using
  Borland C++ 4.5 (and maybe 4.0) with the SSI debugger, you may want to
  set a break point at the end of main() if you wish to regain control at
  the end of NSDEMO.

  Additional link time problems occured with SSI/Borland C++ 4.5.  After
  extensive testing, no error was found in the code, but a trivial change
  was made in the code so that it would link without complaint.  It is 
  possible that the Makefile does something incorrect for the Borland build, 
  or that the SSI Linker/Locator version used here has a bug in Borland 
  support.  If you have problems using this set of tools, please contact 
  "ns486@arador.nsc.com".

WHATS NEW IN VERSION 1.7
------------------------

  *  Initial support was added for the NS486SXL part.  This is a "lite"
     version of the NS486SXF.  This chip removes the DMA controller, LCD
     controller, PCMCIA controller, and ECP parallel port.  This part has
     a different device ID than the NS486SXF.  The code now will recognize
     this ID and behave accordingly.  The SXL part has several new
     registers as well as registers with slightly modified functionality.
     This version of NSDEMO will work fine on either part.  However, changes
     would be required to take advantage of any SXL improvements.

  *  Two new modules were added to NSDEMO.  I2C.C contains code that
     initializes and transfers data on the NS486 three-wire interface in
     Access.bus (I2C) mode.  The module LM75.C contains sample code that
     uses the I2C module to talk to a National LM75 temperature sensor over
     the Access.bus interface.  An LM75 demo board and a custom connector
     are required to execute this code.  An application note is available
     that details this hardware and software.

  *  The debug printf routine (dprintf) now prints messages to three places:
     (1) a buffer in DRAM, (2) the internal UART, and (3) stdout.  Printing
     to stdout is not supported by SSI.  Please consult the manuals for the
     individual tools to determine the support for stdout.

  *  The Real Time Clock code was improved in several ways.  Most importantly,
     the code in RTC.C will now support using the RTC in any supported mode
     of timekeeping (binary vs. BCD, 24 hour vs. 12 hour).  The RTCTEST.C code
     was updated to support the improvements.  This code is now a much better
     example of using the RTC in any mode.  When NSDEMO is ran, if the time
     and date are valid, they will not be overwritten, and the RTC will be left
     in it's current programmed mode.  This is useful if you use the evaluation
     board with other tools that use the Real Time Clock.  Furthermore, out 
     of range checks are performed on all the time and date registers.

  *  The LCD code comments in the LCDBM.C file were improved and corrected.
     Also note that an application note describing the LCD hardware and software
     used by NSDEMO is now available.

WHATS NEW IN VERSION 1.6
------------------------

  *  Added SSI support for Borland C++ 4.0 and 4.5.

  *  Fixed a few small bugs and reworked some code for clarity.

  *  Added functionality in the Real Time Clock module, mostly for
     using Alarms.

  *  Added -sym flag in Pharlap batch files to support debugging with
     symbols and source level debugging.

  *  Added function in UART module to read a character in polled mode.
     This is not currently used in NSDEMO, but has been tested and is a
     simple way to read characters from the NS486 UART.

WHATS NEW IN VERSION 1.5
------------------------

  *  The NOTES section in the RTC.C file was updated.  The comments had
     contained some incorrect information.  No code changes were made.
     A certain RTC initialization sequence should be used to ensure that
     the RTC functions properly.  The new comments draw attention to this
     sequence.  The August 1996 and newer versions of the NS486SXF
     data sheet have fixed innacuracies in the older datasheet, which
     are described in the NOTES section of RTC.C.

  *  Note: unlike previous version releases of NSDEMO, for this release
     the "%VERSION" header in the code files was only updated to 1.5 for 
     the files that were changed (MAIN.H and RTC.C).

WHATS NEW IN VERSION 1.4
------------------------

  *  Support was added for the RTTarget-32 environment from On Time
     Informatik.  The changes are enclosed in "#ifdef ONTIME" statements.
     The changes required were minimal.

  *  The "dprintf" macro now displays messages to both the internal UART
     (UART port) and the buffer named "Buffer" when using SSI or RTTarget-32.
     Pharlap still uses standard I/O, as it supports standard I/O redirection
     to the host.  Previously these messages were only copied to the
     buffer.  Using the UART port allows the user to see the messages
     through a NULL modem cable if they have an extra serial port on
     their PC (or some other terminal to hook to it).  It is generally
     easier to see the messages (especially as they happen) this way.

  *  The __cdecl declaration was added to the ISR Thunk routines to eliminate
     the need for a different declaration when using Watcom C/C++.

  *  The "cpu.asm" file was improved by using the segment name "_TEXT" and
     declaring functions as near or far.  This makes it work in a
     consistant manner independent of which compiler and linker is used.

WHATS NEW IN VERSION 1.3
------------------------

  *  Interrupts now vector to "thunk" routines, written in assembly, in
     the cpu.asm file.  These routines call the C ISRs.  Before this
     release, some registers were not preserved correctly in ISRs, which
     could cause problems, especially if the code was modified.  This new
     method should be stable, and is a more consistant (between compilers)
     way to handle interrupts.

  *  The bcemb.bat and mscemb.bat files were modified so that the command
     lines did not get truncated under DOS.

  *  A bug was fixed in the biu.c code.  A typo was fixed in main.h.  And
     small change was made in rtctest.c to make it work correctly with
     future NS486 revisions.

WHATS NEW IN VERSION 1.2
------------------------

  *  LCD code was added.  The module "lcdtest.c" initializes the
     LCD controller and displays (on the LCD) an image with a National
     logo.  The image is 320x240 pixels and uses 4 levels of grey
     (2 bits per pixel).  To see this image, you must connect external
     LCD hardware (and LCD display with proper voltages and enables)
     to the evaluation board feature connector.  The external hardware
     is fairly simple.  An application note will be available in the
     future describing this hardware and how to build your own.
     Even without an external LCD panel to see the image on, this code
     shows one way to properly initialize and use the LCD controller.

  *  The inline assembly from version 1.1 was moved to the file
     "cpu.asm".  See the "RE-BUILDING" section below for more info.
     The use of this file simplified interrupt code as well.

  *  A PCMCIA test was added to the code.  If a PCMCIA memory card
     is inserted when the test in run, a message will be displayed
     indicating the card was found.  Additionally, you will be
     prompted to remove the card.  A message will indicate if the card
     removal is properly detected.  This test may be difficult to use
     with the SSI tools, since the output messages are to a buffer.
     When using SSI, you could break the code right before the
     PCMCIA test.  Then when you do a "go" command, just wait about a second
     and remove the card.  Non-memory PCMCIA cards should work as well.
     However, if a PCMCIA memory (SRAM, Flash, etc.) card is inserted, the
     code will map a memory window and look for a specific signature
     (the signature is our creation and not of any significance).  If
     this signature is found, a message will be printed.  See the code
     for details.  This is just to show that a memory card can be
     accessed.

  *  Added a way to specify how many clock cycles DMA transfers are
     programmed to.  This parameter can change depending on the use of
     the DMA, so this  method is more flexible.

  *  A few bigs were fixed.

  *  Output messages were cleaned up a little, and a few added.

  *  The code was cleaned up slightly.

RE-BUILDING
-----------

You must have either the Phar Lap or SSI tools for the NS486SXF evaluation
board properly installed to re-build the demo.  The RTTarget-32 tools from
On Time Informatik can also be used, but you will need to use the batch
files and config files supplied with the RTTarget-32 evaluation tools.

The printed evaluation board documentation describes how to rebuild the
NSDEMO program and run the programs using the Phar Lap or SSI tools.
Please try the pre-built version before rebuilding to see how the
program works.

  Pharlap
  -------

  The batch file "bcemb.bat" should work with Borland C++ versions
  4.0, 4.2, 4.5, and 5.0.

  The batch file "mscemb.bat" should work with Microsoft Visual C++
  1.0, 2.x, and 4.0

  The Watcom C++ compiler could probably be used without significant
  problems.  The Pharlap ETS Lite for the NS486SXF does not include
  a "wclite.emb" link file and Watcom libraries, so Watcom was not
  used.  Using the full ETS product, Watcom C++ should work fine.

  SSI
  ---

  The "makefile" will work with the following compilers:

                MN0200 - Microsoft Visual C++ 2.0
                MN0400 - Microsoft Visual C++ 4.0
                BD0400 - Borland C++ 4.0
                BD0450 - Borladn C++ 4.5
                WD1000 - Watcom C++ 10.0
                WD1050 - Watcom C++ 10.5

  Since SSI ships a number of different compiler specific libraries, other
  compilers (e.g., Metaware High C) should work, although modifications 
  will be required to the "makefile", as well as possible small porting 
  issues in the code.

The file "cpu.asm" contains low level assembly code to do a few things
that were not supported in all of the compilers.  This file is pre
assembled into "cpu.o" (the .o extension is used to that the makefile
and "clean.bat" script will not erase the pre-assembled "cpu.asm").  If
you wish to re-assemble this code you can use either MASM, TASM, or WASM.
Borland C++ (32 bit) does not seem to support inline assembly without
purchasing TASM seperately, and Microsoft and Watcom deal with inline
assembly quite differently.  Therefore, the "cpu.asm" file is the most 
portable way to implement assembly code.

ORGANIZATION
------------

The file "main.c" and the C files with the word "test" in their file name
make up the "test" code.  These files are here to show how the other
files are used.  The "other" files, are the C files with names in the
format of a peripheral block (e.g., "pit.c" and "rtc.c").  These files
are generic "drivers" for the specific peripheral, providing common
functionality for each peripheral.  In most cases there are header files
associated with each C module.

FUNCTIONALITY
-------------

Please see the printed documentation for information on the functionality
provided by the peripheral modules.  Furthermore, please consult the
source code itself for specifics.  The source code is fairly well
documented and mostly straight-forward code.

TOOLSET and EXECUTION
---------------------

With the Phar Lap tools, NSDEMO can be run with the "RUNLITE" command
or debugged with the "BEDBUG" command.  With the SSI tools,
the NSDEMO code is run within the "ESP3" debugger.

Both tools use the DEBUG UART to communicate with the target.  (Alternately,
the Phar Lap tools can use the Parallel Port, see the ETSLITE documentation).
The internal NS486 UART is used to display a one line message to 
demonstrate it's use.  If you connect a terminal to the external
UART and set it to 9600bps, you will be able to see this message.

This code works with both the Phar Lap and SSI tool sets for the
NS486SXF evaluation board.  There are several differences in the
capabilities of these toolsets.  In the source code, differences are
isolated with #ifdef's (using the keywords PHARLAP and SSI).
Code specific to RTTarget-32 is isolated with #ifdef's with the keyword
ONTIME.

Output messages are printed to the internal UART on the NS486 (at 9600bps).
These messages are also saved in an internal buffer (named "Buffer") that
can be viewed from within a debugger.  The Pharlap and OnTime tools also
support printing to "stdout", so the output messages are also sent
to "stdout" if applicable.  On the Pharlap tools and version 2.0 and newer
of the OnTime tools, the messages sent to "stdout" will be displayed on
the host machine.

The SSI code uses the makefile to set up the interrupt vectors at build time.  
The PharLap and OnTime versions makes calls dynamically to set up interrupt 
vectors.

HARDWARE NOTES
--------------

Version 1.7 and newer of NSDEMO will not change the time programmed in
the Real Time Clock if it is marked valid (VRT bit in control register D)
and all values are within range.  If the time is invalid it will be
programmed to an arbitrary value.

The Phar Lap ETS Lite package includes a demo program called "GETSETTM"
that can be used to set the Real Time Clock time and date.

Otherwise, we have tried to make sure that after running NSDEMO the hardware
is still in a sane state.  However, you may wish to reset the board after
running the NSDEMO program in case our peripheral mucking has messed up
anything that third party applications use.

CONCLUSION
----------

We hope you find this code useful.  Please send us suggestions and questions
via email!

____________________________________________________________________________

