ftdi_transfer: add manual page

tools/ftdi_transfer.1

@@ -0,0 +1,200 @@
+.TH ftdi_transfer 1 "19 Nov 2024" "ftdi_transfer" "Manual"
+.SH "NAME"
+ftdi_transfer \- Dreamcast data transfer for FTDI chips
+.SH "SYNOPSIS"
+.sp
+.ad l
+.in +8
+.ti -8
+.B ftdi_transfer
+.RI "[ " COMMAND ... "" " ] "
+
+.ti -8
+.sp
+.IR COMMAND " := { "
+.sp
+.ti -4
+.B read
+.IR SRC_ADDR
+.IR READ_SIZE
+.IR FILENAME
+.sp
+.ti -4
+.B write
+.IR DEST_ADDR
+.IR FILENAME
+.sp
+
+.ti -4
+.B jump
+.IR JUMP_ADDR
+.sp
+
+.ti -4
+.B speed
+.IR SCBRR
+.sp
+
+.ti -4
+.B console
+.sp
+
+.ti -4
+.B maple_storage_dump
+.sp
+
+.ti -8
+.IR "" " }"
+
+.SH "DESCRIPTION"
+
+.SS Terminology
+
+.BR host :
+The computer that is directly executing the
+.B ftdi_transfer
+command-line application.
+
+.BR target :
+The computer that is responding to commands generated by
+.BR ftdi_transfer
+(typically a Sega Dreamcast).
+
+.SS COMMAND behavior
+
+Prior to processing any
+.IR COMMAND ","
+.B ftdi_transfer
+first signals a state machine reset by sending UART break signal.  When the
+receiving program running on the Dreamcast observes a UART break signal, the SH4
+SCIF is also reset. This reset sequence also prematurely terminates any
+commands that were in progress from the perspective of the Dreamcast.
+
+.B ftdi_transfer
+processes the
+.IR COMMAND
+list in order from left to right. This ability to process multiple commands is
+intended both as a convenience, and to allow for "scripted" interactions with
+the Dreamcast to be executed more quickly.
+
+For example, a single
+.B ftdi_transfer
+invocation could perform all of these actions in sequence:
+
+.TS
+tab (@);
+l lx.
+-@T{
+copy a newly-compiled test program that manipulates Holly / Texture Memory state in some interesting way
+T}
+-@T{
+execute the test program (eventually returning from `main`)
+T}
+-@T{
+dump the entire content of Texture Memory to a file
+T}
+-@T{
+dump the values of all Holly registers to a file
+T}
+.TE
+
+Such a sequence would be useful in combination with a CORE emulator, such as
+skmp's "refsw".
+
+.SH "COMMANDS"
+.B read
+.I SRC_ADDR
+.I READ_SIZE
+.I FILENAME
+.sp
+.in +4
+Copy
+.IR READ_SIZE
+bytes of
+.B target
+memory starting at address
+.I SRC_ADDR
+on the
+.BR target
+to
+.I FILENAME
+on the
+.BR host .
+
+.in -4
+.B write
+.I DEST_ADDR
+.I FILENAME
+.sp
+.in +4
+Copy the content of
+.I FILENAME
+from the
+.B host
+to
+.I DEST_ADDR
+on the
+.BR target .
+The number of bytes copied to
+.B target
+memory is equal to the size of
+.IR FILENAME .
+
+.in -4
+.B jump
+.I JUMP_ADDR
+.sp
+.in +4
+Set the
+.B target
+program counter to JUMP_ADDR using the SH4 `jsr` instruction. If desired, the
+code may return to the serial transfer program with `rts` when execution is
+finished.
+
+.in -4
+.B speed
+.I SCBRR
+.in +4
+Set the value of the SCIF SCBRR2 register on the
+.B target
+to
+.IR SCBRR .
+If specified,
+.B speed
+should be the last command in the sequence given to
+.BR ftdi_transfer .
+This command has reliability issues, and changing serial speeds is not
+recommended nor generally necessary.
+
+.in -4
+.B console
+.in +4
+Continuously copy all bytes received from the
+.B target
+to the terminal emulator that
+.B ftdi_transfer
+is connected to. This is useful for "printf" debugging of the
+.B target
+program.
+
+.in -4
+.B maple_storage_dump
+.in +4
+Copy the raw content of all Maple storage devices on the
+.B target
+to files on the
+.BR host .
+
+.SH EXAMPLES
+
+Copy and execute a program from the
+.B host
+on the
+.BR target :
+.P
+.EX
+ ./ftdi_transfer \\
+    write 0xac010000 program.bin \\
+    jump  0xac010000 \\
+    console
+.EE