Chapter 2
Application Program Interface

This chapter covers information on how applications programs may make use of the Poqet Extended BIOS calls in order to monitor and control internal Poqet functions. It also gives details on how to use the clock device driver and how to call PQXT interrupts from high level languages.

Poqet Extended BIOS Calls

General Description

A large number of Poqet-specific services are available to you as a developer to ease program development and to utilize the unique features of the PQXT. These services may be accessed through a software interrupt interface that uses INTERRUPT 66H (INT66H). INT66H is a reserved interrupt that is used to differentiate applications written specifically for Poqet and provides extended BIOS services that allow you to directly read, control, or manipulate Poqet functions.

Services are grouped into classes of functions. You must place the function number in the 8OC88 AH register, and the service number in the AL register. You then invoke INT66 to perform the desired function and service. The description of the functions and services in this chapter make use of the terms entry and exit. These terms are used to describe the required contents of registers on entering an extended BIOS call, and the resulting state of the carry flag and register contents on exiting the call.

In general, the carry flag is set for an error condition. Detailed descriptions of the state of the carry flag and the register contents are given for each function and service.

The following functions and services are available:

Function 02H - Hardware Control

Service 02H - Get Current Video Controller

Use this service to determine which video controller is available. The Poqet contains circuitry that allows the use of a CGA or MDA compatible display controller. Applications have access to only one controller at a time. The other controller is disabled and will not respond.
        Poqet BIOS:     All
        Entry:          ah Function number (02H)
                        al Service number (02H)

        Exit:           bl Display type
                           00H MDA compatible
                           01H CGA compatible

Service 03H - Get Current Video Controller

Use this service to change the video hardware to either MDA or CGA compatible. Applications have access to only one controller at a time. The other controller is disabled and will not respond.
        Poqet BIOS:     All
        Entry:          ah Function number (02H)
                        al Service number (03H)
                        bl Display type
                           00H MDA compatible
                           01H CGA compatible

        Exit:           CF Carry flag set on error
                        ax Error code if CF is set; otherwise undefined
                           -3 Parameter error

Service 05H - Power Management Control

Use this service to control or interrogate the mode of the power management software. The power management software is invoked by means of a non-maskable interrupt (NMI) that is generated at a regular timed interval. When the NMI occurs, the power management software executes and provides the functions described in the following paragraphs. Modes 00H, 01H, 02H, and 03H are used for the following purposes: Modes 80H, 81H, 82H, and 83H perform the same functions as the above four services, except that the system is held at a reduced voltage in order to reduce power consumption. These modes are available only on the PQ0181 or higher models.
        Poqet BIOS:   All.  New modes have been added and some have
                      slight changes depending on the BIOS version number.

        Entry:        ah Function number (02H)
                      al Service number (05H)
                      dl Mode
                         00H The power management software is disabled and
                             the system is left at the full voltage level
                             of +5 volts.  At this voltage level, the
                             processor and other circuitry in the PQXT runs
                             at maximum frequency and maximum power
                             consumption.  Beginning with BIOS 1.30, the
                             power management NMI is still enabled.  Int
                             16H, which is the keyboard interrupt, is no
                             longer trapped by the PQXT.

                         01H If the BIOS detects that the system is idle,
                             it causes the PQXT to enter display mode.  In
                             this mode, the CPU clock stops, then restarts
                             to process timer ticks and keystrokes.  The
                             BIOS is free to adjust the system voltage to
                             balance power consumption and performance.

                         02H This is the default power management mode on
                             boot-up.  The BIOS functions as in mode 1,
                             but after being in display mode for
                             approximately four minutes, the system turns
                             off.  The display is shut down, the RS-232-C
                             drivers are disabled, the baud clock is turned
                             off, and keyboard interrupts are disabled.
                             System RAM and video RAM are preserved and the
                             time of day counter is maintained.  The system
                             may be turned back on using the I/O key or by
                             means of a program interface.

                         03H This mode was added in BIOS 1.30.  The power
                             management software is disabled, the system is
                             placed at full voltage, and the power management
                             NMI is removed.  This mode is used to enhance
                             operation of communications programs.  It is
                             automatically selected when the system is in
                             mode 0 and the RS-232-C drivers are enabled.

                         80H Same as mode 00H, except the system is held at
                             a reduced voltage of 3 volts to reduce power
                             consumption.  The system voltage changes to full
                             voltage when accessing memory cards, but returns
                             to the reduced voltage state afterwards.  This
                             mode is known as the communications mode.  The
                             processor operates at reduced speed, so be
                             aware that when running the serial port at
                             high speeds, the processor may not be able to
                             keep up.  Mode 80H is available on BIOS 1.30.

                         81H Same as mode 01H, except the system is held
                             at a reduced voltage of 3 volts to reduce power
                             consumption.  The system voltage changes to full
                             voltage when accessing memory cards, but returns
                             to the reduced voltage state afterwards. Mode
                             80H is available on BIOS 1.30.

                         82H Same as mode 02H, except the system is held at
                             a reduced voltage of 3 volts to reduce power
                             consumption. The system voltage changes to full
                             voltage when accessing memory cards, but
                             returns to the reduced voltage state afterwards.
                             Mode 82H is selected automatically by the BIOS
                             if the system is operating in mode 02H and
                             system voltage is constantly at 5 volts for
                             more than one minute. Mode 82H is available
                             on BIOS 1.30.

                         83H The power management software is disabled and
                             the power management NMI is removed. The system
                             is initially placed in a reduced voltage state.
                             Your application must take care in using this
                             mode, since an access to a memory card will
                             effectively turn this mode into mode 03H.
                             Mode 03H results because the power management
                             NMI is disabled and there is no way to return
                             the system to the reduced voltage state of 3
                             volts automatically. Made 83H is available on
                             BIOS 1.30.

                         FFH Use this parameter to get the currently used
                             mode.

        Exit:         CF Carry flag set on error.
                         Register dl is undefined if this is set.
                      ax Error code if CF was set; otherwise undefined.
                         -3 Parameter error
                      dl Current power management mode. Undefined on error.

