readme.txt

mcs51,2051,x86系列MCU

PROJECT-          LEGACY KEYBOARD/MOUSE to USB CONVERTER.

MicroController-  This project uses the 82930A Microcontroller (rev A3).

                  For use with the 82930AX, you will need to perform a CONVERSION
                  on all code.  Algorithms/methods should be fairly applicable for
                  use with 82930AX though..

PURPOSE-          Provides example code using 82930A for converting Keyboard and Mouse
                  signals into USB format using 82930USBM evaluation board.

                  This is a description of the files required to run the legacy
                  keyboard/mouse to USB converter.  This code was developed using
                  the PLC Compass 251 IDE tool and an 82930 USBM evaluation board
                  with an 82930-A3 processor.  At the end of this document are a few
                  notes on hardware setup required to run this code.


NOTES-            The Compass project file is not included.

                  Portions of the code refer to this converter as a 'DONGLE'.
                  The use of the term is incorrect.  Please consider this functionality
                  as a converter as stated above.

                  Support for this Sample application is not available.  It is provided
                  here only to give the user a sample that they can use to better understand the
                  functionality of the 82930XX series of MicroControllers.

                  For use with the 82930AX, you will need to perform a CONVERSION on all code.
                  However, algorithms/methods should be fairly applicable for use with the 82930AX.


 *          The Software is provided "AS IS."
 *
 *          LIMITATION OF LIABILITY:    NEITHER INTEL NOR ITS VENDORS OR AGENTS
 *          SHALL BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF USE, LOSS OF DATA,
 *          INTERRUPTION OF BUSINESS, NOR FOR INDIRECT, SPECIAL, INCIDENTAL OR
 *          CONSEQUENTIAL DAMAGES OF ANY KIND WHETHER UNDER THIS AGREEMENT OR
 *          OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 *
 *          While we have made every attempt to completely test this code, we request that
 *          you personally test it completely prior to actual inclusion in your own projects.
 *          This code requires conversion for use with the 82930AX Microcontroller.


Assembly Source Files
     LITE_FRM.ASM
     DONGMAIN.ASM
     KBDISR.ASM
     MOUSEISR.ASM
     REPORTS.ASM

Assembly Include Files
     82930.INC
     DEFS.INC
     ONE_OH.INC
     EXTERNS.INC
     DONCONST.INC

                   ** GENERAL DESCRIPTIONS **

~~~~~~~~~~~~~~~~
LITE_FRM.ASM
~~~~~~~~~~~~~~~~
     This file handles USB enumeration and host communications.  It
     initializes all variables and then runs an "ActiveLoop" which
     does nothing more than flash the P1.3 LED.  The rest of the code
     is called by interrupts received from the USB host.

     The "FUNCTION_ISR" routine is vectored to via any of the four
     endpoint TXD or RXD interrupts.  The code then checks to see which
     endpoint was responsible for the call and branches to the appropriate
     handling routine.  All EP0 handling is done inside this file.
     Interrupts received on the second and third endpoints (for the keyboard
     and mouse, respectively) call the required external report generator
     functions (SEND_KBD_REPORT_EP2 & SEND_MOUSE_REPORT).

     At the end of this file are all of the USB Descriptors (Device,
     Configuration, Interface, Endpoint, HID, & Report Descriptors).  As of
     8/2/96, there is only one interface defined and that is for the
     keyboard.  The second interface is for the mouse and its pertinent
     code is commented out.  When a host with full USB capabilities and the
     appropriate drivers is available, this code could be added to provide
     full mouse and keyboard functionality (with some minor modifications).


