Homebrew i8088 SBC - compatibility/porting questions

[and3rson]

Thank you for this awesome project!

I'm currently building a homebrew SBC powered by KM1810VM88 (Ukrainian i8088 clone) - https://github.com/and3rson/pk88

I'm using Soviet chips for this, here's the list of original codes:

• 8088 (of course)
• 8250 (UART + bit-banged uSD card through SPI)
• 8253 (timer interrupts)
• 8255 (bit-banged PS/2, generic I/O for dip switches & LEDs)
• 8259 (PIC)
• 2x AS6C4008 (1M RAM)
• W27C512 mapped to 0xF0000..0xFFFFF (custom BIOS)
• Address decoding with 2x ATF16V8 GALs (1 for memory address decoding & clock generation, 1 for I/O port decoding)
• Character LCD display (40x08 or 40x16, T6963C-based)

I had two choices:

• Make my device IBM PC compatible-ish (and be able to run DOS, ELKS, etc out of the box);
• Build my device as I wish, and then attempt to port ELKS to it.

I decided to go with the first option, i. e. make my SBC convey to all the requirements that OS will have, mostly by moving ports to conventional addresses (e. g. PIC @ 0x20..0x2F, COM1 @ 0x3F8, etc) and writing my own BIOS which implements the required interrupts.

Now, I initially assumed it would be sufficient if I just implemented my own BIOS with the most important interrupts - including 10h, int11h, 12h, 13h, 16h - and then be able to run DOS or ELKS. Seems like I'm wrong. :)

I've checked the porting guide and I still have some questions:

• I'm assuming that it's not possible to run ELKS with stock drivers and make it rely exclusively on BIOS interrupts - is this correct?
• If yes, is there a full list of I/O ports that my SBC need to have (and at which addresses)? I found some mentions in the porting guide, including 03F2h for floppy drive controller. - Just discovered elks/include/arch/ports.h. Hence a different question:
  • Is this an exhaustive list of all required ports?
• Besides interrupts & ports, are there any "special" memory locations where ELKS expects some device data to be present? Does ELKS read anything from BIOS data area?
• Is ELKS OK with 8253 or does it specifically need 8254?
• Can ELKS work without the DMA controller?
• Can ELKS work with non-standard display sizes? (I'm planning to use text mode only, and I'd love to use my trusty 40x08 or 40x16 LCD.)
• Are there any other important chips that ELKS needs to function which I forgot?

As I mentioned in the beginning - my main goal is to make my SBC compatible with ELKS without changing anything in ELKS itself. I find it more fun than manually tweaking ELKS to run on my device. :)

Thanks in advance!

[ghaerr]

Hello @and3rson,

That would be very cool running ELKS on your SBC and using the small LCD display! I think we should be able to make that happen without many changes :)

The porting guide which you've already found is definitely worth studying, it may be a bit out of date, but the BDA areas it mentioned are a good start. You can also grep the source for peekb and peekw to confirm (there shouldn't that many). ELKS has been vetted fairly well and its dependencies are now fairly small, all things considered. You should also take a look at include/linuxmt/config.h at setupw, which grab various values from the second stage boot loader in elks/arch/i86/boot/setup.S.

it's not possible to run ELKS with stock drivers and make it rely exclusively on BIOS interrupts

No, we should be able to run entirely on top of BIOS, but its easier if you let ELKS grab the hw timer at IRQ 0 and program the PIT yourself. The 8253 should work, but you may need to change the timer constants, I have to check the data sheet. Some BIOSes callout (callback) INT 1Ch which ELKS could possibly use otherwise. In general, ELKS now only enables/disables bits in the PIC for devices as they are opened, rather than trying to take over the entire system - this allows the BIOS to still have some say in the system operation, if desired.

Is this an exhaustive list of all required ports?

Probably not. The answer depends on exactly which drivers you use, and the documentation may not be fully up to date, there's been surge of activity lately.

Besides interrupts & ports, are there any "special" memory locations where ELKS expects some device data to be present?

The BIOS and Direct console driver use some special locations, but IIRC they're all in the BDA. We added cursor on/off recently and that turned out to be harder than desired because of assumed BIOS compatibility which doesn't work. I think the floppy disk driver may output a motor off command to the DOR register, even with no drives present, I'll have to check.

Does ELKS read anything from BIOS data area?