Service 06H - RS-232-C Driver Control

Use this service to control the state of the RS-232-C drivers. Normally, the drivers are automatically enabled when a program accesses the Universal Asynchronous Receiver/Transmitter (UART). Use this service to make sure the RS-232-C drivers are enabled and to disable them once your application has completed using them. The drivers are activated by turning on a voltage level converter that boosts the normal battery voltage to positive and negative voltage levels that are RS-232-C-compatible.
        Poqet BIOS:   All
        Entry:        ah Function number (02H)
                      al Service number (06H)
                      dl Desired state
                         00H Enable RS-232-C drivers
                         01H Disable RS-232-C drivers

        Exit:         CF Carry flag set on error
                      ax Error code if CF is set; otherwise undefined
                         -3 Parameter error

Service 07H - Wake System From 'Off Mode'

This service is normally used to turn the system on if it is turned off. Beginning with BIOS 1.30, you may use this service to cause power management to exit display mode and allow normal processing. Call this service from within a routine that handles INT 08H or INT 1CH.
        Poqet BIOS:   Version 1.30 and above.
        Entry:        ah Function number (02H)
                      al Service number (07H)

        Exit:         Nothing returned

Service 08H - Power Management Status

Use this service to find out if the system is asleep and/or turned off. Your application can then decide on the appropriate action.
        Poqet BIOS:   All
        Entry:        ah Function number (02H)
                      al Service number (08H)

        Exit:         dl The system status is returned as a bit pattern.
                         Bits not specifically assigned are undefined and
                         are shown as X.

                      Bit Position     |  Meaning
                      -----------------+--------------
                      7 6 5 4 3 2 1 0  |
                      X 1 X X X X X X  |  System asleep
                      X X X X X X X 1  |  System Off

Service 0CH - User Idle

Use this service to cause the system to go idle if power management is enabled. An immediate return results if power management is disabled. Once the system is idle, control does not return to your application until after a key has been pressed, the UART has been accessed, or the system has been awakened by means of a software call.
        Poqet BIOS:   Version 1.30 and above
        Entry:        ah Function number (02H)
                      al Service number (0CH)

        Exit:         Nothing returned

Service 0DH - User Active

Use this service to indicate that the system is still busy. It is intended to be used by your application to bring the system back from idle, since your application may periodically cause power management to idle the system. Once this service is invoked, it has no effect on User Idle (Service OCH). However, the User Active service cannot keep the system active if the user issues a standard GetKey (Interrupt 16 service 0).
        Poqet BIOS:   Version 1.30 and above
        Entry:        ah Function number (02H)
                      al Service number (ODH)

        Exit:         Nothing returned

Function 07H - Keyboard Control

Service 00H - Get Keyboard Rate

