                        README File for UniLOC

BACKGROUND:

UniLOC (formerly named "LOCATE") is a tool for MS-DOS, which converts an
.EXE file into a .HEX file to be downloaded to an (E)PROM-programmer or
to an emulator. UniLOC has been written as a development tool for the
miniMAX-40 single board computer and its emulator EMU-40, but it can also
be used for any other embedded system, with a NEC 16-bit V-Series or Intel
8088/188 compatible processor.

UniLOC does not (currently) intend to compete against other commercially
available locators. It supports only those features which I considered
necessary for my own developments. Please see the list at the end of this
text for those features, which I intend to implement in future revisions.
UniLOC accesses only the .EXE- and the .MAP-files. Therefore it works
independent of the software development environment, as long as the map
file structure is compatible to Borland C++ V3.1.

UniLOC requires a small modification to the runtime library's startup code.
Two routines have to be implemented, one to copy the initialized data from
a save area in ROM to RAM and another one to initialize data areas. The
startup code will have to be adapted anyway for a non-BIOS and non-DOS
embedded environment and so this is a minor modification.

Only the startup code for Borland C++ 3.1 is supplied with this version of
UniLOC. If you want to use UniLOC with any other software tool, then you
need to adapt the startup code of that compiler package. Please see C0.ASM
for a reference.


LICENSING:
                      ͻ
                       UniLOC is FREEWARE. 
                      ͼ

No licensing or payment is required to use UniLOC. You may copy and
distribute UniLOC as long as you don't charge for it. Make sure to
copy all files, including this one.

UniLOC 2.0 has been used for several years now by different developers
throughout Europe. While I'm confident that all major bugs have been
fixed, I need to exclude any legal claims:

1.) It is your sole responsibility to test your application thoroughly.
2.) UniLOC must not be used for applications which can cause severe
    damage or threaten human life in case of malfunction.


INSTALLATION:
Just copy the file UNILOC.EXE to any directory on your hard disk, which
is in the search path for executible files.

Installation of the runtime libraries involves the following steps:

1.) copy all files from BCSTRTUP.V31 to a directory on your hard disk.
2.) Modify the statement "set lib=d:\borlandc\lib" in the MAKELIB.BAT
    file to the actual path of your Borland-C libraries.
3.) Run the batchfile MAKELIB.BAT with one ore more parameters to
    specify the libraries to be built. Examples:
            makelib s   ;make the library for small memory model
            makelib c,l ;make the library for compact and large memory models
            makelib s,m,c,l,h ;make the libraries for all memory models
    Make sure that the Borland development tools (C-compiler, Assembler, TLIB)
    are setup properly before executing MAKELIB.BAT
4.) You may check the .ERR files for any errors. No error should be reported.
5.) It is strongly recommended to have a different library path for DOS
    developments and for embedded developments. Copy the .LIB and .OBJ files
    to the library path for your embedded developments. Create a directory
    if it does not yet exist.
6.) It is also recommended to have a different include file path for DOS
    developments and for embedded developments. Copy the .H, .INC and .MAC
    files to the include file path for your embedded developments. Create a
    directory if it does not yet exist.
7.) You may delete all files and remove the directory created in step 1.)
    above. I recommend, however, to keep it, because you may want to add new
    library functions either from the Borland C library (by adding them into
    the file MODULES.RSP) or by copying your own assembler or C source files
    into this directory. Having done so, you need to execute the steps 3.)
    to 6.) again.

NOTE: The runtime libraries are identical to those of version 2.2.
      Therefore, if you were using V2.2 before, then you need only replace
      the old executable UNILOC.EXE by the new one. You may also want to
      check the examples which have been slightly changed to show the
      new features.

HISTORY:

V1.0
Version 1.0 was distributed in 1993 to only a few developers. While it was
already reasonably bug-free, it's user interface was quite poor. Also the
warnings and error messages were unsatisfying.

V2.0
Version 2.0 was shipped in fall 1993 to all known users of the previous
release. Many former command line parameters were move into a control
file, whose name must be specified as the first command line parameter.
A warning level can be selected and an output file can be specified to
hold the absolute map. An import function was implemented to insert
another standard HEX-file. The warnings and error messages were improved
and the "Extended HEX"-format was properly supported. Multiple output
files were supported for the "Standard HEX"-format, each having a select-
able address range and offset.

V2.1
Version 2.1 was an intermediate release, distributed only to one developer.
There was a (non-fatal) bug in version 2.0 which has been fixed in V 2.1:
When using the INIT command to initialize a class with a predefined value,
then the start and end addresses for the respective block were stored per
segment instead of per class.
Also the "copy" and "init" structures in the startup file and the handling
by UniLOC has been modified. The number of entries of the "copy" and "init"
structures is now stored in the two words ahead of them instead of using a
NULL pointer at the end of each table as before.
        ͻ
         THEREFORE UniLOC versions above 2.0 are incompatible with the 
                       startup code from previous versions.            
        ͼ
