Nut/OS  4.10.3
API Reference
Terminal Emulator.

Virtual terminal emulator. More...

Collaboration diagram for Terminal Emulator.:

Data Structures

struct  _WINSIZE
struct  _TERMDCB
 Terminal device control block structure. More...

Defines

#define LCD_CMDBYTE   0x0401
#define LCD_CMDWORD16   0x0402
#define LCD_CMDWORD32   0x0403
#define LCD_DATABYTE   0x0405
#define LCD_DATAWORD16   0x0406
#define LCD_DATAWORD32   0x0407
#define LCD_SETCOOKEDMODE   0x0413
 Set raw mode.
#define LCD_GETCOOKEDMODE   0x0414
 Query raw mode.
#define LCD_SET_AUTOLF   0x0415
#define LCD_GET_AUTOLF   0x0416
#define TIOCGWINSZ   0x0501
#define TIOCSWINSZ   0x0502
#define LCD_MF_CURSORON   0x00000001UL
 Cursor on flag.
#define LCD_MF_COOKEDMODE   0x00020000UL
 Control character interpretation on flag.
#define LCD_MF_AUTOLF   0x00040000UL
 Control automatic break into next line on line end.
#define LCD_MF_AUTOSCROLL   0x00080000UL
 Control automatic scrolling at end of display.
#define LCD_MF_INVERTED   0x10000000UL
#define ESC_CHAR   "\x1B"
#define ESC_POS   ESC_CHAR "Y"
#define ESC_UP   ESC_CHAR "A"
#define ESC_DOWN   ESC_CHAR "B"
#define ESC_RIGHT   ESC_CHAR "C"
#define ESC_LEFT   ESC_CHAR "D"
#define ESC_CLRHOME   ESC_CHAR "E"
#define ESC_HOME   ESC_CHAR "H"
#define ESC_CLREND   ESC_CHAR "J"
#define ESC_CLREOL   ESC_CHAR "K"
#define ESC_CLRSTART   ESC_CHAR "d"
#define ESC_CLRSOL   ESC_CHAR "o"
#define ESC_INSCHAR   ESC_CHAR "@"
#define ESC_INSLINE   ESC_CHAR "L"
#define ESC_DELCHAR   ESC_CHAR "P"
#define ESC_DELLINE   ESC_CHAR "M"
#define ESC_RLF   ESC_CHAR "I"
#define ESC_CURSORON   ESC_CHAR "e"
#define ESC_CURSOROFF   ESC_CHAR "f"
#define ESC_INVERTON   ESC_CHAR "i"
#define ESC_INVERTOFF   ESC_CHAR "n"
#define ESC_SPECIALSET   ESC_CHAR "F"
#define ESC_DEFAULTSET   ESC_CHAR "G"
#define ESC_ACTIVE   ESC_CHAR "R"
#define ESC_SLEEP   ESC_CHAR "S"
#define ESC_CLR   ESC_CLRHOME
 Deprecated, use ESC_CLRHOME.

Typedefs

typedef struct _WINSIZE WINSIZE
typedef struct _TERMDCB TERMDCB

Functions

void TermRefresh (TERMDCB *dcb)
int TermIOCtl (NUTDEVICE *dev, int req, void *conf)
 Perform special LCD control functions.
int TermInit (NUTDEVICE *dev)
 Initialize the terminal device.
int TermWrite (NUTFILE *fp, CONST void *buffer, int len)
 Write data to a terminal device.
int TermWrite_P (NUTFILE *fp, PGM_P buffer, int len)
 Write data from program space to a terminal device.
NUTFILETermOpen (NUTDEVICE *dev, CONST char *name, int mode, int acc)
 Open a terminal device.
int TermClose (NUTFILE *fp)
 Close a device or file.

Detailed Description

Virtual terminal emulator.

The virtual terminal driver allows to use a LC or VF display for standard I/O. It supports VT52 control codes.


Define Documentation

#define LCD_CMDBYTE   0x0401

