Better Documentation of stdio?

[schierlm]

I think stdio calls (getC, putC) could need some documentation what userspace can expect from drivers and what not. Of course, it can always happen that a certain device cannot fulfill those expectations, but in that cases you at least know that you may have to update every userspace tool too, and not only make a glue.asm for the kernel.

Examples/Questions:

• What character set is every stdin implementation expected to be able to produce? Some examples in the documentation assume e.g. it can produce nullbytes, and some Z80 software assumes that there can be for example Ctrl+C or Ctrl+O. I think a sensible minimal character set is printable ASCII (0x20-0x7E) in addition to backspace (0x08) and return (0x0a). But that means that userspace applications are responsible that they can work with that character set only. Maybe escape (0x1B) or Tab (0x09) should also be added?

• Should the return key produce 0x0a (LF) or 0x0d (CR) or both? TinyBasic assumes 0x0d, yet the emulator produces 0x0a.

• should stdinGetC be blocking or nonblocking? The code in the shell currently assumes it is nonblocking, yet the emulator's implementation is blocking. It may be useful for userspace to decide whether it needs a nonblocking stdinGetC (which may be a no-op if not supported), e.g. to be able to interrupt something with the keyboard if the keyboard supports it. Making it nonblocking by default is maybe a bad idea, as blocking implementations may require lower energy consumption (important in case you have to produce your energy on the treadmill :D) as it can use the HALT instruction to wait for interrupts.

• similarly for output, what characters can userspace expect output drivers to handle? The current shell requires backspace, LF and printable ASCII, which seems to be a sane option for me. On the other hand, maybe somebody expects to have more convenient editors than "ed" that need a smarter terminal.

[hsoft]

I agree that things are a bit fuzzy in that regard. The reason is that the serial console was initially set up to be plugged into blockdevs. That quickly caused problems, as you can imagine, with blocking and nonblocking expectations. Therefore, I created stdio and stopped plugging the shell into a blockdev.

Therefore, stdio's GetC is not the same as blockdev's GetC. blockdev expects bytes and are nonblocking and stdio expect characters and are blocking.

This split happened rather recently and there are many inconsistencies left.

So yes, a bit of a cleanup is needed in that regard. Maybe rename blockdev's routines GetB and PutB to make sure we don't mix them up.

Same with your other questions: cleanup needed. So far, this has been done in a "whatever works" fashion.

[hsoft]

Oh no, now I remember: stdioGetC is supposed to be nonblocking. I briefly made it blocking after my blockdev/stdio split, but then when I wanted to add support for the SMS, I needed to make in unblocking again so that the shell hook would be called repeatedly, even when no key was pressed (vdpShellLoopHook needs this).

[schierlm]

Shell Hook? I only had a quick look at the code, and it looks like some "screen keyboard" or "IME UI", and I don't see why the shell should update that but stdioReadLine (e.g. from the editor) should not... So perhaps rather have a hook that is called by stdioGetC (which then could be made blocking again)?

Sorry if I misunderstood the code, I don't have a Sega Master System to test :)

[hsoft]

It's for pad-driven character selection. It's true, userspace also needs it, so it doesn't belong in the shell. A refactoring is needed.

[hsoft]

Yeah, this whole shell loop thing was a bad idea (I originally mistyped "bad" as "pad", which I find funny...). Rather than having the shell optionally polling the pad for input, it's padGetC that should inherit the loop from the shell and do that.

Yup, bad idea. I'll undo this soon and make stdioGetC blocking. Good point about HALT.

Regarding "smarter terminal": I chose ed because it's an efficient line editor. If possible, I'd like to avoid having to implement smart terminals.

[hsoft]

The situation is now, I think, much clearer. There still the open question of how special characters are handled. I guess we should aim towards VT-100 compatibility, but I'm not sure it's worth it.

[Allisontheolder]

Vt100 is DEC extended ANSI so it works with a lot of terminals that can easily emulate VT100, most did. If you use a subset its easier.

Most systems put that in termcap for flexibility.

Allison