If you are using your own startup code, then you need to replace the code
in the beginning, which performs the copy and the initialization.
The enclosed startup code for Borland C++ 3.1 has been modified to support
the new structures. Also the new startup code is closer to the original one
from Borland. The most obvious is the name, which is C0.ASM, the one that
Borland use. It should be assembled to object files C0x.OBJ, which the
compiler can automatically include when invoked with the "BC" command.
I have also adapted the floating point library, which was tough, because
there are no sources supplied and the documentation is insufficient. The
floating point library and some others have to be initialized during startup
and uninitialized at exit. They insert configuration data into the INITDATA
and EXITDATA segments. These segments were not used in the previous version
of the startup code that came with V2.0 BUT THEY ARE NOW REQUIRED. They hold
initialized data and so their contents must be preserved in ROM. Please see
the enclosed sample files "PRIME" and "FLOAT".

V2.2
Version 2.2 has been released in January 1996 to support the miniMAX-40
project described in ELRAD 02/1996. V2.2 has implemented again a number
of improved warnings and error messages:
- error generated if "magic word" was not found but SAVE or INIT commands
  were used.
- a warning is generated if segments overlap.
- the "alias" warning has been improved: an alias warning can only occur,
  when a relocation item to an ambiguous start address was found. It will
  not occur, however, when all segments with the same start address are
  relocated to the same absolute address.

UniLOC will now return 0 if no error occured and !=0 if an error occured.
The previous versions of UniLOC had a problem, when the relocation table
of the .EXE-file was empty. That bug has been fixed. The absolute output
file does now also show the absolute addresses of the public symbols, if
they appeared in the map file.

V2.3
Version 2.3 has been released in August 1996. From this version onward,
I will ship a DOS-version together with an OS/2-version. Both versions
have identical features, but those of you who develop their software
under OS/2 (as I do), may appreciate a native OS/2 version. Just for
those who are curious: I'm using the excellent GNU compiler ported by
E. Mattes. The name of the OS/2 executable is "UNILOC2.EXE".
New features in version 2.3:
- Support for Motorola S-records
  (use filetype MOTS or MOTS16 for 16-bit addresses, filetype MOTS24
  for 24-bit addresses and MOTS32 for 32-bit addresses.) Well, to be
  honest, I could not test the MOTS24 and MOTS32 output files exhaus-
  tively, because I do not have an emulator or programmer, that under-
  stands these formats. Please send me an email if you encounter any
  problems.
- Parameter "/M" can display and set the magic word. The magic word is
  currently 10 bytes long and it is used to find the addresses of the
  SAVE and COPY tables in the startup code. /M without parameters
  displays the magic word while /M=xxxxxxxxxxxxxxxxxxxx overwrites the
  default. Please note that you must adapt the magic word in the startup
  code accordingly.
- Parameter "/N=nn" defines the number of data bytes stored by one line
  of the output hex file. This is NOT the number of bytes in a line.
  The maximum value for N is 252. The file size and the transmission
  time of the file are reduced with increasing N, because the overhead
  of the header and trailer for each line is reduced. Note, however, that
  the receiver of your file will probably store a complete line before
  verifying the checksum and transferring the data into the destination
  memory. This may impose a constraint on the upper limit of N.
- New keywords RAM and ROM have been implemented. They define the memory
  map of your target system. The knowledge of this map enables UniLOC to
  generate a warning, if a segment is located to an address where there
  is an inappropriate memory type or no memory at all. The new column "W"
  (warning) has been added to the map list, which can display one of the
  following warnings:

        ' ' no conflict found
        '1' no memory at this address
        '2' saved data must be in ROM
        '3' restored data must be in RAM
        '4' initialized data must be in RAM
        '5' output data must be in ROM

  The "W" column does not appear in the map listing, if you do not use any
  of the RAM or ROM keywords. In that case, the memory map verification is
  effectively disabled.

V2.3a
Version 2.3a supercedes 2.3 from August 1996 onward. This version supports
the specification of an offset for all output file types, including
Extended Hex and MotS24/32. Previous versions supported the offset only
for 16-bit file types.


FUTURE PLANS:
The following items are still on the wish-list, but please don't push me!
I can modify UniLOC only during my spare-time and so I cannot promise to
implement them at all. Also I would like to invite your comments, complaints,
bug reports and modification proposals. Depending on your inputs, the
priorities of the following list may change:

- generate an "absolute .EXE" file, so that TDREMOTE can be used
- support odd/even output files (for byte-wide PROMs in 16-bit systems)
- display unused memory areas in the memory map
- locate classes by end address
- compress PROM-copy of initialized data

Also, if you have adapted the startup code of your development tools to be
used with UniLOC for embedded environments, I would appreciate if you sent
me a copy for redistribution.

DESCRIPTION OF THE FILE FORMATS:

                        Intel-Hex
        ͻ
          An Intel extended hex file holds records of        
          different types. The structure of each record      
          is similar, all lines start with a colon ":" and   
          they end with a checksum. The various record types 
          are described as follows.                          
        Ķ
         Record Type 0 : Data Record                       
                                
          :ssxxxxrrddddddd....dddcc                          
                                                             
          ss      number of data elements in the line        
          xxxx    address where data is to be loaded (offset)
          rr      record type ("00")                         
          dddd... is the data itself                         
          cc      checksum                                   
        Ķ
         Record Type 1 : End of File Record                
                         
          :ssxxxxrrcc                                        
                                                             
          ss      number of codes ("00")                     
          xxxx    address ("0000")                           
          rr      record type ("01")                         
          cc      checksum ("FF")                            
        Ķ
         Record Type 2 : Extended Address Record           
                    
          :ssxxxxrrddddcc                                    
                                                             
          ss      number of codes ("02")                     
          xxxx    address ("0000")                           
          rr      record type ("02")                         
          dddd    paragraph value                            
          cc      checksum                                   
        Ķ
         Record Type 3 : Start Address Record              
                       
          :ssxxxxrrppppoooocc                                
                                                             
          ss      number of codes ("04")                     
          xxxx    address ("0000")                           
          rr      record type ("03")                         
          pppp    paragraph value                            
          oooo    offset value                               
          cc      checksum                                   
        Ķ
          Calculation of the checksum:                       
                                                             
          The checksum is obtained by subtracting all data   
          bytes (before conversion to ASCII characters and   
          except the colon and the CR and LF) from the       
          initial value 0. Any borrow is ignored             
                                                             
        ͼ

                        Motorola S-Records
        ͻ
          An Motorola S-record file holds records of         
          different types. The structure of each record      
          is similar, all lines start with "S" and they end  
          with a checksum. The various record types are      
          described as follows.                              
        Ķ
         Record Type S0 : File Name                        
                                
          S0ssffff...ffcc                                    
                                                             
          ss      number of data elements including cc       
          ffff    file name in ASCII format                  
          cc      checksum                                   
        Ķ
         Record Type 1 : Data Record, 16-bit address       
               
          S1ssxxxxdddd...ddcc                                
                                                             
          ss      number of data elements including xxxx/cc  
          xxxx    16-bit address                             
          dd      data                                       
          cc      checksum                                   
        Ķ
         Record Type 2 : Data Record, 24-bit address       
               
          S2ssxxxxxxdddd...ddcc                              
                                                             
          ss      number of data elements including xxxx/cc  
          xxxx    24-bit address                             
          dd      data                                       
          cc      checksum                                   
        Ķ
         Record Type 3 : Data Record, 32-bit address       
               
          S3ssxxxxxxxxdddd...ddcc                            
                                                             
          ss      number of data elements including xxxx/cc  
          xxxx    32-bit address                             
          dd      data                                       
          cc      checksum                                   
        Ķ
         Record Type 7 : Start Address Record, 32-bit      
              
          S7ssxxxxxxxxcc                                     
                                                             
          ss      length of record ("05")                    
          xxxx    32-bit address                             
          cc      checksum                                   
        Ķ
         Record Type 8 : Start Address Record, 24-bit      
              
          S8ssxxxxxxcc                                       
                                                             
          ss      length of record ("04")                    
          xxxx    24-bit address                             
          cc      checksum                                   
        Ķ
         Record Type 9 : Start Address Record, 16-bit      
              
          S9ssxxxxcc                                         
                                                             
          ss      length of record ("03")                    
          xxxx    16-bit address                             
          cc      checksum                                   
        Ķ
          Calculation of the checksum:                       
                                                             
          The checksum is obtained by adding all data bytes  
          (before conversion to ASCII characters, except the 
          leading "S", the checksum itself and the CR/LF)    
          ignoring any borrow and generating the 1's comple- 
          ment.                                              
                                                             
        ͼ

Other products available from the author of UniLOC:

UniMOS: A Universal Multitasking Operating System for NEC 16-bit V-series
        or Intel 8088/80188 compatible processors. Features include:
        - system size is only limited by the available memory
        - real time and/or round robin scheduling
        - optional timeout for those system functions that wait for events
        - high speed and small size by programming in assembler
        - supports all memory models
        - can be used for embedded controllers and for DOS
        - source code is available
        A copy of the UniMOS library for the small memory model with a few
        demo programs running under DOS is most likely available from the
        same place where you obtained UniLOC. That copy may be legally used
        for evaluation of UniMOS and for private, non-commercial projects.
        If you intend to use UniMOS in a commercial product, then you need
        to buy a license for a small one-time fee. That license includes
        shipment of all UniMOS sources and a printed manual.

miniMAX-40 : A small credit card sized single board computer with the V40HL
        microprocessor and a Xilinx XC3020, 3030 or 3042 FPGA, 32 to 512 kB
        CMOS RAM, 128 kB to 512 kB Flash-EPROM, real time clock, battery
        backup and "Silicon Serial Number".

EMU-40: Development tool for miniMAX-40.

        Please see ELRAD 2/96 and 3/96 for a detailed description of
        miniMAX-40 and EMU-40. In ELRAD 5/96 you will find the description
        of a graphics terminal as a sample application with miniMAX-40.

Comments invited:

                Michael Krmer
                Edenkobener Weg 24
                40229 Dsseldorf/Germany
                email: 100577.117@compuserve.com
