From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Sat, 2 Aug 2025 00:36:36 +0000 (+0300)
Subject: Improve lptdrv documentation
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=e9a2aa595d337cbb655aefd99ef3f9a41558d45b;p=qbasicapps.git

Improve lptdrv documentation
---

diff --git a/Networking/LPT communication driver/index.org b/Networking/LPT communication driver/index.org
index edb8565..5ba91f0 100755
--- a/Networking/LPT communication driver/index.org	
+++ b/Networking/LPT communication driver/index.org	
@@ -31,31 +31,61 @@ By utilizing only three wires and software controlled bit-banging
 algorithm, custom, comparatively simple, cheap and long cable can be
 built to connect 2 computers in a DIY network setup.
 
-* LPT Communication Driver (LPTDRV)
+* LPT Communication Driver
 
-LPTDRV is a memory-resident driver designed to facilitate
-communication between computers using parallel printer ports
-(LPT). Developed in assembly language, this driver hooks into the
-system's IRQ 0 to periodically monitor LPT port statuses, allowing for
-data exchange without requiring constant polling by applications.
 
-Features and Capabilities:
+The LPT Communication Driver is a Terminate and Stay Resident (TSR)
+driver designed to facilitate communication between computers using
+parallel printer ports (LPT). This driver uses bit-banging to send and
+receive data serially over the LPT port, utilizing only three wires
+for communication.
 
-- Interrupt-Driven Communication :: By utilizing hardware interrupts,
-  LPTDRV efficiently handles data transmission and reception without
-  overwhelming system resources.
+Driver hooks into the system's IRQ 0 to ensure that system timer
+always keeps executing it in the background. While operating as a
+background process, it periodically monitors LPT port to detect
+incoming transmission. When transmission is detected, driver receives,
+decodes and stores it into preallocated 5000 byte receive buffer.
 
-- Buffer Management :: It features separate 5000-byte buffers for
-  incoming and outgoing data, providing smooth asynchronous
-  communication.
+Applications can then communicate with the driver on their own
+schedule using INT 63h to poll for and retrieve received messages, if
+any. Applications can also send outgoing messages into 5000 byte
+driver outbox memory buffer. Thereafter driver will transmit those
+messages in background mode over the wire.
+
+Download:
+- Source code: [[file:lptdrv.asm][lptdrv.asm]]
+- Compiled binary: [[file:lptdrv.com][lptdrv.com]]
+
+
+** Driver API
+*** Deactivate the driver
+
+*Parameters*:
+: AH = 0
+
+*Returns*: None
+
+*** Activates the driver
+
+*Parameters*:
+: AH = 1
+
+*Returns*: None
+
+*** Retrieve downloaded data from the driver's input buffer
+
+*Parameters*:
+: AH = 2
+: ES:DI = Pointer to the location where downloaded data should be placed
+
+*Returns*:
+: AX : Number of bytes downloaded
 
-- Protocol Handling :: Implements a simple protocol for data encoding
-  and decoding over parallel ports, demonstrating practical low-level
-  communication techniques.
+*** Upload data to the driver's output buffer for transmission
 
-- Ease of Integration :: Applications can communicate with the driver
-  using INT 63h, making it straightforward to integrate into existing
-  software.
+*Parameters*:
+: AH = 3
+: DS:SI: Pointer to the data to be uploaded
+: CX: Number of bytes to upload
 
-- Speed :: During my testing, it achieved a maximum transfer speed of
-  approximately 12 Kb/s.
+*Returns*: None
diff --git a/Networking/LPT communication driver/test.ASM b/Networking/LPT communication driver/test.ASM
index e98e680..efcb500 100644
--- a/Networking/LPT communication driver/test.ASM	
+++ b/Networking/LPT communication driver/test.ASM	
@@ -3,28 +3,28 @@
 org 100h
 
 mov     ah, 1   ; activate driver
-int	63h
+int	    63h
 
 l1:
-mov	di, last
-mov	ah, 2
-int	63h
-cmp	ax, 0
+mov	    di, last
+mov	    ah, 2
+int	    63h
+cmp	    ax, 0
 je	l2
 
-cmp	byte [last], 0
+cmp	    byte [last], 0
 jne	l3
 call	send4kb
 jmp	l2
 l3:
 
-add	ax, last
-mov	di, ax
-mov	byte [ds:di], 36
+add	    ax, last
+mov	    di, ax
+mov	    byte [ds:di], 36
 
-mov	ah, 9
-mov	dx, d1
-int	21h
+mov 	ah, 9
+mov 	dx, d1
+int	    21h
 
 
 l2:
@@ -39,34 +39,34 @@ mov     ah, 0
 int     16h
 cmp     al, 27
 je      quit
-cmp	al, 13
-je	send
-cmp	al, 32
-je	TestSpeed
+cmp	    al, 13
+je	    send
+cmp	    al, 32
+je	    TestSpeed
 
 jmp     l1
 
 quit:
 mov     ah, 0   ; deactivate driver
-int	63h
+int	    63h
 ret
 
 send:
 mov     cx, d1 - d2
-mov	si, d2
-mov	ah, 3
-int	63h
+mov	    si, d2
+mov	    ah, 3
+int	    63h
 jmp	l1
 
 send4kb:
-mov	cx, 4096
-mov	si, last
-mov	ah, 3
-int	63h
+mov	    cx, 4096
+mov	    si, last
+mov	    ah, 3
+int	    63h
 ret
 
 TestSpeed:
-mov	byte [last], 0
+mov	    byte [last], 0
 mov     cx, 0
 
 l5:
@@ -74,11 +74,11 @@ push	cx
 call	send4kb
 l4:
 mov     di, last + 1
-mov	ah, 2
-int	63h
-cmp	ax, 0
+mov	    ah, 2
+int	    63h
+cmp 	ax, 0
 je      l4
-pop	cx
+pop	    cx
 
 mov     dx, d3
 mov     ah, 9
@@ -95,6 +95,6 @@ jmp	l1
 
 d3      db '. $'
 d4      db 13, 10, 'done', 13, 10, '$'
-d2	db 'Quick brown fox jumped over the lazy dogs. 0123456789ABCDEF'
-d1	db 13,10,'Data recieved:'
+d2	    db 'Quick brown fox jumped over the lazy dogs. 0123456789ABCDEF'
+d1	    db 13,10,'Data recieved:'
 last: