Part 2 serial IO lesson #88

quinnyo · 2024-04-27T23:37:50Z

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 · 2024-05-02T07:16:27Z

unbricked/serial-link/sio.asm

+; ::    /        `--<[|]= |[ m  ]||   ::
+; ::    \      .______    | ```` ||   ::
+; ::    /     !| `````|   | +  oo||   ::
+; ::   (      ||[ ^u^]|   |  .. #||   ::


I love this!

unbricked/serial-link/sio.asm

avivace · 2024-07-12T10:46:21Z

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 · 2025-04-02T11:57:24Z

Hey @quinnyo do you have any news on this?

quinnyo · 2025-04-03T02:49:46Z

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 · 2025-04-04T19:09:43Z

@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 · 2025-05-16T19:26:37Z

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.

avivace · 2025-10-31T14:40:27Z

@quinnyo I see this is still in 'Draft'. Would you consider this merge-able now? or what's missing for you that you would still like to add?

I guess we "only" miss the lesson text to accompany the code?

quinnyo · 2025-11-01T08:44:07Z

I'll take the PR off of 'draft' status, I didn't have any strong intention to leave it on after the last update. Apologies if it being marked as a draft was holding things up or sending the wrong message.

The code is done, I have no changes planned. Of course, I'll be happy to fix any issues that come up.

It needs to be reviewed.
Someone other than me should probably test that the feature actually works.

The lesson text needs work, but I'm reluctant to forge ahead with that without knowing that the implementation is locked in.

From memory (can't check right now) many of the transcluded code snippets were broken, after making changes to the code.
The sections toward the end on integrating Sio, the protocol and handshake stuff (i.e. the code in main.asm) are not in sync with the unbricked based implementation.
- The current implementation (& how it's integrated in unbricked) is pretty simple compared to what the lesson is referring to -- so I'm expecting a fair bit of that text can be cut.
The rest of the text is more general or about code in sio.asm -- most of this should be OK.
- there may be some slight discrepancies with the code
There's some WIP notes & TODOs throughout.

avivace

Wow, great work @quinnyo ! I'm starting a thorough review of the text and it reads amazingly.

src/part2/serial-link.md

avivace · 2026-01-03T20:15:42Z

src/part2/serial-link.md

+
+Before we can transfer any data, we need to configure the *clock source* of both Game Boys.
+To synchronise the two devices, one Game Boy must provide the clock signal that both will use.
+Setting bit 0 of the **Serial Control** register (`SC`) enables the Game Boy's *internal* serial clock, and makes it the clock provider.


Maybe we can link to https://gbdev.io/pandocs/Serial_Data_Transfer_(Link_Cable).html#ff02--sc-serial-transfer-control here ?

avivace · 2026-01-03T20:17:29Z

src/part2/serial-link.md

+The other Game Boy must have its clock source set to *external* (`SC` bit 0 cleared).
+The externally clocked Game Boy will receive the clock signal via the link cable.
+
+Before a transfer, the data to transmit is loaded into the **Serial Buffer** register (`SB`).


SB can link to https://gbdev.io/pandocs/Serial_Data_Transfer_(Link_Cable).html#ff01--sb-serial-transfer-data

src/part2/serial-link.md

avivace · 2026-01-03T20:31:50Z

src/part2/serial-link.md

+The first byte to send is loaded from `wSioBufferTx` before a jump to the next function starts the first transfer immediately.
+
+<!-- PortStart -->
+Activating the serial port is a simple matter of setting bit 7 of `rSC`, but we need to do a couple of other things at the same time, so add a function to bundle it all together:


Am I missing something or this is being called rSC now? but was SC? https://gbdev.io/pandocs/Serial_Data_Transfer_(Link_Cable).html#ff02--sc-serial-transfer-control

All MMIO register names in hardware.inc are prefixed with r to distinguish them from ROM, SRAM, WRAM, and HRAM labels. See "ASM style guide".

@pinobatch thanks Pino. It's just that in other parts of the document it's called SC, so seeing it as rSC after a point may be confusing, so I'd suggest sticking to one name

I think this was deliberate, but it may be needlessly confusing. It's rSC (with the r) here because it's talking about concrete implementation.

@quinnyo can we try to make it a more deliberate? E.g. make it explicit when the shift to rSC happens?

avivace · 2026-01-03T20:32:12Z

src/part2/serial-link.md

+
+:::
+
+To check if the internal clock is enabled, read the serial port control register (`rSC`) and check if the clock source bit is set.


Same comment as previous, regarding rSC.

src/part2/serial-link.md

avivace · 2026-01-03T21:03:51Z

src/part2/serial-link.md

+:::tip
+
+The checksum implemented here has been kept very simple for this tutorial.
+It's probably worth looking into better solutions for real-world projects.


Do we know some alternatives we can suggest?

A good jumping off point to learn more would be Ben Eater's videos:

Reliable data transmission
https://www.youtube.com/watch?v=eq5YpKHXJDM

Error detection: Parity checking
https://www.youtube.com/watch?v=MgkhrBSjhag

Checksums and Hamming distance
https://www.youtube.com/watch?v=ppU41c15Xho

How do CRCs work?
https://www.youtube.com/watch?v=izG7qT0EpBw

src/part2/serial-link.md

avivace · 2026-01-03T21:09:29Z

src/part2/serial-link.md

+A proper and complete explanation of this is beyond the scope of this lesson.
+You can continue the lesson understanding that:
+- This is the serial interrupt handler. It gets called automatically after each serial transfer.
+- The relevant stuff is in `SioPortEnd` but it's necessary to jump through some hoops to call it.


"relevant stuff" here feels a bit confusing

src/part2/serial-link.md

avivace

Missing: build script for the new CI/CD

Co-authored-by: Antonio Vivace <avivace4@gmail.com>

avivace reviewed May 2, 2024

View reviewed changes

quinnyo force-pushed the part2pointserial branch from add7190 to 0352ed2 Compare May 9, 2024 17:34

quinnyo force-pushed the part2pointserial branch 2 times, most recently from 3a0e30d to 431baff Compare June 26, 2024 22:31

This comment was marked as outdated.

Sign in to view

avivace requested a review from Rangi42 July 7, 2024 19:32

avivace requested a review from ISSOtm August 23, 2024 17:38

avivace requested review from AntonioND and removed request for ISSOtm and Rangi42 April 2, 2025 11:57

This comment was marked as outdated.

Sign in to view

Add Serial Link lesson to part 2

84c8f1b

quinnyo force-pushed the part2pointserial branch from 8a9346b to 84c8f1b Compare April 25, 2025 00:38

ISSOtm force-pushed the master branch from 04d4739 to 0c2600f Compare May 3, 2025 17:00

quinnyo added 2 commits May 6, 2025 09:43

Move serial link standalone demo to separate file

d5065c7

Add serial link Unbricked integration

e855ec7

avivace requested a review from ISSOtm May 26, 2025 19:45

avivace removed the request for review from ISSOtm October 31, 2025 14:41

quinnyo marked this pull request as ready for review November 1, 2025 08:44

avivace requested changes Jan 3, 2026

View reviewed changes

avivace self-requested a review January 3, 2026 20:39

avivace requested changes Jan 3, 2026

View reviewed changes

Update src/part2/serial-link.md

d618855

avivace added 7 commits January 6, 2026 00:32

Update src/part2/serial-link.md

34872d3

Update src/part2/serial-link.md

142e461

Update src/part2/serial-link.md

7eb9d34

Update src/part2/serial-link.md

9883e0a

Update src/part2/serial-link.md

8b27e7d

Update src/part2/serial-link.md

80ac372

Update src/part2/serial-link.md

13b1321

avivace requested changes Jan 6, 2026

View reviewed changes

avivace and others added 4 commits January 6, 2026 00:37

Update src/part2/serial-link.md

da406d7

Update src/part2/serial-link.md

28fec9c

Update src/part2/serial-link.md

ab92be9

Co-authored-by: Antonio Vivace <avivace4@gmail.com>

Update src/part2/serial-link.md

6754819

Co-authored-by: Antonio Vivace <avivace4@gmail.com>


		:::

		To check if the internal clock is enabled, read the serial port control register (`rSC`) and check if the clock source bit is set.

Uh oh!

Part 2 serial IO lesson #88

Are you sure you want to change the base?

Part 2 serial IO lesson #88

Uh oh!

Conversation

quinnyo commented Apr 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as outdated.

avivace commented Jul 12, 2024

Uh oh!

avivace commented Apr 2, 2025

Uh oh!

quinnyo commented Apr 3, 2025

Uh oh!

avivace commented Apr 4, 2025

Uh oh!

This comment was marked as outdated.

quinnyo commented May 16, 2025

Uh oh!

avivace commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quinnyo commented Nov 1, 2025

Uh oh!

avivace left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quinnyo Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

avivace left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

quinnyo commented Apr 27, 2024 •

edited

Loading

avivace commented Oct 31, 2025 •

edited

Loading

quinnyo Jan 6, 2026 •

edited

Loading