Solo5

You can write to the tender's standard output using the solo5_console_write function. This function operates on a best-effort basis and may potentially lose some data.

Error

For functions returning a solo5_result_t:

• they return only SOLO5_R_OK on success.
• Application developpers must not rely on these functions returning SOLO5_R_EINVAL or SOLO5_R_EUNSPEC. Solo5 implementations may choose to abort execution of the application in preference to returning an error result on failure.

The operation completed successfully.

The operation cannot be completed at this time. Retrying identical operation at a later time may succeed.

Invalid argument.

The operation failed due to an unspecified error.

The parameters passed to the tender are transferred to the unikernel in the form of a read-only string ending with \0.

A unikernel has at its disposal a continuous, non-executable memory region defined by [heap_start, heap_start+heap_size]. This region can, in particular, be used by an implementation of malloc(3). Also, a C stack is already initialised at the top of this region and grows downwards.

Application entry point. A Solo5 application must implement the solo5_app_main function, and this is the function that will be executed first when the unikernel starts up. A statically allocated solo5_start_info value (read-only) is passed to it.

Here is an example of a small Solo5 application:

#include "solo5.h"

const char hello_world[] = "Hello World!\n";

int solo5_app_main(const struct solo5_start_info *info) {
  solo5_console_write(hello_world, sizeof(hello_world));
  return (0);
}

solo5_exit is used to terminate a unikernel. It (attempts to) return the value passed as a parameter to the host.

solo5_abort is used to shut down the unikernel. The host then returns the value 255.

Thread Local Storage

This implementation of TLS is limited to the local-exec model (offset directly from the TLS_BASE register) which is how Solo5 currently use TLS. The usage is as the following for each thread:

// define a TLS block
uintptr_t tcb1;
// get memory
tcb1 = (uintptr_t) calloc(solo5_tls_size(), sizeof(char));
// initialize TLS block
solo5_tls_init(tcb1);
// set tp ptr
solo5_set_tls_base(solo5_tls_tp_offset(tcb1));

For another thread, you just have to:

solo5_set_tls_base(solo5_tls_tp_offset(tcb2));

Returns the size needed for the thread local storage.

Returns the tp base addresse for the TLS block.

Perform a proper initialisation of the tls block (it should be already allocated): copy .tdata values and set the last bytes correctly.

Solo5 implementations may return SOLO5_R_EINVAL if the tls does not satisfy architecture specific requirements.

Set the architecture specific TLS base register to base.

Solo5 implementations may return SOLO5_R_EINVAL if the base does not satisfy architecture specific requirements.

Time

Solo5 implements two clocks:

• a so-called monotonic clock, which tracks how much time has elapsed. This clock is not subject to any recalibration or changes. It increments monotonically.
• a so-called wall clock, which corresponds to the host system's POSIX clock. It may be subject to recalibration and jumps.

The elapsed time solo5_time_t is given in nanoseconds.

As the monotonic clock does not do recalibration, a drift in the clock relative to real time may be observed. This clock is what is known as a TimeStamp-Counter-based clock: in other words, it increases monotonically in relation to the calculated frequency of the vCPU and the number of instructions it has executed.

In other words, this clock is useful if you can calculate or estimate a short period of time (less than a day), but it becomes out of sync over longer periods.

The wall clock is therefore more accurate than the monotonic clock. However, depending on the backend, a hypercall may be executed, which makes this clock run slower.

Input/Output

Solo5 provides a way of interacting with virtual ‘devices’ that are directly available and connected via the tender being used. These devices are

• net devices (which correspond to TAP interfaces: or, more practically, Ethernet sockets)
• block devices (which correspond to areas where pages can be read from and written to: which, in practical terms, may correspond to SATA sockets).

These devices are represented on the unikernel side by a solo5_handle_t. It is through these values that the unikernel can interact with these devices. You can obtain such a value using the solo5_*_acquire functions.

Type for sets of up to 64 I/O handles.

Suspends executon of the application until either:

• monotonic time reaches deadline, or
• at least one network device is ready for input

If ready_set is not NULL, it will be filled in with the set of solo5_handle_t's ready for input.

This function is generally referred to as the poll point for retrieving events relating to devices (namely, the arrival of an Ethernet frame on one of our network devices).

Network

A Solo5 unikernel can manage a network device (which, in practice, may correspond to an Ethernet port). This device can be configured via the tender, and you can, in particular, set a specific MAC address and a specific Maximum Transmission Unit (MTU). Ethernet frames are expected to be written (using solo5_net_write) and received (using solo5_net_read).

Here is an example of how to invoke solo5-hvt to attach a TAP interface as a network device to the unikernel (with a specific MAC address and a specific MTU):

$ ip tuntap add tap0 mode tap
$ ip link set dev tap0 up mtu 1500
$ solo5-hvt --net:service=tap0 --net-mac:service=11:7e:cf:4b:e7:db \
  -- unikernel.hvt

solo5_net_acquire acquires a handle to the network device declared as name in the application manifest. The returned handle is stored in *handle, and properties of the network device are stored in *info. Caller must supply space for struct solo5_net_info in info. This function may only be called once for each device name. Subsequent calls will return SOLO5_R_EINVAL.

Sends a single network packet to the network device identified by handle, from the buffer *buf, without blocking. If the packet cannot be sent due to a transient error (e.g. no resources available) it will be silently dropped.

The maximum allowed value for size is solo5_net_info.mtu + SOLO5_NET_HLEN. The packet must include the ethernet frame header.

Receives a single network packet from the network device identified by handle into the buffer *buf, without blocking. size must be aat least solo5_net_info.mtu + SOLO5_NET_HLEN).

If not packets are available, it returns SOLO5_R_AGAIN. Otherwise, it returns SOLO5_R_OK and the size of the received packet including the ethernet frame header in *read_size.

Block device

Information relating to a block device when Solo5 is accessing one. The minimum unit of I/O which can be performed on a block device is defined by solo5_block_info.block_size (known as sector size). In other words, reading and writing take place in sectors (rather than bytes).

Acquire a handle to the block device declared as name in the application manifest. The returned handle is stored in *handle, and properties of the block device are stored in *info. Caller must supply space for struct solo5_block_info in info. This function may only be called once for each device name. Subsequent calls will return SOLO5_EINVAL.

Writes data of size bytes from the buffer *buf to the block device identified by handle, starting at byte offset. Data is either written in it's entirety or not at all ("short writes" are not possible).

Both size and offset must be a multiple of the block size/sector size, otherwise SOLO5_R_EINVAL is returned.

Reads data of size bytes into buffer *buf from the block device identified by handle, starting at byte offset. Always reads the full amount of size bytes ("short reads" are not possible).

Both size and offset must be a multiple of the block size/sector size, otherwise SOLO5_R_EINVAL is returned.