[net] Add WD8013 NIC driver enhancements from TLVC

[ghaerr]

Adds TLVC's WD 8013 driver enhancements to ELKS, unchanged with the exception of CLI/STI statements. Thanks @Mellvik!

I have reviewed all changes but am unable to test. It appears most of the changes are much enhanced documentation, code cleanup, ability to force 8- or 16-bit operation, some overflow processing, and the ability to disable the driver from /bootopts.

@Mellvik, if you get a chance to pull the latest ELKS repo and test that this driver runs on one of your WD cards, that would be greatly appreciated!

The hard interrupt CLI/STI calls were updated to the newer approach of saving/restoring interrupt state. These were the only changes made.

Here's the complete diff between ELKS and TLVC now, for this driver:

55d54
< #include <arch/irq.h>
324d322
< 	flag_t flags;
352d349
< 		save_flags(flags);
361c358
< 		restore_flags(flags);
---
> 		set_irq();
591d587
< 	flag_t flags;
593d588
< 	save_flags(flags);
600c595
< 	restore_flags(flags);
---
> 	set_irq();
751a747
> 	//kputchar('I');

This is pretty cool that the ELKS can use the much-enhanced and better-maintained network drivers from TLVC! :)

[ghaerr]

On another note, the ELKS kernel is now within 336 bytes of running out of space in the near (main) code segment. All of the NIC drivers are currently running as near code. I'm not yet quite sure how, but moving all the network drivers over to FAR procs will help a lot, otherwise we might have to disable one of the three NICs from the standard distribution.

One issue is that all of the driver entry points from the filesystem (read, write, ioctl, select, etc) have to be near, although FAR "NICPROC" wrapper procedures could get written for those, I suppose. I may take a pass at defining NICPROC and adding that to some of the static functions in wd.c, but I can't test the results.

Having wd.c as C-only simplifies the conversion to NICPROCs somewhat, as the NE2K and 3C0 drivers have some ASM which complicates parameter passing and trampoline code. So I'll probably start with getting NICPROC working on WD.

What do you think @Mellvik? Is TLVC running low on free near code segment?

[Mellvik]

Adds TLVC's WD 8013 driver enhancements to ELKS, unchanged with the exception of CLI/STI statements. Thanks @Mellvik!

I have reviewed all changes but am unable to test. It appears most of the changes are much enhanced documentation, code cleanup, ability to force 8- or 16-bit operation, some overflow processing, and the ability to disable the driver from /bootopts.

In addition to these enhancements, the driver has much improved probing (including autodetection of bus width), recognizes (and works with) many more variants of the NIC and handles stop/start (as in net stop and net start sequences) reliably.

Adding display of the NICs soft configuration and allowing the bootopts settings to override the NIC's soft settings (like the 3Com and the Lance drivers) are on my wish list - and would be INITPROC. Having to boot into DOS to find the latest configuration setting is always a pain. I keep changing these settings all the time as I move NICs from one machine to another, and my notes are never up to date

@Mellvik, if you get a chance to pull the latest ELKS repo and test that this driver runs on one of your WD cards, that would be greatly appreciated!

I'll put that on my shortlist!

The hard interrupt CLI/STI calls were updated to the newer approach of saving/restoring interrupt state.
...

This is pretty cool that the ELKS can use the much-enhanced and better-maintained network drivers from TLVC! :)

Thanks for the IRQ update, @ghaerr. It will be merged back to the TLVC version.

-M

[Mellvik]

On another note, the ELKS kernel is now within 336 bytes of running out of space in the near (main) code segment. All of the NIC drivers are currently running as near code. I'm not yet quite sure how, but moving all the network drivers over to FAR procs will help a lot, otherwise we might have to disable one of the three NICs from the standard distribution.

One issue is that all of the driver entry points from the filesystem (read, write, ioctl, select, etc) have to be near, although FAR "NICPROC" wrapper procedures could get written for those, I suppose. I may take a pass at defining NICPROC and adding that to some of the static functions in wd.c, but I can't test the results.

