Machine Problem 3: Typing-Tutor 291

Introduction

Ever used a typing tutor to learn how to type? Ever think of doing so? We're about to create one, but don't expect it to be as good as Mavis Beacon.

Problem Description

Our typing tutor has to do three main things:

• Show the current state of the keyboard (to help the typist look at the screen)
• Show a string for the typist to type, showing the typist's progress and mistakes
• Track the time and number of mistakes the typist makes, and display this at the end

To do these somewhat efficiently, we're going to hook into the computer's keyboard and timer interrupts, to run some of the code asynchronously from the main loop. Asynchronously means, in this sense, that you never know ahead of time when it will run. You could have two move opcodes, or a compare and a conditional jump, and either could be interrupted to run the Interrupt Service Routine (ISR). More on this shortly.

Implementation

Interrupt Service Routines

Hardware Interrupts are generated when various hardware events occur.  Examples include the timer, which triggers 18.2 times per second, the keyboard, which triggers for every key press and release, and the mouse which triggers for any movement or button press or release. These interrupts are the hardware's way of saying "I need attention," so that the rest of the time the CPU can completely ignore such devices, and just execute code.

When the interrupt happens, the CPU is informed.  The current opcode finishes execution, and then the current program is interrupted. This is when your Interrupt Service Routine (ISR) is executed. As it happens between two effectively random lines of your program, the ISR needs to save all registers and the flags. The hardware takes care of part of this (by pushing of the flags); the rest you must take care of by using IRET instead of RET (to pop the flags), and saving your registers like normal.

The Timer

The timer will be used to keep track of how long it takes the typist to type the sentences. While we could probably be saving these scores for charting improvement, we'll just use it to report back to the user immediately. Every time your timer ISR is called, increment the tick counter, [ticks]. Then, every 18 ticks increment the seconds counter and the fifths counter, [seconds] and [fifths] respectively, and reset the tick counter to 0. Finally, every 5 seconds, decrement the time counter (to make up for the .2 of the 18.2 ticks per second) and reset the second counter to 0.

The Keyboard

When your keyboard handler is called, you know a key has been pressed or released. Unfortunately, you don't know what key, whether it was pressed or released, and whether the press is a true press or an auto-repeat press. There's no way for us find out the last (except keeping track yourself), but as for which key and press or release, you can (and must) find this out by asking the keyboard for the scancode. See the lab manual, page 75 or thereabouts, for information on retrieving these scancodes. The pages after that describe how scancodes work.

The Keyboard Lookup Tables

If you look at the scancodes, and you look at your ascii table, the first thing you'll probably notice is that there's no connection. If you then look down at the keyboard, however, you may notice a general correlation between the scancode and the location of the key, with ESC being scancode 1, and the numbers following an increasing pattern.

While theoretically we could try to come up with some arbitrary math procedure to translate from scancode to ascii code, it's much easier and much faster to just use a lookup table. And since there are several bits of information we want to handle, using multiple lookup tables is definitely the choice.

The tables we'll be using are as follows:

• QwertyNames
  • Mostly an ascii lookup table, 128 bytes long, one byte per character.
  • If the value is under or equal to KEY_STR, it is a "special" character, and takes a second lookup.
• QwertyShift
  • Just like QuertyNames, but has the values for when shift is pressed.  Special keys are identical to original table.
• SpecialKeys
  • Holds KEY_STR offsets (word sized) that point to '$' terminated strings
• SpecialAscii
  • Holds KEY_STR characters (byte sized) which are the ascii the special keys should use
• KeyLocations
  • Holds screen offsets used for drawing each key.

The Strings

As the user types a string, it needs to be compared against the correct string.  As the user makes mistakes, they need to be highlighted. When the user hits backspace, we need to back up the user version. All these things need to be tracked, and drawn in the appropriate colors.

• Draw the string the user has to match in ATTR_STRING
• Draw pieces of the string the user types correctly in ATTR_NORMAL
• Draw mistaken characters in ATTR_ERROR

Similarly, the keyboard must be updated to match the current state of the keyboard (yes, there are some keys that make it look like shift was pressed when it wasn't.  Don't worry about them; just treat the shift scancode as you always would).

• Draw the keyboard border and all normal keys in ATTR_RELEASE
• Draw the keys that are currently down in ATTR_PRESS

Rather than redrawing the entire keyboard every time, just use HighlightKey to change the attribute of a given key by scancode (for easy use of the lookup table). But do redraw the entire keyboard (not changing the attributes) using the Shift tables, if [shift] changes to true (or the normal tables if it changes to false).