Definition at line 51 of file term.h.

Referenced by TermIOCtl().

#define LCD_CMDWORD16   0x0402

Definition at line 52 of file term.h.

Referenced by TermIOCtl().

#define LCD_CMDWORD32   0x0403

Definition at line 53 of file term.h.

Referenced by TermIOCtl().

#define LCD_DATABYTE   0x0405

Definition at line 54 of file term.h.

Referenced by TermIOCtl().

#define LCD_DATAWORD16   0x0406

Definition at line 55 of file term.h.

Referenced by TermIOCtl().

#define LCD_DATAWORD32   0x0407

Definition at line 56 of file term.h.

Referenced by TermIOCtl().

#define LCD_SETCOOKEDMODE   0x0413

Set raw mode.

Definition at line 57 of file term.h.

Referenced by TermIOCtl().

#define LCD_GETCOOKEDMODE   0x0414

Query raw mode.

Definition at line 58 of file term.h.

Referenced by TermIOCtl().

#define LCD_SET_AUTOLF   0x0415

Definition at line 59 of file term.h.

Referenced by TermIOCtl().

#define LCD_GET_AUTOLF   0x0416

Definition at line 60 of file term.h.

Referenced by TermIOCtl().

#define TIOCGWINSZ   0x0501

Gets the window size

Definition at line 63 of file term.h.

Referenced by TermIOCtl().

#define TIOCSWINSZ   0x0502

Sets the window size

Definition at line 66 of file term.h.

#define LCD_MF_CURSORON   0x00000001UL

Cursor on flag.

Definition at line 69 of file term.h.

#define LCD_MF_COOKEDMODE   0x00020000UL

Control character interpretation on flag.

Definition at line 70 of file term.h.

Referenced by TermIOCtl(), and TermOpen().

#define LCD_MF_AUTOLF   0x00040000UL

Control automatic break into next line on line end.

Definition at line 71 of file term.h.

Referenced by TermIOCtl().

#define LCD_MF_AUTOSCROLL   0x00080000UL

Control automatic scrolling at end of display.

Definition at line 72 of file term.h.

#define LCD_MF_INVERTED   0x10000000UL

display inverted characters on grafic displays

Definition at line 73 of file term.h.

#define ESC_CHAR   "\x1B"

Definition at line 76 of file term.h.

#define ESC_POS   ESC_CHAR "Y"

Definition at line 79 of file term.h.

#define ESC_UP   ESC_CHAR "A"

Definition at line 80 of file term.h.

#define ESC_DOWN   ESC_CHAR "B"

Definition at line 81 of file term.h.

#define ESC_RIGHT   ESC_CHAR "C"

Definition at line 82 of file term.h.

#define ESC_LEFT   ESC_CHAR "D"

Definition at line 83 of file term.h.

#define ESC_CLRHOME   ESC_CHAR "E"

Definition at line 84 of file term.h.

#define ESC_HOME   ESC_CHAR "H"

Definition at line 86 of file term.h.

#define ESC_CLREND   ESC_CHAR "J"

Definition at line 87 of file term.h.

#define ESC_CLREOL   ESC_CHAR "K"

Definition at line 88 of file term.h.

#define ESC_CLRSTART   ESC_CHAR "d"

Definition at line 89 of file term.h.

#define ESC_CLRSOL   ESC_CHAR "o"

Definition at line 90 of file term.h.

#define ESC_INSCHAR   ESC_CHAR "@"

Definition at line 92 of file term.h.

#define ESC_INSLINE   ESC_CHAR "L"

Definition at line 93 of file term.h.

#define ESC_DELCHAR   ESC_CHAR "P"

Definition at line 94 of file term.h.

#define ESC_DELLINE   ESC_CHAR "M"

Definition at line 95 of file term.h.

#define ESC_RLF   ESC_CHAR "I"

Definition at line 96 of file term.h.

#define ESC_CURSORON   ESC_CHAR "e"

