The UART alternative Substituting input from our PC’s serial-port for local keystrokes when we do ‘single-stepping’

Problem background Last time we saw how the x86’s trap-flag and debug-breakpoint registers could be used to support ‘single-stepping’ through program-code, to help us diagnose ‘bugs’ But a conflict arises when we attempt to debug code that handles keyboard-input (as in the ‘isrKBD’ routine for Project 2) Our debugger also uses keyboard input!

Use another control device? To circumvent the contention for keyboard control, we ask: can some other peripheral device substitute for our PC’s keyboard as a convenient ‘debugger-input’ source? Our classroom and CS Lab machines offer us a way to utilize their serial ports as an alternative device-interface for doing this type of debugger ‘single-stepping’ task

Kudlick Classroom Indicates a “null-modem” PC-to-PC serial cable connection lectern

PC-to-PC communications rackmount PC system student workstation KVM cable rackmount PC system student workstation KVM cable ‘ null-modem’ serial cable ethernet cables

Using ‘echo’ and ‘cat’ Our device-driver module (named ‘uart.c’) is intended to allow unprivileged programs that are running on a pair of adjacent PCs to communicate via a “null-modem” cable $ echo Hello > /dev/uart $ _ $ cat /dev/uart Hello _ Receiving…Transmitting…

Instructions in ‘isrDBG’ Our ‘usedebug.s’ used these instructions to support user-control of ‘single-stepping’ isrDBG:.code32# Our trap-handler for Debug Exceptions (interrupt-0x01) … # now await the ‘release’ of a user’s keypress kbwait: in$0x64, %al# poll keyboard-controller status test$0x01, %al# a new scancode has arrived? jzkbwait# no, continue polling controller in$0x60, %al# else input the new scancode test$0x80, %al# was it a key being released? jzkbwait# no, wait for a keypress ‘break’ …

UART’s line-status The PC’s serial-UART interface has a ‘status’ port and a ‘data’ port that behave in a manner that’s similar to those ports in the keyboard controller, so we can replace instructions in our ‘isrDBG’ procedure that accessed keyboard-controller ports with instructions that access the UART’s ports This avoids ‘contention’ for the keyboard!

How to program the UART? Universal Asynchronous Receiver-Transmitter Software controls the UART’s operations by accessing several registers, using the x86 processor’s ‘in’ and ‘out’ instructions See our CS630 course website at: for links to the UART manufacturer’s documentation and to an in-depth online programming tutorial

The UART registers Transmit Data Register Received Data Register Interrupt Enable Register Interrupt Identification Register FIFO Control Register Line Control Register Modem Control Register Line Status Register Modem Status Register Scratch Pad Register Divisor Latch Register 16-bits (R/W) 8-bits (Write-only) 8-bits (Read-only) 8-bits (Read/Write) 8-bits (Read-only) 8-bits (Write-only) 8-bits (Read/Write) 8-bits (Read-only) 8-bits (Read/Write) Base+0 Base+1 Base+2 Base+3 Base+4 Base+5 Base+6 Base+7 Base+0

UART’s I/O-port interface RxD/TxD IER IIR/FCR LCRMCRLSRMSRSCR The PC uses eight consecutive I/O-ports to access the UART’s registers 0x03F8 0x03F9 0x03FA 0x03FB 0x03FC 0x03FD 0x03FE 0x03FF scratchpad register modem status register line status register modem control register line control register interrupt enable register interrupt identification register and FIFO control register receive buffer register and transmitter holding register (also Divisor Latch register)

Comparing ‘STATUS’ ports Parity error Timeout error Data is from Mouse Keyboard locked Last byte went to 0x64 System initialized Input Buffer Full Output Buffer Full Error in Rx FIFO Transmitter idle THR empty Break interrupt Framing error Parity error Overrun error Received Data Ready Keyboard-controller’s status-register (i/o-port 0x64) Serial-UART’s line-status register (i/o-port 0x03FD)

Changes to ‘isrDBG’ isrDBG: … kbwait:# poll for OUTB==1 in$0x64, %al test$0x01, %al jzkbwait # input new scancode in$0x60, %al # ignore ‘make’ codes test$0x80, %al jzkbwait … isrDBG: … inwait:# poll for RDR==1 mov$0x03FD, %dx in%dx, %al test$0x01, %al jzinwait # input new data-byte mov$0x03F8, %dx in%dx, %al # send back a reply mov$’#’, %al out%al, %dx … keyboard controls single-steppingserial-UART controls single-stepping

Using a Linux application To control our debugger from another PC, we’ve written an application-program that runs under Linux, and it uses our ‘uart.c’ device-driver to circumvent privilege-level restrictions that Linux imposes on access to i/o-ports by code which runs in ‘ring3’ Our application is named ‘kb2cable.cpp’ It also illustrates use of ‘i/o multiplexing’

Linux Kernel Modules application standard “runtime” libraries call ret user spacekernel space Operating System kernel syscall sysret device-driver module Linux allows us to write our own installable kernel modules and add them to a running system call ret Runs in ring3 Runs in ring0

Linux char-driver components init exit fops function... Device-driver LKM layout registers the ‘fops’ unregisters the ‘fops’ module’s ‘payload’ is a collection of callback-functions having prescribed prototypes AND a ‘package’ of function-pointers the usual pair of module-administration functions