Yes, but as little as possible - refer to console-direct.c and console-bios.c for most of that (in console_init).

Is ELKS OK with 8253 or does it specifically need 8254?

8253 should work. See elks/arch/i86/timer-8254.c.

Can ELKS work without the DMA controller?

A DMA controller is only used by the new direct floppy driver. I would recommend using BIOS INT 13h at this point instead.

Can ELKS work with non-standard display sizes? (I'm planning to use text mode only, and I'd love to use my trusty 40x08 or 40x16 LCD.)

Yes - the BIOS and Direct console source mention some issues with getting the screen lines and cols through BDA and setup.S - You should be able to temporarily replace that with your device hard width/height and things should work, providing that the BIOS also knows about it. If the LCD doesn't support video RAM character mapping, then you'll want to use the BIOS console, as the direct console writes directly to segment A000 or B800 depending on mode.

Are there any other important chips that ELKS needs to function which I forgot?

The big two are PIC and PIT, both of which are easily changed, as that was done on the 8018X port. If the BIOS handles the rest, we should be good to go.

Let me know how else I can help! :)

[and3rson]

This is totally awesome - I like the way ELKS is organized, and I'm literally enjoying every minute of reading the sources. :) (To be honest - my first bet was DOS 1.x which I assumed would be easy to run on my SBC due to its simplicity, but it ended up being somewhat painful since the official sources are incomplete, and it's hard to find reliable information on certain techincal caveats.)

Thank you for your quick, friendly and verbose response, it's extremely helpful. I'll post my progress once I have my PCB printed - and hopefully run ELKS there!

