9292 to understand how reading and writing behave when developing an application
9393 as a unikernel using Solo5/Unikraft.
9494
95- Writing a packet to the net interface is direct and failsafe. In other
95+ Writing a packet to the net interface is {b direct} and failsafe. In other
9696 words, we don't need to wait for anything to happen before writing to the
9797 net device (if an error occurs on your host system, the tender will fail —
9898 and by extension, so will your unikernel). So, from the scheduler's point of
@@ -187,14 +187,32 @@ module Net : sig
187187 @raise Invalid_argument
188188 if [off] and [len] do not designate a valid range of [bstr]. *)
189189
190+ (* * {4 Writing to a net device according to the backend.}
191+
192+ Depending on the backend used (Solo5/hvt or Unikraft & Solo5/virtio),
193+ writing to a TAP interface may involve an intermediate "queue" between the
194+ unikernel (which fills this queue) and the tender (which consumes this
195+ queue). This feature allows for a process on the tender side that attempts
196+ to write without interruption (and thus improves performance).
197+
198+ In this case, unlike Solo5/hvt, writing is not necessarily effective
199+ between the unikernel and the TAP interface. However, this effectiveness
200+ also involves the tender's point of view, which is not taken into account
201+ (deliberately) in this documentation.
202+
203+ Furthermore, from the point of view of the unikernel, OCaml and Miou (and
204+ only on that side), the write is effective. *)
205+
190206 val write_bigstring : t -> ?off : int -> ?len : int -> bigstring -> unit
191207 (* * [write_bigstring t ?off ?len bstr] writes [len] (defaults to
192208 [Bigarray.Array1.dim bstr - off]) bytes to the net device [t], taking them
193209 from byte sequence [bstr], starting at position [off] (defaults to [0]) in
194210 [bstr].
195211
196- [write_bigstring] is currently writing directly to the net device [t].
197- Writing cannot fail.
212+ [write_bigstring] is currently writing directly to the net device [t]. In
213+ other words, the write is effective and does not give the scheduler the
214+ opportunity to execute another task during the write. It is therefore an
215+ atomic operation. Writing cannot fail.
198216
199217 @raise Invalid_argument
200218 if [off] and [len] do not designate a valid range of [bstr]. *)
@@ -207,7 +225,11 @@ module Net : sig
207225 to write a new Ethernet frame. In the case of Unikraft, for example, we
208226 need to allocate a buffer that will be added to Unikraft's internal queue
209227 so that it can be written to the TAP interface. The same applies to Solo5
210- and its virtio support.
228+ and its {i virtio} support.
229+
230+ [write_into] has the same characteristic as {!val:write_bigstring}, i.e.
231+ it is an atomic operation that does not give the scheduler the opportunity
232+ to execute another task.
211233
212234 In this specific case, [write_into] is more useful than
213235 {!val:write_bigstring} because it prepares the allocation and lets the
0 commit comments