

                ETHFLOP, COPYRIGHT (C) 2019-2024 MATEUSZ VISTE
                        http://ethflop.sourceforge.net


=== WHAT IS IT? ==============================================================

ETHFLOP is a DOS TSR that emulates a floppy disk drive. The emulated (virtual)
floppy disk is, in fact, stored on a server as a floppy image. All the
communication between ETHFLOP (the TSR) and the server (Linux or DOS) runs
over raw Ethernet. No need for any network configuration - the client (DOS)
PC only needs to have some kind of Ethernet adapter (physical or emulated, for
example through PLIP) and a suitable packet driver. The server and the client
must be connected to a common Ethernet segment (same LAN), preferrably on the
same switch. I recommend avoiding any kind of wireless connectivity, some
WIFI access points and bridges are filtering out raw Ethernet frames.

Shortly said, ETHFLOP:
 - emulates many types of floppies (360K, 720K, 1.2M, 1.44M... up to 31M)
 - requires only a working packet driver for network connectivity
 - presents a block device to DOS, almost indistinguishable from a real FDD
 - consumes less than 2 KiB of memory (and can be loaded high)

Compared to EtherDFS*, what are the downsides of using ETHFLOP?
 - a virtual floppy disk can be used only by one machine at a time (unless
   the virtual floppy is inserted as 'read-only')
 - the available space on a floppy is (obviously) limited, although ethflop
   supports virtual floppies of up to 31M, which is quite a lot of space

On the upside, ETHFLOP is significantly smaller than EtherDFS (less than 2K
resident, vs 7K for EtherDFS). It is also much more transparent to the OS
and applications so it should have higher compatibility, and it does not use
(too much) dark sorcery to do its job, meaning it is expected to work with
most existing DOS flavours.

*) EtherDFS can be found at http://etherdfs.sourceforge.net


=== HOW TO USE IT? ===========================================================

Quick-start instructions (example):

1. start the ETHFLOPD server on a PC in your LAN (Linux or DOS)
2. on your client (DOS) PC, load the TSR: "ETHFLOP A"
3. create a new 720K diskette: "ETHFLOP n720 MYFLOPPY"
4. "insert" the newly created diskette: "ETHFLOP i MYFLOPPY"
5. you can access the virtual floppy now through A:.

Read the program's help for more details (run ETHFLOP without arguments).


=== REQUIREMENTS =============================================================

 - DOS 2.x+
 - an 8088+ CPU and 4K of available RAM
 - an Ethernet adapter with its packet driver


=== ORIGINS ==================================================================

A couple of years ago I needed to hook my 8086 PC to a network drive, so I
could easily share files between my ancient PCs and the real world. I have
created EtherDFS then, a little TSR that connects to a network drive. EtherDFS
is awesome, but it is also extremely complex, for a variety of reasons: it
interacts with obscure, often undocumented, MS-DOS structures, it needs to
handle all kinds of file operations and, last but not least, it does a lot of
trickery to keep its resident size small.

While EtherDFS is perfectly suited for many use cases, I longed for a simpler
alternative for more basic needs. My oldest machines do not need access to
terabytes of data, their software often holds on a couple of floppy disks. So
I thought - why not go one level lower, and instead of emulating an entire
filesystem, create a virtual, Ethernet-backed floppy-like block device? And
that's exactly what ETHFLOP is about.


=== THE B: DRIVE STORY =======================================================

If you have a computer with a single floppy drive (A:), you might be tempted
to install ethflop under B:. Unfortunately, this is unlikely to work. On
single-floppy systems, MS-DOS installs a "ghost" drive under B:. All requests
sent for B: are then in fact redirected to A:, hence if ethflop would listen
under B: it would effectively see no requests. A possible workaround would be
to declare a non-existing secondary diskette drive in your BIOS, so DOS won't
hook B: itself.


=== STACK SIZE VS PACKET DRIVERS =============================================

ETHFLOP relies on your network card's packet driver to send Ethernet frames.
Some packet driver need much stack space to operate, others not. ETHFLOP
defaults to reserving a relatively large stack of 690 bytes for the needs of
the packet driver. Such cautious stack size is enough for all the packet
drivers I tested, but most packet drivers need much less. And perhaps there
are some packet drivers out there that might require more, who knows.

The amount of stack space ETHFLOP reserves is configurable through a hidden
option: when ETHFLOP is being installed, one can pass an extra "$X" argument,
where X is a digit from 1 to 9 representing the size of private stack that
should be reserved, in multiples of 128 bytes:

ETHFLOP A $1     --> installs ETHFLOP as A: and reserves 128 bytes of stack
ETHFLOP A $2     --> ...256 bytes of stack
ETHFLOP A $3     --> ...384 bytes of stack
etc

The minimum is "$1" (128 bytes). It is unlikely that any packet driver would
need more than "$9" (1152 bytes), but for truly extreme cases it is possible
to use "$@" which will reserve a stack of 2048 bytes.

Decreasing ETHFLOP's stack reduces its memory footprint at the risk that some
packet drivers might damage ETHFLOP. In such event ETHFLOP will not crash, but
it will likely loose its connectivity with the server. It will also detect the
stack overflow and output an error message next time the user tries to insert
or eject a virtual floppy, list available images or query the TSR status.

ETHFLOP records the maximum stack usage that occured during TSR's lifetime.
This information is shown by "ETHFLOP !". You may use it to set the optimal
stack size for your system. Note that stack usage may vary depending on the
type of disk operations that are performed, hence "ETHFLOP !" should be
consulted once some extensive usage of virtual floppy disks.


=== QUESTIONS & BUG REPORTS ==================================================

I have put a lot of effort into this software and did my best to ensure it
works as advertised. However, just like with any software, it is possible -
if not probable - that it still has some bugs. If you observe any unexpected
behavior or simply have a question about ETHFLOP, write me an email. You will
find pointers about how to do so on my web homepage: http://mateusz.viste.fr


=== LICENSE (MIT) ============================================================

ETHFLOP, Copyright (C) 2019-2024 Mateusz Viste

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


====================================================================== EOF ===
