                                          
                                            
                       Documentation for MarcSoft 68000 Software Development Environment.
                                     Copyright 2002 MarcSoft Computers
                                           All Rights Reserved
                                                MARCH 2002  

                     *** FEATURES *** 
    1)  A Virtual Memory Address Space of 160KB ( HEX Viewer )
    2)  Space to Write/Assemble Up to 3000 Lines of Code ( ASM Viewer )
    3)  A Dis-Assembler That also will divert Dis-Assembled Code to the ASM Viewer
    4)  A Variety of Editing Tools
    5)  A 68000 Register Display that allows for user interaction
    6)  A Process to Set/Clear up to 3 breakpoints
    7)  A Display of 8 Virtual LED's & Switches
    8)  A Display of 4 Seven Segment Virtual LCD's
    9)  A Graphics Tablet to Do Simple color graphics
   10)  Ability to Save/Load ASM & HEX Files
   11)  Cin & Cout Functions
   12)  Support for ActiveWire USB MicroController

    1) Virtual Memory Address Space
   
        The VM Address Space ( HEX Viewer ) allows for 160KB of memory organized in row/column fashion.
        Columns contain the address of the row, 8 bytes displayed and ASCII representation of the corresponding
        byte. All Values are in Hexadecimal ( Base 16 ) between 00h - FFh. The HEX Viewer scrolls, and
        individual bytes may be edited by left clicking on the byte in the HEX Viewer and editing the value
        in the EDIT Window. Since the memory is organized into USER and SUPERVISOR areas, if the SDE is
        in USER mode, the first $400 bytes and the last 32KB are off limits. This prevents overwriting of system areas.
        When the SDE is in SUPERVISOR mode ( more on that later ), full access to the HEX Viewer is allowed.
        Pressing the enter key after editing a HEX Viewer byte will Automatically Update the row the byte is located
        in and advances the HEX Viewer focus square to the next cell. The HEX Viewer contains code and data for any
        program assembled or any HEX Binary file loaded.

    2) Assembly Area ( ASM Viewer )
 
        The ASM Viewer allows for 3000 lines of assembler source code and data. The First column is the line 
        number, the second is for Symbolic Labels, The Third is For 68K Assembler Commands/Directives
        the fourth is The Operands ( eg  D0,(A7) ) and the last column is for comments. Note : when the source 
        code is assembled, comments are omitted. When the source is Assembled, The starting Line # ( ASM Viewer )
        is asked for. If no line number is supplied, Assembly is started at line #1. The Assembler continues until the
        first END directive is reached. If no ORG is supplied in the source code, the Assembler assembles starting
        at HEX Viewer location 0. A List File is Then Generated, and Loaded into the .LST Display, so
        that any Assembly Errors can be corrected. Also, the .HEX ( object ) file generated by the assembler is loaded
        in memory according to the values supplied in the  .HEX  ( object ) file.

    3) Dis-Assembly Viewer
 
        Clicking on the Dis-Assemble button causes the SDE to prompt you for a starting address IN HEX FORMAT.
        if No address is supplied, the Dis-Assembler Begins at location $400. Then An ending HEX Address 
        ( again -- in HEX FORMAT ) is asked for. If no Value is supplied, the Dis-Assembler Dis-Assembles 256 bytes.
        Next, You Will be prompted for Diverting the Dis-Assembly to the ASM Viewer. Clicking YES causes another
        prompt for inserting at what LINE # in the ASM Viewer you want to begin Diverting to. You will then be prompted 
        to see if the Dis-Assembly window needs to be cleared. This allows for maximum flexability, such as loading a
        .HEX file, Dis-Assembling & Diverting to the ASM Viewer, and then including this diverted code with a program 
        already being written. USER and SUPERVISOR modes are respected here, also.

    4)  ASM Edit Tools ( F1 - F3 )
      
        F1 -- Insert
               Insert A Line into ASM Viewer
 
        F2 -- Delete
               Delete a line in the ASM Viewer
 
        F3 -- Clear ASm Workspace
               Delete the entire ASM workspace
    
    *** Hex Viewer Tools ( F4 - F8 )  
  
        F4 -- Refresh Hex Display.
               Please note that there are times when the HEX viewer needs to be refreshed. Such as viewing the  
               contents of a recently run program. Why ? well, i didn't want to slow down the program by refreshing
               memory every time a program finishes running, so remember that if your program wrote some value to
               memory during the execution of the Assembler program, you need to refresh.
  
        F5 -- Zero Hex Display
               this feature zero's all the bytes in the USER space when in USER mode, and ALL Memory when in
               SUPERVISOR mode. The Hex Viewer refreshes automatically after zero-ing.
 
        F6 -- Fill Memory with a HEX value.
               You will be asked to supply the starting and ending addresses and the fill value, all in HEX and then,
               according to the USER / SUPERVISOR rules, fills memory accordingly. If you are in USER mode and try to 
               write to a SUPERVISOR mode memory area, you will get a error message telling you that. When in
               SUPERVISOR mode, if you write to a system area, you will be asked if you want to proceed or bail out 
               and not fill.
 
        F7 -- Search Memory for a HEX value
               You can find and highlight all occurrances of the value. The cell in the HEX viewer will be highlighted.
               Again, this works according to the USER / SUPERVISOR rules, except that when in USER mode, if the value
               being searched for is in the first $400 bytes, the value will be highlighted. This is the only anomaly.
 
        F8 -- Clear the search
               This just clears the HEX viewer of any searched for values.
 
        F9 -- Clear the Dis-Assembly window
               Clear out the Dis-Assembly window of any text that may be in it.

    5) 68000 Register Display

        This is the heart of the program. Once a valid, no error program has been assembled, pressing the Emulator button
        causes this window to appear. Since there is so much going on here, an explanation of the individual components
        will be discussed first. PC is the program counter. When started for the first time, PC = $400. The user may
        change this by editing this box. HEX format only. All the other boxes may be edited by clicking in them and
        then editing. Clicking Load causes the values entered in the boxes to be loaded into the 68000's corresponding
        registers. All Flags are 0 or 1 , regardless of Number base. The window that shows USER or SUPERVISOR
        is not editable. Neither are the Stack Pointers. To change USP, this must be done in the assembly program
        via the A7 register. To change the SSP, one must be in supervisor mode, and then change SSP via A7. This 
        holds close to what I believe Motorola had in mind. Changing D0 - D7 and A0 - A7 can be done in either
        mode. The SR flags can only be changed in SUPERVISOR mode. In fact, The CCR is used in USER mode
        and reflects flag conditions in USER mode. SR flags are used During SUPERVISOR mode, and are thus
        reflecting the state of the machine during SUPERVISOR mode.
    
        The Number Base currently selected changes only the D0 - D7 and A0 - A7 registers. USP and SSP are not
        affected by changing number base. ( Some things never change... ). Valid number bases are Binary ( base 2 ),
        Octal ( base 8 ), Decimal ( base 10 ) and Hexadecimal ( base 16 ). The Change Base select only affects how
        a number is displayed. So, if you're in Binary base, and edit D0 and type a number that is not a zero or one,
        the register(s) display the last valid number in each box...

        The Run mode is basically a single step, a timed and free run. Single Step is Just that -- execute one 
        instruction and then wait to click Start again. This is useful when observing the behavior of a area of code,
        a specific register, PC, USP, SSP, Flags, etc. Timed Run mode is a mode of operation that is automatic.
        One instruction is executed approximately every 800 milli-seconds. This is useful for keeping an eye on the
        program but allowing it to execute the instructions. Free Run is just that -- execute your assembler
        program at full speed. The speed of this mode is determined by the Host computer...

    *** Breakpoints Menu -- 
                 Clicking here brings up the breakpoints window. Basically, any register can be
                 compared against any other register -- OR -- a value. Selecting a breakpoint is as 
                 simple as clicking the check box for the given breakpoint, selecting a register under
                 the WHEN , selecting a comparison operation under IS ( GT -- LT -- EQ  -- NE  --  etc)
                 and then selecting a register or enter a number ( again -- in the current base value ).
                 If 2 or more breakpoints are selected, the program will stop whenever any of the 
                 breakpoints evaluate to a true condition, regardless of which breakpoint is selected.

    *** IO Menu -- 
                 Four tools for use in the program. The first is a Switch & LED display, with 8 simulated 
                 Switches and LED's.
    
    The memory mapping is such : 

    
        $17FEF : Current value for Input Switches ( Located on LED Display Tool )
        $17FEE : N/A

        $17FED : LED current value  $0 - $FF : LED's Light According to Value
               : A value of $55 lights the odd number LED's. The right most
               : LED is equivalent to bit position 0 ( 2 ^ 0 ).
        $17FEC : LED Enable. $0 = not enabled, $FF = enabled.

    The Next is a LCD display of 4 Simulated LCD digits. The memory map looks like this:
        $17FEB : Digit 4 value ( left most digit ). See digit one value   
        $17FEA : Digit 3 Value. See digit 1 value
        $17FE9 : Digit 2 value. See digit one value
        $17FE8 : Digit 1 value ( $0 - $FF ). For example, to display a 0 ( zero ), place a value of $3F here
    
        $17FE7 : Enable Individual Digits 
          Bit0 : N/A
          Bit1 : Digit 1  0 = off  1 = on
          Bit2 : Digit 2  0 = off  1 = on
          Bit3 : Digit 3  0 = off  1 = on
          Bit4 : Digit 4  0 = off  1 = on
          Bit5 : N/A
          Bit6 : N/A
          Bit7 : N/A
        
        $17FE6 : Enable LCD Display  0 = off  255 = on
   

    the following is a layout of the display and weights.

                     2 ^ 0
                  ----------
          2 ^ 5  |          | 2 ^ 1
                 |   2 ^ 6  |
                  ----------
                 |          |
         2 ^ 4   |          |  2 ^ 2
                  ----------
                     2 ^ 3

        0 : 63
        1 : 6
        2 : 91
        3 : 79
        4 : 101
        5 : 109
        6 : 125
        7 : 7
        8 : 127
        9 : 103
        A : 119
        b : 124
        c : 88
        C : 57
        d : 95
        E : 121
        F : 113

   *** note : the values supplied for the corresponding digits are in base 10 

   *** Graphics Tablet.

       the origin is in the upper left hand corner of the tablet ( 0,0 ). The following memory locations control the
       functions of the tablet. x coordinates go left to right. y coordinates go top to bottom.
                                 
        $17FD9 : y2 Lo Byte
        $17FD8 : y2 Hi Byte
    
        $17FD7 : x2 Lo Byte
        $17FD6 : x2 Hi Byte

        $17FD5 : y1 Lo Byte
        $17FD4 : y1 Hi Byte

        $17FD3 : x1 Lo Byte
        $17FD2 : x1 Hi Byte
     
     The color controls are such :

        $17FD1 : Red   0 - 255  the larger the value, the more Red it is
        $17FD0 : Green 0 - 255   "    "     "   "      "   "   green it is
        $17FCF : Blue  0 - 255   "    "     "   "      "   "   blue it is
 
        $17FCE : The following functions can be performed
          Bit0 : N/A
          Bit1 : N/A
          Bit2 : N/A
          Bit3 : Change Color  0 = no color change  1 = change color according to color info -- redraw causes new color to take effect
          Bit4 : Auto ReDraw   0 = Do not redraw    1 = Perform a redraw -- necessary when changing these values
          Bit5 : Clear         0 = Do Not Clear     1 = Perform a Clear -- Do a redraw to clear everything
          Bit6 : Draw          0 = Do Not Draw      1 = Perform the draw function 
          Bit7 : Enable        0 = Not Enabled      1 = Drawing tablet enabled

     Usually , the sequence of events will be :
 
       1) Enable
       2) Clear
       3) change color
       4) Draw
       5) ReDraw
 
       normally, the enable & redraw are done at the beginning, clear,change color and draw are dynamic -- can be done w/o
       having to enable,redraw, etc. The redraw is required because of VB5 and its limitations. 

  10) Load / Save files --
                       The SDE uses its own format to save ASM and HEX files for use later on. For example, an ASm file 
                       saved from the ASM viewer is formatted so visual basic can read it back in. Since this is the case,
                       a yet future thing will be the ability to parse and input ASM files from other systems. The HEX 
                       viewer can read in binary files in the Motorola .S record format and also straight binary files that
                       have the SDE extension, which is factory default format. when saving the HEX Viewer, the whole 160KB 
                       is saved. This is similar to doing workspace saves, and just made for a simpler approach. As of yet,
                       there is no support for output of .S record format binary files.

    *** Supervisor mode -- 
                       To enter SUPERVISOR mode, a trap to a user  TRAP #0 - #12  will suffice. This places the SDE into
                       Supervisor mode and then the Registers window can be minimized and access to HEX viewer is allowed.
                       Note -- a .S record file that occupies address space $0 - $3ff  or $20000 - $27fff can now be loaded. 
                       Since the SDE only executes code in this address space when in SUPERVISOR mode, this is a handy litte
                       way around the actual and emulated. Also, the SR becomes active, and the SSP is now used to control
                       the stack. The Stacks are located at startup at $1FFFF for USP  and $27FFF for SSP. If the SSP is 
                       located outside the 32KB space ( $20000 - $27FFF ), you are on your own. Also, The trap vectors
                       currently point to address $20000, which is a memory location with the RTE command pre-programmed.
                       Thus, a TRAP #0 in the assembly code will cause a system trap to occurr. the stacks are doing their 
                       thing, then processor mode is set to SUPERVISOR , PC = $20000 , which is the default pointer setup 
                       in $0 - $3FF . Then the program stops, and a RTE will be the next instruction to be executed after 
                       pressing start. This puts the SDE back into USER mode and continues processing. A TRAP #15 causes 
                       any program currently running to stop, without putting the SDE into SUPERVISOR mode.

    *** Current Traps

        TRAP #0  - not in use  enter SUPERVISOR mode
        TRAP #1  - not in use    "        "      "
        TRAP #2  - not in use    "        "      "
        TRAP #3  - not in use    "        "      "
        TRAP #4  - not in use    "        "      "
        TRAP #5  - not in use    "        "      "
        TRAP #6  - not in use    "        "      "
        TRAP #7  - not in use    "        "      "
        TRAP #8  - not in use    "        "      "
        TRAP #9  - not in use    "        "      "
        TRAP #10 - not in use    "        "      "
        TRAP #11 - not in use    "        "      "
        TRAP #12 - not in use    "        "      "
        TRAP #13 - cin routine  *see below
        TRAP #14 - cout routine *see below
        TRAP #15 - Stop execution of program w/o going to SUPERVISOR mode

        exceptions are handled the same way, and are currently supporting illegal addressing modes and some illegal commands.
        the user defined commands ( start nibbles A or F ) are not being trapped.

    *** Cin Function -- This function allows for input from the keyboard. due to limitations of Win32 Programming, interaction
                        with this function is as follows 
  
        $17FDF : bits 0  - 7  of string virtual memory target address 
        $17FDE : bits 8  - 15 of string virtual memory target address
        $17FDD : bits 16 - 23 of string virtual memory target address ( currently 1 or 2   )
        $17FDC : bits 24 - 31 of string virtual memory target address ( not currently used )

        $17FDB : Length of string brought in
        $17FDA : N/A -- reserved for future use

        when initiated with a TRAP #13 , a window opens up where the user types in characters. The string is loaded into
        virtual memory according to the address held in $17FDC - $17FDF. USER & SUPERVISOR rules apply. The sequence is as
        follows:

          1) Load $17FDC - $17FDF with address where string is to go in virtual memory ( valid addresses are $00000 - $27fff )
          2) Issue a TRAP #13 in ML program
          3) click close
          4) press start to resume processing. length of string is in $17FDB

    *** Cout Function -- This function allows for a string to be output to a window. This window will keep track of all
                         strings output. The following apply.
       
        $17FE5 : bits 0  - 7  of output string virtual memory address
        $17FE4 : bits 8  - 15 of output string virtual memory address
        $17FE3 : bits 16 - 23 of output string virtual memory address ( currently 1 or 2   ) 
        $17FE2 : bits 24 - 31 of output string virtual memory address ( not currently used )
 
        $17FE1 : length of string to be sent
        $17FE0 : N/A -- reserved for future use

        when initiated by the user with a TRAP #14 , a window opens and the string is displayed whose address is contained
        at $17FE2 - $17FE5 . USER and SUPERVISOR rules apply. The sequence is as follows:

          1) Load $17FE2 - $17FE5 with address in virtual memory where string is located.
          2) Issue a TRAP #14 in ML program
          3) Click close when done viewing output
          4) click start to resume processing ML program

    12) ActiveWire USB support.
   
        Much can be said for USB. It is very complicated to try and write a driver and make it work with the few
        chips on the market that support USB. However, i think its here to stay, at least for a few more years.
        With the advent of the USB 2.0 standard, the problem of speed has been addressed. However, most new ( 2002 )
        computers still do not support the new standard. There are a few options. First is to use Serial Communications
        viz COM1 , COM2 , etc. This is easy but uou have to figure all the timing stuff, and besides, this is 2002.
        Next is to make your own USB controller. Though this may sound easy, tis no small matter. However, the solution
        of communicating with the 'REAL' world has been solved. A company in California called ActiveWire Inc.
        ( www.activewireinc.com ) sells the total package for like $60.00 US . Another company, DLP Design, located
        in the U.K. sells a device also. The activewire USB device has 16 I/O pins, any configuration. The DLP Design
        board has 8 I/O. Since the ActiveWire USB has more I/O and the driver for the device downloads itself into the
        USB Board, this makes for the most flexible, cost effective device around. Since USB controller chips are made
        with either static firmware ( cheaper & less flexible ) or dynamic firmware ( costlier but easier to upgrade ),
        these factors were taken into consideration. So....

        $17FFF : device number to close, not used at this time
        $17FFE : Close AWUSB  0 = no action  255 = Issue a Close Command on ( i believe ) all the Open AWUSB devices.

        $17FFD : Device to Open ( 0 - 127 ) 
        $17FFC : Open a AWUSB device

        $17FFB : 0's = input  1's = output  on lower 8 I/O pins of open AWUSB device
        $17FFA : 0's = input  1's = output  on upper 8 I/O pins of open AWUSB device
        $17FF9 : AWUSB Enable command enabler. 0 = N/A  255 = Issue Enable Command
        $17FF8 : Not currently used

        $17FF7 : Lower 8 pins Output Value
        $17FF6 : upper 8 pins Output Value
        $17FF5 : Issue Output To AWUSB device currently open  0 = N/A   255 = Issue Output Command
        $17FF4 : Not currently Used

        $17FF3 : Lower 8 pins of value input from open device
        $17FF2 : upper 8 pins of value input from open device
        $17FF1 : Issue Input From AWUSB device currently open
        $17FF0 : Not currently used

        usually, the following sequence is used for AWUSB :

          1) Plug device into USB chain
          2) Give Windows the location of the driver ( included on CD-ROM or Distribution file in Drivers folder )
          3) Issue a Open command
          4) Issue a Enable command. 16 bits  0 = input   1 = output  correspond to pins on AWUSB
             e.g. --  1111000011110000   results in pins 0-3 input; pins 4-7 output; pins 8-11 input; pins 12-15 output
          5) Do Input and/or Output
          6) close AWUSB

        The Enable command can change the pin configuration on-the-fly. this is a neat feature, allowing for swapping
        projects w/o having all the mess.