                              ARC APPLICATION DEVELOPMENT KIT.


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

This file contains information about the ARC application development kit.  This kit offers 
ARC routines as well as ANSI-C libraries to facilitate the development of NT firmware 
applications that will run under AlphaBIOS or NT ARC firmware on Alpha AXP systems.  Some 
examples of ARC applications built under the ADK are 'arcdos' and 'pciscan', which you can 
find in the sub-directory ..\adk\adkapps.

We will include a copy of Revision 1.2 of the ARC spec under the name 'Riscspec.doc'.  You can
also download it or the latest revision from http://www.microsoft.com/hwdev/download/respec/riscspec.zip.
Some related documents are the fwvendor.txt and fwarc.txt, which specify our current implementation
and can be found in this kit as well.  

Digital Equipment Corporation is not liable or responsible for any damages resulting from 
the use of this file.

We believe that this document provides enough information for an external vendor to correctly 
build an ARC app for Alpha AXP systems.  We are committed to assisting such work, so please
tell us where this document is inadequate.


                               ----------------
                                MAIN LIBRARIES
                               ----------------

      1. Arc 
      2. Ctype 
      3. Math 
      4. Stdio
      5. Stdlib
      6. String
      7. Time

      All of these libraries are combined into adk.lib. 



			   -------------------------
                            ARC APPLICATION DESIGN 
                           -------------------------
               
   1. Some points about memory management:

      a) The execution environment of your application has no memory management protection.
         If your application wants to, it can corrupt or completely overwrite the firmware. 
         (Be careful!)

      b) Memory addressing works as follows:

	   Virtual addresses = Physical addresses + bit <31> set.

         For example, memory address 0 is represented as 0x80000000, and memory address 1MB
         is represented as 0x80100000.

      c) The format of I/O space addresses depends on what Alpha platform your application 
         is executing on.  Always use the firmware API functions given in fwvendor.txt to 
         calculate and access I/O space.  NEVER ACCESS IT DIRECTLY IN YOUR SOURCE CODE WITH
         A C OR ASSEMBLY LANGUAGE STATEMENT.


   2. Location of System Parameter Block:

      The ARC system parameter block is located at address 0x806fe000.


   3. Unicode support:

      As of V3.5 vintage firmware, Unicode support is not available.


   4. Output device:

      Whether to a serial line terminal or to the video tube, the output screen is an 
      80x25 screen.


   5. Serial lines:

      The NT Alpha firmware provides you with some assistance for reading the keyboard of
      VT320-series terminals on the serial line.  For such a terminal, the firmware will 
      translate most input key sequences into their ARC keyboard equivalent.  This means, 
      for example, that an application making use of the cursor control or page-up/down keys
      will not have to know whether it is running on the serial line or the main PC keyboard.                       

   6.  Arguments:

      The maximum number of arguments the firmware can take to run an ARC application is 16. 

   

                           --------------------------
                            ARC APPLICATION BUILDING 
                           --------------------------

   1. Environment: You must have MSVC++4.1 (or higher), SDK and DDK for NT4.0 installed on 
      your AXP system.  ARC applications should be built under Razzle windows, which are 
      available from the DDK (Free Build Environment and Checked Build Environment). Users
      should look at the sample arcapps and create all the files necessary for the build. 
      To work with WinDebug, arcapps should be built under Checked Build Environment. The
      debug directory contains all libraries and object files needed for debugging purpose. 

   2. Loading: The NT firmware on Alpha AXP does not yet support the loading of relocatable
      images.  Therefore, your image must be linked such that it is non-relocatable and does 
      not overlap any part of the firmware.

      Practically, this means that the application image must not overlap or try to use an 
      address within the range of:

    	0x806fe000 - 0x80900000

      Note that Alpha AXP machines will ship with a minimum of 16MB of memory.


   3. Entry point: should be 'start' instead of 'main' (users still write a 'main' routine). 
      An example of of a linker response file for an ARC application is:

     -machine:alpha
     -map:arcdos.map
     -fixed
     -rom
     -base:0x80900000
     -align:0x100
     -debug:none
     -debugtype:coff
     -entry:start
     obj\alpha\arcdos.obj
     ..\..\adk\lib\adk.lib
 
     For debugging purposes, a xxx.dbg file should be created. An example is the arcdos.dbg 
     in the directory ..\adk\adkapps\arcdos.

                      

                              --------------------
                               ANSI-C CONSTRAINTS
                              --------------------

     Due to the way the NT ARC firmware is implemented, there are currently restrictions
     on several routines normally found in C run-time libraries, specifically:

     1. Time library: 
     
        - gmtime() routine is not supported.
        - time() routine works with local time rather than UTC time.

     2. Stdio library:
    
        - Output routines: 
            + DOS conventions are followed, e.g., '\r\n' must be explicitly output to get
              a new line.

        - Input routines: 
            + Can't display input from keyboard to screen.
            + Can't get input from console.
            + Can't scan floating number either from file or console.
     
     3. Math library: Arcapps must include math.h when calling math library functions.   

     4. String library: Arcapps must include string.h when calling string library functions.
        
   
------------------------------------------------------------------------------------------

Please give us feedback on this document and any problem you encounter when using the adk.

pham@zso.dec.com


      
      
   
    



