HFT(4,F) AIX Technical Reference HFT(4,F)
-------------------------------------------------------------------------------
hft
PURPOSE
Implements a high-function virtual terminal device.
SYNOPSIS
#include <sys/hft.h>
INTRODUCTION
The hft device driver allows one or more virtual terminals to be opened and
used by application processes. The hft device driver is unique to AIX PS/2.
Only one of these virtual terminals can be active at any given time; any others
are hidden from view. The operator uses keyboard "hot key" sequences to switch
between the active and inactive ones. There is an AIX command called open to
create new virtual terminals from the keyboard.
Each of the virtual terminals can be set to specific terminal characteristics.
There are AIX commands such as display, keyboard, locator, sound, and stty
which can be used to adjust these characteristics.
This section describes the programmer's interface to hft. This interface was
used by IBM to program the AIX commands mentioned above, and is also available
for you to use in your application programs.
GETTING STARTED
The /usr/lib/samples directory contains several README files that describe more
information of interest to the programmer. There is also a
/usr/lib/samples/hft directory which contains many example programs which show
how to program the various hft functions. These examples often serve as a good
starting point for constructing your own programs. If you are not familiar
with hft, then you should first read the Concepts below, then proceed by trying
one or more of the example programs. You should also print out a copy of
/usr/include/sys/hft.h which will help in understanding the structures
described in this section.
CONCEPTS
The virtual terminal concept supports the illusion that more devices exist than
are physically present and that these virtual devices have characteristics and
features not necessarily limited by the actual physical devices. In addition
to displays and keyboards, virtual terminals support locators and sound
generators. Virtual terminals are logically independent of each other but
share physical resources over time. Each virtual terminal embodies the
characteristics of a single keyboard send/receive terminal. That is, it
recognizes and processes the data stream received from the process causing the
Processed November 8, 1990 HFT(4,F) 1
HFT(4,F) AIX Technical Reference HFT(4,F)
requested actions to occur, for example, move the cursor, or draw characters
onto the virtual display, or change the attributes of characters. In addition
to these actions, the outbound data stream can cause the generation of
sequences of continuous tone sounds or cause the virtual display to be rendered
on any of the available physical displays.
A virtual terminal receives input from a virtual keyboard and/or a virtual
locator; it outputs to a virtual display. Thus the virtual terminal can always
expect to get input from its virtual input devices and can always output to its
virtual display. Since physical devices are shared between virtual terminals,
there will be times when a process desires to read or write and the physical
device is allocated to another virtual terminal. In these cases the process is
blocked until the device becomes allocated. The virtual terminal that can
accept physical input or modify the physical screen at a given time is called
the active virtual terminal. Processes are never blocked for write if they are
sending a data stream in KSR mode. The inactive virtual terminal accepts the
data stream and outputs it to a presentation space. This presentation space
will be rendered on the physical display when the virtual terminal becomes
active.
There is a Screen Manager which performs the allocation of physical devices to
virtual terminals over time. The Screen Manager implements a ring of virtual
terminals in which one virtual terminal is active and the others are inactive.
There are keyboard "hot key" sequences to control switching between the active
and inactive virtual terminals. The Screen Manager allocates needed physical
devices to the virtual devices of the active virtual terminal. The Screen
Manager also allows the switching of virtual terminals to occur under program
control.
There is a Resource Manager that allows global changes to be made to the
default characteristics of new virtual terminals. For instance, it is possible
to redefine the default display so that subsequent opens of the hft device will
have different characteristics.
Each virtual terminal provides a model of a single terminal that can be in one
of the following modes at a given time:
o Keyboard Send-Receive Mode (KSR)
o Monitor Mode (MOM).
The KSR mode emulates an ASCII terminal using a data stream, which is described
in detail in "data stream." The monitor mode allows applications to have a
direct output path to the display hardware and shortened path for keyboard and
locator. The form of the data accepted in each mode is unique to that mode.
This optimizes the movement of data between the virtual terminal and the
application program and supports the different functions within each mode. The
default mode is KSR, which supports existing applications expecting an ASCII
terminal.
Additional functions supported include:
Processed November 8, 1990 HFT(4,F) 2
HFT(4,F) AIX Technical Reference HFT(4,F)
o Reporting data from input devices such as locators (mice)
o Switching between interactive and noninteractive states
o Changing color palette settings
o Controlling the sound hardware
o Switching between the monitor mode and KSR mode.
The virtual terminal supplies default values for keyboard-to-character mapping,
character-to-display mapping, echo/break specification, tab rack, and protocol
mode flags to be used until a definition is received from the application.
This hft facility is the kernel-level support for virtual terminals. Since the
association of virtual terminals to physical terminals is dynamic, this special
file, which represents the physical terminal, is multiplexed across virtual
terminals by expanding the open, close, read, write, and especially the ioctl
system calls to the driver. This type of driver is specified by the M flag in
the master file. Many extra ioctl system calls are provided to allow access to
advanced features of the hft facility. The facilities described in "termio"
also apply to the virtual terminal.
The first (or only) hft is minor device 0, and special file /dev/hft is
associated with it. The special file /dev/console is minor device 1.
Each time /dev/hft is opened, a new hft virtual terminal is created and opened.
A maximum of 16 virtual terminals can be opened due to limits on system
resources. Each hft virtual terminal is given both a channel number and an I/O
device number (IODN). You use the channel number if you wish to reopen an
already existing virtual terminal. You use the IODN as part of certain hft
ioctl operations, such as controlling the screen manager. The IODN specifies
upon which virtual terminal to operate.
To reopen an existing virtual terminal, open the special file /dev/hft/i, where
i is the number of an open driver channel. The channel number can be
determined with the HFGCHAN ioctl operation. The /dev/console special file is
channel number 1. The /dev/tty special file is often used by programs to
direct output and input to the current controlling terminal. For AIX, this
special file acts as a synonym for the current virtual terminal.
A process can also communicate with the hft screen manager by opening the
/dev/hft/mgr file. Only the screen manager HFQSMGR and HFCSMGR ioctl
operations can be issued to this file. read and write system calls are not
allowed.
The /usr/lib/samples/hft directory contains sample programs that use the hft
virtual terminal subsystem. See the file /usr/lib/samples/README.hft for more
information about these sample programs. When you develop programs that access
the hft device driver, you should use the header file hft.h to define the
necessary structures and constant definitions.
OPEN/CLOSE
Refer to the sample program hftopen.c for an example of the topics discussed in
this section.
Processed November 8, 1990 HFT(4,F) 3
HFT(4,F) AIX Technical Reference HFT(4,F)
Creating a New Virtual Terminal
The hft device driver is a multiplexed device where each virtual terminal has a
specific hft channel number associated with it. Opening the file /dev/hft
causes the Screen Manager to create a new virtual terminal using the first
available hft channel.
The hft channels available are:
Channel Device
Number Name Use
0 Reserved Screen Manager
1 /dev/hft/1 console (/dev/console)
2 Reserved
3 /dev/hft/3 Virtual Terminal
4 /dev/hft/4 Virtual Terminal
.
.
.
17 /dev/hft/17 Virtual Terminal
The function call:
fildes = open("/dev/hft",O_RDWR)
causes the Screen Manager to create a new virtual terminal and assign the first
available channel to it. The monitor immediately switches to the new screen.
The file descriptor returned can be used to read or write from that virtual
terminal.
Determining the New Terminal's Channel Number
Some hft operations require the channel number of the terminal as a parameter.
After opening a new terminal issue the function call:
channel = ioctl(fildes,HFGCHAN,0)
Note that this function actually returns the channel of whichever terminal is
currently displayed. Since the Screen Manager switched you to the new terminal
immediately after creating it, the channel number of the new virtual terminal
is returned.
Redirecting Input and Output
After you open a new virtual terminal, the standard input is still from the
original virtual terminal (usually /dev/console) and the output is also sent to
the original virtual terminal, even when this virtual terminal is not
displayed. To redirect input and output to the new virtual terminal:
Processed November 8, 1990 HFT(4,F) 4
HFT(4,F) AIX Technical Reference HFT(4,F)
outdesc = freopen("/dev/hft/(channel number)","w",stdout)
indesc = freopen("/dev/hft/(channel number)","r",stdin)
Now you can use printf, getc, and other functions normally. When the original
console screen is displayed, keyboard input is sent to the program running on
the console and output is sent to the console screen. When the new virtual
terminal screen is displayed, keyboard input is sent to the program running on
the virtual terminal and output is sent from that program to the virtual
terminal screen.
Switching between Virtual Terminals
The operator uses Alt-Action or Shift-Action to switch between the virtual
terminals available for display. Each time these key combinations are pressed,
the next or previous virtual terminal is displayed.
Your program can also control the switch between virtual terminals by issuing
the HFQSMGR and HFCSMGR ioctls to the hft Screen Manager using pseudo device
/dev/hft/mgr. Refer to the sample programs hftcsm.c and hftqsm.c.
INPUT
Data read from an hft device with the read system call can contain not only
character data entered from the keyboard, but also input from other devices,
such as a locator or mouse.
Mouse input arrives in the form of Mouse Reports. See the section called
"Using the Mouse" for more information.
Keyboard input normally arrives in the form of ASCII characters and control
sequences as described in "data stream." Such characters are essentially the
same as the datastream that an ASCII terminal would produce.
If an application needs to know the exact state of the keyboard, such as when
keys are pressed and released then Untranslated Key Control should be used.
This is done by turning off the HFXLATKBD protocol. See "Set Protocol Modes."
When keyboard input is untranslated the hfunxlate sequence is returned for each
change in keyboard state. See "keyboard" for additional information.
The key position identifies the logical key pressed. The key status bits
indicate Alt, Alt-Gr, Ctrl, Shift, Caps Lock, and Num Lock key states.
Note: This control sequence contains binary data. To prevent the binary data
from being misinterpreted as ASCII control codes, set the terminal's
canonical processing off.
The structure of the untranslated key control is:
struct hfunxlate
{
char hf_esc;
char hf_lbr;
Processed November 8, 1990 HFT(4,F) 5
HFT(4,F) AIX Technical Reference HFT(4,F)
char hf_ww;
char hf_keypos;
char hf_scancode;
char hf_status[2];
};
The fields of the structure are:
Field Description
hf_esc ESC (0x1B)
hf_lbr "[" (0x5B)
hf_ww "w" (0x77)
hf_keypos Key Position
Field Description
hf_scancode
Scan Code (See PS/2 Hardware Interface Technical Reference.) The
scancode returned is the "makecode" as defined in Set 3 scancode
tables.
hf_status[0]
Status:
HFUXSHIFT A shift key is pressed.
HFUXCTRL Ctrl key is pressed.
HFUXALT Alt key is pressed.
HFUXCAPS Caps Lock mode is in effect.
HFUXNUM Num Lock mode is in effect.
HFUXMAKE If set, key has been pressed. If not set, key has been
released.
hf_status[1]
Status:
HFUXRPT Automatic repeat (typematic) state.
HFUXLSH Left shift state.
HFUXRSH Right shift state.
HFUXLALT Left alternate shift state
HFUXRALT Right alternate shift state. (Alt-Gr for 102-key
keyboards)
Using the Mouse
Refer to the hftmouse.c sample program for an example of the topics discussed
in this section.
Processed November 8, 1990 HFT(4,F) 6
HFT(4,F) AIX Technical Reference HFT(4,F)
AIX architecture allows many forms of non-keyboard input, including a class
called locator. Locators can provide input in either relative or absolute
coordinates. The PS/2 mouse produces Mouse Reports which contain relative
coordinates.
ENABLE/DISABLE MOUSE:
Use the HFLOCATOR bit in the hfprotocol structure. See "Set Protocol Modes."
Note that the mouse is initially set to disabled.
INPUT DEVICE REPORT:
Mouse data is reported in the hflocator structure, in response to the read
system call.
MOUSE REPORT
hf_esc ESC (0x1B)
hf_lbr "[" (0x5B)
hf_why "y" (0x79)
hf_deltax The X delta, a signed integer that holds the relative X delta
accumulations in counts of 0.25 millimeters of the locator movement
in twos-complement form. This information is sent to the virtual
terminal to indicate horizontal movement since the last locator
movement.
hf_deltay The Y delta, a signed integer that holds the relative Y delta
accumulations in counts of 0.25 millimeters of the locator movement
in twos-complement form. This information is sent to the virtual
terminal to indicate vertical movement since the last locator
movement.
hf_seconds
Time of the locator report in whole seconds since system startup.
hf_sixtyths
The fractional part, of locator report time stamp, in 1/60th seconds.
hf_buttons
The status of the locator buttons. This information is sent to the
virtual terminal to indicate a change in the status of the buttons
since the last locator movement in the following manner:
HFBUTTON1 Button 1 has been pressed.
HFBUTTON2 Button 2 has been pressed.
hf_stype 0
Processed November 8, 1990 HFT(4,F) 7
HFT(4,F) AIX Technical Reference HFT(4,F)
Note: This control sequence contains binary data. To prevent the binary data
from being misrepresented as ASCII control codes, set the terminal's
canonical processing off. See ICANON in "termio" for
details.
QUERY LOCATOR:
The resolution of the locator and the current threshold settings can be
obtained by issuing the Query Locator command. This is described within the
section on the Query ioctl.
CHANGE LOCATOR SAMPLE RATE:
The sampling rate of the locator can be changed by the HFCHGLOCRATE option of
the Reconfigure ioctl.
SET LOCATOR THRESHOLDS:
The locator device receives notice of horizontal and vertical movement. The
delta of these movement events are monitored by the driver, until the
accumulated events exceed either the horizontal or vertical thresholds, or
both. The locator device accumulates measurements at consecutive samplings.
When a threshold is exceeded, the driver queues the information to the virtual
terminal. When the status of the locator buttons change, the accumulated
measurements are returned to the virtual terminal, even if these measurements
do not exceed a threshold. The virtual terminal provides neither echoing nor
positional management functions for the locator.
Each opened virtual terminal has its own threshold values. When a virtual
terminal is opened, the threshold values default to 2.75 millimeters horizontal
and 5.5 millimeters vertical. If the thresholds are 0, each event report is
returned to the virtual terminal at the sampling rate supported by the locator
device driver.
Setting the HFLOCATOR bit to 0 in the protocol mode definition or setting both
thresholds to the maximum values completely disables the locator input.
Setting a -1 for either or both threshold values indicates not to change the
current setting.
The hfloth structure is used for the locator threshold command, and it contains
the following fields:
Field Value
hf_intro.hf_typehi HFLOTHCH
hf_intro.hf_typelo HFLOTHCL
hf_sublen 2
Processed November 8, 1990 HFT(4,F) 8
HFT(4,F) AIX Technical Reference HFT(4,F)
Field Value
hf_subtype 1
hf_hthresh Specifies the horizontal threshold in values from 0 to
32767 in units of 0.25 millimeters.
hf_vthresh Specifies the vertical threshold in values from 0 to
32767 in units of 0.25 millimeters.
OUTPUT
The virtual terminal is initially set into KSR mode which emulates an ASCII
display. If an application needs direct control of physical hardware, then it
can enter monitor mode.
Keyboard Send-Receive Mode (KSR)
In KSR mode, each byte written to the virtual terminal is interpreted as an
ASCII code, which can be a displayable character, a single-byte control, or
part of an escape or control sequence. "data stream" explains the supported
ASCII/ANSI data stream in detail. KSR mode also supports a number of special
control sequences specific to the virtual terminal environment.
A KSR virtual terminal has a presentation space (PS) of a fixed number of
columns per line, and a fixed number of lines. A symbol can be placed at any
column on any line in the presentation space. A pointer into the virtual
terminal defines the cursor position with a column and a line number. Graphics
from the KSR data stream are placed in the PS relative to the cursor position.
Keyboard input also relates to the cursor position.
Two common modes for displaying graphics are replace and insert. In replace
mode, a graphic character sent to a KSR terminal is placed above the cursor,
replacing the symbol already there. In insert mode, a graphic character sent
to a KSR terminal is also placed above the cursor, but the symbol above the
cursor and all symbols to the right on the same line are shifted right one
column position on the line. Characters shifted from the last column on the
line disappear.
Another mode determines cursor movement after the last column position of a
line. This mode, automatic new line (AUTONL), determines if the cursor wraps
around to the first column position of the next line or stays at the last
column on the current line.
If AUTONL is set, the cursor moves to the first column position of the
following line. If the cursor happens to be on the bottom line of the
presentation space, the presentation space scrolls up one line. If AUTONL is
reset, the cursor stays on the last column of the current line.
Blank lines in the presentation space and erased character positions display in
the active background color with normal attributes.
Processed November 8, 1990 HFT(4,F) 9
HFT(4,F) AIX Technical Reference HFT(4,F)
To set the KSR protocol modes, write a protocol mode control, which is
described under "Set Protocol Modes." Specify the type as HFKSRPROH, HFKSRPROL.
Monitor Mode (MOM)
Refer to the hftmom.c sample program for an example of the topics discussed in
this section.
Programs that choose to interact more efficiently with a virtual terminal or
that must operate the display in all-points-addressable mode should select the
monitor mode of the virtual terminal. In this mode, the program performs
output directly to the display adapter via a memory mapped I/O bus, thus
avoiding write system calls. Such a program can optionally read data from a
circular buffer, (known as the "Input Ring Buffer"), thus avoiding read system
calls. Some execution speed is gained by operating in this mode, but
portability is sacrificed because the program depends on specific display
adapters.
Notes:
1. Do not leave terminal open in monitor mode.
2. No more than 1 process should be open to a virtual terminal that is in
monitor mode.
In order for a user program to switch from normal KSR mode to monitor mode, it
must perform several mode changes, which are accomplished using system calls.
The display-sharing concept using virtual terminals causes the program in
monitor mode to participate in the next window function by temporarily
releasing the display. This is also accomplished using system calls. While
the user program is active to the display, it performs output operations
directly to the display hardware with memory mapped I/O ports.
ENTERING MONITOR MODE:
The first mode change the user program should perform is to issue the HFSMON
ioctl operation to enable monitor mode signals SIGGRANT and SIGRETRACT, and to
specify the method by which processes are to receive the signals. (See "Enter
Monitor Mode (HFSMON).")
Next, the program should write a protocol mode control, which is described
under "Set Protocol Modes," specifying the type HFMOMPROH, HFMOMPROL. Only
certain protocols are valid for monitor mode.
The virtual terminal is now in monitor mode.
Only certain controls are valid for the write system call while in monitor
mode. All other ASCII codes and controls are ignored. The valid controls and
VTDs are:
o Disable Manual Input (DMI)
o Enable Manual Input (EMI)
o Set Keyboard LEDs
Processed November 8, 1990 HFT(4,F) 10
HFT(4,F) AIX Technical Reference HFT(4,F)
o Set Locator Threshold
o Sound
o Cancel Sound
o KSR Protocol (Enable/Disable Locator)
o MOM Protocol
o Screen Request (Establish Ring Buffer)
o Screen Release.
SCREEN REQUEST AND INPUT RING BUFFER DEFINITION:
Although the virtual terminal is in monitor mode, the program can perform
direct operations on the display hardware only when granted permission by the
operating system. The program first writes a screen request Virtual Terminal
Command.
This request uses the hfmomscreq structure, which contains the following
fields:
Field Value
hf_intro.hf_len The length of the request from the start of this len
field up to and including the ring buffer.
hf_intro.hf_typehi HFMOMREQH
hf_intro.hf_typelo HFMOMREQL
hf_sublen Subheader length
hf_subtype Subheader type
hf_ringlen[2] Shows the length of the hfmomring structure in bytes.
hf_ringoffset[4] Shows the offset to the input buffer ring (offset from
the hf_ringlen field).
The hf_ringlen field specifies the size of the structure including the pointers
and status fields. The program can directly access input key and locator data
contained in the buffer without issuing read system calls. A minimum
recommended ring buffer size would be 32 bytes.
The ring buffer structure (hfmomring, defined following) can be at any location
in memory aligned on a word boundary. hf_ringoffset is the difference between
the ring buffer address and the address of hf_ringlen, and it must be a
positive value. Usually, the hfmomring ring buffer structure is defined so
that it immediately follows the hfmomscreq structure in memory. Note that the
compiler may implicitly insert one or more filler bytes between the two
structures to align them at a memory address boundary. The value of
hf_ringoffset must reflect such filler bytes. See the
/usr/lib/samples/hft/hftmom.c source file for an example of how to calculate
hf_ringoffset.
Processed November 8, 1990 HFT(4,F) 11
HFT(4,F) AIX Technical Reference HFT(4,F)
If you do not want to specify or use a ring buffer, then set the hf_len field
of the hf_intro to the size of only the introducer. In this case, read input
with the standard read system call. The hftmom2.c sample program shows how to
develop a program without use of the ring.
struct hfmomring
{
char hf_rsvd[2];
char hf_intreq;
char hf_ovflow;
unsigned hf_source;
unsigned hf_sink;
int hf_unused[5];
char hf_rdata[HFRDATA];
};
The fields in this structure are defined as:
Field Value
hf_rsvd Reserved.
hf_intreq Interrupt request can be set to 0xFF by the application to cause
the virtual terminal subsystem to send a SIGMSG signal each time
an input event occurs. If this flag is set to 0 (the default),
then a signal is sent to the application only when the buffer
goes from being empty to nonempty. This byte is automatically
reset to 0 by the virtual terminal each time it stores input data
into the ring buffer. See "Reading Input Data from the Ring
Buffer" for further discussion.
hf_ovflow Overflow determines whether the input buffer ring can accommodate
more input information. A value of 0xFF indicates an overflow;
0x00 indicates normal operation.
hf_source Ring offset for virtual terminal represents the offset into the
input ring where the virtual terminal queues keyboard and locator
input. This offset starts from the beginning of the ring, so the
absolute minimum value for the virtual terminal offset is 32
bytes. Application programs must not alter this field. If a
program attempts to alter it, then the virtual terminal is
killed. See "Reading Input Data from the Ring Buffer" for
further discussion.
hf_sink Ring offset for application shows the offset into the input ring
from which the application reads keyboard and locator information
from the event queue. This offset also starts from the beginning
of the input ring, so the minimum value for this offset is 32
bytes. See "Reading Input Data from the Ring Buffer" for further
discussion.
hf_unused Reserved.
Processed November 8, 1990 HFT(4,F) 12
HFT(4,F) AIX Technical Reference HFT(4,F)
READING INPUT DATA FROM THE RING BUFFER:
The program should initialize the offsets hf_source and hf_sink to be equal.
This indicates buffer empty condition. The program should then issue the pause
system call, waiting for input. When the buffer goes from being empty to not
empty, the program receives a SIGMSG signal. (Note that sending the hfmomscreq
structure and defining the input ring buffer enables the sending of this
signal.) The program should extract characters from the ring buffer while
incrementing the hf_sink offset for each character extracted, making sure to
wrap around after reaching the end of the buffer. Care should be taken to
ensure the buffer empty condition is properly detected. The program should
test the equality of the offsets after it has updated the hf_sink offset.
Therefore, the order of operation is: extract a character, update the offset in
its memory location, and test the equality of offsets; if the offsets are
equal, then set hf_intreq to 0xFF.
If hf_source == hf_sink - 1 (module ring size), then the ring buffer is full.
If hf_ovflow == 0xff, then an overflow condition exists. The overflow
condition indicates input data has been lost. The program resets the overflow
condition by clearing hf_ovflow.
Certain keys can be designated so they can be obtained using the read system
call. This is particularly useful when such keys are the Intr and Quit keys
(see "termio"). These keys are designated using HFSECHO. Thus, by designating
these keys in the break map, and by setting the ISIG mode of termio, it is
possible to asynchronously interrupt a monitor mode program by pressing one of
these keys.
NEXT WINDOW FUNCTION:
If a virtual terminal in monitor mode is active, pressing the Next Window key
causes a SIGRETRACT signal to be sent to the process or group of processes
specified by the HFSMON type ioctl system call. Before activating the next
virtual terminal, the operating system allows the program a chance to save the
state of the display hardware, such as registers and refresh memory. After
this is done, the program should write a screen release control to the terminal
to inform the operating system the state of the display hardware can be
changed.
The screen release control is given by the hfmomscrel structure:
Field Value
hf_intro.hf_len The length of the entire structure, minus 3; typically 6
bytes.
hf_intro.hf_typehi HFMOMRELH
hf_intro.hf_typelo HFMOMRELL
Processed November 8, 1990 HFT(4,F) 13
HFT(4,F) AIX Technical Reference HFT(4,F)
After the display is released, the next virtual terminal is activated. If this
is not done within 30 seconds of the receipt of the SIGRETRACT signal, all
processes in that terminal group receive a SIGKILL signal. This is a safeguard
to prevent runaway monitor mode programs from disrupting the next window
function.
The program can issue a pause system call if there is no work to do while the
display is not available. When the monitor mode virtual terminal is activated
again with the Next Window key, the program receives a SIGGRANT signal. In
other words, the program can resume direct output to the display. The display
hardware state cannot be assumed to be the same as when the program released
it. Therefore, the SIGGRANT signal handler must restore the state that the
SIGRETRACT signal handler saved.
EXITING MONITOR MODE:
When the program has no further use of the monitor mode, it should first write
a screen release control, followed by a KSR protocol control. The screen
release control causes addressability to video RAM and the I/O ports to be
rescinded. This is especially important if the virtual terminal is open by
another process, such as the parent process, which is often the command shell.
Changing back to KSR protocol tells the hft device driver that it may resume
having control over the hardware. Only in KSR mode will the hft driver draw
characters on the screen. If the program is certain that no other processes
have the terminal open, it can simply issue a close system call to remove that
virtual terminal.
Next, an HFCMON ioctl operation should be issued to turn off monitor mode
signalling to this process or other process in the terminal group.
SIGNALS:
In addition to the standard terminal signals (SIGINT and SIGQUIT), the virtual
terminal generates other unique signals to inform the application program of
asynchronous events. These signals include:
SIGGRANT
Informs the user program that the display hardware can be directly
accessed. This signal is sent following a monitor mode screen request
VTD sequence. It is also sent after a monitor mode terminal has been
made active with the next window key.
SIGRETRACT
Informs the user program that the display hardware must be released for
use by another program. This signal is sent after a monitor terminal
being made inactive with the next window key.
SIGKILL Sent to all processes in the terminal tty group to enforce the
SIGRETRACT signal. If the user program does not respond with a screen
release VTD sequence within 30 second after receiving a SIGRETRACT
signal, the SIGKILL terminates all processes associated with that
virtual terminal and the terminal is closed.
Processed November 8, 1990 HFT(4,F) 14
HFT(4,F) AIX Technical Reference HFT(4,F)
SIGMSG Informs the user program that data has been placed into a previously
empty input buffer.
Controlling Sound through the Speaker
Refer to the sample programs, hftsound.c, hftcansnd.c, hftdsnd.c, and hftesnd.c
for examples of the topics discussed in this section.
SOUND:
This command sends output to the speaker. The mode byte determines whether to
execute sound commands for the active virtual terminal and whether to interrupt
the application after the sound command executes. No range check is made for
the frequency or duration values. The hfsound structure is used for this
command:
Field Value
hf_intro.hf_typehi HFSOUNDCH
hf_intro.hf_typelo HFSOUNDCL
hf_sublen Subheader length
hf_subtype Subheader type
hf_mode Mode:
HFSIGSOUND
If set, causes the SIGSOUND signal to be sent to the
process when this sound command is executed or
discarded. If not set, then no signal is sent.
HFEXECALWAYS
If set, causes this sound command to be executed
whether or not this virtual terminal is active. If
not set, then the sound command is executed only if
the terminal is active; if not active, the sound
command is discarded.
hf_dur Duration in 1/128 seconds.
hf_freq Frequency in hertz.
ENABLE SOUND SIGNAL (HFESOUND):
This command informs the terminal driver of the intent to use sound, enabling
the routing of the sound response signal. This is invoked by the following:
int ioctl(fildes, HFESOUND, arg)
int fildes;
Processed November 8, 1990 HFT(4,F) 15
HFT(4,F) AIX Technical Reference HFT(4,F)
struct hfsmon *arg;
struct hfsmon
{
int hf_momflags;
};
The hf_momflags field contains one of the following values:
HFSINGLE Only the process issuing the ioctl system call is to receive a sound
response signal.
HFGROUP All members of the current process group are to receive a sound
response signal.
DISABLE SOUND SIGNAL (HFDSOUND):
This informs the terminal driver of the intent to discontinue the use of sound.
Sound response signals are not sent. This is invoked by the following:
int ioctl (fildes, HFDSOUND, 0)
int fildes;
CANCEL SOUND:
The cancel sound command removes all commands from the speaker device that do
not want sound commands executed. Only the commands that have the HFEXECALWAYS
flag are left in the active terminal queue. An inactive terminal ignores this
command.
Sending a cancel and/or enable sound command flushes the speaker driver queue
when a virtual terminal transition occurs. Regardless of whether the sound
request is executed or purged, the virtual terminal receives a response
(SIGSOUND) if the response flag is set (bit 0 of sound command byte 0 is equal
to 1).
The hfcansnd structure is used for this command, and it contains the following
fields:
Field Value
hf_intro.hf_typehi HFCANSNDCH
hf_intro.hf_typelo HFCANSNDCL
IOCTL OPERATIONS
The hft supports a number of operations issued by the ioctl system call to
provide access to features of the hft. See "ioctlx, ioctl, gtty, stty" for
details about the syntax of the system call itself. For information about
issuing requests for these operations to an emulated hft device, see
"Considerations for hft Emulation." There are also other operations which
Processed November 8, 1990 HFT(4,F) 16
HFT(4,F) AIX Technical Reference HFT(4,F)
control the Virtual Terminal through use of writes. See "Virtual Terminal
Commands."
Query I/O Error (HFQEIO)
If an I/O operation or other system call to the hft fails due to a hardware
error, the system call returns a nonzero value and sets the errno external
variable to the value EIO. The calling program can get a more detailed device
error code by using ioctl to issue an HFQEIO operation. This is invoked by the
following:
int ioctl(fildes, HFQEIO, 0)
int fildes;
The return value from the HFQEIO ioctl operation is either 0 (indicating that
the last I/O operation was successful), -1 (indicating that the HFQEIO
operation itself failed), or the error code for the last hft I/O operation.
The possible terminal error codes are:
6401 Invalid virtual terminal IODN
6461 Maximum number of virtual terminals open
6480 Invalid operation
6516 Invalid virtual address
6521 Unsuccessful, invalid length specified in VTD block
6522 Unsuccessful, invalid major type
6523 Unsuccessful, invalid minor data
6524 Unsuccessful, invalid minor type
6527 Unsuccessful, VTD block exceeds 128K bytes
6528 Unsuccessful, VTD block is less than the minimum length
6531 Unsuccessful, cannot remap a character set other than unique 1 or 2
6532 Invalid locator/mouse/tablet type request
6533 Unsuccessful, invalid font ID
6537 Invalid graphics asynchronous device driver request
6538 Specified device not configured
6539 Specified device not selected
Processed November 8, 1990 HFT(4,F) 17
HFT(4,F) AIX Technical Reference HFT(4,F)
6544 Unsuccessful, data received for an inactive mode
6545 Unsuccessful, specified virtual terminal not active.
6546 Unsuccessful, invalid virtual terminal identifier
6548 Unsuccessful, invalid coordinates specified in Query ASCII Codes
command
6549 Unsuccessful, invalid parameter detected in a control sequence
6550 Unsuccessful, unsupported control sequence or code received
6555 Unsuccessful, sound error
6562 Unsuccessful, invalid echo map length
6564 Unsuccessful, cannot remap keys reserved for resource controller
6565 Unsuccessful, invalid flags in the keyboard mapping structure
6566 Unsuccessful, invalid key position
Enter Monitor Mode (HFSMON)
This requests monitor mode. Monitor mode provides a program with direct
control of the screen and keyboard. This is invoked by the following:
int ioctl(fildes, HFSMON, arg)
int fildes;
struct hfsmon *arg;
struct hfsmon
{
int hf_momflags;
int hf_momscnt;
caddr_t hf_momsaddrs[MAX_MON_ADDRS];
};
The hf_momflags field contains one of the following values:
HFSINGLE Only the process issuing the ioctl system call is to receive monitor
mode signals.
HFGROUP All members of the current process group are to receive monitor mode
signals.
The hf_momscnt field must be set to MAX_MON_ADDRS to define the maximum number
of entries in the hf_momsaddrs field.
Processed November 8, 1990 HFT(4,F) 18
HFT(4,F) AIX Technical Reference HFT(4,F)
The hf_momsaddrs[0] field will return the virtual address of the start of the
video I/O buffer. For the VGA adapter, this address will correspond to 0xA0000
in PC memory. (See the PS/2 Hardware Interface Technical Reference.)
The other elements in hf_momsaddrs are reserved for adapters that work with
more than one video address. See /usr/lib/samples/README.mom for information
on other supported adapters.
Exit Monitor Mode (HFCMON)
Releases monitor mode. This is invoked by the following:
int ioctl(fildes, HFCMON, 0)
int fildes;
Get Virtual Terminal ID (HFGETID)
Gets identification information for the current hft virtual terminal. This is
invoked by the following:
int ioctl(fildes, HFGETID, arg)
int fildes;
struct hfgetid *arg;
struct hfgetid {
unsigned hf_iodn;
unsigned hf_pgrp;
unsigned hf_chan;
};
The hf_iodn field is the I/O device number (IODN) of the virtual terminal. The
hf_pgrp field is the process group ID; that is, the process ID of the terminal
group leader. The hf_chan field is the channel number that is also returned by
the HFGCHAN ioctl operation.
Each hft virtual terminal is given both a channel number and an IODN or I/O
device number. You use the channel number if you wish to reopen an already
existing virtual terminal. You use the IODN as part of certain hft ioctl
operations, such as controlling the screen manager. The IODN specifies which
virtual terminal is to be operated upon for certain hft ioctl operations such
as controlling the screen manager. See the hftgetid.c sample program.
Get Channel Number (HFGCHAN)
Returns the current driver channel number as the value of the ioctl system
call. This number can be used to open a specific virtual terminal. The arg
parameter is ignored. This is invoked by the following:
int ioctl (fildes, HFGCHAN, 0)
int fildes;
See the hftgchan.c sample program.
Processed November 8, 1990 HFT(4,F) 19
HFT(4,F) AIX Technical Reference HFT(4,F)
Query (HFQUERY)
Refer to the hftqdid.c, hftqpd.c, hftqpres.c, and hftqhft.c sample programs for
examples of the topics discussed in this section.
HFQUERY gets information about the current virtual terminal. This is invoked
by the following:
int ioctl(fildes, HFQUERY, arg)
int fildes;
struct hfquery *arg;
struct hfquery {
char *hf_cmd;
int hf_cmdlen;
char *hf_resp;
int hf_resplen;
};
The first two fields describe a buffer containing the command. The second two
fields describe a buffer large enough to hold the largest possible response.
Note that each command and response structure begins with a virtual terminal
data (VTD) header. (See "Virtual Terminal Commands" for an explanation of the
VTD header.) The following query commands use this ioctl operation.
QUERY DEVICE IDS COMMAND:
This command uses the hfqdevidc structure, which contains the following fields:
Field Value
hf_intro.hf_typehi HFQDEVIDCH
hf_intro.hf_typelo HFQDEVIDCL
This command fills the response buffer with the information about the display
devices. The information is returned in an hfqdevidr structure, which has the
following fields:
Field Value
hf_intro.hf_typehi HFQDEVIDRH
hf_intro.hf_typelo HFQDEVIDRL
hf_numdev The number of devices for which data is reported.
The following fields are repeated for each physical device:
Processed November 8, 1990 HFT(4,F) 20
HFT(4,F) AIX Technical Reference HFT(4,F)
hf_devid Physical device ID.
The first device ID is the active display device ID,
unless the change physical display command has changed
the active display ID. The following values are
possible:
0x0411mmnn VGA adapter with 8503 Display
0x0412mmnn VGA adapter with 8512 Display
0x0413mmnn VGA adapter with 8513 Display
0x0414mmnn VGA adapter with 8514 Display
0x0415mmnn VGA adapter with 8507 display
0x0416mmnn VGA adapter with 8604 display
0x0418mmnn 8514/A adapter with 8503 display
0x0419mmnn 8514/A adapter with 8512 display
0x041Ammnn 8514/A adapter with 8513 display
0x041Bmmnn 8514/A adapter with 8514 display
0x041Cmmnn 8514/A adapter with 8507 display
0x041Dmmnn 8514/A adapter with 8604 display
0x0421mmnn reserved
Note: The mm value indicates whether the adapter is
totally functional. When this value is 0x00, the
adapter is totally functional. Any other value
indicates the adapter is less than fully
functional or not working at all, but is present
on the machine. The nn value can be from 0x01 to
0x04 and differentiates between multiple
instances of the same adapter type.
hf_class Display class (0x44).
QUERY PHYSICAL DEVICE COMMAND:
This command returns information about display or locator devices. The
hfqphdevc structure is used to issue this command:
Field Value
hf_intro.hf_typehi HFQPDEVCH
hf_intro.hf_typelo HFQPDEVCL
hf_phdevid Physical device ID. The value 0 specifies the active
device that is currently attached to the virtual
terminal.
The response to this command gives the following information:
struct hfqphdevr
Processed November 8, 1990 HFT(4,F) 21
HFT(4,F) AIX Technical Reference HFT(4,F)
{
char hf_intro[HFINTROSZ];
char hf_sublen;
char hf_subtype;
/* locator device */
char hf_scale[4];
char hf_locattr[1];
char hf_rsvd[3];
/* display device */
char hf_attrib[4];
char hf_pwidth[4];
char hf_pheight[4];
char hf_mwidth[4];
char hf_mheight[4];
char hf_bperpel[4];
char hf_phdevid[4];
/* display font */
char hf_numfont[4];
/* remainder is of variable length */
/* struct hffont hffont[N]; where N is value in hf_numfont */
char hf_fontstart;
/* following is one color response */
/* struct hfcolor hfcolor; */
};
struct hfqfont
{
char hf_fontid[4];
char hf_fontstyle[4];
char hf_fontattr[4];
char hf_fontwidth[4];
char hf_fontheight[4];
};
struct hfcolor
{
char hf_numcolor[4];
char hf_numactive[4];
char hf_numfgrnd[4];
char hf_numbgrnd[4];
char hf_actcolor[4];
};
These structures are explained in the following sections that have headings
beginning with the word Physical.
Physical Device Information VTD Header
Field Value
hf_intro.hf_typehi HFQPDEVRH
Processed November 8, 1990 HFT(4,F) 22
HFT(4,F) AIX Technical Reference HFT(4,F)
hf_intro.hf_typelo HFQPDEVRL
Physical Locator Information
Field Value
hf_scale Scale factor (millimeters per 100 counts)
hf_locattr[0] Locator attributes:
HFLOCABS If set, then the locator device reports absolute
coordinates (for example, a tablet device). If not
set, then it reports relative coordinates (for
example, a mouse).
Physical Display Device Information
Field Value
hf_attrib[0]
Display device attributes:
HFISAPA All-points-addressable (APA) display.
HFHASBLINK Blink function allowed.
All other values are reserved.
hf_attrib[2]
Display device attributes:
HFHASCOLOR Color allowed.
All other values are reserved.
hf_attrib[3]
Display device attributes:
HFCHGPALET Can change display adapter's color palette.
All other values are reserved.
hf_pwidth Displayable width of physical screen, expressed in pels or pixels
for all displays.
hf_pheight Displayable height of physical screen, expressed in pels for all
displays.
hf_mwidth Displayable width (in millimeters).
hf_mheight Displayable height (in millimeters).
Processed November 8, 1990 HFT(4,F) 23
HFT(4,F) AIX Technical Reference HFT(4,F)
hf_bperpel Bits per pel (1, 2, or 4).
hf_phdevid Display device ID.
Physical Display Font Information
Field Value
hf_numfont Number of fonts available to this display. The following fields
appear for each available font.
hf_fontid Physical font ID.
hf_fontstyle
Physical font style.
HFFNTVAR This font results in a variable presentation space
depending on the display type used.
HFFNTKSR This font results in a 80x25 presentation space
regardless of the display type used.
Field Value
hf_fontattr[3]
Physical font attribute. This field may have the following values:
HFFNTPLAIN Plain
HFFNTBOLD Bold
HFFNTITALIC Italic.
hf_fontwidth
Physical font width (the width of a character cell in pels).
hf_fontheight
Physical font height (the height of a character cell in pels).
Physical Display Color Information
Field Value
hf_numcolor Total number of colors possible
hf_numactive Number of colors that can be active at any one time
hf_numfgrnd Number of foreground color options
hf_numbgrnd Number of background color options
hf_actcolor Active color value. The value of this field can be in the range
0 to the total number of colors possible (hf_numcolor) minus 1.
This field is repeated for each of the currently active colors.
Processed November 8, 1990 HFT(4,F) 24
HFT(4,F) AIX Technical Reference HFT(4,F)
QUERY LOCATOR COMMAND:
To query the locator, use the hfqgraphdev structure with fields set as follows:
Field Value
hf_intro.hf_typehi HFQLOCCH
hf_intro.hf_typelo HFQLOCCL
This command returns a hfqlocr structure with the following fields:
Field Value
hf_intro.hf_typehi HFQLOCRH
hf_intro.hf_typelo HFQLOCRL
hf_resolution The resolution of the locator (a 4-byte value) in
millimeters per 100 count.
hf_devinfo[0] Locator attributes:
HFLOCABS If set, absolute coordinates (tablet).
If not set, relative coordinates (mouse).
HFLOCUNKNOWN Unknown sensor type, or the locator is a
mouse.
HFLOCSTYLUS The tablet has a stylus sensor.
HFLOCPUCK The tablet has a puck sensor.
hf_horzmax_cnt Horizontal maximum count (a 2-byte value).
hf_vertmax_cnt Vertical maximum count (a 2-byte value).
hf_horzdead_zone Horizontal tablet dead zone or mouse threshold.
hf_vertdead_zone Vertical tablet dead zone or mouse threshold.
QUERY PRESENTATION SPACE COMMAND:
This data determines how to define a block of characters in the presentation
space to query. Attribute and character set information on the queried block
are returned. This query is valid only in KSR mode.
The hfqpresc structure is used for this command,
Field Value
hf_intro.hf_typehi HFQPRESCH
hf_intro.hf_typelo HFQPRESCL
Processed November 8, 1990 HFT(4,F) 25
HFT(4,F) AIX Technical Reference HFT(4,F)
hf_sublen 2
hf_subtype 0
hf_xuleft The upper-left X coordinate (first column of the block)
hf_yuleft The upper-left Y coordinate (first row in the block)
hf_xlright The lower-right X coordinate (last column in the block)
hf_ylright The lower-right Y coordinate (last row in the block).
The data returned from this command is an ASCII data stream that contains
character codes from the queried block. Character set and attribute changes
are indicated with SGR and SG0 control sequences. A line feed control is
returned after the last character code in each line of the queried block. This
command is useful when you want to save the attributes of a screen for
restoring at some later time.
Note: The returned attributes may be only a subset of the original attributes
specified for query. The subset in this case is those attributes
actually supported by the physical device.
The response is returned in an hfqpresr structure, which contains the following
fields:
Field Value
hf_intro.hf_typehi HFQPRESRH
hf_intro.hf_typelo HFQPRESRL
The response contains an ASCII data stream that includes all ASCII data
currently associated with the input buffer.
QUERY HFT DEVICE COMMAND:
This command gets information about the hft device. To issue this command, use
the hfqhftc structure with fields set as follows:
Field Value
hf_intro.hf_typehi HFQHFTCH
hf_intro.hf_typelo HFQHFTCL
The command returns an hfqhftr structure with the following fields:
Field Value
hf_intro.hf_typehi HFQHFTRH
Processed November 8, 1990 HFT(4,F) 26
HFT(4,F) AIX Technical Reference HFT(4,F)
hf_intro.hf_typelo HFQHFTRL
hf_phdevid Physical display device ID (the same as returned by
"Query Device IDs Command")
hf_phrow Number of character rows, based on the current font
hf_phcol Number of character columns, based on the current font
hf_phcolor Number of colors allowed on the display
hf_phfont Number of fonts defined in the system
hf_phkbdid Physical keyboard ID:
0 101-key keyboard
1 102-key keyboard
SCREEN MANAGER IOCTLS
Refer to the hftqsm.c and hftcsm.c programs for examples of the topics
discussed in this section.
Query Screen Manager (HFQSMGR)
Queries the screen manager. The file descriptor must be associated with the
screen manager, that is, /dev/hft/mgr. This is invoked by the following:
int ioctl(fildes, HFQSMGR, arg)
int fildes;
struct hfbuf *arg;
struct hfbuf
{
char *hf_bufp;
int hf_buflen;
};
The contents of the following hfqstat structure are stored in the memory area
pointed to by hf_bufp.
struct hfqstat
{
short hf_numvts;
struct hfvtinfo
{
unsigned short hf_vtiodn;
unsigned short hf_vtstate;
} hf_vtinfo[HFNUMVTS];
};
Processed November 8, 1990 HFT(4,F) 27
HFT(4,F) AIX Technical Reference HFT(4,F)
Field Description
hf_numvts The number of virtual terminals.
The following fields are repeated for each virtual terminal:
hf_vtiodn The virtual terminal IODN.
hf_vtstate Status:
HFVTHIDDEN The virtual terminal is hidden.
HFVTACTIVE The virtual terminal is active.
HFVTCOMMAND The virtual terminal is the command terminal.
Control Screen Manager (HFCSMGR)
This commands the screen manager which controls the status of virtual
terminals. Virtual terminals are linked together in a group called the screen
manager ring. The screen manager places an entry in the ring for each virtual
terminal opened. The terminal that is currently active is called the head of
the ring; the last terminal on the ring is called the tail. When a new
terminal is added to the ring, that terminal becomes the head of the ring.
Three key sequences switch between virtual terminals and control which terminal
is currently active. The active terminal is the terminal that accepts keyboard
or locator input and updates the physical display. Pressing the Alt + Action
keys on the active terminal makes the next virtual terminal active. This
relationship is indicated by a in Figure 14. Pressing the Shift + Action keys
on the active terminal makes the last virtual terminal active. The b in
Figure 14 indicates this relationship. Pressing the Ctrl and Action keys on
the active virtual terminal make the command virtual terminal active.
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
Figure 14. Screen Manager Ring Examples. In this figure, a indicates the path
from the active virtual terminal to the next and b indicates the
path from the active virtual terminal to the last.
Note that with three entries in the ring, all the terminals can be accessed
with a single key sequence. With four or more entries, terminals can be
skipped in some cases to activate a particular terminal. For example, in the
preceding figure with four terminal entries, terminal number 2 cannot be
accessed from the active terminal number 4 without first skipping to terminal
number 1 or terminal number 3.
The hide option of this command logically removes terminals from the ring.
Hiding a terminal causes it to be bypassed when its position in the ring would
ordinarily make it the active terminal.
Processed November 8, 1990 HFT(4,F) 28
HFT(4,F) AIX Technical Reference HFT(4,F)
The file descriptor must be associated with a screen manager, that is,
/dev/hft/mgr. This is invoked by the following:
int ioctl(fildes, HFCSMGR, arg)
int fildes;
struct hfsmgrcmd *arg;
struct hfsmgrcmd {
int hf_cmd;
int hf_vtid;
int hf_vsid;
};
The hf_vtid and hf_vsid fields are set as follows:
hf_vtid The IODN of the virtual terminal
hf_vsid 0.
The hf_cmd field contains one of the following screen manager commands:
SMACT Activates the virtual terminal. This command places the virtual
terminal specified by the IODN at the head of the screen manager
ring, making it the active terminal. The terminal's hidden flag is
also cleared. The screen manager cannot activate the virtual
terminal if the currently active virtual terminal cannot be
deactivated.
SMHIDE Hides the virtual terminal. This command marks the terminal
identified by the IODN so that the screen manager will not activate
it. This does not affect the terminal's position in the ring. When
the hidden flag is set, the screen manager ignores the terminal's
presence in the ring until an SMUNHIDE command is issued. If the
virtual terminal is active when the hide command is issued, then the
screen manager makes the terminal inactive. Hiding the active
virtual terminal has the same effect as the last window function.
If all virtual terminals are hidden, then the physical display
continues to show the contents of the last virtual terminal that was
hidden.
SMSCMD Sets the command virtual terminal. This command designates a
terminal as the command virtual terminal. The command virtual
terminal is the terminal that is activated by pressing both locator
buttons at the same time, or by pressing the Ctrl-Action key
sequence.
SMUNHIDE Undoes the action performed by SMHIDE. The hf_vtid field contains
the IODN of the virtual terminal where the command should be sent.
The hf_vsid field is reserved.
This command restores the presence of the terminal in the ring, but
does not affect its ring position or make it active. If the virtual
Processed November 8, 1990 HFT(4,F) 29
HFT(4,F) AIX Technical Reference HFT(4,F)
terminal happens to be at the head of the ring when this command is
issued, then it becomes visible and active.
SMCVTEN Causes the command virtual terminal to be activated when both
locator buttons are pressed at the same time. This is the default
setting. Since all virtual terminals are affected, programs that
change this setting should restore it as soon as the locator is no
longer needed.
SMCVTDI Undoes the function done by SMCVTEN. Causes input data to be
reported when both locator buttons are pressed at the same time.
The data reported is similar to that reported when a single button
is pressed.
VIRTUAL TERMINAL COMMANDS
Application programs control the behavior of their virtual terminals either
through ioctls or by writing VTD character sequences into the output stream.
ASCII data can be sent to the virtual terminal using the write system call
along with data of any length. In addition, virtual terminal control
structures are sent to the virtual terminal using the write system call.
VTD Control Structure
Each control structure is introduced by a virtual terminal data (VTD) character
sequence. The VTD prefix consists of the ASCII codes ESC, [, and x (0x1B5B78).
This prefix is followed by a length and an operation type code. The data that
follows this structure depends on the type of control.
The hfintro structure looks like this:
{
char hf_esc;
char hf_lbr;
char hf_ex;
char hf_len[4];
char hf_typehi;
char hf_typelo;
};
The significant fields in the hfintro structure are:
hf_len The total number of bytes in the header and associated data, not
including the three-character VTD control sequence. In other
words, the length is the total number of characters in the control
sequence minus 3.
hf_typehi The high-order byte of the information type code.
hf_typelo The low-order byte of the information type code.
The values of hf_typehi and hf_typelo are documented with each command.
Processed November 8, 1990 HFT(4,F) 30
HFT(4,F) AIX Technical Reference HFT(4,F)
Because the hfintro structure is an odd number of bytes in length, it is
designated as the character array hf_intro[HFINTROSZ] in the structures that
define the various operation requests. This prevents the C compiler from
inserting bytes into the structure to align the following fields on word
boundaries. The hf_typehi and hf_typelo fields are referred to
hf_intro.hf_typehi and hf_intro.hf_typelo in this book, although these
references are not precisely correct.
All reserved and unused fields must be set to 0. You can set the entire
structure to 0 and then fill in the appropriate fields.
Set KSR Color Palette
This command specifies the color to associate with certain display adapters.
The default color palettes are the ANSI 3.64 palette for character terminals
and the PC color palette for all-points-addressable terminals. If the color
specified is not supported by the adapter, the virtual display driver sets that
color to the default for that mode.
The structure for this command is hfcolorpal, and it contains the following
fields:
Field Value
hf_intro.hf_typehi HFCOLORPALH
hf_intro.hf_typelo HFCOLORPALL
hf_sublen 2
hf_subtype 1
hf_numcolor Number of entries in the palette
hf_palet Adapter-specific settings of the first entry in the
color palette. These settings must be repeated for each
entry of the color palette corresponding to the display
adapter. See the appropriate hardware technical
reference for information about the display adapter.
The file /usr/lib/samples/hft/ksrpal.c contains a sample program that
illustrates how to use this function with the VGA adapter.
Change Fonts
When a virtual terminal is first opened, and whenever it is changed, the
default font is used. AIX PS/2 allows the user to change between two built-in
80 column by 25 row fonts. The default font (1025) uses the hardware of the
VGA to produce the symbols in code page P0 (see "data stream"). The other font
(1026) uses the APA mode of the VGA adapter to produce all the symbols in code
pages P0, P1, and P2.
Processed November 8, 1990 HFT(4,F) 31
HFT(4,F) AIX Technical Reference HFT(4,F)
Note that if the font is changed, the data currently in the presentation space
is lost, and the cursor reverts to the double underscore and is placed at the
home position (first column, first row). If it is desirable to control fonts,
the fonts should be explicitly set when opening a terminal or changing a
display.
Field Value
hf_intro.hf_typehi HFFONTH
hf_intro.hf_typelo HFFONTL
hf_sublen 2
hf_subtype 1
hf_primary Physical font ID of primary font attribute.
hf_alt1 Reserved.
hf_alt2 Reserved.
hf_alt3 Reserved.
hf_alt4 Reserved.
hf_alt5 Reserved.
Field Value
hf_alt6 Reserved.
hf_alt7 Reserved.
POSSIBLE GRAPHIC RENDITIONS OF VGA ADAPTER:
Hardware Font Software Font 1026
1025
Bold or Bright Yes Yes
Underscore No Yes
Slow Blink Yes No
Reverse Image Yes Yes
Alternate Fonts No No
Code Page P0 Yes Yes
Code Pages P1 and No Yes
P2
Set Cursor Representation
The cursor representation data format determines how the cursor is presented on
the display screen. The hfcursor structure is used for this request:
Processed November 8, 1990 HFT(4,F) 32
HFT(4,F) AIX Technical Reference HFT(4,F)
Field Value
hf_intro.hf_typehi HFCURSORH
hf_intro.hf_typelo HFCURSORL
hf_sublen 2
hf_subtype 0
hf_rsvd Reserved.
hf_shape Cursor shape:
HFNONE No cursor.
HFSINGLUS Single underscore.
HFDBLUS Double underscore.
HFHALFBLOB Lower half of illuminated character cell.
HFMIDLINE Double mid-character line.
HFFULLBLOB Full illuminated character cell.
Set Keyboard LEDs
The structure for this command is hfkled, and it contains the following fields:
Field Value
hf_intro.hf_typehi HFKLEDCH
hf_intro.hf_typelo HFKLEDCL
hf_sublen 2
hf_subtype 1
hf_ledselect Indicates which of three LEDs to change:
HFNUMLOCK The Num Lock LED
HFCAPSLOCK The Caps Lock LED
HFSCROLLOCK The Scroll Lock LED.
Field Value
hf_ledvalue Indicates the value to which to set the LEDs specified
in hf_ledselect. LEDs that are specified with a 1 bit
are set:
HFNUMLOCK The Num Lock LED
HFCAPSLOCK The Caps Lock LED
HFSCROLLOCK The Scroll Lock LED.
The hftskleds.c sample program has an example of this command.
Processed November 8, 1990 HFT(4,F) 33
HFT(4,F) AIX Technical Reference HFT(4,F)
Set Protocol Modes
Refer to the hftinput.c sample program for an example of the topics discussed
in this section.
Protocol mode settings determine how the virtual terminal will interpret coded
data, translate and return input data. Two bits control each mode. The first,
in the hf_select field, indicates whether to use the current mode setting. If
this bit is set, then the corresponding bit in hf_value indicates the new
setting for the mode. The mode bits are set to the default value when the
virtual terminal is opened.
The hfprotocol structure gives the protocol definitions:
Field Value
hf_intro.hf_typehi HFKSRPROH or HFMOMPROH
hf_intro.hf_typelo HFKSRPROL or HFMOMPROL
hf_sublen 2
hf_subtype 0
hf_select Specifies which modes to change. A bit value of 1
specifies the mode represented by that bit to change.
hf_select[0] Mode selectors:
HFHOSTS
HFXLATKBD
hf_select[1] Mode selectors:
HFWRAP
HFLOCATOR
hf_value[0] New mode values:
HFHOSTS
HFXLATKBD
hf_value[1] New mode values:
HFWRAP
HFLOCATOR
When issuing this command, specify a type of either HFKSRPROH, HFKSRPROL or
HFMOMPROH, HFMOMPROL depending on whether you are sending this command from
within Keyboard Send-Receive mode (KSR) or Monitor mode (MOM). Only certain
protocol modes are valid in each of these modes, as shown in the following
Processed November 8, 1990 HFT(4,F) 34
HFT(4,F) AIX Technical Reference HFT(4,F)
table. An attempt to set an invalid protocol mode results in rejection of the
entire request.
Protocol When
Mode Valid Meaning
HFHOSTS KSR A 0 bit (default) means not to report shift key
depressions. A 1 bit means report shift key
depressions.
HFHOSTS mode specifies whether to report keyboard
status changes. If HFHOSTS mode is set, the keyboard
status information is returned in the KSI ANSI
control (see "Multi-Byte Controls").
HFXLATKBD KSR, MOM A 1 bit (default) specifies that the keyboard input
is translated. A 0 bit indicates send key data as
untranslated key controls.
HFWRAP KSR A 1 bit (default) causes the cursor to wrap when the
presentation space boundary is exceeded. A 0 bit
specifies do not wrap the cursor.
HFLOCATOR KSR, MOM A 0 bit (default) disables the locator from sending
data. A 1 bit enables the locator to send data.
CONFIGURING THE VIRTUAL TERMINAL
Some applications may require that the virtual terminal be set to other than
the IBM-defined initial characteristics. The hft driver provides methods of
querying the settings and capabilities of the virtual terminal, and methods of
setting these to new values if required.
Earlier sections have described some of these methods:
Query locator
Set locator thresholds
Query physical device (color, fonts, display attributes)
Set KSR color palette
Change fonts
Set cursor representation
Set keyboard LEDs
Set protocol modes (keyboard translation, enable locator, etc.)
Query and control Screen Manager
This section describes the initial default settings of each virtual terminal
and facilities for changing the ones that have not already been described in
prior sections:
Initial State
Reconfigure ioctl
Processed November 8, 1990 HFT(4,F) 35
HFT(4,F) AIX Technical Reference HFT(4,F)
Change keyboard typematic rate
Change keyboard typematic delay
Change locator sample rate
Replace keyboard position map
Replace Unique 1 and Unique 2 character set map
Replace echo/break map
If the physical display model is ever to be changed or if the physical keyboard
(country keycap markings) are ever to be changed, then you should use the
change parameters option of the AIX PS/2 boot to change them.
Initial State
When a new terminal is opened, it is initialized to a known default state. The
initial terminal state is the following:
o Mode: Keyboard Send-Receive (KSR).
o Echo/Break Map: Echo all characters; break for none.
o Tab Rack: The first, every eighth, and the last position of every line.
o ASCII Controls:
LNM Set (line feed-new line mode)
IRM Not set (insert mode)
SRM Not set (send receive mode-set echo off)
TSM Not set (tab stop mode)
CLM Not set (carriage return-new line mode)
AUTONL Set (wrap character to following line when end of correct line is
reached)
o Protocol:
WRAP Set (wrap cursor at boundary)
LOCATOR Not set (do not return locator input)
XLATKBD Set (translate keyboard input)
HOSTS Not set (do not report keyboard status change)
o Locator (Mouse) Threshold: 2.75 millimeters horizontal, 5.5 millimeters
vertical.
o Font: Provides a presentation space of 80 columns by 25 rows.
o Character mode color palette:
Foreground Background
Entry Color Entry Color
0 Black 0 Black
1 Red 1 Red
2 Green 2 Green
Processed November 8, 1990 HFT(4,F) 36
HFT(4,F) AIX Technical Reference HFT(4,F)
Foreground Background
3 Yellow 3 Yellow
4 Blue 4 Blue
5 Magenta 5 Magenta
6 Cyan 6 Cyan
7 White 7 White
8 Gray
9 Light red
10 Light green
11 Brown
12 Light blue
13 Light magenta
14 Light cyan
15 High intensity
white
Reconfigure (HFRCONF)
Refer to the notes in /usr/lib/samples/README.conf before using Reconfigure.
A user program can reconfigure the virtual terminal to include different real
devices. This operation is invoked by the following:
int ioctl(fildes, HFRCONF, arg);
int fildes;
struct hfrconf *arg;
struct hfrconf
{
unsigned hf_op;
unsigned hf_obj;
union
{
uint hf_infob;
struct
{
ushort hf_iodn;
ushort hf_iocn;
} hf_info2;
} hf_info;
union
{
char *hf_cptr;
struct hfbuf *hf_hfbufptr;
} hf_mapinfo;
};
This command changes the configuration of the physical terminal or the virtual
terminal defaults.
The hf_op field contains the requested operation. The valid operations appear
in the following list. These reconfigure operations, with the exception of
Processed November 8, 1990 HFT(4,F) 37
HFT(4,F) AIX Technical Reference HFT(4,F)
those followed by an * (asterisk), take effect only for terminals opened after
the reconfiguration. The operations followed by an asterisk take effect for
the terminals that are currently open as well as those opened after the
reconfiguration.
HFCHGKBDRATE* Changes the keyboard typematic rate. Bits 24 - 31 of hf_obj
indicate the keyboard typematic rate. For the standard PS/2
keyboard, valid values are between 2 and 30 characters per
second and can be incremented in 1 character-per-second units.
The default value for the PS/2 keyboard is 11 characters per
second.
HFCHGKBDDEL* Changes the keyboard typematic delay. Bits 16 - 31 of hf_obj
indicate the keyboard typematic delay. For the standard PS/2
keyboard, valid values are between 250 and 1000 milliseconds and
can be incremented in 250 millisecond units. The default value
for the PS/2 keyboard is 500 milliseconds.
HFCHGLOCRATE* Change locator sample rate. Bits 24 - 31 of hf_obj indicate the
locator sample rate. For the standard PS/2 locator, valid
values are 10, 20, 40, 60, 80, and 100 samples per second. The
default for the PS/2 locator is 60 samples per second.
HFKEYMAP Replaces the keyboard position code map. hf_mapinfo contains
the new position code map address. See the
/usr/lib/samples/hft/hftkbdmap.c file.
HFDISPMAP Replaces the character code maps for the Unique 1 and Unique 2
character sets. hf_mapinfo contains the new unique character
code map address. See the /usr/lib/samples/hft/hftchrmap.c
file.
HFECHOMAP Replaces the echo/break map. hf_mapinfo contains the new
echo/break map address. See the
/usr/lib/samples/hft/hftecbrmap.c file.
Set User-Defined Character Set
The ASCII character set-to-display code (font) mapping of a virtual terminal
can be altered. For each virtual terminal, the virtual terminal maintains
character set mapping tables for two unique user-definable character sets
called Unique One and Unique Two. These sets contain 256 ten-bit display
symbol codes, and are activated by the SG0 or SG1 control (see "Multi-Byte
Controls").
Note: Data is kept in display symbol form in the virtual terminal, and
translation back to ASCII codes is done using the standard character set
definitions, not Unique One or Two.
The hfcharset structure is used for character set definition, and it contains
the following fields:
Processed November 8, 1990 HFT(4,F) 38
HFT(4,F) AIX Technical Reference HFT(4,F)
Field Value
hf_intro.hf_typehi HFCHARSETH
hf_intro.hf_typelo HFCHARSETL
hf_sublen 2
hf_subtype 1
hf_setnum User-defined character set
HFUNIQ1 Unique One (user-definable set 1)
HFUNIQ2 Unique Two (user-definable set 2)
hf_rsvd Reserved
hf_code 10-bit display symbol code. This field may be repeated
up to 256 times. See "display symbols" for the values
of the display symbols.
Set Echo and Break Maps (HFSECHO)
Refer to the hftsmap.c sample program for an example of the topics discussed in
this section.
HFSECHO sets the hft echo and break maps. Echoing displays the character
associated with a keystroke on the screen or performs the function associated
with a control. Breaking switches the input path from the monitor mode input
ring buffer to the unsolicited ASCII datastream flow. Echoing applies only to
KSR mode; breaking applies only to MOM mode. Echoing and breaking can be
selectively enabled for each ASCII code point and multibyte control sequence.
The default is to echo all characters and control sequences, but not to break
on any of them.
The HFSECHO operation is invoked by the following ioctl call:
int ioctl(fildes, HFSECHO, arg)
int fildes;
struct hfbuf *arg;
struct hfbuf
{
char *hf_bufp;
int hf_buflen;
};
The hf_bufp field points to an array of 32 integers. The hf_buflen field
contains the value 128 (0x80), which is the length of the array in bytes. The
first sixteen integers constitute the echo map; the second sixteen integers are
the break map.
Processed November 8, 1990 HFT(4,F) 39
HFT(4,F) AIX Technical Reference HFT(4,F)
Each of the two maps is treated as a set of bits. Bit 0 is the most
significant bit of the first integer. Bit 511 is the least significant bit of
the sixteenth integer. Each bit corresponds to an ASCII code point or
multibyte control. Bits 0 through 255 (0xFF) correspond to the single-byte
codes. Bits 256 (0x100) and higher correspond to multibyte control sequences,
as illustrated in Figure 15. Bit 511 (0x1FF) specifies whether to echo or
break on invalid and unsupported multibyte control sequences. See "data
stream" for a detailed explanation of each of the multibyte control sequences.
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
Figure 15. Bit Positions of ASCII Controls in Echo Map
For the echo map, a bit set to 1 means the character or control sequence is
echoed when a key that is mapped to it is pressed. The echo map is active only
in KSR mode and can be set only from KSR mode.
For the break map, a bit set to 1 means that the character or control sequence
is reported using the read system call instead of being placed in the input
ring buffer. Also, the SIGMSG signal is sent to the process to indicate that
input data is available. The break map is active only in monitor mode. (See
"Monitor Mode (MOM)" for a description of the input ring buffer.)
The echo and break maps are shared by all code pages. For P0 graphic code
points (0x20 to 0xFF), bits 32 to 255 (0x20 to 0xFF) of each map are used. For
other code pages, each half of the code page is associated with bits 128 to 255
(0x80 to 0xFF). For example, bit 160 (0xA0) specifies the echo or break status
of code points P0 0xA0, P1 0x20, P1 0xA0, P2 0x20, and P2 0xA0.
Set Keyboard Map (HFSKBD)
Refer to the hftskch.c, hftskfn.c, and hftskst.c sample programs for examples
of the topics discussed in this section.
HFSKBD sets the keyboard map. Most keys on the keyboard can be remapped,
changing the character or control sequence each key generates when pressed.
See "keyboard" for additional details. This is invoked by the following:
int ioctl(fildes, HFSKBD, arg)
int fildes;
struct hfbuf *arg;
struct hfbuf
{
char *hf_bufp;
int hf_buflen;
};
Processed November 8, 1990 HFT(4,F) 40
HFT(4,F) AIX Technical Reference HFT(4,F)
The hf_bufp field points to a hfkeymap structure, and hf_buflen contains its
length.
struct hfkeymap {
char hf_rsvd1 ;
char hf_nkeys;
struct hfkey {
char hf_kpos;
char hf_kstate;
struct hfkeyasgn
{
/* for single character */
char hf_pagenum; /* Code page */
char hf_character; /* Character to map */
#define hf_page hf_pagenum
#define hf_char hf_character
/* for function id */
#define hf_keyidh hf_pagenum /* high byte of id */
#define hf_keyidl hf_character /* low byte of id */
/* for character string */
#define hf_kstrl hf_character /* length of string */
}hf_keyasn;
} hfkey[HFNKEYS];
};
The hfkeymap structure can remap one or more keys, the number of which is
specified by the hf_nkeys field. This many hfkey structures follow. HFNKEYS,
which is used as the dimension for the hfkey array, is by default defined to be
1, allowing one key to be remapped. To change HFNKEYS, set its value in a
#define statement that comes before the #include <hft.h> statement.
The hfkey structure contains information for each key being remapped, such as
key position, shift states, and the type of remapping being done. The fields
in the hfkey structure are:
hf_kpos The key position number. See "keyboard."
hf_kstate This field is subdivided into three groups of bits:
HFMAPMASK
Defines the bits that specify the type of mapping to be
performed:
HFMAPCHAR Specifies mapping a single character to a key.
HFMAPNONSP Specifies mapping a nonspacing character to a
key. (See "Nonspacing Characters" for
information about nonspacing characters.)
HFMAPFUNC Specifies mapping a function ID to a key.
HFMAPSTR Specifies mapping a string of more than one
character to a key. Maximum string size is 256
bytes.
Processed November 8, 1990 HFT(4,F) 41
HFT(4,F) AIX Technical Reference HFT(4,F)
HFSHFMASK
Defines the bits that specify the shift state that applies to
the key being mapped:
HFSHFNONE Specifies the base state (no shift state)
HFSHFSHFT Specifies the shift state
HFSHFCTRL Specifies the Ctrl state
HFSHFALT Specifies the Alt state
HFSHFALTGR Specifies the Alt Gr (Alternate Graphics)
state.
HFCAPSL
Specifies whether the Caps Lock state affects the key. If
set, then when Caps Lock mode is on, the base state of a key
functions as the shift state, and the shift states functions
as the base state.
The hfkeyasgn structure specifies the key to be remapped and the character
codes generated when the key is pressed or released. The fields of this
structure differ depending on the value of the HFMAPMASK bits in hf_kstate:
HFMAPCHAR, HFMAPNONSP:
hf_page Specifies the code page
< P0 Display symbols 32-255
= P1 Display symbols 256-479
> P2 Display symbols 480-703
hf_char Specifies a character (also called a code point) in that code
page.
HFMAPSTR:
hf_page Specifies the code page
< P0 Display symbols 32-255
= P1 Display symbols 256-479
> P2 Display symbols 480-703
hf_kstrl Specifies (the length of the string in bytes) minus 1.
This is immediately followed by the string.
Note: Due to limitations of the hfkeymap structure, only one key can be
assigned a string value, and it must be the last key specified in the
hfkey array. This is because the structure itself does not contain
space for the variable-length string, but the string must immediately
follow the structure in memory.
See "Mapping Multiple Strings" if you wish to set more than one string using
HFSKBD. You can also make repeated HFSKBD ioctls with different assignments.
HFMAPFUNC:
hf_keyidh Specifies the high-order byte of the function ID.
hf_keyidl Specifies the low-order byte of the function ID.
Processed November 8, 1990 HFT(4,F) 42
HFT(4,F) AIX Technical Reference HFT(4,F)
The following list gives the function IDs for each of the functions that can be
assigned to keys. See "Multi-Byte Controls" for more details about these
functions.
ID Name
0x0000 - 0x00FE
(PFK) Issues the Programmable Function Key sequence for PF key 1
(ID = 0x0000) through 255 (ID = 0x00FE).
0x0101 (CUU) Moves the application cursor up one line.
0x0102 (CUD) Moves the application cursor down one line.
0x0103 (CUF) Moves the application cursor forward one character.
0x0104 (CUB) Moves the application cursor backward one character.
0x0105 (CBT) Moves the application cursor to the previous horizontal tab
stop or beginning of field.
0x0106 (CHT) Moves the application cursor to the next horizontal tab stop
or beginning of field.
0x0107 (CVT) Moves the application cursor down one vertical tab stop.
0x0108 (HOME) Moves the application cursor to the first line, first
character in the presentation space.
0x0109 (LL) Moves the application cursor to the last line, first character
in the presentation space.
0x010A (END) Moves the application cursor to the last line, last character
in the presentation space.
0x010B (CPL) Moves the application cursor to the first character of the
previous line.
0x010C (CNL) Moves the application cursor to the first character of the
next line.
0x0151 (DCH) Deletes the character over the application cursor.
0x0152 (IL) Inserts one line following the line of the application cursor.
0x0153 (DL) Deletes the line of the application cursor.
0x0154 (EEOL) Erases to the end of the line.
0x0155 (EEOF) Erases to the next tab stop.
0x0156 (CLEAR) Erases all characters from the presentation space.
0x0157 (INIT) Restores the initial state of the virtual terminal. (See
the description of RIS in "Multi-Byte Controls.")
0x0162 (RI) Performs one line reverse index control.
0x0163 (IND) Performs one line index control.
0x01FF (IGNORE) Sends no information when the key is pressed.
Note: On the U.S. 101-key keyboard, the left Alt key produces the Alt shift
state, and the right Alt key produces the Alt Gr shift state. The
default keyboard mapping for the Alt and Alt Gr states is identical for
all keys.
If a U.S. 101-key keyboard is attached, then mapping the Alt state of a key
automatically causes the same mapping to be assigned to the Alt Gr state. This
allows the two Alt keys on the U.S. keyboard to function identically for most
applications. If you want to remap both the Alt and Alt Gr states of a key,
you must remap the Alt state first, then the Alt Gr state. Software written
Processed November 8, 1990 HFT(4,F) 43
HFT(4,F) AIX Technical Reference HFT(4,F)
primarily for keyboards other than the U.S. keyboard should remap the states in
this order to ensure compatibility.
MAPPING MULTIPLE STRINGS:
The hft device driver allows any number of keys to be assigned string values
with HFSKBD. You do this by setting up your own key map buffer instead of
using the hfskeymap structure.
The following example shows a data structure which can be used to map two keys
to strings:
char map [] = {
0x00, /* Reserved */
0x02, /* Number of keys = 2 */
/* Key pos, shift state, code page, string length, string */
108, HFMAPSTR, '<', 3, '\033', 'O', 'M',
105, HFMAPSTR, '<', 3, '\033', 'O', 'm'
};
This data structure can be used to assign key position 108 and 105 to string
"Escape O M" and "Escape O m", respectively.
TERMIO SUPPORT
Input modes described in "termio" supported are INLCR, IGNCR, ICRNL, IUCLC,
IXON, and IXANY. Input modes IGNBRK and BRKINT are not supported because there
is no Break key. Input modes IGNPAR, PARMRK, and INPCK are not supported
because parity is not provided. Input mode ISTRIP is not supported either.
ICRNL is supported by using the keyboard remap facility to change the code sent
by the Enter (Return) and Ctrl-M keys. Also, the implementation of IXON is
different. If the user presses Ctrl-S while output is being performed on the
screen, the output does not stop until the end of the current write system
call.
Output modes supported are OPOST, ONLCR, and OCRNL. The delay insertion,
parity, and stop bit modes are not supported.
Line discipline modes supported are ISIG, ICANON, ECHO, ECHOE, ECHOK, ECHONL,
NOFLSH, and Enhanced Edit Mode.
Screen paging is also supported using the TCGLEN and TCSLEN ioctl operations.
When paging is active, the contents of the buffer supplied by the write call
are written out in page-size pieces.
Other ioctl operations supported by hft include TCXONC and TCFLSH. The TCSBRK
operation is not supported.
SELECT SUPPORT
The hft device driver supports the select system call in the following manner:
Processed November 8, 1990 HFT(4,F) 44
HFT(4,F) AIX Technical Reference HFT(4,F)
o Read selects are satisfied when input data is available.
o Write selects are always satisfied immediately.
o Exception selects are never satisfied, or hang indefinitely if no timeout
value is specified.
See "select" for more information about this system call.
CONSIDERATIONS FOR HFT EMULATION
Refer to the sample program hftctl.c for examples of the topics discussed in
this section.
Communicating with an emulated or remote hft device presents a unique situation
because the ioctl system call cannot be used. This is a result of the fact
that ioctl passes data directly to the virtual terminal subsystem, bypassing
the data stream. An hft emulator is usually connected through a pseudo-TTY
device, which means that all communication with it must be done through the
data stream. Pseudo-TTY devices are discussed under "pty."
Therefore, two special multibyte control sequences can be used in place of
invoking the ioctl system call, allowing applications to request an emulated
hft to perform the ioctl operations. However, the hft device driver, which
controls the local console, does not recognize these control sequences; you
must still use ioctl to perform these operations on an hft device that is not
emulated.
Both of these multibyte control sequences begin with a virtual terminal data
(VTD) header. VTDs are explained under "Virtual Terminal Commands."
To perform an hft ioctl operation whether or not the hft is emulated, an
application should do the following:
1. Determine whether the hft device is being emulated. If the call ioctl
(fildes, IOCTYPE, 0) returns the value DD_PSEU, then fildes is a pseudo-tty
device, which means that fildes may be connected to an hft emulator.
Otherwise, the hft device is not emulated.
2. If the hft is not emulated, then issue a regular ioctl system call, as
outlined in "ioctl Operations."
3. If the hft is emulated, then do the following:
a. Set the pseudo-tty for raw data. That is, disable all input and
output processing. This is necessary because the control sequences can
contain binary data that would be misinterpreted by the pseudo-tty
device driver as ASCII control codes. See "termio" for details.
b. Use the write system call to send an hfctlreq VTD structure,
immediately followed by the request structure, if any, that would
Processed November 8, 1990 HFT(4,F) 45
HFT(4,F) AIX Technical Reference HFT(4,F)
normally be pointed to by the ioctl arg parameter. The hfctlreq
structure contains the following fields:
Field Value
hf_intro.hf_typehi HFCTLREQH
hf_intro.hf_typelo HFCTLREQL
Field Value
hf_request The request type.
hf_arg_len The length of the argument structure that
follows the hfctlreq VTD, or 0 if none.
hf_rsp_len The maximum length of the response data
structure that is to be returned with the
hfctlack VTD. This value is 0 if no response
buffer is expected.
c. Read (using the read system call) until an acknowledgement VTD is
received. This acknowledgement takes the form of an hfctlack
structure, which is sometimes followed by a returned data structure,
depending on the operation requested. The hfctlack structure contains
the following fields:
Field Value
hf_intro.hf_typehi HFCTLACKH
hf_intro.hf_typelo HFCTLACKL
hf_request The type of request that is being acknowledged.
hf_ret_code The error code: 0 indicates successful
completion; a nonzero value is the value that
is normally found in errno.
hf_arg_len The length of the response data structure that
follows the hfctlack VTD, or 0 if none. The
length must not exceed the value of hf_rsp_len
that was specified in the hfctlreq structure.
AIX PS/2 HFT COMPATIBILITY WITH AIX RT
In general, hft for AIX PS/2 is compatible with hft for AIX RT. However, there
are a few areas of difference which are due to differences in the hardware of
these systems, or due to the absence of a VRM Operating System layer on the
PS/2. Highlights of the differences are as follows:
DIFFERENCES DUE TO HARDWARE:
Processed November 8, 1990 HFT(4,F) 46
HFT(4,F) AIX Technical Reference HFT(4,F)
o There is no support for Lighted Program Function Keys (LPFKs), dials, or
tablets.
o The keyboard click is not settable.
o The sound volume is not settable.
o Only the VGA adapter of the PS/2 is supported. It has characteristics
similar to the EGA adapter on the RT, however the PS/2 implementation
allows a choice of two built-in fonts, one utilizing hardware character
generation and the other using software character formation. The hardware
font is faster and more efficient than the software font, but is limited to
code page P0. The software font is slower and uses more CPU cycles, but is
capable of generating all 616 symbols in code pages P0, P1, and P2.
o There is no /dev/bus pseudo-device. Applications that use Monitor Mode
will get the virtual address of the display adapter memory returned in the
structure used to enter Monitor Mode (the HFSMON ioctl).
DIFFERENCES DUE TO VRM:
There is limited reconfigurability of physical devices and drivers. It is not
possible to replace individual virtual terminal subsystem components.
Relationships and allocation of hft channels and IODNs are not the same.
Applications should not make any assumptions about this or about the ordering
of these numbers. For compatibility, applications should use open and accept
the virtual terminal that is allocated.
Compatibility Table
The following table shows the compatibility between AIX PS/2 and AIX RT for
each hft operation. Refer to the list of explanatory "Notes" which follows the
table.
HFT Operation RT Notes
Compatible?
HFQEIO Query I/O Error Yes
HFQDEV Query Device No 1,2
HFRCONF Reconfigure
HFADDLOC Not 1,4
Implemented
HFADDSOUND Not 1,4
Implemented
HFADDDISPLAY Not 1,4
Implemented
HFDELDISPLAY Not 1,4
Implemented
HFADDFONT Not 1,4
Implemented
HFCHGKBDRATE Yes
Processed November 8, 1990 HFT(4,F) 47
HFT(4,F) AIX Technical Reference HFT(4,F)
HFT Operation RT Notes
Compatible?
HFCHGKBDDEL Yes
HFCHGLOCRATE Yes
HFCHGCLICK Yes 6
HFCHGVOLUME Yes 6
HFKEYMAP No 8
HFDISPMAP No 8
HFECHOMAP No 8
HFDEFAULT Not 1,4
Implemented
HFSETDD Not 1,4
Implemented
HFADDDIALS Not 1,3
Implemented
HFADDLPFK Not 1,3
Implemented
HFCHNGDMA Not 1,3
Implemented
HFGCHAN Get Channel Number Yes
HFSECHO Set Echo/Break Maps Yes
HFSKBD Set Keyboard Map Yes
HFGETID Get Virtual Term ID Yes
HFQUERY Query Command
HFQDEVID Yes
HFQPDEV Yes
HFQLOC Yes
HFQLPFK Yes 9
HFQDIALS Yes 9
HFQPRES Yes
HFQHFT Yes
HFQDMA Not 1,3
Implemented
HFESOUND Yes
HFDSOUND Yes
HFSMON Yes 7
HFCMON Yes
HFQSMGR Yes
HFCSMGR Yes
HFMDMA Not 1,3
Implemented
HFKLED Set Keyboard LEDs Yes
HFLOTH Set Loc Threshold Yes
HFSOUND Sound Yes
HFCANSND Cancel Sound Yes
HFCHGDSP Change Phys Disp Yes 6
HFKSRPRO KSR Protocol Yes
Modes
HFMOMPRO MOM Protocol Yes
Modes
Processed November 8, 1990 HFT(4,F) 48
HFT(4,F) AIX Technical Reference HFT(4,F)
HFT Operation RT Notes
Compatible?
HFTDZ Set Tablet Dead Yes 9
Zones
HFLPFKS Enab/Disab LPFK's Yes 9
HFDIALS Set Dial Yes 9
Granularity
HFCHARSET Uniq1/Uniq 2 Yes
HFCOLORPAL Set KSR Color Yes
Palette
HFFONT Change Fonts Yes
HFCURSOR Cursor Yes
Representation
HFMOMREQ Scrn Req Input Yes
Ring
HFMOMREL Screen Release Yes
Notes:
1. Produces a compile time error if specified.
2. Not implemented due to dependence on VRM.
3. No PS/2 Hardware to support this function.
4. Not implemented in Release 1 of AIX PS/2.
5. Implemented in a different way due to dependence on VRM.
6. Capability does not exist; a null success status is returned and no action
is taken.
7. Function now returns an address in the response structure.
8. User programs will need to be modified to use an address instead of an
IOCN due to dependence on the VRM.
9. No PS/2 hardware for these functions, however the correct values will be
returned to reflect lack of hardware.
Byte-Ordering Considerations
There are several instances in the hft driver where a binary integer is being
passed in a string of characters. The integer will always be arranged such
that the most significant byte comes first and the least significant byte comes
last, regardless of the machine that is being used to execute the code.
You should not use a union to align an integer with a byte field. This
technique is machine-dependent and is not portable between RT and PS/2.
Processed November 8, 1990 HFT(4,F) 49
HFT(4,F) AIX Technical Reference HFT(4,F)
Consider an integer containing the hex value 0x12345678 stored at memory
location 8. The stored memory image of this integer differs between RT and
PS/2:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
Figure 16. Stored memory differences between RT and PS/2
This difference in byte-ordering can get you in trouble. Assume that the
character field x is known to contain an integer.
The following code should not be used:
union
{
char c[4];
int i;
} u;
char x[4];
u.c[0] = x[0];
u.c[1] = x[1];
u.c[2] = x[2];
u.c[3] = x[3];
What does "u.i" contain? On the RT, it contains the integer "x" and can safely
be used. On the PS/2 it does not contain the integer "x" in the proper order.
Bytes 0 and 3 are swapped and bytes 1 and 2 are swapped.
To get the correct results on both RT and PS/2, you should use code similar to
the following:
int i;
char x[4];
i = ((x[0] << 24) + (x[1] << 16) + (x[2] << 8) + (x[3]));
This technique pulls the bytes from the character field in the proper order and
uses the machine-independent shift instruction to position them in the integer.
It will work properly for both types of machine. The same technique can be
applied to retrieving char[2] and char[3] fields.
Sample Programs from AIX RT hft
Some of these sample programs did contain unions of integers and byte fields.
They will not execute properly on the PS/2 and have been modified to follow the
guidelines in Byte-Ordering Considerations. User programs based on these
samples should be checked to see if such unions are being employed.
Processed November 8, 1990 HFT(4,F) 50
HFT(4,F) AIX Technical Reference HFT(4,F)
DOS Merge
Programs operating under control of DOS Merge participate in the HFT screen
manager ring for hot-keying but otherwise cannot be controlled by HFT ioctls or
VTD sequences. /dev/hft/* In this book: "ioctlx, ioctl, gtty, stty," "fonts,"
"data stream," and "termio."
Processed November 8, 1990 HFT(4,F) 51