Procedures

• This assignment has 15 procedures. You will receive credit for this assignment by replacing each of the fifteen procedures listed below with your own code.
• Experiment with the working code to gain a full understanding of how the program works.
• Use defined constants/variables where appropriate.
• Comment ALL the functions and make sure that they preserve all register values.  Be sure to include function headers for ALL functions that you write.
• Optionally, for a gold star, implement word wrapping and longer strings..

• MP3Main
• Purpose : Do all necessary initializations, set up interrupt handlers, run the main loop, remove handlers, exit
• Inputs : None
• Outputs : None
• Calls : InstallKeyboard, InstallTimer, DrawKeyboard, NextString, GetKeyPress, TypeKey, DisplayStats, RemoveKeyboard, RemoveTimer
• Notes :
• Exit immediately on [quit] being set to nonzero. This requires smart coding of GetKeyPress.
• Install and remove the Interrupt Service Routines only once.
• On end of string, call DisplayStats and wait for a key press before resetting with NextString.
• Don't forget to reset your string offset to the beginning of each new string!
• Points : 3

   

• DrawKeyboard
• Purpose : Draw the keyboard onto the screen; includes lines, attributes, and names.
• Inputs : None
• Outputs : None
• Calls : DrawKeyNames
• Notes :
• Loop over the characters in KeySkin, drawing them to the screen starting at KBD_OFF, and looping for 11 rows of 80 characters.
• Call DrawKeyNames second, as DrawKeyboard draws blanks where the names will go.
• Points : 3

   

• DrawKeyNames
• Purpose : Draw the key names onto the screen, paying attention to [shift]
• Inputs : None
• Outputs : None
• Calls : None
• Notes :  
  • Use QwertyNames if [shift]==0, or QwertyShift otherwise.
  • Draw only the character bytes; don't draw the attribute bytes.
  • Pay close attention to the structure of the lookup tables: (view them directly in the include file)
    • If QwertyNames[scancode] > KEY_STR, just use the byte value as its appearance.
    • Else (QwertyNames[scancode] <= KEY_STR) it is a lookup into SpecialKeys, which points to '$' terminated strings.
    • If the location for the key is 0, don't draw it.
• Points : 6

• NextString
• Purpose : Sets up the various variables for the next string run
• Inputs : None
• Outputs : None (several variables are changed, however)
• Calls : None
• Notes :
• Reset [errors], [seconds], [ticks], and [fifths]
• Clear the four string rows to ATTR_NORMAL, update [currentStr], and draw the new string with ATTR_STR
• Use the constants STR_OFF, IN_OFF, ERR_OFF, and TIME_OFF appropriately
• No string can be more than 80 characters long.
• If StrTable[currentStr] is zero, this is one past the final string. Reset [currentStr] to zero.
• Update the cursor position in from this function too. The library code cheats by calling TypeKey with a backspace. You may (but are not required) to do it this way.
• Points : 4

• InstallTimer, RemoveTimer
• Purpose : These procedures Install and Remove the Timer ISR
• Inputs : location of TimerISR
• Outputs : None
• Calls : Interrupt 21h
• Notes : See http://www.ctyme.com/intr/int-21.htm
• Points : 2

• TimerISR
• Purpose : Increment counters and set update to track player's time
• Inputs : None
• Outputs : None
• Calls : Original Timer ISR
• Notes :
• Don't forget to call the original handler (this is called chaining) to ensure the functionality that is dependant on the timer
• See Lecture 14 for more information on writing and installing ISRs
• Increment [ticks] every time, [seconds] and [fifths] every 18 ticks, and decrement [seconds] every five fifths.
• reset [ticks] and [fifths] after they trigger an increment or decrement, respectively.
• Points : 2

• InstallKeyboard, RemoveKeyboard
• Purpose : These procedures Install and Remove the Keyboard ISR
• Inputs : location of KeyboardISR
• Outputs : None
• Calls : Interrupt 21h
• Notes :
• See http://www.ctyme.com/intr/int-21.htm
• Points : 2

• KeyboardISR
• Purpose : Sets variables such that the main loop will react to the keyboard inputs
• Inputs : None
• Outputs : None (writes to several variables)
• Calls : HighlightKey, DrawKeyNames
• Notes :
  • See the lab manual for a skeleton ISR
  • Set [nextKey] to the ascii according to the lookup tables: like in DrawKeyNames, if QwertyNames[scancode] > KEY_STR, just use it as the ascii, but use SpecialAscii[scancode] if QwertyNames[scancode] <= KEY_STR
  • Call HighlightKey on any scancode < SCAN_MAX
  • Track the status of the shift keys in [shift], and call DrawKeyNames when it changes
  • Set [quit] to 1 when ESC is pressed.
