Example + Userdata for Maple Attach/Detach Events

[gyrovorbis]

An example of this functionality was actually requested by one of our developers looking to hook it into the raylib DC implementation.

1. Added userdata pointer to maple attach/detach callback event registration.
2. Added an example called "maple" which shows users how to subscribe to the attach/detach events and displays detailed device information.
3. Added a few more details to the Doxygen description for the API.

Example output just playing around attaching/removing devices:

KallistiOS Git revision 68b489de-dirty:
  Sat Mar 23 11:34:45 PM CDT 2024
  falco@slutserv:/opt/toolchains/dc/kos
  sh-elf-gcc (GCC) 13.2.0
thd: pre-emption enabled, HZ=100
maple: active drivers:
    Dreameye (Camera): Camera
    Sound Input Peripheral: Microphone
    PuruPuru (Vibration) Pack: JumpPack
    VMU Driver: Clock, LCD, MemoryCard
    Mouse Driver: Mouse
    Keyboard Driver: Keyboard
    Controller Driver: Controller
    Lightgun: LightGun
  DMA Buffer at ac066560
vid_set_mode: 640x480 VGA with 1 framebuffers.
dc-load console support enabled
maple: attached devices:
  A0: Dreamcast Controller          (01000000: Controller)
  A1: Visual Memory                 (0e000000: Clock, LCD, MemoryCard)
  A2: Visual Memory                 (0e000000: Clock, LCD, MemoryCard)
  B0: Dreamcast Camera Flash  Devic (01000000: Controller)
  B1: Dreamcast Camera Flash LDevic (00080000: Camera)
  B2: Dreamcast Camera Flash LDevic (00080000: Camera)
  B3: Dreamcast Camera Flash LDevic (00080000: Camera)
  B4: Dreamcast Camera Flash LDevic (00080000: Camera)
  B5: Dreamcast Camera Flash LDevic (00080000: Camera)

Listening for device hotplug events...
Maple device detached [A2]: Visual Memory                
Maple device attached [A2]: Visual Memory                
	Functions      :                                  Clock, LCD, MemoryCard
	Driver         :                                              VMU Driver
	Region Code    :                                                       2
	Orientation    :                                                       0
	Standby Power  :                                                     124
	Max Power      :                                                     130
	License        : Produced By or Under License From SEGA ENTERPRISES,LTD.    
Maple device detached [A0]: Dreamcast Controller         
Maple device detached [A1]: Visual Memory                
Maple device detached [A2]: Visual Memory                
Maple device attached [A0]: Dreamcast Controller         
	Functions      :                                              Controller
	Driver         :                                       Controller Driver
	Region Code    :                                                     255
	Orientation    :                                                       0
	Standby Power  :                                                     430
	Max Power      :                                                     500
	License        : Produced By or Under License From SEGA ENTERPRISES,LTD.    
Maple device attached [A1]: Visual Memory                
	Functions      :                                  Clock, LCD, MemoryCard
	Driver         :                                              VMU Driver
	Region Code    :                                                       2
	Orientation    :                                                       0
	Standby Power  :                                                     124
	Max Power      :                                                     130
	License        : Produced By or Under License From SEGA ENTERPRISES,LTD.    
Maple device attached [A2]: Visual Memory                
	Functions      :                                  Clock, LCD, MemoryCard
	Driver         :                                              VMU Driver
	Region Code    :                                                       2
	Orientation    :                                                       0
	Standby Power  :                                                     124
	Max Power      :                                                     130
	License        : Produced By or Under License From SEGA ENTERPRISES,LTD.    
Maple device detached [A2]: Visual Memory                
Attached Events: 4, Detached Events: 5

arch: exit return code 0
arch: shutting down kernel
maple: final stats -- device count = 8, vbl_cntr = 1171, dma_cntr = 1170
vid_set_mode: 640x480 VGA with 1 framebuffers.

[gyrovorbis]

OoOooO! I saw that @pcercuei's PR just got merged: https://github.com/KallistiOS/KallistiOS/pull/393.

I think this controller event callback mechanism is a good candidate for using threaded IRQs, so taking this bad boy back to Draft while I update it.

[gyrovorbis]

I'm opening this up for review with the caveat: I'm not actually sure how to make this use the threaded-interrupt mechanism, because the triggering interrupt is doing all kinds of extra work... Maybe @pcercuei can help show me how?

[pcercuei]

This is nested quite deep, you would have to use a threaded interrupt for the VBLANK handler in vblank.c.

Alternatively, modify maple_vbl_irq_hnd to call maple_queue_flush in a worker thread that would be notified from the IRQ context.

[gyrovorbis]

This is nested quite deep, you would have to use a threaded interrupt for the VBLANK handler in vblank.c.

Alternatively, modify maple_vbl_irq_hnd to call maple_queue_flush in a worker thread that would be notified from the IRQ context.

Alrighty, that sounds good. Maybe I can help make a generalized solution for doing this which could be used in other places as well... Might be better to leave this PR as-is then and tackle that as another feature, then update all of these hooks in IRQ-contexts?

[pcercuei]

I think this would benefit from using #505.

[gyrovorbis]

Do you guys think we should merge this PR, and then I'll do a follow-up using the worker thread system, or do you think we should put this PR on hold until the worker system PR is approved then take care of it all at once?

[ljsebald]

Do you guys think we should merge this PR, and then I'll do a follow-up using the worker thread system, or do you think we should put this PR on hold until the worker system PR is approved then take care of it all at once?

Being that the other PR is "ready", if there's a question, then I'd say wait until that is done.

[QuzarDC]

Would adding a callback for the periodic function of the driver be too big/unnecessary of an investment for this? I have a usecase in mind that could be made extremely more simple with that (currently I'm inserting a custom callback by basically writing a wrapper around periodic and hijacking the device's driver) .

Such a thing could also be a way to have sync'd input processing (userland triggers their updates based on our actual polling rather than on its own scheme) though I'm not sure how useful that is.