This service allows your application to set the rate at which held keys will repeat and the delay until the first repeat starts after the key is pressed and held.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (OOH)
                      dl Bits 2 and 3 give the repeat rate:

                      Bit Position       Repeat Rate
                      --------------------------------
                      7 6 5 4 3 2 1 0
                      --------------------------------
                      x x x x 0 0 x x    281 ms
                      x x x x 0 1 x x    187 ms
                      x x x x 1 0 x x     93 ms
                      x x x x 1 1 x x     47 ms

                      Bits 0 and 1 give the delay until the first repeat:

                      Bit Position       Repeat Rate
                      --------------------------------
                      7 6 5 4 3 2 1 0
                      --------------------------------
                      x x x x x x 0 0    625 ms
                      x x x x x x 0 1    500 ms
                      x x x x x x 1 0    375 ms
                      x x x x x x 1 1    281 ms

        Exit:         Nothing returned

Service 01H - Get Keyboard Rate

This service allows your application to determine the current settings for keyboard repeat rate and delay until first repeat.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (01H)

        Exit:         dl Bits 2 and 3 give the repeat rate:
                      Bit Position	Repeat Rate

                      Bit Position       Repeat Rate
                      --------------------------------
                      7 6 5 4 3 2 1 0
                      --------------------------------
                      x x x x 0 0 x x    281 ms
                      x x x x 0 1 x x    187 ms
                      x x x x 1 0 x x     93 ms
                      x x x x 1 1 x x     47 ms

                      Bits 0 and 1 give the delay until the first repeat:

                      Bit Position       Repeat Rate
                      --------------------------------
                      7 6 5 4 3 2 1 0
                      --------------------------------
                      x x x x x x 0 0    625 ms
                      x x x x x x 0 1    500 ms
                      x x x x x x 1 0    375 ms
                      x x x x x x 1 1    281 ms

Service 02H - Get Keyboard Click

This service allows your application to turn the keyboard click on or off.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (02H)
                      bl Desired state
                         00H Turn click off
                         01H Turn click on

        Exit:         CF Carry flag set on error
                      ax Error code if CF set; otherwise undefined
                         -3 Parameter error

Service 03H - Get Keyboard Click State

This service allows your application to interrogate the state of the keyboard click.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (03H)

        Exit:         bl Click state
                         00H Keyboard click off
                         01H Keyboard click on

Service 04H - Get Poqet Extended Key Status

This service allows your application to determine the state of the special Poqet key, since this particular key does not generate a scan code like the other keys. This service also allows your application to determine if a user has enabled alarms via the keyboard.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (04H)
        Exit:         al Key status. Bits shown as "x" are undefined.

                      Bit Position	    Meaning
                      ---------------------------------------------------
                      7 6 5 4 3 2 1 0
                      ---------------------------------------------------
                      x x x x x 0 x x     Poqet key is currently pressed
                      x x x x 1 x x x     Alarms are enabled

Service 06H - Power Management Key Combination Control

This service allows your application to determine if the Poqet-F4 key combination is allowed to change the power management mode.
        Poqet BIOS:   All
        Entry:        ah Function number (07H)
                      al Service number (06H)
                      bl Key status
                         00H Disable Poqet-F4 key combination
                         01H Enable Poqet-F4 key combination. Current BIOS
                             allows any nonzero value to enable the function;
                             however, 01H should be used to ensure upward
                             compatibility.

        Exit:         Nothing returned

Service 06H - Software Keyboard Debounce Time

This service allows your application to set or interrogate the amount of time in milliseconds for debouncing the keyboard. Normally, this time should be set to zero, since thehardware has some built-in debounce. This service is intended for use with abused or very old keyboards that are exhibiting extreme bounce.
	Poqet BIOS:   Version 1.30 and above

        Entry:        ah Function number (07H)
                      al Service number (07H)
                      dl Debounce time in milliseconds.  The time is
                         rounded down to the nearest 2 milliseconds
                         before being used.  The maximum debounce time
                         allowed is 20 milliseconds.

                         00H-01H Disable software debounce
                         02H-l4H Debounce time in milliseconds
                         15H-FEH Illegal
                         FFH     Return current debounce setting

        Exit:         CF Carry flag set on error
                      ax Error code if CF set
                      al Current debounce time.  This register is part of
                         the error code if CF is set.

Function 30H - Version Number

Service 04H - PQBIOS Version Number

This service returns the major and minor versions of the BIOS. For example, in BIOS Vl.30, the major version number is 1, and the minor version number is 30. This service returns the version numbers to the caller in binary.
        Poqet BIOS:   All
        Entry:        ah Function number (30H)
                      al Service number (04H)

        Exit:         al Major version number in binary
                      ah Minor version number in binary

Copyright (c) 1989, 1990, 1991, 1992 Poqet Computer Corporation. All rights reserved.
Filename: PoqetPC/docs/poqetpc/techref/chapter2.html
Date Created: 7 Feb 96, Last Modified: 13 Feb 96
Created by Bryan Mason - E-Mail: poqetpc<at>bmason<dot>com