My end goal is to build an all-in-one machine (inspired by TRS-80 Model 100) with built-in keyboard & display. I did a similar project with 6502 (https://github.com/and3rson/deck65), but i8088 version with an actual *nix OS is going to be way more fun!

[and3rson]

So I've finally got some time to assemble my new computer! I'll be trying to apply necessary patches to ELKS to make it run with my custom BIOS (https://github.com/and3rson/pk88/tree/main/metalbios).

So far I've done the following bare minimum:

• I've implemented a minimal BIOS with some of the most important software interrupts - 10h, 11h, 12h, 13h (SD card via SPI bit-banging), 14h, 16h & 1Ch
• I have PIC & PIT mapped to PC/XT port addresses (0x20-0x21 for PIC & 0x40-43n for PIT) and they are wired to corresponding IRQs in range 8-15.
• I try to store all my stuff in appropriate locations in BDA (such as cursor position)

Now here's some thoughts.

Since the two primary ways for OS to interact with my metal are software interrupts and ports, at this point the only bottleneck is ports (since I can implement "polyfills" for interrupts in software, but not for ports).

My obvious route would be to fork & patch ELKS to rely on interrupts as much as possible (since I only have 2 PC/XT-compatible port groups - PIC & PIT), and this works perfectly fine for me!

However, I've seen many people trying to build their own BIOS in order to be able to run some useful OS like ELKS, and they usually struggle with ports as well (and for the same reason it's hard to get e. g. DOS running on a custom homebrew computer). Another solution is to use some existing BIOS that is truly PC/XT compatible, but of course that eliminates all the fun of building your own BIOS!

So, my questions are:

• Shall I just keep the patches for myself so that upstream ELKS code continues to target only some specific old-school platforms?
• Or would it probably make sense to introduce a new "target" in upstream ELKS with a name like "HOMEBREW" or "PUREBIOS", which could have more homebrew-friendly implementations of various subsystems? (i. e. to use BIOS interrupts wherever possible instead of ports). Good example is BIOS console support which is one of those things that make ELKS very generic and easy to port.

(Of course, by adding this new target I don't mean adapting upstream ELKS to my specific build/hardware - just adding a new very generic homebrew-friendly target. And, of course, I'm willing to contribute all the patches myself - I'm not asking anyone to write a code to support my computer! :D )

I'll be happy to hear any thoughts!

[ghaerr]

Hello @and3rson,

Nice to see you back here working on your homebrew i8088 SBC and ELKS! :)

To directly answer your question of whether patches and port I/O vs a new/extended-BIOS hardware abstraction layer would be better - frankly I don't know at this point. It would seem there might be advantages to each. It'd be great to see/commit the changes somewhere upstream so that others might benefit, I would think. That said, I'd be happy to help figure out how improvements and/or changes required for a custom port might best be kept within this repo. Actually, somewhat the same method was used in originally working towards getting ELKS easier to port by observing requested changes and changing the source tree/files to accommodate that. My preference is to try to keep the HW dependencies absolutely required by ELKS to a bare minimum, and allow for config options to add more features for various hardware or systems.

With regards to a custom BIOS with an extended hardware abstraction vs other methods and ELKS: I have tried to use C function calls, rather than BIOS interfaces, as a lower hardware abstraction level for ELKS, as this allows running on systems without a BIOS at all, for instance. Thus, if you choose to go with a extended custom BIOS, those calls should be further wrapped using the existing C functions (in possibly new filenames or directories) if possible. OTOH, if the abstraction shows good reason for changing/improving the existing C wrappers, then those could be changed throughout ELKS, but we'd want to ensure the various ports (PC-98, 8018X, etc) still compile and run.

An advantage of having ELKS make a BIOS call for absolutely everything would, IMO, mostly be that there would exist a strict HW interface that ELKS could be configured to rely on. However, this is sometimes easier said than done, as even now there exists code that directly accesses the BIOS Data Area, for instance. In addition, the system startup in setup.S is pretty system-dependent, and all in assembly. There are also many cases where direct access using port I/O might be preferable for speed, although in an educational system, this may not be as important.

just adding a new very generic homebrew-friendly target

Can you explain more what you mean by "target" - are we talking about a "make" target, a configuration target, or something else? Either should be pretty straightforward to add.

All this said, I would encourage you to post PRs, if initially just to see what you've done, for more discussion on how they might be best integrated into the master repo. I am always interested in new work and ways to expand the ability for others to use and port ELKS on any systems one might have.

Thank you!

[and3rson]

Hey @ghaerr!

By "target" I meant a configuration target, similar to CONFIG_ARCH_IBM - perhaps something like CONFIG_ARCH_HOMEBREW, which could pretty much extend CONFIG_ARCH_IBM, but also make ELKS behavior more "patchable" - for instance, by replacing port I/O with call instructions (or undocumented interrupts) that user's BIOS can implement. I'll provide more inputs once I dig deeper into ELKS and have a better understanding of its internals. So far IBM target has been working rather well - in fact, after some tinkering with my BIOS and fixing some nasty bugs, I managed to pass the bootloader and get as far as loading the kernel:

At this point I could use some help.
By monitoring the SPI bus I can see that ELKS is successfully loading the kernel and then starts to load some additional files. After that, it stops without printing anything. I added stubs for all unimplemented interrupts & functions so that I get some text printed if ELKS attempts to do something that my BIOS doesn't know how to do, plus some convenience things like printing registers to LCD in INT 0x03.

• What should be the best way to debug this?
• Is there some debug parameter that increases ELKS verbosity to print as much info as possible?

Thanks in advance!

[ghaerr]

What should be the best way to debug this?

Since chasing the problem with an emulator won't work on real hardware, I resort to using old fashioned printf debugging in these cases, to find the routine the system is crashing in.

I can see that ELKS is successfully loading the kernel and then starts to load some additional files. After that, it stops without printing anything.

The final letters and numbers displayed on your screen indicate setup.S showing the text, fartext and data segments before jumping out of that to _start in elks/arch/i86/boot/crt0.S. That routine clears BSS then jumps to the C kernel start routine kernel_start in elks/init/main.c. You'll notice in crt0.S there's a routine called early_putchar, which can be called from C to display a character using INT 10h.

Look at kernel_start() and you'll see that the scheduler, memory management and irq init routines are called. You could call early_putchar('1') etc before/after these to see what's happening. After enough init routines are called that the console driver init can be called, that is done and it tries to write to the "real" console, whatever that is. This could very well be where your problem lies, but using early_putchar beforehand will help. The console init routine will display something like "BIOS Console ..." which we're not seeing so you may not be making it that far, or it could be dying in console_init, since it is dependent on various BDA variables for lines/cols, etc. After console_init is finished, printk can be used for further kernel debug display using the console.

Is there some debug parameter that increases ELKS verbosity to print as much info as possible?

In the early stages, no. But I left in the various 't', 'f', 'd' display that you're seeing just for this purpose - which shows you're making it through the initial setup.S boot. (That routine also relocates the kernel so if early_putchar doesn't work as the first call in start_kernel, that would indicate relocation issues).

[and3rson]

This is extremely helpful, thanks!

After some debugging (and BIOS fixes), it seems like the code is actually getting to at least as far as then end of kernel_init. So far so good!

However, I'm not able to see any output from printk. I tried setting console= in bootopts to 0 and empty string as well. early_putchar works though. I've also set console to BIOS in kernel config but still cannot see any output, including kernel banner. Any ideas if I'm missing anything?

Here's my config for char device drivers:

EDIT: Nevermind - it's my mistake. I haven't implemented INT 0x10 function 0x09 (which is used in bios_writecharattr) and only implemented function 0x0E. I can see the banner now! 🎉

[ghaerr]

I haven't implemented INT 0x10 function 0x09 (which is used in bios_writecharattr) and only implemented function 0x0E. I can see the banner now! 🎉

There you go! I was thinking the the BIOS console itself wasn't working - which in this case means it was using a different INT 10h subfunction than what you have implemented! :)

It could well be the case that ELKS is in fact fully booting up - but you just can't see it!

[and3rson]

Okay, this is AWESOME!

Thank you for you help, I'm so happy I can now run ELKS on my machine.

I did some very minor changes to hard-coded values in INITSEG. I'll probably create a PR in the coming days for some improvements:

• Configuring some values in menuconfig, such as display size (which is currently hard-coded in VGA is not used)
• Forcing a specific UART to be used (e. g. 16550A in my case), since I'm using its status registers for SPI bit-banging and thus ELKS interferes with it while probing the chip.

[ghaerr]

I'm so happy I can now run ELKS on my machine.

Very nice! Now where's your keyboard? (BTW, I don't see a cursor :) I have some ideas on how to easily implement such a thing if needed.)

