.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