Definition at line 98 of file term.h.

#define ESC_CURSOROFF   ESC_CHAR "f"

Definition at line 99 of file term.h.

#define ESC_INVERTON   ESC_CHAR "i"

Definition at line 100 of file term.h.

#define ESC_INVERTOFF   ESC_CHAR "n"

Definition at line 101 of file term.h.

#define ESC_SPECIALSET   ESC_CHAR "F"

Definition at line 102 of file term.h.

#define ESC_DEFAULTSET   ESC_CHAR "G"

Definition at line 103 of file term.h.

#define ESC_ACTIVE   ESC_CHAR "R"

Definition at line 104 of file term.h.

#define ESC_SLEEP   ESC_CHAR "S"

Definition at line 105 of file term.h.

#define ESC_CLR   ESC_CLRHOME

Deprecated, use ESC_CLRHOME.

Although wrong, we keep it for now in order not to break existing code.

Definition at line 111 of file term.h.


Typedef Documentation

typedef struct _WINSIZE WINSIZE

Definition at line 116 of file term.h.

typedef struct _TERMDCB TERMDCB

Terminal device control block type.

Definition at line 128 of file term.h.


Function Documentation

void TermRefresh ( TERMDCB dcb)
int TermIOCtl ( NUTDEVICE dev,
int  req,
void *  conf 
)

Perform special LCD control functions.

Parameters:
devIdentifies the device that receives the device-control function.
reqRequested control function. May be set to one of the following constants:
  • LCD_CMDBYTE Send command byte to display. Parameter conf points to an u_char value containing the command byte.
  • LCD_CMDWORD16 Send 16 bit command word to display. Parameter conf points to an uint16_t value containing the command bytes. The most significant byte is send first.
  • LCD_CMDWORD32 Send 32 bit command byte to display. Parameter conf points to an uint32_t value containing the command bytes. The most significant bytes are send first.
  • LCD_DATABYTE Send raw data byte to display. Parameter conf points to an u_char value containing the data byte.
  • LCD_DATAWORD16 Send 16 bit raw data word to display. Parameter conf points to an uint16_t value containing the data bytes. The most significant byte is send first.
  • LCD_DATAWORD32 Send 32 bit raw data word to display. Parameter conf points to an uint32_t value containing the data bytes. The most significant bytes are send first.
  • LCD_SETCOOKEDMODE Set terminal control character mode. Parameter conf points to an uint32_t value containing 0 (off) or 1 (on).
  • LCD_GETCOOKEDMODE Query terminal control character mode. Parameter conf points to an uint32_t value receiving 0 (off) or 1 (on).
confPoints to a buffer that contains any data required for the given control function or receives data from that function.
Returns:
0 on success, -1 otherwise.

Definition at line 318 of file term.c.

References _TERMDCB::dcb_modeflags, _TERMDCB::dcb_nrows, _TERMDCB::dcb_vcols, _NUTDEVICE::dev_dcb, _TERMDCB::dss_command, _TERMDCB::dss_write, LCD_CMDBYTE, LCD_CMDWORD16, LCD_CMDWORD32, LCD_DATABYTE, LCD_DATAWORD16, LCD_DATAWORD32, LCD_GET_AUTOLF, LCD_GETCOOKEDMODE, LCD_MF_AUTOLF, LCD_MF_COOKEDMODE, LCD_SET_AUTOLF, LCD_SETCOOKEDMODE, TIOCGWINSZ, _WINSIZE::ws_col, _WINSIZE::ws_row, _WINSIZE::ws_xpixel, and _WINSIZE::ws_ypixel.

int TermInit ( NUTDEVICE dev)

Initialize the terminal device.

Prepares the device for subsequent writing.

Application should not call this function directly, but use the stdio interface.

Parameters:
devIdentifies the device to initialize.
Returns:
0 on success, -1 otherwise.

Definition at line 406 of file term.c.