I did some very minor changes to hard-coded values in INITSEG. I'll probably create a PR
Configuring some values in menuconfig, such as display size

At this point, rather than adding menuconfig entries for not-often changed settings for a specific target, I'd rather think about using the mechanism we are using in elks/include/linuxmt/config.h: target-specific settings for your machine. (Yes, this might entail moving to a new CONFIG_ARCH_<something> like you originally suggested, but we don't want to add tons of ifdef ARCH1 || ARCH2 type stuff if possible). You'll see there are already defines/overrides for things you need, like SETUP_VID_COLS, SETUP_VID_LINES, etc.

The first PR(s) could add a new target CONFIG_ARCH_xxx, possibly selectable through menuconfig, but generally keep the new additions in config.h. This will allow a more immediate commit while giving some time as to how to most appropriately address where new settings might be kept. I say this because I've been cleaning up all sorts of ifdefs and CONFIG_ settings that were used years ago and then dropped and not maintained, making it harder to understand exactly what ELKS really needs in order to port, etc. Having most of your changes in config.h will allow you to continue to develop quickly and getting committed without having to go through lots of system tests for the other architectures currently maintained. In general, I'm trying to decrease, not increase, the number of ifdefs in the kernel.

Forcing a specific UART to be used (e. g. 16550A in my case)

Not sure exactly yet how to handle this, but yet another ifdef, controlled in config.h, could possibly be used to omit the probing code and simultaneously select a UART. Later on it might make sense to have your own architecture-specific console or serial drivers, depending on what issues you find.

Nonetheless, feel free to post a PR just showing your changes, I'm happy to help and comment.

Thank you!

[and3rson]

Very nice! Now where's your keyboard? (BTW, I don't see a cursor :) I have some ideas on how to easily implement such a thing if needed.)

I'm using an external PS/2 keyboard controlled with GAL22V10 (http://forum.6502.org/viewtopic.php?f=10&t=7833#p104655). The cursor is indeed there - just barely visible! :)
You can see part of Mini-DIN-6 keyboard connector next to the LCD on the right.
Here it is in action (I was finally able to log in as root):

(Darn, that sneaky cursor disappeared the very moment I was taking a photo, lol)

My screen scrolling implementation is still buggy and some fonts are missing on my end, so at this point I'm going to improve my BIOS to achieve some basic feature parity with http://copy.sh/v86/
Sorry for the slow response - I've been busy with some work, I'll try to cleanup my code and see if there is anything that's generic enough to be submitted as PR.
Thanks for all your help so far! Now that I have a functional system, the sky is the limit. :)