Better Documentation of stdio? #64

schierlm · 2019-10-20T18:48:27Z

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 · 2019-10-20T19:32:56Z

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 · 2019-10-20T19:39:37Z

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 · 2019-10-21T20:54:54Z

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 · 2019-10-21T21:11:47Z

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.


        Rename blockdev's API routines to GetB/PutB

The goal is to avoid mixing those routines with "character devices" (acia, vpd, kbd) which aren't block devices and have routines that have different expectations. This is a first step to fixing #64.

hsoft · 2019-10-31T01:24:48Z

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.


        Remove SHELL_LOOPHOOK

It was a bad idea and having sms/pad interact directly with sms/vdp is much simpler. ref #64


        stdio: make stdioGetC and stdioReadline blocking

ref #64. Also, fix a bug in the shell where it would write outside the buffer's bounds when given a completely filled buffer without a space character in it.


        stdio: add "Accepted characters" comment section

ref #64

hsoft · 2019-11-05T21:24:12Z

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 · 2019-11-12T17:48:57Z

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

hsoft added a commit that referenced this issue Nov 5, 2019

Remove SHELL_LOOPHOOK

16bf8e2

It was a bad idea and having sms/pad interact directly with sms/vdp is much simpler. ref #64

hsoft added a commit that referenced this issue Nov 5, 2019

stdio: make stdioGetC and stdioReadline blocking

2a513e6

ref #64. Also, fix a bug in the shell where it would write outside the buffer's bounds when given a completely filled buffer without a space character in it.

hsoft added a commit that referenced this issue Nov 5, 2019

stdio: add "Accepted characters" comment section

41338a4

ref #64

hsoft / collapseos

Better Documentation of stdio? #64

Better Documentation of stdio? #64

schierlm commented Oct 20, 2019

hsoft commented Oct 20, 2019

hsoft commented Oct 20, 2019

schierlm commented Oct 21, 2019

hsoft commented Oct 21, 2019

hsoft commented Oct 31, 2019

hsoft commented Nov 5, 2019

Allisontheolder commented Nov 12, 2019

hsoft / collapseos

Join GitHub today

Better Documentation of stdio? #64

Better Documentation of stdio? #64

Comments

schierlm commented Oct 20, 2019

hsoft commented Oct 20, 2019

hsoft commented Oct 20, 2019

schierlm commented Oct 21, 2019

hsoft commented Oct 21, 2019

hsoft commented Oct 31, 2019

hsoft commented Nov 5, 2019

Allisontheolder commented Nov 12, 2019