• To provide a basic introduction to the Machine Controller Debug Monitor.
• Run the simulation of the Machine Controller Debug Monitor binary code in the simulator provided (Avrsim).

• Make sure that the 'AVRA' AVR assembler is installed correctly,
• if not then read 'setup C build environment.txt' also do Demo-1.
• side4linuxDVD owners should look HERE for the AVRA Tar file.

1. Open the side4linux IDE and click on 'Project>Open Project' in the Main Menue.
   
2. Double click on the 'DEMOS' Product Area,
3. Double click on the 'SIDEdemos' Product,
4. In the file dialog double click the  'AVRA' folder, this takes you to where 'AVR' assembler projects are kept.
5. Double click on 'Sample2', this opens the 'Sample2' project folder.
6. Click on 'Open-TXT' and open the file 'sample2.asm'.
   

---

Practical-1 The 'Interupts'

First section of the Debug Monitor is the 'Interupt Handler Locations' starting at location 0002h this is after the 'cold boot' point called 'Start'.

;================================== Start of main ===================================
.nolist
.include "src/AvrMega128/m128def.inc"     ;Atmel part definition file
.include "src/Globals.inc"                            ;Global Defs & Sets
.list
.cseg
.org 0
Start:
    rjmp     reStart
interuptVectors:                                            ;interupt handler routine vectors
Int_0:
    nop                                                            ;int0, not in use
Int_1:
    nop                                                            ;int1, not in use
Int_2:
    nop
Int_3:
    nop                                                           ;Timer2 counted down to zero
    rcall    Error_02                                        ;failed interupt call

---

Practical-2 The 'Entry Point'

From 'Start' at location 0000h we relative jump to the 'ReStart' point which is used as the 'warm boot' point. Here the stack and serial ports are setup and we send the 'sign on' message stored in the 'hello' subroutine out on serial port zero. The program then settles into the command decoder loop at the label 'controlLoop' awaiting an inputed command string from the controlling Linux computer.

ReStart:
    cli                                                             ;kill interupts
    ldi        r16,high(StackTop)                       ;init stack pointer
    out       sph,r16     
    ldi        r16,low(StackTop)                        ;stack grows down
    out       spl,r16
    rcall     RS232Out_initUart0                     ;setup input uart
    nop
    rcall    hello                                              ;send sign on message to serial input
controlLoop:
    rcall    CmdLoop_cmdDecoder                  ;holds monitor command choices       <----<<< entry point for command strings.
    rjmp    controlLoop                                   ;program control loop
;------------------------------------ End of Main------------------------------------
hello:                                                            ;call writeString, put message after as .db "text", followed by nop
    rcall    RS232Out_writeString0
    .db     "MC-1 Ver 7.0"
    nop
    rcall    RS232Out_writeln0                       ;sends  10h, line feed
    ret
;================================== Include Files Next ==============================
.include "src/Includes.inc"
    nop
    nop
    nop
    nop
    nop

---

Practical-3 The 'Command Decoder'

Here is presented the 'Primary Command Decoder' from the file 'CmdLoop.inc'. It's job is to read in the commands sent from the controlling Linux computer, decode and execute them. This means that the output is sent to the machine being controlled at a set rate if the incomming command is a step command and at the full speed of the serial transmission if it is any other command. Buffers are provided at the incoming and outgoing end to relieve the Linux computer of any real-time performance requirement. Hence a standard Linux kernel can be used. The command format is as follows,

;      CMD1    CMD2   CMD3  n0      n1      n2      n3      n4     n5           ; up to three letters per command line followed by ASCII number digits.
;      CMD1    n0          n1        n2      n3      n4      n5                            ; or at least one command character followed by ASCII number digits.

So commands can be one to three letters in length followed by numbers all in seven bit upper case hex ASCII format. ]
The serial transmission Baud rate is 9600, no parity, eight data bits and two stop bits.

The first action is to get a command string of up to a sixteen bytes from the Linux control computer terminated with a Line Feed character at the label 'CmdLoop_cmdDecoder'. This means that the maximum command length is fifteen.

Notice that through out the Monitor the exported/imported labels are prefixed with the filename and an underbar, since we are looking at code from the file 'CmdLoop.inc' the prefix is 'CmdLoop_'. 

Debug commands start the decode at 'debugCmdDecoderEntry' by decoding the Debug 'Q' and then branch out from there.