Having wd.c as C-only simplifies the conversion to NICPROCs somewhat, as the NE2K and 3C0 drivers have some ASM which complicates parameter passing and trampoline code. So I'll probably start with getting NICPROC working on WD.

What do you think @Mellvik? Is TLVC running low on free near code segment?

A very 'clear and present danger' (apologies to Tom Clancy) @ghaerr. I believe the situation for TLVC may be even worse since we're not using BIOS for anything at all, and the IDE driver is quite voluminous, in particular when XT-IDE support is compiled in. So yes, the situation has been bad for quite some time and I keep manipulating the config file more or less continuously during development. Enabling live switching between NICs exacerbated the situation because some code had to be moved from INITPROC to near kernel (from initialization to open/close), but for development, that has been extremely valuable (although it does not work well on XT class machines). I'm worried about the complexity and possible performance penalty of 'FARing out' the network drivers, and my solution this far has been to remove the EL3 driver from the standard configuration. There are now 5 NIC drivers to chose from in TLVC and they cannot all be in there anyway, so making the EL3 optional seemed just natural. Also, the parallell driver - even though minimal - is going the same way.

IOW, moving driver code to 'far' is not on my list, but it's definitely an issue of great interest.

On a different (really unrelated) note - now that I've ran ELKS a little for the first time in years, among many nice enhancements I found that what I was immediately missing (apart from the reboot command :-) ) was TLVC's unlimited size bootopts file. What a difference it makes. Having been beaten up daily for more than 6 months, the implementation is really stable. The benefit? Organized into sections, easily readable (spacious), lots of documentation, many config-lines for different cards (NICs in particular, like 5 ne0 configurations), just comment-in-and-out as we go. It immediately becomes a developer's extra memory bank :-) .

All the XMS and buffer and floppy stuff we've worked on together has moved both systems miles ahead. And apropos memory, you may find it useful to take a look at the simple bit-vector UMB bootopts configuration used in TLVC - as an alternative to the more complicated mechanism in ELKS. My 2¢.

[ghaerr]

and the IDE driver is quite voluminous, in particular when XT-IDE support is compiled in.

You might want to take a look at the ELKS ATA driver (ata.c). It's written from scratch, super tiny, and works with ATA HD and XTE IDE (v1, v2 and XTCF versions), and supports partitions. It doesn't yet support read interrupts, but those could be added pretty easily. Looking at the mess that we inherited from the original directhd.c ELKS driver from 20 years ago, I believe it was a good idea to start from scratch. Now that I think of it, I need to remove directhd.c entirely, as a former quick review shows it doesn't do anything that ata.c now does.

TLVC's unlimited size bootopts file.

I reviewed your implementation at the time and increased ELKS to 1K bytes. IIRC I had some concern about something or other, but can't remember offhand the reason. The 1K byte enhancement was of course greatly needed. I'll take another look at this. My only comment is that promoting large /bootopts does slow the boot time down a bit. Do you support non-contiguous /bootopts, or does it still have to be contigous sectors?

You may find it useful to take a look at the simple bit-vector UMB bootopts configuration used in TLVC - as an alternative to the more complicated mechanism in ELKS.

Thanks! If it's less complicated, I'm all for it :) I'll take a look at it.

A very 'clear and present danger'
moving driver code to 'far' is not on my list, but it's definitely an issue of great interest.

See my comment in #2462 (comment). Very large parts of ELKS and TLVC are already FAR, and IMO none of the device drivers, except possibly the serial input, will see any degradation moving to a FAR model. I strongly suggest looking hard at (even slowly) moving all the TLVC NIC drivers to NICPROC. You can start with just a few dedicated leaf functions that don't call other (or many) other functions, then continue to add. If you have all the functions declared, you'll not run into any problems. I have changed elks/Makefile-rules to emit maximum warnings. It's only the case where code is generated to an unknown function of different segment where a crash would occur - and it would be immediate.