‘write()’ and ‘read()’ Obviously your driver-module’s ‘payload’ will have to include ‘methods’ (functions) which perform the ‘write()’ and ‘read()’ operations that applications will invoke You may decide your driver needs also to implement certain additional ‘methods’ For example, to support ‘i/o multiplexing’ our driver needed to implement ‘poll()’

UART initialization For two PC’s to communicate via the serial null-modem cable, their UART’s must be configured to use identical baudrates and data-formats (i.e., bps, 8-N-1) Our ‘uart.c’ driver performs this essential configuration in its ‘module_init()’ function Our ‘remotedb.s’ application does it in an extra ‘real-mode’ subroutine we’ve added

The sequence of steps # initializing the UART communication parameters for bps, 8-N-1 outb0x00, UART_BASE+1# Interrupt Enable register outb0xC7, UART_BASE+2# FIFO Control register outb0x83, UART_BASE+3# Line Control (DLAB=1) outw0x0001, UART_BASE+0# Divisor Latch register outb0x03, UART_BASE+3# Line Control (DLAB=0) outb0x03, UART_BASE+4# Modem Control l inbUART_BASE+6# Modem Status inbUART_BASE+5# Line Status inbUART_BASE+0# Received Data inbUART_BASE+2# Interrupt Identification (steps are described below in pseudo-code)

The i/o-multiplexing problem Normally when an application ‘reads’ from a device-file, that process will ‘sleep’ until some data is available from that device So if data becomes available on another device, it will not get processed because the application is ‘blocked’ from being given any CPU time by the OS scheduler This would spoil our ‘kb2cable’ application

‘read()’ causes ‘blocking’ ‘kb2cable’ application KeyboardSerial UART Whichever device this application attempts to read from, it will get ‘blocked’ until that device has some data to deliver read write

Do multiprocessing? One idea for getting around this ‘blocking’ problem would be to just use the ‘fork()’ system-call to create separate processes for reading from the different device-files Each process can sleep, and whichever process receives any new data will be awakened and scheduled for execution No changes needed to device-driver code

Different processes do ‘read()’ ‘kb2cable’ parent- process KeyboardSerial UART ‘kb2cable’ child-process read write Using multiple processes can overcome the ‘blocking-read’ problem, but complicates the code for program termination

Non-blocking ‘read’ It is possible for the application to request ‘non-blocking’ read-operations – i.e., any ‘read()’ calls will immediately return with 0 as return-value in case no data is available The standard-input device-driver already has support for this non-blocking option, and it can be easily added to the ‘read()’ function in our serial UART’s device driver

Driver-code modification ssize_t my_read( struct file *file, char *buf, size_t len, loff_t *pos ) { static intrxhead = 0; // in case no new data has been received, then either // return immediately if non-blocking mode is in effect // or else sleep until some new data arrives (or until // the user hits -C to cancel execution) if ( rxhead == ioread32( io + E1000_RDH ) { if ( file->f_flags & O_NONBLOCK ) return 0; if ( wait_event_interruptible( wq_recv, inb( UART_LINE_STATUS ) & 0x01 ) return –EINTR; } …

Uses ‘busy-waiting’ loop ‘kb2cable’ application Keyboard Serial UART read write Using the ‘nonblocking-read’ option overcomes the problem of a sleeping task, but it wastefully consumes the CPU time write

The ‘elegant’ solution The ‘select()’ system-call provides a very general scheme for doing i/o-multiplexing in a manner that avoids wasting CPU time or making the program-code complicated But it does require adding an extra driver ‘method’ – the so-called ‘poll()’ function

The ‘select()’ arguments Using ‘select()’ requires an application to setup an ‘fd_set’ object, which defines the set of file-descriptors whose activity needs to be monitored by the Linux kernel (in our ‘kb2cable’ application this would be just the two device-files’ handles (the keyboard and the serial UART) This ‘fd_set’ object becomes an argument

Using ‘select()’ in ‘kb2cable’ intkbd = STDIN_FILENO;// keyboard ID intuart = open( “/dev/uart”, O_RDWR );// device-file ID fd_set permset;// create an ‘fd_set’ object FD_ZERO( &permset );// initialize it to ‘empty’ FD_SET( kbd, &permset );// add keyboard to set FD_SET( uart, &permset );// and add the nic to set while (1){ fd_setreadset = permset; if ( select( 1+uart, &readset, NULL, NULL, NULL ) < 0 ) break; if ( FD_ISSET( kbd, &readset ) ) { /* process keyboard input */ } if ( FD_ISSET( uart, &readset ) ) { /* process network input */ } }

How it works The ‘readset’ argument to the ‘select()’ system-call lets the kernel know which device-drivers should have their ‘poll()’ method invoked Then each device-driver’s ‘poll()’ method will perform a test to determine if any new data is ready to be read from that device So the application calls ‘read()’ only when a device is ready with data immediately!

In-class demo As a proof-of-concept demonstration, we adding a “trivial” Interrupt Service Routine for keyboard interrupts to our ‘remotedb.s’ program (we called it ‘addkbisr.s’) Then we used our ‘kb2cable’ application running on an adjacent Linux machine to do ‘single-stepping’ through ‘linuxapp.o’ -- and through the added ‘isrKBD’ handler