Memory Buffer Device

This Generic IO Device uses blocks of memory for input and/or output. The source code is in LIB\GENIO\Buffer.fth. This is not a circular buffer system. After a buffer has been used, the read and write pointers are not reset. You must reset the buffer pointers using the IOCTL functions.

As of VFX Forth build 2380, this code has been overhauled. If this causes you problems, the file BUFFER.old.FTH contains the previous (but now unsupported) version. The major changes are:

  1. More error checking.
  2. The KEY operation (and hence ACCEPT blocks if no data is available.
  3. The KEY? operation returns the number of unread bytes.
  4. The EMIT? operation returns the number of unwritten bytes in the buffer..
  5. The close operation is protected if the device is already closed.
  6. The GENIO ReadEx function is implemented.
  7. The Textbuff-sid GENIO structure has been documented.
  8. IOCTL functions have been added. See later for details.

Note that the ACCEPT operation does not echo. It is designed for extracting lines from saved input.

In order to create a device use the TEXTBUFF: definition given later. TEXTBUFF: is compatible with ProForth 2.

When opening a memory device the parameters to OPEN-GEN have the following meaning:

ADDR

Address of memory to use as buffer or ignored if dynamic allocation is required.

LEN

The maximum length of the memory image.

ATTRIBS

Bit 0: When zero the ADDR parameter is ignored and LEN bytes of memory are allocated from the heap; When 1, ADDR is used as the buffer address.

ATTRIBS

Bit 1: When 0, the buffer is FREEd on close; when 1, buffer is not freed on close.

struct textbuff-sid     \ -- len
Defines the length of a SID for a text buffer device.

  gen-sid +             \ handle=buffer, reuse field names of GEN-SID
  int tb-len            \ length of buffer
  int tb-attribs        \ attributes
  int tb-wr             \ address to write to, set by SETPOS, WRITE
  int tb-rd             \ address to read from set by SETPOS, READ
end-struct

: ff-tb         \ sid -- ; page/cls on display devices
This word is run by PAGE, CLS and FF-GEN. It resets (empties) the buffer.

: setpos-tb     \ x y mode sid -- ior
This word is run by SETPOS-GEN. Mode controls the x and y input values as follows.

0

x = #bytes written, y is ignored

-1

x=col, y=line for next character to be written

-2

x = #bytes read, y is ignored

-3

x=col, y=line for next character to be read

: getpos-tb     \ mode sid -- x y ior
This word is run by GETPOS-GEN. Mode controls the x and y return values as follows.

0

x = #bytes written, y = 0

-1

x,y for next character to be written

-2

x = #bytes read, y = 0

-3

x,y for next character to be read

-4

x = addr, y = len of unread data

-5

x = base address, y = size of data area

: ioctl-tb      \ addr len fn sid -- ior
This word is run by IOCTL-GEN and IOCTL-GIO. Fn controls the meaning of addr, len and the ior return value as follows:

0

Get buffer address: addr=0, len=0, ior=addr.

-1

Set write pointer: addr=0, len=offset, ior=0.

-2

Get write pointer: addr=0, len=0, ior=offset.

-3

Set read pointer: addr=0, len=offset, ior=0.

-4

Get read pointer: addr=0, len=0, ior=offset.

Device Creation

: initTextBuffSid       \ addr --
Initialise a previously allocated SID for a text buffer to the default values.

: textbuff:     \ "name" -- ; Exec: -- sid
Create a memory buffer called name.

: SizedTextBuff \ size -- sid|0
Allocates and opens a SID with a buffer of size size bytes, and returns the SID on success or 0 on failure.

: AllocTextBuff \ -- sid|0
Allocates and opens a SID with a default 16kb text buffer and returns the SID on success or 0 on failure.

: FreeTextBuff  \ sid --
Closes the SID and frees memory allocated by AllocTextBuff or SizedTextBuff.

File Device

This Generic IO Device operates on a disk file for input and/or output. The source code can be found in Lib\Genio\file.fth. Neither input nor output are buffered, so that this device should not be used when speed is required. A buffered version is available in Lib\Genio\FileBuff.fth.

In order to create a device use the FILEDEV: definition given later. FILEDEV: is compatible with ProForth 2.

When opening a file device the parameters to OPEN-GEN have the following meaning:


   ADDR            Address of string for filename.
   LEN             Length of string at ADDR.
   ATTRIBS         Open flags. These match the ANS r/o r/w etc.

The ReadEx function is now implemented.

Device Creation

struct /FileDev \ -- len
Returns the size of the sid structure for a file device.

: initFileDev   \ sid --
Initialise the sid for a file device. Mostly used when the structure has been allocated from the heap.

: filedev:      \ "name" -- ; Exec: -- sid
Create a File based Generic IO device in the dictionary.

NULL Device

This Generic IO Device is used as a bit bucket for unwanted output. When used as input KEY? is always false and and read will never return.

In order to create a device use the NULLDEV: definition given later.

When opening a null device the parameters to OPEN-GEN have no meaning.

Device Creation

: nulldev:        \ "name" -- ; Exec: -- sid
Create a NULL Generic IO device in the dictionary.