201 lines
3.3 KiB
Groff
201 lines
3.3 KiB
Groff
.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
|