9. The Serial group of Modules

This is the code that works our serial emulation. This needs to be very fast if we are to convince DOS that we have a very fast serial port.

9.1 base/serial/ser_defs.h Information

ser_defs.h: Include file for all files in the 'serial' subdirectory. Please send bug reports and bugfixes to marky@magmacom.com Please read the files in this 'serial' subdirectory for more info.

9.2 Remarks in base/serial/ser_defs.h

Extensions to serial debugging.

SER_DEBUG_MAIN (0 or 1) - extra debug output on the most critical information.

SER_DEBUG_HEAVY (0 or 1) - super-heavy extra debug output, including all ports reads and writes, and every character received and transmitted!

SER_DEBUG_INTERRUPT (0 or 1) - additional debug output related to serial interrupt code, including flagging serial interrupts, or PIC-driven code.

SER_DEBUG_FOSSIL_RW (0 or 1) - heavy FOSSIL debug output, including all reads and writes.

SER_DEBUG_FOSSIL_STATUS (0 or 1) - super-heavy FOSSIL debug output, including all status checks.

You must recompile dosemu everytime one of these constants are modified. Just type 'make' in the dosemu dir and it will recompile the changes only.

-----

IMPORTANT INFO about com[] variable array structure used in serial.c

Most of the serial variables are stored in the com[] array. The com[] array is a structure in itself. Take a look at the 'serial_t' struct declaration in the serial.h module for more info about this. Only the most commonly referenced global variables are listed here:

config.num_ser Number of serial ports active. com[x].base_port The base port address of emulated serial port. com[x].real_comport The COM port number. com[x].interrupt The PIC interrupt level (based on IRQ number) com[x].mouse Flag mouse (to enable extended features) com[x].fd File descriptor for port device com[x].dev[] Filename of port port device com[x].dev_locked Flag whether device has been locked

The arbritary example variable 'x' in com[x] can have a minimum value of 0 and a maximum value of (config.numser - 1). There can be no gaps for the value 'x', even though gaps between actual COM ports are permitted. It is strongly noted that the 'x' does not equal the COM port number. This example code illustrates the fact, and how the com[] array works:

for (i = 0; i < config.numser; i++) s_printf("COM port number %d has a base address of %x", com[i].real_comport, com[i].base_port);

9.3 base/serial/ser_init.c Information

ser_init.c: Serial ports initialization for DOSEMU Please read the README.serial file in this directory for more info!

Lock file stuff was derived from Taylor UUCP with these copyrights: Copyright (C) 1991, 1992 Ian Lance Taylor Uri Blumenthal <uri@watson.ibm.com> (C) 1994 Paul Cadach, <paul@paul.east.alma-ata.su> (C) 1994

Rest of serial code Copyright (C) 1995 by Mark Rejhon

The code in this module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is maintained by Mark Rejhon at these Email addresses: marky@magmacom.com ag115@freenet.carleton.ca

Maintainers:

Mark Rejhon <marky@ottawa.com>

9.4 Functions in base/serial/ser_init.c

These are the functions defined in base/serial/ser_init.c.

serial_init

This is the master serial initialization function that is called upon startup of DOSEMU to initialize ALL the emulated UARTs for all configured serial ports. The UART is initialized via the initialize_uart function, which opens the serial ports and defines variables for the specific UART.

If the port is a mouse, the port is only initialized when i

9.5 Items for Fixing in base/serial/ser_init.c

This needs more work before it is implemented into /etc/dosemu.conf as an 'rtscts' option.

9.6 base/serial/ser_ports.c Information

ser_ports.c: Serial ports for DOSEMU: Software emulated 16550 UART! Please read the README.serial file in this directory for more info!

Copyright (C) 1995 by Mark Rejhon

The code in this module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is maintained by Mark Rejhon at these Email addresses: marky@magmacom.com ag115@freenet.carleton.ca

9.7 Functions in base/serial/ser_ports.c

These are the functions defined in base/serial/ser_ports.c.

do_serial_in

The following function returns a value from an I/O port. The port is an I/O address such as 0x3F8 (the base port address of COM1). There are 8 I/O addresses for each serial port which ranges from the base port (ie 0x3F8) to the base port plus seven (ie 0x3FF). [num = abritary port number for serial line, address = I/O port address]

do_serial_out

The following function writes a value to an I/O port. The port is an I/O address such as 0x3F8 (the base port address of COM1). [num = abritary port number for serial line, address = I/O port address, val = value to write to I/O port address]

9.8 Items for Fixing in base/serial/ser_ports.c

Should clearing UART cause THRE int if it's enabled? */

-----

Fix the calculation assumption

-----

Is this safe to put this here? */

-----

Is this safe to put this here? */

9.9 base/serial/ser_irq.c Information

ser_irq.c: Serial interrupt services for DOSEMU Please read the README.serial file in this directory for more info!

Copyright (C) 1995 by Mark Rejhon

The code in this module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

9.10 Functions in base/serial/ser_irq.c

These are the functions defined in base/serial/ser_irq.c.

serial_int_engine

This function is the serial interrupts scheduler. Its purpose is to update interrupt status and/or invoke a requested serial interrupt. If interrupts are not enabled, the Interrupt Identification Register is still updated and the function returns. See pic_serial_run() below it is executed right at the instant the interrupt is actually invoked.

Since it is not possible to run the interrupt on the spot, it triggers the interrupt via the pic_request() function (which is in pic.c) and sets a flag that an interrupt is going to be occur soon.

Please read pic_serial_run() for more information about interrupts. [num = port, int_requested = the requested serial interrupt]

pic_serial_run

This function is called by the priority iunterrupt controller when a serial interrupt occurs. It executes the highest priority serial interrupt for that port. (Priority order is: RLSI, RDI, THRI, MSI)

Because it is theoretically possible for things to change between the interrupt trigger and the actual interrupt, some checks must be repeated.

serial_run

This is the main housekeeping function, which should be called about 20 to 100 times per second. The more frequent, the better, up to a certain point. However, it should be self-compensating if it executes 10 times or even 1000 times per second. Serial performance increases with frequency of execution of serial_run.

Serial mouse performance becomes more smooth if the time between calls to serial_run are smaller.

9.11 Remarks in base/serial/ser_irq.c

Linux code hackers: How do I detect a break signal without having to rely on Linux signals? Can I peek a 'break state bit'? Also, how do I 'turn on' and 'turn off' the break state, via an ioctl() or tcsetattr(), rather than using POSIX tcsendbrk()?

9.12 Items for Fixing in base/serial/ser_irq.c

how do we cancel a PIC interrupt, when we have come this far?

-----

Perhaps this can be modified to limit max chain length?

9.13 base/serial/int14.c Information

int14.c: Serial BIOS services for DOSEMU. Please read the README.serial file in this directory for more info!

Copyright (C) 1995 by Mark Rejhon

The code in this module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is maintained by Mark Rejhon at these Email addresses: marky@magmacom.com ag115@freenet.carleton.ca

9.14 Functions in base/serial/int14.c

These are the functions defined in base/serial/int14.c.

int14

The following function executes a BIOS interrupt 0x14 function. This code by Mark Rejhon replaced some very buggy, old int14 interface a while back. These routines are not flawless since it does not wait for a character during receive, and this may confuse some programs.

9.15 New Ideas for base/serial/int14.c

If any of you coders are ambitious, try thinking of the following: - Converting this into inline assembler and use direct port access

9.16 base/serial/fossil.c Information

fossil.c: FOSSIL serial driver emulator for dosemu.

Copyright (C) 1995 by Pasi Eronen. Portions Copyright (C) 1995 by Mark Rejhon

The code in this module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

9.17 Items for Fixing in base/serial/fossil.c

This really should be write-with-wait. */

9.18 include/serial.h Information

serial.h: Include file for port data array for DOSEMU serial. Please send bug reports and bugfixes to marky@magmacom.com Please read the files in the 'serial' subdirectory for more info.

9.19 Items for Fixing in include/serial.h

Why does a RX_BUFFER_SIZE of 256 cause slower performance than a size of 128?