I'm happy to wait for NICPROC conversions to the TLVC drivers, it'll help us both.

[ghaerr]

@Mellvik
In addition to the driver enhancements, you've also done a great job of keeping up on the man pages. I brought a couple of your TLVC pages over, ftp, telnet and wd, thank you.

I ended up slightly rewriting them so that they don't mention TLVC or ELKS but read more generically (hope that's ok with you), unless something specific is mentioned (e.g. "See the TLVC Wiki..."). On that note, I'm not sure you're aware, but typically in the first line, e.g. .TH WD 4 TLVC, the third parameter is optional, and if its left off, then the man page reader automatically adds the system name in the middle of the displayed page - "ELKS Embeddable Linux Kernel Subset" in my case. This is nice because the man reader could be updated with a system version number, etc. in the future, thus automatically revising all displayed pages. I'm not sure if you revised man/eman for TLVC. If a third parameter is present, then it always overrides the man page reader display.

I also noticed several references to See Also ktcp(8). Is there a man page for that? If not, I can take a pass at it if you like.

I've updated several (non-networking) man pages as well, but don't recall what they were. I've a note to take a look at the differences.

[Mellvik]

I ended up slightly rewriting them so that they don't mention TLVC or ELKS but read more generically (hope that's ok with you), unless something specific is mentioned (e.g. "See the TLVC Wiki..."). On that note, I'm not sure you're aware, but typically in the first line, e.g. .TH WD 4 TLVC, the third parameter is optional, and if its left off, then the man page reader automatically adds the system name in the middle of the displayed page - "ELKS Embeddable Linux Kernel Subset" in my case. This is nice because the man reader could be updated with a system version number, etc. in the future, thus automatically revising all displayed pages. I'm not sure if you revised man/eman for TLVC. If a third parameter is present, then it always overrides the man page reader display.

Thanks @ghaerr, no, I didn't know that. And of course I don't mind. On the contrary, I do encourage 'neutralizing' the manpages as much as possible to aid portability. Appreciated.

I also noticed several references to See Also ktcp(8). Is there a man page for that? If not, I can take a pass at it if you like.

The ktcp manpage is little more than good intentions on my part. Actually, the reference may be a remnant from historical intentions. If you decide to take a stab at it, that would be great. Which reminds me: In your intro of the 'new' ktcp on ELKS you mentioned Slow Start as being off by default. I'm curious as to what triggered this perception. It has been a while (>12months) since I did this stuff, but my recollection is that both SS and CA are always on and are in fact inseparable. It is quite possible that your keen eye has caught something I should be aware of.

I've updated several (non-networking) man pages as well, but don't recall what they were. I've a note to take a look at the differences.

Thanks, appreciated.

[Mellvik]

and the IDE driver is quite voluminous, in particular when XT-IDE support is compiled in.

You might want to take a look at the ELKS ATA driver (ata.c). It's written from scratch, super tiny, and works with ATA HD and XTE IDE (v1, v2 and XTCF versions), and supports partitions. It doesn't yet support read interrupts, but those could be added pretty easily. Looking at the mess that we inherited from the original directhd.c ELKS driver from 20 years ago, I believe it was a good idea to start from scratch.

Thanks for the hint, @ghaerr, I'm very interested in this. I'll take a deep dive into the new driver, with particular focus on the indues I've encountered over the past two years with the current driver. IDE (aka ATA) is so simple yet has so many variants and idiosyncrasies in itself. Then comes XT-IDE with its own set of challenges. Including the fact that some XT-IDE cards, CF-IDE in particular, don't support interrupts. So while adding interrupt support is important, we end up with something akin to two drivers in one, because the flows of the interrupt-driven and the (current) polled variant are very different.

TLVC's unlimited size bootopts file.