~~~~~~~~~~~~~~~
DONGMAIN.ASM
~~~~~~~~~~~~~~~
     This file defines all of the variables and constants needed for
     the non-USB part of the code (i.e. the keyboard and mouse handling
     parts).  It also contains three main functions:

          1. DONGLE_INITIALIZATION - This function is called only from the
             initialization part of "lite_frm.asm" and done only at reset
             or power up.  It sets all of the variables and buffer areas to
             their desired starting values.  It sets up the Timer 2 to be
             used for the serial port baud rate generator (for the mouse)
             and enables all interrupts.  Starting with the section labeled
             "send "ECHO" to kbd", is a series of commands to be sent to the
             keyboard.  This first command (ECHO) is sent only to see if the
             keyboard is connected.  If not, the code will bypass all other
             sends to the keyboard and return to lite_frm.asm.  This is done
             to prevent the code from waiting indefinitely for keyboard
             acknowledgements that will never come.  If a keyboard is
             connected, it should send back EE hex and the other keyboard
             commands will be sent out.  Here is a brief explanation of each
             command and why it is sent:

                    RESET -
                         To clear out the keyboard buffer and set all
                         parameters to their default state. The keyboard
                         should respond with an "ACK" of FA hex and then
                         it does a self-test returning AA hex upon
                         successful completion.

                    ENABLE -
                         Needed to enable the keyboard. The keyboard
                         should respond with an FA hex (ACK).

                    SELECT SCAN SET -
                         Tells the keyboard that a change in the scan set
                         it uses is desired.  It responds with an FA hex
                         and then waits for the next byte which will tell
                         it which set to use.  This is done because the
                         default scan set (Scan Set 2) is not easily used
                         in this code.  The main reason is that special
                         keys like Pause and Print Screen (et al) send
                         many bytes back for both make and break codes.
                         Scan set three (which this code uses) is friendly
                         in that no matter what key is hit you get its make
                         code followed, upon its release, by F0, and then
                         by the same code that it sent for the make.  This
                         is ideal for storing the keys in a buffer area upon
                         make and then, when FO is received, wait for the
                         next byte and simply remove it from the buffer area.

                    SCAN SET REQUEST -
                         03 hex is sent to tell it to change to Scan Set 3.
                         The keyboard responds with FA hex.

                    SET ALL KEYS MAKE-BREAK/NO TYPEMATIC -
                         This completes the set up for the ideal make/break
                         code scheme described above.  No typematic is set
                         since this is now a function of the USB host, as
                         described in the HID Class Specification.  The
                         keyboard responds with FA hex.

             Next, an initial keyboard report is written to TXFIFO2 by
             calling the SEND_KBD_REPORT_EP2 function (in reports.asm).
             This is done so that there is some data in the FIFO when the
             first IN-TOKEN request comes from the host.  Upon receiving
             this first report the host will send back an ACK which causes
             a TXD2 interrupt.  This interrupt calls the same function
             again (which fills TXFIFO2 again) so that the next IN-TOKEN
             will retrieve the next keyboard report.  This process continues
             indefinitely.

          2. SET_LED_STATUS - This function is called upon initialization
             and then by lite_frm.asm whenever the host sends a "SET REPORT
             (output)" request.  In either case, the variable "LED_STATUS"
             has the desired LED pattern in it and is sent to the keyboard.

          3. TIMER0_ISR - This function is called whenever Timer 0 overflows.
             It is used specifically for timing the duration since the last
             report was sent if a "SET IDLE" command has been received from
             the host.  There are two different types of IDLE mode -
             INDEFINITE and TIMED.

             INDEFINITE idle causes the system to inhibit report writing
             (i.e. ignore the TXD2 interrupts) until a key event occurs.
             Therefore, whenever a key is added to or removed from the
             keyboard buffer (in kbdisr.asm) the SEND_KBD_REPORT_EP2
             function must be called.  TIMED idle is a means of delaying
             the periodic reports, but reports are still sent at a periodic
             rate even if there are no new key events.  However, a key
             event does take precedence over the timer status.  Timer 0 has
             been used to cause overflows which happen at 4ms intervals.
             A tally is kept on how many times a 4ms overflow has occurred
             and this tally variable (TIMER0_4MS) is compared to the value
             of the IDLE Duration specified in the SET IDLE host request.
             If they are equal, a report is written, regardless of the state
             of the keyboard keys.


                    NOTE- This is a detailed HID compliant issue that is
                          described in more detail in section 7.2.4 of the
                          version 1.0 HID Class Specification.

