Sortix cross-nightly manual

This manual documents Sortix cross-nightly. You can instead view this document in the latest official manual.

NAME

serial-transfer — files over serial device

DESCRIPTION

You can transfer data using the serial line. The sf(1) program provides simple framing which is useful to conduct advanced transfers by combining with other tools such as tar(1).

The serial device will be available at the appropriate device after boot, such as /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.

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.

The sf(1) program encodes and decodes frames. sf -o will emit a start byte sequence, then read from stdin and encode a body, and finally emit an end sequence. 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.

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 build-tools target during cross-development(7). You can also just transfer its code from /src/sf/sf.c over the serial line.

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:

   -serial unix:/tmp/serial,server,nowait

In VirtualBox, in the virtual machine settings, under serial ports, enable one and put it in mode Host Pipe and mark Create Pipe.

Conventions

Let /dev/receiver mean the device on the receiving machine and let /dev/transmitter mean the device on the transmitting machine. This will be devices such as /dev/com1. If one end is the host of a virtual machine as described above, its device will be an unix socket such as /tmp/serial.

Simple File Transfer

You can then transfer a file from this system to another. First run on the receiving machine:

    sf -i /dev/receiver > file.txt

Then run on the transmitting machine:

    sf -o /dev/transmitter < file.txt

The sender will stop when it has transmitted the last byte and the receiver will end when it has recognized an end sequence.

Advanced File Transfer

You can transfer multiple files using tar(1). This also allows you to preserve file meta data such as permissions and modified time. First run on the receiving machine:

    sf -i /dev/receiver | tar -xv

Then run on the transmitting machine:

    tar -cv *.patch | sf -o /dev/transmitter

The -v option is useful as it displays the names of files as they are transferred.

Network Connection

It is possible to use the sfnc(1) and sfncd(1) scripts to create a bidirectional communication channel using two serial ports, one for each direction. The scripts use a protocol where sfnc(1) sends a hostname, a port, and the body from stdin. Likewise the sfncd(1) script receives the two parameters and invokes nc(1) (or another program as specified).

For instance, run on the server:

    sfncd /dev/receive /dev/transmit

And then run on the client:

    sfnc example.com 443 /dev/transmit /dev/receive

This will last for the duration of the connection. 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.