References _TERMDCB::dcb_nrows, _TERMDCB::dcb_smem, _TERMDCB::dcb_vcols, _NUTDEVICE::dev_dcb, _TERMDCB::dss_init, and malloc().

Here is the call graph for this function:

int TermWrite ( NUTFILE fp,
CONST void *  buffer,
int  len 
)

Write data to a terminal device.

Application should not call this function directly, but use the stdio interface.

The data may contain special character sequences, which are interpreted by the terminal device to control specific display functions:

  • Ctrl-H (ASCII 8) Backspace
  • Ctrl-J (ASCII 10) Linefeed
  • Ctrl-L (ASCII 12) Formfeed
  • Ctrl-M (ASCII 13) Carriage return

In addition a superset of VT52 control sequences are interpreted. Each sequence starts with an ESC character (ASCII 27):

  • ESC @ Insert space(*).
  • ESC A Move cursor up, ignored if on first line.
  • ESC B Move cursor down, ignored if on last line.
  • ESC C Move cursor right, ignored if on last column.
  • ESC D Move cursor left, ignored if on first column.
  • ESC E Clear display and move cursor home (*).
  • ESC H Move cursor home.
  • ESC I Reverse linefeed.
  • ESC J Erase to end of display.
  • ESC K Erase to end of line.
  • ESC L Insert line (*).
  • ESC M Delete line (*).
  • ESC P Delete character (*).
  • ESC R Reactivate display (*).
  • ESC S Put display in sleep mode (*).
  • ESC Y x+32 y+32 Move cursor to position.
  • ESC e Cursor on (*).
  • ESC f Cursor off (*).
  • ESC d Erase to start of display (*).
  • ESC o Erase to start of line (*).

(*) Not a VT52 command.

Parameters:
fpFile pointer to a previously opened device.
bufferPointer to the data bytes to be written.
lenNumber of bytes to write.
Returns:
The number of bytes written.
Todo:
TAB should be interpreted.
Bug:
Switching from graphic mode back to text mode will not work, because all escape sequences are ignored as soon as the graphic mode has been enabled. Applications should use _ioctl() functions to switch modes.

Definition at line 727 of file term.c.

References _NUTFILE::nf_dev.

int TermWrite_P ( NUTFILE fp,
PGM_P  buffer,
int  len 
)

Write data from program space to a terminal device.

Similar to TermWrite() except that the data is located in program memory.

Application should not call this function directly, but use the stdio interface.

Parameters:
fpFile pointer to a previously opened device.
bufferPointer to the data bytes in program space to be written.
lenNumber of bytes to write.
Returns:
The number of bytes written.

Definition at line 747 of file term.c.

References CONST, and _NUTFILE::nf_dev.

NUTFILE* TermOpen ( NUTDEVICE dev,
CONST char *  name,
int  mode,
int  acc 
)

Open a terminal device.

Application should not call this function directly, but use the stdio interface.

Parameters:
devPointer to device information structure.
nameFilename. Not used with terminal devices.
modeOperation mode. May be any of the following:
  • _O_BINARY Raw mode, no control character interpretation.
  • _O_TEXT Text mode. Control characters are interpreted and tranlated to LCD commands.
accAccess mode. Not used with terminal devices.
Returns:
Pointer to a NUTFILE structure or –1 to indicate an error.

Definition at line 770 of file term.c.

References _O_BINARY, _TERMDCB::dcb_modeflags, _NUTDEVICE::dev_dcb, LCD_MF_COOKEDMODE, malloc(), _NUTFILE::nf_dev, _NUTFILE::nf_fcb, _NUTFILE::nf_next, and NUTFILE_EOF.

Here is the call graph for this function:

int TermClose ( NUTFILE fp)

Close a device or file.

Application should not call this function directly, but use the stdio interface.

Parameters:
fpPointer to a previously opened NUTFILE structure.
Returns:
0 if the device was successfully closed or –1 to indicate an error.

Definition at line 799 of file term.c.

References free(), and NUTFILE_EOF.

Here is the call graph for this function: