hft
Purpose
Implements a high-function virtual terminal device.
Synopsis
#include <sys/hft.h>
Description
The hft device driver supports a virtual terminal concept
based on the virtual terminal subsystem of the Virtual
Resource Manager. The following information is intended
to supplement the discussion of the virtual terminal sub-
system in Virtual Resource Manager Technical Reference.
Additional information can also be found in the file
/usr/lib/samples/README.hft.
The virtual terminal concept supports the illusion that
more devices exist than are physically present and that
these devices have characteristics and features not nec-
essarily limited by the actual devices. In addition to
displays and keyboards, virtual terminals support loca-
tors, valuators, lighted programmable function keys, and
sound generators. Virtual terminals are logically inde-
pendent of each other but share physical resources over
time. The virtual terminal that can accept physical
input or modify the physical screen at a given time is
called the active virtual terminal.
The virtual terminal provides a model of a single ter-
minal 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 an RT ASCII
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 opti-
mizes 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:
o Reporting data from input devices such as locators
and valuators
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 S_IMPX
bit in the stat.h 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. Minor devices 2 and
higher are associated with additional hft physical termi-
nals, if there are any.
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.
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.
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 pro-
grams that use the hft virtual terminal subsystem. See
the file /usr/lib/samples/README.hft for more information
about these sample programs.
The following list can be used as a reference to locate
where specific topics are discussed:
CONTENTS OF HFT SECTION
Initial State . . . . . . . . . . . . . . . . . . 4-40
termio Support . . . . . . . . . . . . . . . . . 4-41
select Support . . . . . . . . . . . . . . . . . 4-41
ioctl Operations . . . . . . . . . . . . . . . . 4-42
Query I/O Error (HFQEIO) . . . . . . . . . . . . 4-42
Query Device (HFQDEV) . . . . . . . . . . . . . . 4-42
Reconfigure (HFRCONF) . . . . . . . . . . . . . . 4-45
Get Channel Number (HFGCHAN) . . . . . . . . . . 4-48
Set Echo and Break Maps (HFSECHO) . . . . . . . . 4-48
Set Keyboard Map (HFSKBD) . . . . . . . . . . . . 4-49
Set Japanese Keyboard Map (HFSJKBD) . . . . . . . 4-52
Get Virtual Terminal ID (HFGETID) . . . . . . . . 4-53
Query (HFQUERY) . . . . . . . . . . . . . . . . . 4-53
Query Device IDs Command . . . . . . . . . . . 4-54
Query Physical Device Command . . . . . . . . . 4-55
Query Locator Command . . . . . . . . . . . . . 4-57
Query LPFKs Command . . . . . . . . . . . . . . 4-58
Query Dials Command . . . . . . . . . . . . . . 4-58
Query Presentation Space Command . . . . . . . 4-59
Query HFT Device Command . . . . . . . . . . . 4-60
Query DMA Command . . . . . . . . . . . . . . . 4-60
Enable Sound Signal (HFESOUND) . . . . . . . . . 4-61
Disable Sound Signal (HFDSOUND) . . . . . . . . . 4-61
Enter Monitor Mode (HFSMON) . . . . . . . . . . . 4-61
Exit Monitor Mode (HFCMON) . . . . . . . . . . . 4-61
Query Screen Manager (HFQSMGR) . . . . . . . . . 4-62
Control Screen Manager (HFCSMGR) . . . . . . . . 4-62
DMA Move (HFMDMA) . . . . . . . . . . . . . . . . 4-64
Considerations for hft Emulation . . . . . . . . 4-66
Input . . . . . . . . . . . . . . . . . . . . . . 4-68
Untranslated Key Control . . . . . . . . . . . . 4-68
Input Device Report . . . . . . . . . . . . . . . 4-69
Adapter-Generated Input . . . . . . . . . . . . . 4-71
Output . . . . . . . . . . . . . . . . . . . . . 4-73
Protocol Modes . . . . . . . . . . . . . . . . . 4-73
Set Keyboard LEDs . . . . . . . . . . . . . . . . 4-75
Set Locator Thresholds . . . . . . . . . . . . . 4-76
Set Tablet Dead Zones . . . . . . . . . . . . . . 4-77
Set LPFKs . . . . . . . . . . . . . . . . . . . . 4-77
Set Dial Granularities . . . . . . . . . . . . . 4-78
Sound . . . . . . . . . . . . . . . . . . . . . . 4-78
Cancel Sound . . . . . . . . . . . . . . . . . . 4-79
Change Physical Display . . . . . . . . . . . . . 4-79
Keyboard Send-Receive Mode (KSR) . . . . . . . . 4-80
Character Set Definition . . . . . . . . . . . . 4-80
Set KSR Color Palette . . . . . . . . . . . . . . 4-81
Change Fonts . . . . . . . . . . . . . . . . . . 4-82
Cursor Representation . . . . . . . . . . . . . . 4-83
Monitor Mode (MOM) . . . . . . . . . . . . . . . 4-84
Entering Monitor Mode . . . . . . . . . . . . . . 4-84
Screen Request and Input Ring Buffer Definition . 4-85
Reading Input Data from the Ring Buffer . . . . . 4-86
Next Window Function . . . . . . . . . . . . . . 4-87
Exiting Monitor mode . . . . . . . . . . . . . . 4-87
Signals . . . . . . . . . . . . . . . . . . . . . 4-88
INITIAL STATE
When a new terminal is opened, it is initialized to a
known state. This initial state can be changed, if
desired. 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
IRM Not set
SRM Not set
TSM Not set
CLM Not set
AUTONL Set.
o Protocol Mode:
WRAP Set (wrap cursor at boundary)
HOSTPC Not set (do not return locator input)
XLATKBD Set (translate keyboard input)
HOSTS Not set (do not report keyboard status
change)
LPFKS Not Set (disable lighted programmable func-
tion key input)
DIALS Not set (disable dial or valuator input).
o Locator Threshold: 2.75 millimeters horizontal, 5.5
millimeters vertical.
o Font: Initially, and whenever the physical display
device is changed, this is set to be the first font
in the customized list of fonts that:
- Results in a presentation space of 80 columns by
25 rows, and
- Has a normal appearance (not bold or italic).
If no font meets these criteria, then the first font
that can be displayed on the device is chosen. All
alternate fonts are initialized to the selected font.
o Character mode color palette for both foreground and
background:
Entry Color
0 Black
1 Red
2 Green
3 Yellow
4 Blue
5 Magenta
6 Cyan
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.
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 sup-
ported 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 sup-
ported.
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 con-
tents 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:
o Read selects are satisfied when input data is avail-
able.
o Write selects are always satisfied immediately.
o Exception selects are never satisfied, or hang indef-
initely if no timeout value is specified.
See "select" for more information about this system call.
IOCTL OPERATIONS
The hft supports a number of operations issued by the
ioctl system call to provide access to sophisticated fea-
tures of the hft. See "ioctl" 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."
Query I/O Error (HFQEIO)
If an I/O operation or other system call to the hft fails
due to 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 suc-
cessful), -1 (indicating that the HFQEIO operation itself
failed), or the error code for the last hft I/O opera-
tion. See Virtual Resource Manager Technical Reference
for an explanation of the individual virtual terminal
error codes.
Query Device (HFQDEV)
Obtains detailed device information about the types of
devices that are associated with the virtual terminal.
For details about this query operation, see the Query
Device SVC in Virtual Resource Manager Technical Refer-
ence. This is invoked by the following:
int ioctl(fildes, HFQDEV, arg)
int fildes;
struct hfqdev *arg;
struct hfqdev
{
unsigned short hf_qdrsvd;
unsigned short hf_qdopts;
unsigned int hf_qdlen;
};
This ioctl operation stores information into an hfqdresp
structure that overlays the hfqdev structure in memory.
Only one option is recognized: the hf_qdopts field must
be set to the value 2. The hfqdresp structure contains
the following members:
Field Description
hf_vtrmiodn The virtual terminal resource manager
IODN.
hf_vtrmiocn The virtual terminal resource manager
IOCN.
hf_devtype The device type. The value in this field
is 0x0002 (shared device).
hf_devname[4| The device name. The value is ""VTRM""
for "Virtual Terminal Resource Manager."
hf_hwoffset The offset to hardware characteristics.
hf_devoffset The offset to the device characteristics.
hf_erroffset The offset to the error log.
The next eight fields contain information about the last
operation that was completed by the virtual terminal for
this virtual machine. For more detailed information
about these fields, see the discussion of the Query
Device SVC in Virtual Resource Manager Technical Refer-
ence.
hf_newics New Interrupt Control Status register
value.
hf_statflags Status flags.
hf_ovrncnt Overrun count.
hf_opresult Operation result.
hf_deviodn Device IODN.
hf_dataword1 Device-dependent data or command exten-
sion segment ID.
hf_dataword2 Device-dependent data or command exten-
sion address.
hf_dataword3 Device-dependent data.
hf_ddilen The length (in words) of the device-
dependent information.
hf_rc The return code from IPL or the
Define_Device SVC. A value of 0 indi-
cates a successful operation.
hf_smiocn The screen manager IOCN.
hf_vtmpiocn The virtual terminal mode processor IOCN.
hf_keyiodn The keyboard IODN.
hf_lociodn The locator IODN. This field is set at
IPL time. Note that the locator is
optional. If the locator is not used,
this field is set to 0.
hf_spkiodn The speaker IODN. This field is set at
IPL time.
hf_numfont The number of fonts. One font is sup-
plied by the VRM; however up to 31 addi-
tional fonts can be defined.
hf_fontiocn[i| The font IOCNs. Undefined font IOCN
fields are set to 0.
hf_numdisp The number of physical displays. This
field is completed at IPL time. The VRM
supports as many as 4 physical displays.
The next three fields (hf_devid, hf_deviodn, and
hf_deviocn) are repeated four times to accommodate addi-
tional displays. Fields in this array that are not used
are set to 0.
hf_physd[i|.hf_devid
Contains a value that is a code identi-
fier for a particular physical device,
such as a display adapter or monitor com-
bination, in use.
hf_physd[i|.hf_deviodn
The IODN for the physical display device.
hf_physd[i|.hf_deviocn
The IOCN for the virtual display driver.
hf_keymapiocn The IOCN that defines how key positions
map to characters.
hf_chrmapiocn The IOCN that defines how characters map
to display codes for the Unique 1 and
Unique 2 character sets.
hf_echomapiocn The IOCN that defines the echo and break
maps.
hf_initiocn The IOCN of the virtual terminal mode
processor initialization parameters.
Examples of these parameters include pro-
tocol modes, tab rack, and so on.
hf_dialsiodn The IODN of the valuator dial device
driver.
hf_lpfkiodn The IODN of the lighted program function
key device driver.
Reconfigure (HFRCONF)
A user program can reconfigure the virtual terminal to
include different real devices. Helpful information
about virtual terminal reconfiguration can be found in
the file /usr/lib/samples/README.conf. 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;
};
This command changes the configuration of the physical
terminal or the virtual terminal defaults. For example,
there can be up to four display devices, one locator, one
speaker, and up to 32 fonts associated with a real ter-
minal.
The hf_op field contains the requested operation. The
valid operations appear in the following list. These
reconfigure operations, with the exception of those fol-
lowed by an * (asterisk), take effect only for terminals
opened after the reconfiguration. The operations fol-
lowed by an asterisk take effect for the terminals that
are currently open as well as those opened after the
reconfiguration.
HFADDLOC Adds a real locator. hf_obj contains the
real locator device driver IODN.
HFADDSOUND Adds a real sound device. hf_obj contains
the real sound device driver IODN.
HFADDDISPLAY Adds a real display. The following fields
must also be set for this operation:
hf_obj The real display identifier
hf_iodn The display device driver IODN
hf_iocn The virtual display driver IOCN.
HFDELDISPLAY Deletes a real display. hf_obj contains
the real display identifier.
HFADDFONT Adds a font. hf_obj contains the font
IOCN.
HFCHGKBDRATE* Changes the keyboard typematic rate. Bits
24 - 31 of hf_obj indicate the keyboard
typematic rate. For the standard RT PC
keyboard, valid values are between 2 and
40 characters per second and can be incre-
mented in 1 character-per-second units.
The default value for the RT PC keyboard
is 14 characters per second.
HFCHGKBDDEL* Changes the keyboard typematic delay.
Bits 16 - 31 of hf_obj indicate the key-
board typematic delay. For the standard
RT PC keyboard, valid values are between
300 and 600 milliseconds and can be incre-
mented in 100 millisecond units. The
default value for the RT PC keyboard is
400 milliseconds.
HFCHGLOCRATE* Change locator sample rate. Bits 24 - 31
of hf_obj indicate the locator sample
rate. For the standard RT PC locator,
valid values are 10, 20, 40, 60, 80, and
100 samples per second. The default for
the RT PC locator is 60 samples per
second.
HFCHGCLICK* Turns the keyboard click mechanism on or
off. Bit 31 of hf_obj indicates whether
the speaker produces a sound when a key is
pressed. Sound is suppressed when bit 31
equals 0 and produced when bit 31 equals
1. The default for the RT PC keyboard is
keyboard click on.
HFCHGVOLUME* Sets the sound volume level. Bits 24 - 31
indicate the volume of sounds produced by
the speaker. For the standard RT PC
speaker, valid values are 0 (sound off)
and, 1 (low volume), 2 (medium volume) and
3 (high volume). The default for the
RT PC speaker is medium volume.
HFKEYMAP Replaces the position code map. hf_obj
contains the new position code map IOCN.
See the /usr/lib/samples/hft/hftkbdmap.c
file.
HFDISPMAP Replaces the character code maps for the
Unique 1 and Unique 2 character sets. See
the /usr/lib/samples/hft/hftchrmap.c file.
hf_obj contains the new unique character
code map IOCN.
HFECHOMAP Replaces the echo/break map. hf_obj con-
tains the new echo/break map IOCN. See
the /usr/lib/samples/hft/hftecbrmap.c
file.
HFDEFAULT Replaces miscellaneous default values.
hf_obj contains the new miscellaneous
defaults IOCN. See the
/usr/lib/samples/hft/hftmiscdef.c file.
HFSETDD Changes the default display. hf_obj con-
tains the real display identifier.
HFADDDIALS Adds a real dial device. hf_obj contains
the dial device driver IODN.
HFADDLPFK Adds a real lighted programmable function
key (LPFK) device. hf_obj contains the
LPFK device driver IODN.
HFCHNGDMA Changes the DMA start address and length.
hf_obj contains the new DMA start address,
and hf_infob contains the length of the
new DMA area.
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;
Set Echo and Break Maps (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 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 multi-byte 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.
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
multi-byte control. Bits 0 through 255 (0xFF) correspond
to the single-byte codes. Bits 256 (0x100) and higher
correspond to multi-byte control sequences, as illus-
trated in Figure 4-1. Bit 511 (0x1FF) specifies whether
to echo or break on invalid and unsupported multi-byte
control sequences. See "data stream" for a detailed
explanation of each of the multi-byte control sequences.
ol807038
Figure 4-1. 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)
Sets the keyboard map. Most keys on the keyboard can be remapped, changing
the character or control sequence each key generates when pressed. See "key-
board" 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;
};
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> state-
ment.
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 per-
formed:
HFMAPCHAR Specifies mapping a single character to a key.
HFMAPNONSP Specifies mapping a nonspacing character to a
key. (See "data stream" for information about
nonspacing characters.)
HFMAPFUNC Specifies mapping a function ID to a key.
HFMAPSTR Specifies mapping a string of more than one char-
acter to a key.
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
hf_char Specifies a character (also called a code point) in that code
page.
HFMAPSTR:
hf_page Specifies the code page
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. The virtual terminal subsystem supported by the VRM
allows any number of keys to be assigned string values, and you can you
can do so if you set up your own key map buffer instead of using hfkeymap.
HFMAPFUNC:
hf_keyidh Specifies the high-order byte of the function ID.
hf_keyidl Specifies the low-order byte of the function ID.
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 char-
acter 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 primarily for keyboards other than the U.S. keyboard should remap the
states in this order to ensure compatibility.
If the Japanese 106-key keyboard is attached, then access to the Alt Gr shift
state is not possible.
Set Japanese Keyboard Map (HFSJKBD)
Sets the Japanese keyboard map. This ioctl is designed to work with the
106-key Japanese keyboard and Japanese licensed program software only.
The HFSJKBD operation is invoked by the following ioctl system call.
int ioctl(fildes, HFSJKBD, arg)
The structures used in the HFSJKBD ioctl are them same as those in "Set Key-
board Map (HFSKBD)" with the following difference in the interpretation of
the shift states.
The Japanese keyboard has the following shift states:
o Roma-ji base
o Roma-ji shift
o Control
o Alternalte
o Kana base
o Kana shift.
For base and shift, the distinction between Roma-ji and Kana script systems
is determined by the Alt Gr bit in the hf_kstate field of the hfkey struc-
ture. This bit may be combined with the base or shift bit to indicate one of
four states. When this bit is 0, Roma-ji is assumed. When this bit is 1,
Kana is assumed.
Note: The Japanese keyboard does not have a Alt Gr state.
The following literals are defined for this ioctl:
HFSHFMASK Defines the bits that specify the shift state that applies to the
key being mapped.
HFROMBASE Specifies the base Roma-ji state
HFROMSHFT Specifies the shift Roma-ji state
HFSHFCTRL Specifies the Ctrl state
HFSHFALT Specifies the Alt state
HFKANBASE Specifies the base Kana state
HFKANSHFT Specifies the shift Kana state.
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 of the virtual terminal. The
hf_pgrp field is the process group ID; that is, the process ID of the ter-
minal group leader. The hf_chan field is the channel number that is also
returned by the HFGCHAN ioctl operation.
Query (HFQUERY)
This 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 expected response.
Note that each command and response structure begins with a virtual terminal
data (VTD) header. (See "Output" 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:
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 pos-
sible:
0x0401mmnn IBM 5151 Display and 5151 Display and
Printer Adapter
0x0402mmnn IBM 6153 Display and 6153 Display Adapter
0x0403mmnn IBM 5151 Display and 5154 Display Adapter
0x0404mmnn IBM 5154 Display and 5154 Display Adapter
0x0405mmnn IBM 6155 Display and 6155 Display Adapter
0x0406mmnn IBM 6154 Display and 6154 Display Adapter
0x0408mmnn IBM 5081 Display and 5081 Display Adapter
Note: The mm value indicates whether the adapter is
totally functional. When this value is 0x00, the
adapter is totally functional. Any other value indi-
cates 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 ter-
minal.
The response to this command gives the following information:
struct hfqphdevr
{
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
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:
HFHACOLOR 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).
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.
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.
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 LPFKS COMMAND: To query the LPFKs, use the hfqgraphdev structure with
fields set as follows:
Field Value
hf_intro.hf_typehi HFQLPFKSCH
hf_intro.hf_typelo HFQLPFKSCL
This command returns a hfdial_lpfk structure with the following fields:
Field Value
hf_intro.hf_typehi HFQLPFKSRH
hf_intro.hf_typelo HFQLPFKSRL
hf_numlpfks Number of LPFKs on the device.
hf_data2.lpfk.flags A set of 32 bits corresponding to each of the LPFKs.
Bits that are set to 1 indicate enabled LPFKs; bits set
to 0 indicate disabled LPFKs.
QUERY DIALS COMMAND: To query the dials, use the hfqgraphdev structure with
fields set as follows:
Field Value
hf_intro.hf_typehi HFQDIALSCH
hf_intro.hf_typelo HFQDIALSCL
This command returns a hfdial_lpfk structure with the following fields:
Field Value
hf_intro.hf_typehi HFQDIALSRH
hf_intro.hf_typelo HFQDIALSRL
hf_numdials Number of dials on the device.
hf_data2.granularity An array of sixteen 1-byte values giving the
granularity of each dial. Granularity is the number
of events per full 360°ree. revolution of the dial.
The values in the array represent powers of 2.
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. (Note that this operation is called "Query ASCII Codes and
Attributes" in Virtual Resource Manager Technical Reference.)
The hfqpresc structure is used for this command, and it contains the fol-
lowing fields:
Field Value
hf_intro.hf_typehi HFQPRESCH
hf_intro.hf_typelo HFQPRESCL
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.
Note: The returned attributes may be only a subset of the original attri-
butes specified for query. The subset in this case is those attributes actu-
ally supported by the physical device.
The response is returned in an hfqpresr structure, which contains the fol-
lowing 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 cur-
rently 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
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:
HF101KBD 101-key keyboard
HF102KBD 102-key keyboard
HF106KBD 106-key keyboard.
QUERY DMA COMMAND: This command queries the starting address and length of
the application's DMA area. To issue this command, use the hfqdmac structure
with fields set as follows:
Field Value
hf_intro.hf_typehi HFQDMACH
hf_intro.hf_typelo HFQDMACL
The command returns an hfqdmar structure with the following fields:
Field Value
hf_intro.hf_typehi HFQDMARH
hf_intro.hf_typelo HFQDMARL
hf_dmaaddr Starting address of the DMA area
hf_dmalen Length of the DMA area.
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;
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 fol-
lowing:
int ioctl (fildes, HFDSOUND, 0)
int fildes;
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;
};
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.
Exit Monitor Mode (HFCMON)
Releases monitor mode. This is invoked by the following:
int ioctl(fildes, HFCMON, 0)
int fildes;
Query Screen Manager (HFQSMGR)
Queries the screen manager. The file descriptor must be associated with a
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];
};
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. This command 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, the terminal becomes the head of the
ring.
Two key sequences switching between virtual terminals and control which ter-
minal 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 4-2. Pressing the Shift +
Action on the active terminal makes the last virtual terminal active. The b
in Figure 4-2 indicates this relationship.
ol811182
ol811183
Figure 4-2. 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 #2 cannot be accessed
from the active terminal #4 without first skipping to terminal #1 or terminal
#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
ordinarily makes it the active terminal.
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 deac-
tivated.
SMHIDE Hides the virtual terminal. This command marks the terminal iden-
tified 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 termi-
nal'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 (if possible),
but does not prevent the virtual machine attached to it from com-
municating with it. 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 con-
tents of the last virtual terminal that was hidden.
SMSCMD Sets the command virtual terminal. This command designates a ter-
minal as the command virtual terminal. The command virtual ter-
minal 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 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 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.
DMA Move (HFMDMA)
Specifies the source, destination, and length of a Monitor Mode DMA move data
operation. This is invoked by the following:
int ioctl(fildes, HFMDMA, arg)
int fildes;
struct hfmdma *arg;
struct hfmdma
{
uint hf_srcaddr; /* Virtual source address of DMA data */
uint hf_dmalen; /* Length of data to be moved by DMA */
uint hf_destaddr; /* Virtual destination address of DMA data */
}
This ioctl operation maps an application data area to segment E DMA space or
unmaps an application data area. Mapping occurs when the source address
specifies the application data area and the destination address specifies the
segment E space. Unmapping takes place when the addresses are reversed from
mapping. Pages are pinned when mapping takes place and unpinned during
unmapping.
The range of space available for segment E DMA depends on the amount of
memory installed in the system and on the amount of memory allocated to DMA
space by the HFCHNGDMA option of the HFRCONF ioctl operation (see "Recon-
figure (HFRCONF)").
Warning: Once a data space is mapped onto segment E space with this ioctl
operation, do not attempt to access the data space until after it is
unmapped. Otherwise, loss of data, unpredictable results, and permanent
depletion of system resources may occur.
CONSIDERATIONS FOR HFT EMULATION
Communicating with an emulated or remote hft device presents a unique situ-
ation 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 multi-byte 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 multi-byte control sequences begin with a virtual terminal data
(VTD) header. VTDs are explained under "Output."
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, imme-
diately followed by the request structure, if any, that would
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
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 struc-
ture 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 struc-
ture, which is sometimes followed by a returned data structure,
depending on the operation requested. The hfctlack structure con-
tains 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: zero indicates successful com-
pletion; a non-zero 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.
The file /usr/lib/samples/hft/hftctl.c contains a sample program that illus-
trates how to implement this procedure.
INPUT
Data read from an hft device with the read system call can contain not only
character data entered from a keyboard, but also input from other devices,
such as a locator, a tablet, valuators, and lighted programmable function
keys. Data from devices other than the keyboard is passed back from the read
system call in the form of special control sequences that are described in
this section.
Note: These control sequences contain binary data. To prevent the binary
data from being misinterpreted as ASCII control codes, set the terminal's
canonical processing off. See &ldq.ICANON&rdq. for details.
Untranslated Key Control
If keyboard input is received when HFXLATKBD is turned off, this control
sequence is returned. 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. The scan code and make/break keys are dependent upon hard-
ware and require knowledge of the physical keyboard in use. See "keyboard"
for additional information.
The structure of the untranslated key control is:
struct hfunxlate
{
char hf_esc;
char hf_lbr;
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
hf_scancode Scan Code (see "keyboard")
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)
Input Device Report
This control reports input data from the mouse, tablet, LPFKs, or valuator
dials. The data is reported in the form of an hflocator structure, and the
following sections describe the fields of this structure for each type of
input device.
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.
HFBUTTON3 Button 3 has been pressed.
hf_stype 0
TABLET REPORT
hf_esc ESC (0x1B)
hf_lbr "[" (0x5B)
hf_why "y" (0x79)
hf_deltax The absolute X coordinate of the tablet sensor.
hf_deltay The absolute Y coordinate of the tablet sensor.
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 The left button has been pressed.
HFBUTTON2 The right button has been pressed.
hf_stype 1
LPFK REPORT
hf_esc ESC (0x1B)
hf_lbr "[" (0x5B)
hf_why "y" (0x79)
hf_deltax The LPFK number.
hf_deltay Reserved.
hf_seconds Time of the 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 LPFK.
hf_stype 2
VALUATOR DIAL REPORT
hf_esc ESC (0x1B)
hf_lbr "[" (0x5B)
hf_why "y" (0x79)
hf_deltax The dial number.
hf_deltay The dial value delta. This is a signed integer value in the
dial's units of granularity (see "Set Dial Granularities").
hf_seconds Time of the 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 dial.
hf_stype 3
Adapter-Generated Input
Some adapters can return status information to MOM applications by way of a
ring buffer. This status information is placed in the ring buffer with a VTA
multi-byte control (ESC [ r). This feature is not available to KSR mode.
The information that immediately follows the control sequence includes a
1-byte queue ID and 20 bytes of data. Note that the hardware returns 16-bit
words and that the bit-numbering conventions are reversed. See IBM RT PC
Hardware Technical Reference for details on the data returned for each
adapter status entry.
+--------------------------------+------+-----------------------------------+
| Status | QID | Data |
+--------------------------------+------+-----------------------------------+
| FIFO mode entered | 0x01 | 0x03 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| PHIGS traversal started | 0x01 | 0x05 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| FIFO pick mode set | 0x01 | 0x07 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| CGA mode entered | 0x01 | 0x09 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Traversal stopped | 0x01 | 0x0B in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Single-step mode completed | 0x01 | 0x0F in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Echo cursor completed | 0x01 | 0x11 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Defined pointer echo completed | 0x01 | 0x13 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Remove cursor completed | 0x01 | 0x15 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Clear frame buffer completed | 0x01 | 0x17 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Load look-up table completed | 0x01 | 0x21 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Set pick window size completed | 0x01 | 0x27 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
+--------------------------------+------+-----------------------------------+
| Status | QID | Data |
+--------------------------------+------+-----------------------------------+
| Reset FIFO pick mode completed | 0x01 | 0x29 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Set blink mode completed | 0x01 | 0x2D in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Reset blink mode completed | 0x01 | 0x2F in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Initialization complete | 0x02 | 0x01 in first data byte, rest |
| | | reserved. |
+--------------------------------+------+-----------------------------------+
| Traversal complete | 0x03 | No data, all 20 bytes reserved. |
+--------------------------------+------+-----------------------------------+
| Pick occurred | 0x04 | Data words 1-5 set to reason |
| | | extension words 1-10. |
+--------------------------------+------+-----------------------------------+
| Buffer error | 0x05 | Data words 1-5 set to reason |
| FIFO overflow | | extension words 1-10. |
| Illegal graphic order | | |
| Illegal request code | | |
| Invalid page | | |
| Stack error | | |
| Traversal error | | |
+--------------------------------+------+-----------------------------------+
| PELPRO task completed | 0x06 | No data, all 20 bytes reserved. |
+--------------------------------+------+-----------------------------------+
| PELPRO pick | 0x07 | Data words 1-5 set to reason |
| | | extension words 1-10. |
+--------------------------------+------+-----------------------------------+
| PELPRO vertical synch. | 0x08 | No data, all 20 bytes reserved. |
+--------------------------------+------+-----------------------------------+
| FIFO half full | 0x09 | No data, all 20 bytes reserved. |
+--------------------------------+------+-----------------------------------+
| FIFO half empty | 0x0A | No data, all 20 bytes reserved. |
+--------------------------------+------+-----------------------------------+
| Synchronize | 0x0B | Data words 1-5 set to reason |
| | | extension codes 1-10. |
+--------------------------------+------+-----------------------------------+
OUTPUT
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 struc-
tures are sent to the virtual terminal using the write system call.
Each control structure is introduced by a virtual terminal data (VTD) char-
acter 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.
Note that hf_typehi and hf_typelo are called the major and minor data types
in Virtual Resource Manager Technical Reference. The values of hf_typehi and
hf_typelo are documented with each command.
Because the hfintro structure is an odd number of bytes in length, it is des-
ignated 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 refer-
ences 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.
Protocol Modes
Protocol modes 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. These defaults may be changed during configura-
tion with the HFRCONF operation.
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 spec-
ifies the mode represented by that bit to change.
hf_select[0| Mode selectors:
HFHOSTS
HFXLATKBD
hf_select[1| Mode selectors:
HFWRAP
HFLOCATOR
HFLPFKS
HFDIALS
HFDINTR
HFDINTRONLY
HFJKANA
hf_value[0| New mode values:
HFHOSTS
HFXLATKBD
hf_value[1| New mode values:
HFWRAP
HFLOCATOR
HFLPFKS
HFDIALS
HFDINTRONLY
HFJKANA
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
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
boardt statureturnedoi(seeh"Multi-Byte Controls").
If HFHOSTS mode is set, the key-
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. See
"Untranslated Key Control."
HFWRAP KSR A 1 bit (default) causes the
cursor to wrap when the presenta-
tion 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.
HFLPFKS KSR, MOM A 0 bit (default) disables LPFK
input. A 1 bit enables LPFK
input.
HFDIALS KSR, MOM A 0 bit (default) disables dial
(valuator) input. A 1 bit enables
dial input.
HFDINTR MOM A 0 bit (default) indicates that
display adapter status information
is not to be sent to the host. A
1 bit specifies that the display
status is to be sent.
HFDINTRONLY MOM A 0 bit (default) specifies not to
restrict the use of the MOM input
ring buffer. A 1 bit specifies to
restrict the use of the MOM input
ring buffer to display adapter
status information only.
HFJKANA KSR, MOM A 0 bit (default) disables Kana
shift state. A 1 bit enables Kana
input (for use with Japanese
licensed program only).
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.
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.
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 accumu-
lated 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 ter-
minal. When the status of the locator buttons change, the accumulated meas-
urements 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 hori-
zontal 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.
The hfloth structure is used for the locator threshold command, and it con-
tains the following fields:
Field Value
hf_intro.hf_typehi HFLOTHCH
hf_intro.hf_typelo HFLOTHCL
hf_sublen 2
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.
Set Tablet Dead Zones
Dead zones are areas of the tablet from which no input reports are generated.
Each virtual terminal can set its own dead zones.
Initially, both of the dead zone values are set to 0, making the entire
tablet active. Setting both values to 32767 completely disables tablet
input, as does turning off HFLOCATOR in the protocol mode definition (see
"Protocol Modes").
The hftdzone structure is used for this command, and it contains the fol-
lowing fields:
Field Value
hf_intro.hf_typehi HFTDZCH
hf_intro.hf_typelo HFTDZCL
hf_sublen 2
hf_subtype 1
hf_horizontal A 2-byte nonnegative value specified in units of 0.25
millimeters.
hf_vertical A 2-byte nonnegative value specified in units of 0.25
millimeters.
Set LPFKs
The hfdial_lpfk structure is used for this command, and it contains the fol-
lowing fields:
Field Value
hf_intro.hf_typehi HFLPFKSCH
hf_intro.hf_typelo HFLPFKSCL
hf_sublen 2
hf_subtype 1
hf_mask.keys A 4-byte bit mask numbered 0 to 31. Bits that are set
specify LPFK flag values to change.
hf_data2.lpfk.flags A 4-byte set of bits numbered 0 to 31. For LPFKs
selected by hf_mask.keys, a 0 bit disables the LPFK,
and a 1 bit enables the LPFK.
Set Dial Granularities
The hfdial_lpfk structure is used for this command, and it contains the fol-
lowing fields:
Field Value
hf_intro.hf_typehi HFDIALSCH
hf_intro.hf_typelo HFDIALSCL
hf_sublen 2
hf_subtype 1
hf_mask.dials A 4-byte bit mask numbered 0 to 31. Bits that are set
specify dial granularity values to change.
hf_data2.granularity An array of sixteen 1-byte values giving the
granularity of each dial. Granularity is the number
of events per full 360°ree. revolution of the dial.
The values in the array represent powers of 2, and
they can range from 2 to 8.
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 2
hf_subtype 1
hf_mode Mode:
HFSIGSOUND
If set, causes the SIGSOUND signal to be sent to the
process when this sound command is executed or dis-
carded. 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.
hf_dur Duration in 1/128 seconds.
hf_freq Frequency in hertz.
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 execute
all sound to this terminal 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 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 fol-
lowing fields:
Field Value
hf_intro.hf_typehi HFCANSNDCH
hf_intro.hf_typelo HFCANSNDCL
Change Physical Display
This command changes the physical display to which the virtual terminal is
logically attached.
The hfchgdsp structure is used for this command:
Field Value
hf_intro.hf_typehi HFCHGDSPCH
hf_intro.hf_typelo HFCHGDSPCL
hf_sublen 2
hf_subtype 0
hf_mode Bits 0-1 and 3-15 of these bytes are reserved. Bit 2
specifies the default or another value specified for the
physical display.
HFNONDEF If set, uses the identifier specified in
bytes 10-13 for the physical display. If not
set, no changes occur.
hf_rsvd1 Reserved.
hf_devid Physical display device identifier.
hf_rsvd2 Reserved.
Note: If the physical terminal is changed, it may be necessary to change the
TERM environment variable. See "TERM" and "terminfo."
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 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 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 fol-
lowing line. If the cursor happens to be on the bottom line of the presenta-
tion 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.
To set the KSR protocol modes, write a protocol mode control, which is
described under "Protocol Modes." Specify the type as HFKSRPROH, HFKSRPROL.
The following control sequences are valid only in a KSR-mode data stream.
Character Set Definition
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:
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 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 IBM RT PC Hardware Technical Reference for
information about the display adapter.
Change Fonts
When a virtual terminal is first opened, and whenever it is changed, this
assignment is made to the first font in the list of configured fonts. The
virtual terminal initially tries to select a font that results in a presenta-
tion space of 80 columns by 25 rows. The first font with a normal appearance
(not italics) that meets this criteria is chosen. If no fonts meet this cri-
teria, the first font that can be displayed on the particular device is
selected. All alternate fonts will be initialized to this chosen ID.
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.
If the change fonts request is accepted and the installed fonts are a dif-
ferent size than the previous fonts, the presentation space size is adjusted
to the number of rows and columns that fit on the physical display screen for
the new font size.
See the /usr/lib/samples/README.font file for information about defining and
selecting fonts.
The hffont structure is used for this request:
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 Physical font ID of first alternate font attribute.
hf_alt2 Physical font ID of second alternate font attribute.
hf_alt3 Physical font ID of third alternate font attribute.
hf_alt4 Physical font ID of fourth alternate font attribute.
hf_alt5 Physical font ID of fifth alternate font attribute.
hf_alt6 Physical font ID of sixth alternate font attribute.
hf_alt7 Physical font ID of seventh alternate font attribute.
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:
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.
MONITOR MODE (MOM)
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, 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 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 tempo-
rarily releasing the display. This is also accomplished using system calls.
While the user program is active to the display, it performs output oper-
ations 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 request I/O bus
access mode by opening the bus access pseudo device. See "bus" for more
information.
The next mode change that must be performed is to issue the HFSMON ioctl
operation to enable monitor mode signals SIGGRANT and SIGRETRACT, and to
specify the method that processes are to receive the signals. (See "Enter
Monitor Mode (HFSMON).")
Next, the program should write a protocol mode control, which is described
under "Protocol Modes," specifying the type HFMOMPROH, HFMOMPROL.
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
o Set Locator Threshold
o Set Locator Dead Zones
o Set Dials
o Sound
o Cancel Sound
o KSR Protocol
o MOM Protocol
o Screen Request
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 control.
This request uses the hfmomscreq structure, which contains the following
fields:
Field Value
hf_intro.hf_len The length of the request up to and including the ring
buffer.
hf_intro.hf_typehi HFMOMREQH
hf_intro.hf_typelo HFMOMREQL
hf_sublen 2
hf_subtype 0
hf_ringlen[2| Shows the length of the ring 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,
locator, LPFK, and valuator data contained in the buffer without issuing read
system calls.
The ring buffer structure (hfmomring, defined following) can be at any
location in memory aligned on a word boundary. hf_ringoffset is the differ-
ence 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 calcuate
hf_ringoffset.
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.
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 accommo-
date 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.
Reading Input Data from the Ring Buffer
The program should start 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 (modulo ring size), then the ring buffer is full.
If hf_ovflow == 0xff, then an overflow condition exists. The overflow condi-
tion 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 Int and Quit keys
(see "termio"). These keys are designated using HFSECHO. Thus, by desig-
nating 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, including the ring
buffer, minus 3.
hf_intro.hf_typehi HFMOMRELH
hf_intro.hf_typelo HFMOMRELL
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 disabled programs from disrupting the next window func-
tion.
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 acti-
vated again with the Next Window key, the program receives a SIGGRANT signal.
In other words, the 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.
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. This is
especially important if the virtual terminal is open by another process, such
as the parent process, which is often the command shell. 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 make sure that no monitor
mode signals have been sent to this process or other process in the terminal
group in error.
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.
SIGMSG Informs the user program that data has been placed into a previously
empty input buffer.
Files
/dev/hft/*
Related Information
In this book: "ioctl," "fonts," "data stream," "config," and "termio."
The discussion of the virtual terminal subsystem in Virtual Resource Manager
Technical Reference.
Keyboard Description and Character Reference.