*************************************************************************************
README.TXT:  Application notes for the Cypress Keyboard Demonstration Firmware



This file contains some useful information regarding the organization of the
keyboard code contained in this distribution.




1. CODE ORGANIZATION

The code is broken down into modules which are "included" together during assembly
to form a single executable.  You may build one of four variants  by assembling one
of the following files:

usb.asm:                builds a usb interface keyboard
ps2.asm:                builds a ps2 interface keyboard
usbps2.asm:             builds a usb/ps2 dual-interface keyboard
usbsm.asm:            builds a usb with slave mouse keyboard
usbsmps2.asm:           builds a usb with slave mouse/ps2 dual-interface keyboard.

Each of the above files contains include statements which control the assembling of
the necessary files to produce the variant executable.  The *.hex and *.rom files
which are produced by the assembler will have the same file name as the files above.
For instance if you were to assemble usbps2.asm, the resulting executable files would
be usbps2.hex and usbps2.rom.

Both dual-interface variants produce absolute code size which is greater than 4k 
in length. Due to the restrictions on code 
organization placed by the processor (namely, the restriction that code running 
in the upper 4k of memory cannot call a subroutine in the lower 4k), the primary
processing code for both USB and PS2 reside in the lower 4k of memory.  All shareable
and utility functions which may be called by either or both of these entities resides
in the upper 4k.  This would include the generic keyboard scanning routines, timing and delay
loops, the code which auto-detects which keyboard interface is connected, and
the USB and PS2-specific keyboard modules which receive key presses from the generic
keyboard scanning routine and converts them to the proper format (for PS2, this includes
the generation of scan codes for sets 1-3, the typematic key function, and the implementation
of a keyboard scan code fifo buffer; for USB, the usage table scan set and
the implementation and maintenance of the USB key packet buffer).  Thus, all code
in the upper 4k consists of functions which are called from code running in the lower
4k.  As such, there is free space for additional code development in both the
upper and lower 4k regions of code space.  See the listing file for the details of code usage.


A brief summary of the contents of each module is as follows:

usb.asm: contains the interrupt vector table, 1msec ISR and startup code for a 
usb interface keyboard. 

ps2.asm: contains the interrupt vector table, 1msec ISR and startup code for a 
ps2 interface keyboard. 

usbps2.asm: contains the interrupt vector table, 1msec ISR and startup code for a 
usb/ps2 dual-interface keyboard. 

usbsm.asm: contains the interrupt vector table, 1msec ISR and startup code for a 
usb with slave mouse keyboard. 

usbsmps2.asm: contains the interrupt vector table, 1msec ISR and startup code for a 
usb with slave mouse/ps2 dual-interface keyboard. 

usbmain.asm: contains the implementation of the USB w/slave ps2 mouse interface. 
This includes usb packet reception/transmission, suspend/resume functions, ISR routines,etc.


ps2main.asm: contains the implementation of the PS2 interface with the host. This
is entirely analagous to usbmain.asm.

ps2_io.asm: contains the implementation of the low-level PS2 clock/data interface.

usbdesc.asm: contains the usb descriptors for a usb keyboard. 

kbm_desc.asm: same as usbdesc.asm but contains descriptors for a usb with slave mouse
keyboard.

usbkey.asm: contains the USB-specific keyboard scanning functions.

ps2key.asm: contains the PS2-specific keyboard scanning functions.

keyscan.asm: contains the generic keyboard scanning functions.

util.asm:  contains the time-delay subroutine and the keyboard autodetection routine.

matrix.asm: contains the keyboard matrix lookup.

regs.inc: contains processor register definitions

usb.inc: contains equates for the USB implementation

ps2.inc: contains equates for the PS2 implementation

macros.inc: contains macro definitions

at101.inc: contains definitions for a standard 101-key keyboard

kb_mouse.asm,kbm_cmd.asm,kbm_util.asm,kbm_defs.asm kbm_task.asm : slave ps2 mouse functions.

*************************************************************************************


2. RAM USAGE

For both the dual-interface variants,
ram is "overlaid" for the USB and PS2 implementations; that is, common RAM locations are
used by the portions of USB and PS2 code that never run simultaneously. There is a
restriction on data memory usage in USB mode which was pointed out in the following
revision note for the USB code:
 
;========================================================================
; 12/08/97      nxk             Chip bug workaround
; Some data RAM addresses cannot be written to while the SETUP pid bit
; is set in the EP0 mode register.  These are:
; 70h - 7Fh, F0h - F7h in the CY3651
; E0h - E7h in the CY7C634/635xx
; Only F8h - FFh (end point 0 FIFO) is supposed to be locked out.
; This problem caused the Ch. 9 tests to fail after a large number
; of iterations in continuous loop mode.
; The firmware has been changed to avoid use of these locations.
; - data stack begins at address E0h rather than E8h
; - data memory variables no longer use addresses from 70h - 7Fh so that
;   the code will run on both the development board and chip.
;========================================================================


The dual-interface implementation adheres to this restriction. To do so, RAM is divided
into the following regions:


For USB:
00h-2fh:  program stack

30h-6fh:  data memory (currently used by usbmain) 

80h-xxh:  data memory (currently used by keyscan,usbkey, and slave mouse functions)

xxh-e0h:  data stack


For PS2:
00h-2fh:  program stack

30h-7fh:  data memory (currently used by ps2main) 

80h-xxh:  data memory (currently used by keyscan,ps2key)

xxh-ffh:  data stack


The 80h boundary avoids  the use of the data region 70h-7fh
in  USB interface variants. If RAM variables are added to any of the modules, the
listing file must be examined to insure that none of the RAM regions exceed the
region boundaries outlined above.  Note that all variants produce in the listing
file a series of labels in the cross-reference, beginning with the prefix "AA", 
which display RAM usage information for that executable. This allows RAM
RAM consumption to be examined at a glance.


*************************************************************************************


3. AUTODETECTION

Upon power-up, dual-interface firmware attempts to identify the host interface (PS2 or USB) 
to which it is attached.  It does this using the following algorithm:

Connect Bit is driven low.
Both D+ and D- are set to high-Z;

Wait 10 ms;

Poll D+ and D- for 1ms, sampling approximately every 2 us. If either or both D+
and D- are sampled high (1) for 4 consecutive samples, the interface is PS2.


ELSE:

Connect bit is driven high.

Delay 10 usec.

Poll D+ and D- for 50msec.  If D+ remains low (0) and D- remains high (1) for
50msec, the interface is USB.

ELSE:



Connect bit is driven low.
Interface is PS2.


The code which implements this algorithm can be found in util.asm.