;cmdDecoder
;THIS ROUTINE ACCEPTS AS INPUT A COMMAND LINE FORMED
;IN RAM called 'SioBuf0'
;END OF THE COMMAND LINE POINTED TO BY r17.
;address of command string in XH/XL
;destroys r16 & r17 & RX pair
;
CmdLoop_cmdDecoder:  
    rcall    RS232In_readSerial0IntoBuffer     ;get command string
    cpi       r17,0                                             ;end if string length is zero
    breq    cmd_decoder_length_error
debugCmdDecoderEntry:     
    ldi       XL,low(SioBuf0Start)                     ;get address of command string
    ldi       XH,high(SioBuf0Start)
    ld        r16,X+                                           ;get character of command string
    cpi      r16,'M'                                            ;a Misc command?
    breq   cmdMiscs
    cpi      r16,'T'                                             ;a Tool command?
    breq   cmdTools
    cpi      r16,'Q'                                             ;a debug command?   <-------<<< Start Decode of Debug Commands HERE!
    breq   cmdDecode
    cpi      r16,'%'                                             ;Ignore this one
    breq   cmdIgnore
    cpi      r16,'@'                                             ;Ignore this one
    breq   cmdIgnore
    rcall   ERROR_03                                        ;Unknown Commandline Primary Command
    ret
cmd_decoder_length_error:
    rcall    ERROR_00                                       ;zero length command error
    ret
     
cmdMiscs:
    rjmp    DecodeM_cmdM
cmdTools:                                                       ;send it as is to the Machine!
    push    r17                                                  ;save byte counter register
    ldi       r17,16                                              ;set for full length
    rcall    RS232Out_WriteSio0Buffer
    pop     r17                                                  ;restore byte counter register
    ret
cmdIgnore:
    ret
;-------------------------------------------------------------------------
;cmdDecode (debug)
;THIS ROUTINE ACCEPTS AS INPUT A COMMAND LINE FORMED
;IN RAM called 'SioBuf0'
;END OF THE COMMAND LINE POINTED TO BY r17.
;address of command string in XH/XL
;destroys r16 & r17 & RX pair
;
cmdDecode:  
    ld      r16,X+                                             ;get next character of command string
    cpi    r16,'D'                                              ;IS IT Display memory selected line?
    bre   displayingDecode
    cpi    r16,'F'                                               ;IS IT Fill memory?
    bre   memoryFilling
    rcal  ERROR_06                                        ;UNKNOWN Debug select COMMAND
    ret
     
displayingDecode:
    rjmp    Debug_DisplayDecode
memoryFilling:
    rjmp    Debug_MemoryFill
    ret
     
;end of debug cmd primary decoder     
;------------------------------------------------------------------------------------
;END OF PRIMARY COMMAND DECODERS
;------------------------------------------------------------------------------------

---

Practical-4 The 'Command Decoder Debug Commands'

The following Debug commands are available, please refer to the MANUAL (Local) for more detail.

Command	Usage
QDnnnn Display next sixteen bytes of data memory from address nnnn.	QD01E3
QFxxxxyyyyzz Fill data RAM memory from xxxx to yyyy with data zz.	QF010012E4FF

NOTE

1/ All characters and hex letters are to be in upper case only.
2/ All numbers are in hex ascii.

---

Practical-5 Simulation

Click on 'Tools>AVRA>Avrsim' to launch 'avrsim' the built in graphical AVR simulator as seen in figure-1 below,

'Step' down to                            Line C:00000a bf0d          out     spl,r16

Click on 'Jump' twice to land on Line C:00000c  ef0f          ldi       r16,0xff                                             ;blink on step fudge

Click on 'Step' three times to     Line C:00000f  d002         rcall    hello

Click on 'Jump' to                      Line C:000010 d1e3         rcall    CmdLoop_cmdDecoder                    ;holds monitor command choices

Notice that this is the 'Primary Command Decoder' where we would call in the next command string from Serial Port zero, decode it to action the first command character of the string. This command character will then branch off to further command characters as the command is decoded. Finally any variables from the command string would be read and the command then actioned.

You may study this fetch and decode sequence at your leasure but for now close the Avrsim simulator and close the Project as this is the end of Demo-2!

Note: A similar Monitor Rom is used in PCBScodingHelpDemo-8.html, have a look at this Project to learn how to program an AVR chip and also for general AVR chip programming Chip Programming (local).

We will provide other demos as 'side4linux' develops to cover AVR programming and integration into a real world machine controller.