140 lines
4.0 KiB
Groff
140 lines
4.0 KiB
Groff
.Dd January 6, 2016
|
|
.Dt SERIAL-TRANSFER 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm serial-transfer
|
|
.Nd files over serial device
|
|
.Sh DESCRIPTION
|
|
You can transfer data using the serial line.
|
|
The
|
|
.Xr sf 1
|
|
program provides simple framing which is useful to conduct advanced transfers by
|
|
combining with other tools such as
|
|
.Xr tar 1 .
|
|
.Pp
|
|
The serial device will be available at the appropriate device after boot, such
|
|
as
|
|
.Pa /dev/com1 .
|
|
Data written to it will be available to readers on the other end and likewise
|
|
data written on the other end will be available to local readers.
|
|
Take care to ensure that the reader is always reading before writing or you may
|
|
lose data.
|
|
.Pp
|
|
You get a byte stream between the guest and host using this interface.
|
|
This is powerful but often you want to transfer finite payloads and have the
|
|
transfer finish when done rather than needing to manually interrupt it.
|
|
.Pp
|
|
The
|
|
.Xr sf 1
|
|
program encodes and decodes frames.
|
|
.Li sf -o
|
|
will emit a start byte
|
|
sequence, then read from stdin and encode a body, and finally emit an end
|
|
sequence.
|
|
.Li sf -i
|
|
will read bytes until it finds a start sequence, then it will decode the body
|
|
and emit it to stdout, and finally stop when it receives the end sequence.
|
|
We can use this to do transfers over the serial connection.
|
|
.Pp
|
|
.Xr sf 1
|
|
is a Sortix specific program.
|
|
Other operating systems don't come with it and you need to build it from the
|
|
Sortix source code.
|
|
This is automatically done by the
|
|
.Sy build-tools
|
|
target during
|
|
.Xr cross-development 7 .
|
|
You can also just transfer its code from
|
|
.Pa /src/sf/sf.c
|
|
over the serial line.
|
|
.Ss Virtual Machines
|
|
This method is useful when running inside a virtual machine and you wish to
|
|
communicate with the host system.
|
|
This is particularly useful if you connect the serial line to a unix socket.
|
|
In Qemu, this is done with:
|
|
.Bd -literal
|
|
-serial unix:/tmp/serial,server,nowait
|
|
.Ed
|
|
.Pp
|
|
In VirtualBox, in the virtual machine settings, under serial ports, enable one
|
|
and put it in mode Host Pipe and mark Create Pipe.
|
|
.Ss Conventions
|
|
Let
|
|
.Pa /dev/receiver
|
|
mean the device on the receiving machine and let
|
|
.Pa /dev/transmitter
|
|
mean the device on the transmitting machine.
|
|
This will be devices such as
|
|
.Pa /dev/com1 .
|
|
If one end is the host of a virtual machine as described above, its device will
|
|
be an unix socket such as
|
|
.Pa /tmp/serial .
|
|
.Ss Simple File Transfer
|
|
You can then transfer a file from this system to another.
|
|
First run on the receiving machine:
|
|
.Bd -literal
|
|
sf -i /dev/receiver > file.txt
|
|
.Ed
|
|
.Pp
|
|
Then run on the transmitting machine:
|
|
.Bd -literal
|
|
sf -o /dev/transmitter < file.txt
|
|
.Ed
|
|
.Pp
|
|
The sender will stop when it has transmitted the last byte and the receiver will
|
|
end when it has recognized an end sequence.
|
|
.Ss Advanced File Transfer
|
|
You can transfer multiple files using
|
|
.Xr tar 1 .
|
|
This also allows you to preserve file meta data such as permissions and modified
|
|
time.
|
|
First run on the receiving machine:
|
|
.Bd -literal
|
|
sf -i /dev/receiver | tar -xv
|
|
.Ed
|
|
.Pp
|
|
Then run on the transmitting machine:
|
|
.Bd -literal
|
|
tar -cv *.patch | sf -o /dev/transmitter
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fl v
|
|
option is useful as it displays the names of files as they are transferred.
|
|
.Ss Network Connection
|
|
It is possible to use the
|
|
.Xr sfnc 1
|
|
and
|
|
.Xr sfncd 1
|
|
scripts to create a bidirectional communication channel using two serial ports,
|
|
one for each direction.
|
|
The scripts use a protocol where
|
|
.Xr sfnc 1
|
|
sends a hostname, a port, and the body from stdin.
|
|
Likewise the
|
|
.Xr sfncd 1
|
|
script receives the two parameters and invokes
|
|
.Xr nc 1
|
|
(or another program as specified).
|
|
.Pp
|
|
For instance, run on the server:
|
|
.Bd -literal
|
|
sfncd /dev/receive /dev/transmit
|
|
.Ed
|
|
.Pp
|
|
And then run on the client:
|
|
.Bd -literal
|
|
sfnc irc.freenode.net 6667 /dev/transmit /dev/receive
|
|
.Ed
|
|
.Pp
|
|
This will last for the duration of the connection.
|
|
.Xr sfncd 1
|
|
needs to be run again to start another connection.
|
|
This scheme only allows one connection at one given time, but with it is
|
|
possible for custom programs on either side to multiplex connections.
|
|
.Sh SEE ALSO
|
|
.Xr sf 1 ,
|
|
.Xr tar 1 ,
|
|
.Xr development 7 ,
|
|
.Xr user-guide 7
|