view Documentation/input/atarikbd.txt @ 452:c7ed6fe5dca0

kexec: dont initialise regions in reserve_memory()

There is no need to initialise efi_memmap_res and boot_param_res in
reserve_memory() for the initial xen domain as it is done in
machine_kexec_setup_resources() using values from the kexec hypercall.

Signed-off-by: Simon Horman <horms@verge.net.au>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Feb 28 10:55:18 2008 +0000 (2008-02-28)
parents 831230e53067
line source
1 Intelligent Keyboard (ikbd) Protocol
4 1. Introduction
6 The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard
7 controller that is flexible enough that it can be used in a variety of
8 products without modification. The keyboard, with its microcontroller,
9 provides a convenient connection point for a mouse and switch-type joysticks.
10 The ikbd processor also maintains a time-of-day clock with one second
11 resolution.
12 The ikbd has been designed to be general enough that it can be used with a
13 ariety of new computer products. Product variations in a number of
14 keyswitches, mouse resolution, etc. can be accommodated.
15 The ikbd communicates with the main processor over a high speed bi-directional
16 serial interface. It can function in a variety of modes to facilitate
17 different applications of the keyboard, joysticks, or mouse. Limited use of
18 the controller is possible in applications in which only a unidirectional
19 communications medium is available by carefully designing the default modes.
21 3. Keyboard
23 The keyboard always returns key make/break scan codes. The ikbd generates
24 keyboard scan codes for each key press and release. The key scan make (key
25 closure) codes start at 1, and are defined in Appendix A. For example, the
26 ISO key position in the scan code table should exist even if no keyswitch
27 exists in that position on a particular keyboard. The break code for each key
28 is obtained by ORing 0x80 with the make code.
30 The special codes 0xF6 through 0xFF are reserved for use as follows:
31 0xF6 status report
32 0xF7 absolute mouse position record
33 0xF8-0xFB relative mouse position records(lsbs determind by
34 mouse button states)
35 0xFC time-of-day
36 0xFD joystick report (both sticks)
37 0xFE joystick 0 event
38 0xFF joystick 1 event
40 The two shift keys return different scan codes in this mode. The ENTER key
41 and the RETurn key are also distinct.
43 4. Mouse
45 The mouse port should be capable of supporting a mouse with resolution of
46 approximately 200 counts (phase changes or 'clicks') per inch of travel. The
47 mouse should be scanned at a rate that will permit accurate tracking at
48 velocities up to 10 inches per second.
49 The ikbd can report mouse motion in three distinctly different ways. It can
50 report relative motion, absolute motion in a coordinate system maintained
51 within the ikbd, or by converting mouse motion into keyboard cursor control
52 key equivalents.
53 The mouse buttons can be treated as part of the mouse or as additional
54 keyboard keys.
56 4.1 Relative Position Reporting
58 In relative position mode, the ikbd will return relative mouse position
59 records whenever a mouse event occurs. A mouse event consists of a mouse
60 button being pressed or released, or motion in either axis exceeding a
61 settable threshold of motion. Regardless of the threshold, all bits of
62 resolution are returned to the host computer.
63 Note that the ikbd may return mouse relative position reports with
64 significantly more than the threshold delta x or y. This may happen since no
65 relative mouse motion events will be generated: (a) while the keyboard has
66 been 'paused' ( the event will be stored until keyboard communications is
67 resumed) (b) while any event is being transmitted.
69 The relative mouse position record is a three byte record of the form
70 (regardless of keyboard mode):
71 %111110xy ; mouse position record flag
72 ; where y is the right button state
73 ; and x is the left button state
74 X ; delta x as twos complement integer
75 Y ; delta y as twos complement integer
77 Note that the value of the button state bits should be valid even if the
78 MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard.
79 If the accumulated motion before the report packet is generated exceeds the
80 +127...-128 range, the motion is broken into multiple packets.
81 Note that the sign of the delta y reported is a function of the Y origin
82 selected.
84 4.2 Absolute Position reporting
86 The ikbd can also maintain absolute mouse position. Commands exist for
87 reseting the mouse position, setting X/Y scaling, and interrogating the
88 current mouse position.
90 4.3 Mouse Cursor Key Mode
92 The ikbd can translate mouse motion into the equivalent cursor keystrokes.
93 The number of mouse clicks per keystroke is independently programmable in
94 each axis. The ikbd internally maintains mouse motion information to the
95 highest resolution available, and merely generates a pair of cursor key events
96 for each multiple of the scale factor.
97 Mouse motion produces the cursor key make code immediately followed by the
98 break code for the appropriate cursor key. The mouse buttons produce scan
99 codes above those normally assigned for the largest envisioned keyboard (i.e.
100 LEFT=0x74 & RIGHT=0x75).
102 5. Joystick
104 5.1 Joystick Event Reporting
106 In this mode, the ikbd generates a record whever the joystick position is
107 changed (i.e. for each opening or closing of a joystick switch or trigger).
109 The joystick event record is two bytes of the form:
110 %1111111x ; Joystick event marker
111 ; where x is Joystick 0 or 1
112 %x000yyyy ; where yyyy is the stick position
113 ; and x is the trigger
115 5.2 Joystick Interrogation
117 The current state of the joystick ports may be interrogated at any time in
118 this mode by sending an 'Interrogate Joystick' command to the ikbd.
120 The ikbd response to joystick interrogation is a three byte report of the form
121 0xFD ; joystick report header
122 %x000yyyy ; Joystick 0
123 %x000yyyy ; Joystick 1
124 ; where x is the trigger
125 ; and yyy is the stick position
127 5.3 Joystick Monitoring
129 A mode is available that devotes nearly all of the keyboard communications
130 time to reporting the state of the joystick ports at a user specifiable rate.
131 It remains in this mode until reset or commanded into another mode. The PAUSE
132 command in this mode not only stop the output but also temporarily stops
133 scanning the joysticks (samples are not queued).
135 5.4 Fire Button Monitoring
137 A mode is provided to permit monitoring a single input bit at a high rate. In
138 this mode the ikbd monitors the state of the Joystick 1 fire button at the
139 maximum rate permitted by the serial communication channel. The data is packed
140 8 bits per byte for transmission to the host. The ikbd remains in this mode
141 until reset or commanded into another mode. The PAUSE command in this mode not
142 only stops the output but also temporarily stops scanning the button (samples
143 are not queued).
145 5.5 Joystick Key Code Mode
147 The ikbd may be commanded to translate the use of either joystick into the
148 equivalent cursor control keystroke(s). The ikbd provides a single breakpoint
149 velocity joystick cursor.
150 Joystick events produce the make code, immediately followed by the break code
151 for the appropriate cursor motion keys. The trigger or fire buttons of the
152 joysticks produce pseudo key scan codes above those used by the largest key
153 matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75).
155 6. Time-of-Day Clock
157 The ikbd also maintains a time-of-day clock for the system. Commands are
158 available to set and interrogate the timer-of-day clock. Time-keeping is
159 maintained down to a resolution of one second.
161 7. Status Inquiries
163 The current state of ikbd modes and parameters may be found by sending status
164 inquiry commands that correspond to the ikbd set commands.
166 8. Power-Up Mode
168 The keyboard controller will perform a simple self-test on power-up to detect
169 major controller faults (ROM checksum and RAM test) and such things as stuck
170 keys. Any keys down at power-up are presumed to be stuck, and their BREAK
171 (sic) code is returned (which without the preceding MAKE code is a flag for a
172 keyboard error). If the controller self-test completes without error, the code
173 0xF0 is returned. (This code will be used to indicate the version/rlease of
174 the ikbd controller. The first release of the ikbd is version 0xF0, should
175 there be a second release it will be 0xF1, and so on.)
176 The ikbd defaults to a mouse position reporting with threshold of 1 unit in
177 either axis and the Y=0 origin at the top of the screen, and joystick event
178 reporting mode for joystick 1, with both buttons being logically assigned to
179 the mouse. After any joystick command, the ikbd assumes that joysticks are
180 connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE
181 DISABLE) then causes port 0 to again be scanned as if it were a mouse, and
182 both buttons are logically connected to it. If a mouse diable command is
183 received while port 0 is presumed to be a mouse, the button is logically
184 assigned to Joystick1 ( until the mouse is reenabled by another mouse command).
186 9. ikbd Command Set
188 This section contains a list of commands that can be sent to the ikbd. Command
189 codes (such as 0x00) which are not specified should perform no operation
190 (NOPs).
192 9.1 RESET
194 0x80
195 0x01
197 N.B. The RESET command is the only two byte command understood by the ikbd.
198 Any byte following an 0x80 command byte other than 0x01 is ignored (and causes
199 the 0x80 to be ignored).
200 A reset may also be caused by sending a break lasting at least 200mS to the
201 ikbd.
202 Executing the RESET command returns the keyboard to its default (power-up)
203 mode and parameter settings. It does not affect the time-of-day clock.
204 The RESET command or function causes the ikbd to perform a simple self-test.
205 If the test is successful, the ikbd will send the code of 0xF0 within 300mS
206 of receipt of the RESET command (or the end of the break, or power-up). The
207 ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found
208 closed will cause the break scan code to be generated (the break code arriving
209 without being preceded by the make code is a flag for a key matrix error).
213 0x07
214 %00000mss ; mouse button action
215 ; (m is presumed = 1 when in MOUSE KEYCODE mode)
216 ; mss=0xy, mouse button press or release causes mouse
217 ; position report
218 ; where y=1, mouse key press causes absolute report
219 ; and x=1, mouse key release causes absolute report
220 ; mss=100, mouse buttons act like keys
222 This command sets how the ikbd should treat the buttons on the mouse. The
223 default mouse button action mode is %00000000, the buttons are treated as part
224 of the mouse logically.
225 When buttons act like keys, LEFT=0x74 & RIGHT=0x75.
229 0x08
231 Set relative mouse position reporting. (DEFAULT) Mouse position packets are
232 generated asynchronously by the ikbd whenever motion exceeds the setable
233 threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse
234 key mode, mouse position reports may also be generated when either mouse
235 button is pressed or released. Otherwise the mouse buttons behave as if they
236 were keyboard keys.
240 0x09
241 XMSB ; X maximum (in scaled mouse clicks)
242 XLSB
243 YMSB ; Y maximum (in scaled mouse clicks)
244 YLSB
246 Set absolute mouse position maintenance. Resets the ikbd maintained X and Y
247 coordinates.
248 In this mode, the value of the internally maintained coordinates does NOT wrap
249 between 0 and large positive numbers. Excess motion below 0 is ignored. The
250 command sets the maximum positive value that can be attained in the scaled
251 coordinate system. Motion beyond that value is also ignored.
255 0x0A
256 deltax ; distance in X clicks to return (LEFT) or (RIGHT)
257 deltay ; distance in Y clicks to return (UP) or (DOWN)
259 Set mouse monitoring routines to return cursor motion keycodes instead of
260 either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate
261 cursor keycode after mouse travel exceeding the user specified deltas in
262 either axis. When the keyboard is in key scan code mode, mouse motion will
263 cause the make code immediately followed by the break code. Note that this
264 command is not affected by the mouse motion origin.
268 0x0B
269 X ; x threshold in mouse ticks (positive integers)
270 Y ; y threshold in mouse ticks (positive integers)
272 This command sets the threshold before a mouse event is generated. Note that
273 it does NOT affect the resolution of the data returned to the host. This
274 command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds
275 default to 1 at RESET (or power-up).
279 0x0C
280 X ; horizontal mouse ticks per internel X
281 Y ; vertical mouse ticks per internel Y
283 This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode.
284 In this mode, the specified number of mouse phase changes ('clicks') must
285 occur before the internally maintained coordinate is changed by one
286 (independently scaled for each axis). Remember that the mouse position
287 information is available only by interrogating the ikbd in the ABSOLUTE MOUSE
288 POSITIONING mode unless the ikbd has been commanded to report on button press
289 or release (see SET MOSE BUTTON ACTION).
293 0x0D
294 Returns:
295 0xF7 ; absolute mouse position header
297 0000dcba ; where a is right button down since last interrogation
298 ; b is right button up since last
299 ; c is left button down since last
300 ; d is left button up since last
301 XMSB ; X coordinate
302 XLSB
303 YMSB ; Y coordinate
304 YLSB
306 The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE
307 POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
311 0x0E
312 0x00 ; filler
313 XMSB ; X coordinate
314 XLSB ; (in scaled coordinate system)
315 YMSB ; Y coordinate
316 YLSB
318 This command allows the user to preset the internally maintained absolute
319 mouse position.
321 9.10 SET Y=0 AT BOTTOM
323 0x0F
325 This command makes the origin of the Y axis to be at the bottom of the
326 logical coordinate system internel to the ikbd for all relative or absolute
327 mouse motion. This causes mouse motion toward the user to be negative in sign
328 and away from the user to be positive.
330 9.11 SET Y=0 AT TOP
332 0x10
334 Makes the origin of the Y axis to be at the top of the logical coordinate
335 system within the ikbd for all relative or absolute mouse motion. (DEFAULT)
336 This causes mouse motion toward the user to be positive in sign and away from
337 the user to be negative.
339 9.12 RESUME
341 0x11
343 Resume sending data to the host. Since any command received by the ikbd after
344 its output has been paused also causes an implicit RESUME this command can be
345 thought of as a NO OPERATION command. If this command is received by the ikbd
346 and it is not PAUSED, it is simply ignored.
350 0x12
352 All mouse event reporting is disabled (and scanning may be internally
353 disabled). Any valid mouse mode command resumes mouse motion monitoring. (The
354 valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET
356 N.B. If the mouse buttons have been commanded to act like keyboard keys, this
357 command DOES affect their actions.
361 0x13
363 Stop sending data to the host until another valid command is received. Key
364 matrix activity is still monitored and scan codes or ASCII characters enqueued
365 (up to the maximum supported by the microcontroller) to be sent when the host
366 allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode,
367 joystick events are also queued.
368 Mouse motion should be accumulated while the output is paused. If the ikbd is
369 in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the
370 normal threshold limits to produce the minimum number of packets necessary for
371 transmission when output is resumed. Pressing or releasing either mouse button
372 causes any accumulated motion to be immediately queued as packets, if the
374 Because of the limitations of the microcontroller memory this command should
375 be used sparingly, and the output should not be shut of for more than <tbd>
376 milliseconds at a time.
377 The output is stopped only at the end of the current 'even'. If the PAUSE
378 OUTPUT command is received in the middle of a multiple byte report, the packet
379 will still be transmitted to conclusion and then the PAUSE will take effect.
380 When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON
381 MONITORING mode, the PAUSE OUTPUT command also temporarily stops the
382 monitoring process (i.e. the samples are not enqueued for transmission).
386 0x14
388 Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a
389 joystick switch or trigger causes a joystick event record to be generated.
393 0x15
395 Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK
396 INTERROGATE commands to sense joystick state.
400 0x16
402 Return a record indicating the current state of the joysticks. This command
403 is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK
408 0x17
409 rate ; time between samples in hundreths of a second
410 Returns: (in packets of two as long as in mode)
411 %000000xy ; where y is JOYSTICK1 Fire button
412 ; and x is JOYSTICK0 Fire button
413 %nnnnmmmm ; where m is JOYSTICK1 state
414 ; and n is JOYSTICK0 state
416 Sets the ikbd to do nothing but monitor the serial command lne, maintain the
417 time-of-day clock, and monitor the joystick. The rate sets the interval
418 between joystick samples.
419 N.B. The user should not set the rate higher than the serial communications
420 channel will allow the 2 bytes packets to be transmitted.
424 0x18
425 Returns: (as long as in mode)
426 %bbbbbbbb ; state of the JOYSTICK1 fire button packed
427 ; 8 bits per byte, the first sample if the MSB
429 Set the ikbd to do nothing but monitor the serial command line, maintain the
430 time-of-day clock, and monitor the fire button on Joystick 1. The fire button
431 is scanned at a rate that causes 8 samples to be made in the time it takes for
432 the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate).
433 The sample interval should be as constant as possible.
437 0x19
438 RX ; length of time (in tenths of seconds) until
439 ; horizontal velocity breakpoint is reached
440 RY ; length of time (in tenths of seconds) until
441 ; vertical velocity breakpoint is reached
442 TX ; length (in tenths of seconds) of joystick closure
443 ; until horizontal cursor key is generated before RX
444 ; has elapsed
445 TY ; length (in tenths of seconds) of joystick closure
446 ; until vertical cursor key is generated before RY
447 ; has elapsed
448 VX ; length (in tenths of seconds) of joystick closure
449 ; until horizontal cursor keystokes are generated
450 ; after RX has elapsed
451 VY ; length (in tenths of seconds) of joystick closure
452 ; until vertical cursor keystokes are generated
453 ; after RY has elapsed
455 In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes.
456 On initial closure, a keystroke pair (make/break) is generated. Then up to Rn
457 tenths of seconds later, keystroke pairs are generated every Tn tenths of
458 seconds. After the Rn breakpoint is reached, keystroke pairs are generated
459 every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint
460 feature.
461 Note that by setting RX and/or Ry to zero, the velocity feature can be
462 disabled. The values of TX and TY then become meaningless, and the generation
463 of cursor 'keystrokes' is set by VX and VY.
467 0x1A
469 Disable the generation of any joystick events (and scanning may be internally
470 disabled). Any valid joystick mode command resumes joystick monitoring. (The
471 joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK
477 0x1B
478 YY ; year (2 least significant digits)
479 MM ; month
480 DD ; day
481 hh ; hour
482 mm ; minute
483 ss ; second
485 All time-of-day data should be sent to the ikbd in packed BCD format.
486 Any digit that is not a valid BCD digit should be treated as a 'don't care'
487 and not alter that particular field of the date or time. This permits setting
488 only some subfields of the time-of-day clock.
492 0x1C
493 Returns:
494 0xFC ; time-of-day event header
495 YY ; year (2 least significant digits)
496 MM ; month
497 DD ; day
498 hh ; hour
499 mm ; minute
500 ss ; second
502 All time-of-day is sent in packed BCD format.
504 9.24 MEMORY LOAD
506 0x20
507 ADRMSB ; address in controller
508 ADRLSB ; memory to be loaded
509 NUM ; number of bytes (0-128)
510 { data }
512 This command permits the host to load arbitrary values into the ikbd
513 controller memory. The time between data bytes must be less than 20ms.
515 9.25 MEMORY READ
517 0x21
518 ADRMSB ; address in controller
519 ADRLSB ; memory to be read
520 Returns:
521 0xF6 ; status header
522 0x20 ; memory access
523 { data } ; 6 data bytes starting at ADR
525 This comand permits the host to read from the ikbd controller memory.
529 0x22
530 ADRMSB ; address of subroutine in
531 ADRLSB ; controller memory to be called
533 This command allows the host to command the execution of a subroutine in the
534 ikbd controller memory.
538 Status commands are formed by inclusively ORing 0x80 with the
539 relevant SET command.
541 Example:
542 0x88 (or 0x89 or 0x8A) ; request mouse mode
543 Returns:
544 0xF6 ; status response header
545 mode ; 0x08 is RELATIVE
546 ; 0x09 is ABSOLUTE
547 ; 0x0A is KEYCODE
548 param1 ; 0 is RELATIVE
549 ; XMSB maximum if ABSOLUTE
551 param2 ; 0 is RELATIVE
552 ; YMSB maximum if ABSOLUTE
554 param3 ; 0 if RELATIVE
555 ; or KEYCODE
557 param4 ; 0 if RELATIVE
558 ; or KEYCODE
560 0 ; pad
561 0
563 The STATUS INQUIRY commands request the ikbd to return either the current mode
564 or the parameters associated with a given command. All status reports are
565 padded to form 8 byte long return packets. The responses to the status
566 requests are designed so that the host may store them away (after stripping
567 off the status report header byte) and later send them back as commands to
568 ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the
569 ikbd.
571 Valid STATUS INQUIRY commands are:
573 0x87 mouse button action
574 0x88 mouse mode
575 0x89
576 0x8A
577 0x8B mnouse threshold
578 0x8C mouse scale
579 0x8F mouse vertical coordinates
580 0x90 ( returns 0x0F Y=0 at bottom
581 0x10 Y=0 at top )
582 0x92 mouse enable/disable
583 ( returns 0x00 enabled)
584 0x12 disabled )
585 0x94 joystick mode
586 0x95
587 0x96
588 0x9A joystick enable/disable
589 ( returns 0x00 enabled
590 0x1A disabled )
592 It is the (host) programmer's responsibility to have only one unanswered
593 inquiry in process at a time.
594 STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING
595 mode or FIRE BUTTON MONITORING mode.
598 10. SCAN CODES
600 The key scan codes return by the ikbd are chosen to simplify the
601 implementaion of GSX.
603 GSX Standard Keyboard Mapping.
605 Hex Keytop
606 01 Esc
607 02 1
608 03 2
609 04 3
610 05 4
611 06 5
612 07 6
613 08 7
614 09 8
615 0A 9
616 0B 0
617 0C -
618 0D ==
619 0E BS
620 0F TAB
621 10 Q
622 11 W
623 12 E
624 13 R
625 14 T
626 15 Y
627 16 U
628 17 I
629 18 O
630 19 P
631 1A [
632 1B ]
633 1C RET
634 1D CTRL
635 1E A
636 1F S
637 20 D
638 21 F
639 22 G
640 23 H
641 24 J
642 25 K
643 26 L
644 27 ;
645 28 '
646 29 `
648 2B \
649 2C Z
650 2D X
651 2E C
652 2F V
653 30 B
654 31 N
655 32 M
656 33 ,
657 34 .
658 35 /
659 36 (RIGHT) SHIFT
660 37 { NOT USED }
661 38 ALT
662 39 SPACE BAR
664 3B F1
665 3C F2
666 3D F3
667 3E F4
668 3F F5
669 40 F6
670 41 F7
671 42 F8
672 43 F9
673 44 F10
674 45 { NOT USED }
675 46 { NOT USED }
676 47 HOME
677 48 UP ARROW
678 49 { NOT USED }
679 4A KEYPAD -
681 4C { NOT USED }
683 4E KEYPAD +
684 4F { NOT USED }
686 51 { NOT USED }
687 52 INSERT
688 53 DEL
689 54 { NOT USED }
690 5F { NOT USED }
691 60 ISO KEY
692 61 UNDO
693 62 HELP
694 63 KEYPAD (
695 64 KEYPAD /
696 65 KEYPAD *
697 66 KEYPAD *
698 67 KEYPAD 7
699 68 KEYPAD 8
700 69 KEYPAD 9
701 6A KEYPAD 4
702 6B KEYPAD 5
703 6C KEYPAD 6
704 6D KEYPAD 1
705 6E KEYPAD 2
706 6F KEYPAD 3
707 70 KEYPAD 0
708 71 KEYPAD .