Part 2 serial IO lesson

[quinnyo]

This PR adds a lesson on the serial port to resolve #42.

Still a draft because the lesson text needs to be updated.

About the implementation:
Sio (sio.asm) is a kind of multi-byte version of the underlying GB serial API.

• implements the timeout for the externally clocked device
• implements the clock provider's "catchup delay"
• a data integrity test for received packets is included, using a rather simple checksum

main.asm is based on the BCD unbricked code.

• each peer sends its current score to the other and the remote peer's score is displayed below the local one.
• an initial handshake is performed to establish the connection (automatically determines the clock provider)
• there's no attempt made to guarantee delivery of packets but if a corrupt or non-sequential packet arrives, the connection is terminated.
• To build it you just need to compile and link both main.asm and sio.asm.

demo.asm is a standalone test rom I used to test and debug the serial transfer implementation. It isn't part of the lesson and can be removed if necessary, but it provides more debug information than the integration with unbricked.

[avivace]

I love this!

[avivace]

The code has been updated a bit. I updated the PR comment to reflect the changes. I don't think there are any glaring holes in the implementation and it works consistently in my simple test program. (so I need to improve the test!)

I'm not sure how this should be integrated with the unbricked code, or if I need to provide something more significant for testing purposes?

I didn't want to add test code to this repo, so I've been working on the impl in a standalone project (https://github.com/quinnyo/gbserial). sio.asm in this PR should be the same as in that repo at time of writing. The current program is a simple test where the two devices yell at each other. You first need to press START to toggle clock source on one GB. You get a tick if the checksum of the received packet checks OK, F for uhh, "big Fail" (timed out / incomplete packet). The relevant test bits are in sio_demo.asm.

Not sure about more significant testing, but I'd start thinking about how to integrate it in Ubricked for the simple "share high scores" case (although I really like @eievui5 idea here, maybe for a further improvement).

Maybe start the paragraph explaining sio.asm then hooking the "share high score" routine when e.g. pressing select on the game over screen?

To be honest, I don't think having an independent, standalone ROM only to showcase the serial feature is a bad idea, so I'd merge that as well.

[avivace]

Hey @quinnyo do you have any news on this?

[quinnyo]

Hi!

I just lost my momentum on it towards the end of last year, when life things happened.
Things are relatively stable now, so I can probably start getting back to it.

[avivace]

@quinnyo thanks a lot!

Also, since we did put bounties on this issues, if you give us an email address (you can DM me that on Discord or to 'gbcompo' at 'gbdev.io') I can send you an OpenCollective invitation to claim those $ bounties :D

[quinnyo]

I've been doing a bit of work on this so I figured an update was in order:

• It's excessively long and nobody is ever going to get through it!
• Almost all of the material that needs covering is present in the text in some form, at least.
  • Currently there's no starting point for the demo / main.asm
• I'm not intending on making any further significant changes to the code that features in the lesson.
  • This includes sio.asm and the Link* prefixed code in main.asm.
  • The notable exception is the handshake implementation which is a bit confusing (wHandshakeState) but as it's working I've been leaving it alone.
• Minor:
  • There's a thing near the start about testing on emulators which makes it sound like using an emulator is pointless (it's not, but there are issues)
  • I'm intending to provide the code that draws the everything as a chunk that reader doesn't need to worry about -- it's not relevant to the serial stuff.
  • The demo display output is not very intuitive or labeled, so a map/legend is probably in order.

Please roast it!

@avivace I sent an email!

[quinnyo]

OK so I implemented something in unbricked, which seemed to make more sense than continuing with the demo/test tool.
The tool was really for me to develop the thing and for others to test it, anyway. With that in mind, I kept the code, but moved it to a separate file.
Anyway the feature is "score sharing" -- but it's the current score, so it's a little bit similar to how Tetris worked.
The lesson text will obviously need to be brought up to speed but I'll work on that once someone's looked at the code.

Oh, and just a note to anyone testing this: if you're using Emulicious, expect trouble -- its serial emulation is a bit weird and introduces problems that don't happen on real hardware. GBE+ serial seems good but it's a bit lacking in other areas.