~~~~~~~~~~~~~~~
KBDISR.ASM
~~~~~~~~~~~~~~~
     This file handles all of the keyboard communications.  It is called
     ONLY by a negative edge transition on INT1 (P3.3).  This is the pin
     that is connected to the CLOCK output of the keyboard.  Rather than
     explain the code in detail, a brief description of the two communications
     modes (send and receive) will be given:

     SEND TO KEYBOARD -
          To initiate a send to the keyboard, the DATA line (P3.4 - an
          arbitrary I/O pin) is cleared by the code.  This is considered to
          be a start bit by the keyboard and it responds with a set of eleven
          clock pulses (within 15ms).  The data pin is then set or cleared
          on each pass through the KBDISR code depending on whether a 1 or
          a 0 is needed (LSB sent first).  After the eighth data bit is sent,
          a parity bit is calculated and sent and then a stop bit (logic high)
          is sent.  The keyboard pulls the data line low briefly after the
          stop bit is received to tell the code that the data was received
          properly.

     RECEIVE FROM KEYBOARD -
          Assuming that both the DATA and CLOCK lines are high, the keyboard
          is free to send data at any time.  The keyboard will pull the data
          line low (start bit) and then start a series of eleven clock pulses.
          The keyboard shifts out the eight data bits (one during each clock
          cycle) and then sends a parity bit and a stop bit.  Again, every
          falling edge of the clock equals one pass through the KBDISR.

     After receiving the stop bit, the code has the keyboard data stored in
     the variable "DATA_FROM_KBD".  This byte is immediately sent to the
     function "KEY_CODE_LOOP" which uses the table defined at the top of
     "DONGMAIN.ASM" to convert the keycode to its appropriate USB Usage Index
     value.  Then, if this is a key make code (not a break code), the byte
     is stored into the keyboard buffer area by calling the function
     "ADD_A_KEY".  If the data sent from the keyboard was F0 hex, the code
     simply sets the "BREAK_CODE_MODE" variable to one so that on the next
     pass through, the keycode will be sent to the "REMOVE_A_KEY" function.
     This is all happening with no concern for the status of the USB side
     of the code.  These buffered keys will simply be read by the USB host
     when it requests the data and what keys are down at that moment are
     what it will receive.

~~~~~~~~~~~~~~~
MOUSEISR.ASM
~~~~~~~~~~~~~~~
     This file receives data from the serial port and stores it in
     the mouse buffer.  This routine is called by the serial port interrupt
     whenever a byte of data has been received.  Unlike the keyboard ISR,
     this code simply has to read the stored byte out of the SBUF register.

     The "MOUSE_BUFFER_WOFFSETH" and "MOUSE_BUFFER_WOFFSETL" variables keep
     track of the offset from the start of the "MOUSE_BUFFER" where the first
     empty (or the oldest data) location is.  The new byte is stored there,
     and the write pointer word is incremented as is the MOUSE_DATA_COUNT
     word. Note that the "anl   WR10, #RINGWORDMASK" instruction simply sets
     the write offset back to zero after it has reached the end of the mouse
     buffer area.  The start of the mouse buffer is "org'd" at 00:1000 hex
     purposely to facilitate this rollover (any location ending in three
     zeros would work).  For example, as the code is setup here, "RINGWORDMASK"
     has the value 07FF hex (defined in "DONCONST.INC") and the buffer size
     is defined as 8000 hex.  When the write offset hits 8000, the "anl"
     instruction causes it to become zero again.  This is done in different
     areas throughtout the mouse buffer writing and reading routines.

     After that, an "INITIAL_REPORT_CHECK" is done.  This forces a call to
     the "MOUSE_REPORT_GENERATOR" routine if indeed this is the first report.
     This is done for the same reason the initial keyboard report was sent
     in the keyboard initialization - to arm the TXFIFO with data so the
     next IN-TOKEN will not get NACKED.  Notice that this check is only done
     if there are at least three bytes of data in the mouse buffer.  This is
     because of the nature of the mouse reports.  They always consist of three
     bytes and only three bytes.  If there are less than three bytes available,