• Points : 8

• HighlightKey
• Purpose : Change attributes on pressed (or released) key to show which keys are currently pressed
• Inputs : al = scancode
• Outputs : None
• Calls : None
• Notes :
  • Use ATTR_PRESSED or ATTR_RELEASED as your attribute byte
  • Change only the attribute byte; don't change the character byte
  • Don't forget the Special keys which need to have entire strings highlighted
  • See DrawKeyNames for documentation on the lookup table structure
  • Beware rogue inputs - don't try looking up scancodes > SCAN_MAX
• Points : 4

• GetKeyPress
  • Purpose : Retrieve the next key pressed, like kbdin
  • Inputs : None
  • Outputs : al = ascii of key, unless [quit] > 0 (then it can be anything)
  • Calls : None
  • Notes : 
    • Wait  for (loop until) either [quit] or [nextKey] to be nonzero
  • Points : 3

• TypeKey
  • Purpose : Draw the next pressed key to the screen, updating the cursor appropriately
  • Inputs :
    • al = ascii of key
    • bx = offset into current string
  • Outputs : 
    • bx = next offset into string
    • cf = 1 if and only if we have finished the current string
  • Calls : CheckKey
  • Notes : 
    • Draw the character at IN_OFF+f(bx) 
    • If CheckKey claims a match, use ATTR_NORMAL, but use ATTR_ERROR otherwise
    • Display either a null (0) or a space to the screen after moving one space to the left on backspace
    • Don't backspace before the beginning of the buffer
    • End the current string if either CheckKey says we're done, or the user presses enter
    • Use Interrupt 10h, function 2 to move the cursor to row IN_ROW, column bx (See http://www.ctyme.com/intr/int-10.htm)
  • Points : 6

• CheckKey
  • Purpose : Check if the pressed key matches the appropriate character of the string, or if the string is complete
  • Inputs : 
    • al = ascii of key
    • bx = offset into current string
  • Outputs : 
    • ZF = 1 if and only if key matches (don't worry about during end case; user can't press 00h)
    • CF = 1 if and only if we're at the end of the string (zero terminated)
  • Calls : None
  • Notes : 
    • Take advantage of your compare to set the zero flag appropriately
    • Set the carry flag and exit if appropriate, and ignore the zero flag if at the end of the string
    • [currentStr] is the index of the string (0..STR_MAX-1)
    • StrTable is a lookup table of string starting addresses: thus compare [[StrTable+[currentStr]]+bx] to al, but make it work in assembly
    • Increment [errors] on any mismatched key
  • Points : 3

• DisplayStats
  • Purpose : Display the statistics earned by the user, both errors and time
  • Inputs : None
  • Outputs : None
  • Calls : None
  • Notes : 
    • Call binasc on [errors] and [seconds] pointing to errorNum and timeNum, respectively
    • Display strings errorMsg and timeMsg starting at ERR_OFF and TIME_OFF, respectively, with ATTR_STR
    • Writing a helper function to draw strings of a given attribute to the screen may be useful
    • Note that errorMsg is directly before errorNum and relies on the '$' that binasc places at the end of errorNum
  • Points : 4

Monitor the newsgroup and this on-line section for revisions to the MP or to the write-up

Procedure

• You will begin this MP with the following files:
  • MP3.ASM: Program Framework
  • Makefile: Specifies how and when programs are assembled and linked.
  • LIBMP3.LIB: Library functions for MP2
  • LIB291.LIB: General-purpose library functions
• You may copy these files from the network drive to your home directory with the following command:
  xcopy /s V:\ece291\mp3 W:\mp3
  or download the files from this server as mp3.zip
• Add your code to MP3.ASM.
• Assemble and link your program by typing
  make
  This command reads Makefile then invokes NASM and LINK to build an executable program.
• Use Turbo Debugger (TD) to find and correct program errors.
• Verify your program operation by testing the input test file. You should alter the test file to check different scenarios with your code.

Final Steps

1. Demonstrate your MP3.EXE to a TA. You may be asked to recompile and demo the program. Your program must work with all given input.

2. Be prepared to answer questions about any aspect of the operation of your program. The TAs will not accept an MP if you cannot fully explain your code and your implementation. Delayed MPs will be subject to late penalties as described in the course syllabus (10/pts per day).

3. The TA will complete the code submission procedure.

mp3.asm