I reviewed your implementation at the time and increased ELKS to 1K bytes. IIRC I had some concern about something or other, but can't remember offhand the reason. The 1K byte enhancement was of course greatly needed. I'll take another look at this. My only comment is that promoting large /bootopts does slow the boot time down a bit. Do you support non-contiguous /bootopts, or does it still have to be contigous sectors?

First, even a really big bootopts file will not slow down the boot process noticeably. Secondly, even though the bootopts file may technically be 10k or more (IIRC I've tested 20k), a very reasonable (big) file is less than 2k. And yes, it still has to be contiguous. To fight with the boot block size is never going to go away.

A very 'clear and present danger'
moving driver code to 'far' is not on my list, but it's definitely an issue of great interest.

See my comment in #2462 (comment). Very large parts of ELKS and TLVC are already FAR, and IMO none of the device drivers, except possibly the serial input, will see any degradation moving to a FAR model. I strongly suggest looking hard at (even slowly) moving all the TLVC NIC drivers to NICPROC. You can start with just a few dedicated leaf functions that don't call other (or many) other functions, then continue to add. If you have all the functions declared, you'll not run into any problems. I have changed elks/Makefile-rules to emit maximum warnings. It's only the case where code is generated to an unknown function of different segment where a crash would occur - and it would be immediate.

I'm happy to wait for NICPROC conversions to the TLVC drivers, it'll help us both.

Thanks for the encouragement - and examples, this is now on the top of my list - along with a critical look at the use of driver level interrupt protection.

[ghaerr]

In your intro of the 'new' ktcp on ELKS you mentioned Slow Start as being off by default. I'm curious as to what triggered this perception.

I'm probably in error. I quickly noticed USE_SWS as OFF, but that's Silly Window Syndrome handling. It appears there's no way to disable Slow Start nor Congestion Avoidance anyways, is that correct?

[ghaerr]

I'll take a deep dive into the new driver

Including the fact that some XT-IDE cards, CF-IDE in particular, don't support interrupts.

Yes, agreed. The ATA driver doesn't deal with interrupts, so it's much simpler, as revising C code for "interrupt driven" operation changes the approach to everything.

The new ATA driver (ata.c) was initially contributed by @fhendrikx. It was quite simple, well-designed and easy to understand, built for a new Solo/86 machine he is designing. That machine supports XTIDE with the port numbers arranged in a nonstandard way. Then came requests for "standard" XTIDE and XTCF. At that point, I dived in heavily and realized there's actually three different (hardware) versions of XTIDE out there, and ended up having to study the hell out of the XTIDE BIOS source code in order to understand what was happening. In order to test XTIDE CF, I actually rewrote some the PCem emulator to support both. Take a look at the various ELKS contributions for lots of discussion on XTIDE.

Out of all this came a big enhancement - the ability to boot from XTIDE/XT CF cards. This is a big deal for older systems, essentially a fast way to support large filesystems without having to get an old HD running, as well as quickly being able to copy or create large filesystems on the host for use on an XT.

So the ATA support is mostly for XTIDE and XTCF, but seems to handle HDs well, except for the problem of retries, which aren't performed. I'm not really sure how many retries ATA controllers will perform by default. I've also not calculated the time wasted waiting for an average HD sector versus floppy. Have you done that? What performance improvement is seen with TLVC on interrupt-driven HD access? And is that for both read and write? I'm interested in learning more about that.

[Mellvik]

In your intro of the 'new' ktcp on ELKS you mentioned Slow Start as being off by default. I'm curious as to what triggered this perception.

I'm probably in error. I quickly noticed USE_SWS as OFF, but that's Silly Window Syndrome handling. It appears there's no way to disable Slow Start nor Congestion Avoidance anyways, is that correct?

Yes, that's right. The evaluation being that 1) worst case is that they have minimal effect, 2) they are mandatory per the standard.

There is more potential in tuning the implementation, but it's a slow and tedious process - one that I plan to get back to next time I have a 4.77MHz machine available.