Summary: udi.txt

''This document contains the UDI design methods''

Topic: General Design
The libudi included is meant for mostly hosted applications. It requires that
a C library is present as a compilation dependency. Of the C library, only 
the freestanding headers, <string.h> and malloc/free are used.

Topic: Control transfers
MOS is based on a message passing infrastructure, and the UDI implementation
is designed to act accordingly. The message format is mostly mapped 1:1 to UDI
requests except for the control blocks, which have to be maintained locally.
Specifically, the initiator_context field has to be maintained over paired
calls.

To match, every request will have to be associated with a control block during
the conversion. Control block lifecycle depends on the kind of message:
Request (sent) - A driver sending a request expects an answer corresponding to
that request, so the control block is maintained until the reply arrives. The
interfacing code is expected to call <_udi_park_cb> to get a request ID.
Request (received) - A received request has no associated control block, so
one needs to be created. <_udi_enter_cb> creates a control block without
depending on an existing context like <udi_create_cb>.
Reply (sent) - Sending a reply completes a transaction, and the associated
control block is no longer needed. <_udi_exit_cb> releases the cb
Reply (received) - When a reply is received, the control block needs to be
retrieved that originally created the request. This is performed by matching
the park with an <_udi_cb_unpark> where the request id is converted back to
the original cb.
UDI uses acknowledgements, eliminating the need for unidirectional messaging.
Instead, a simple ack is used as the reply.

The enter/exit/park/unpark functions maintain enough state so that it becomes
possible to instrument pending requests.

Topic: Porting
Porting the core of UDI requires that the host is able to provide an 
implementation of malloc/free, which are allowed to block. This is done to
simplify the implementation and might be removed later when full continuation
support is wanted.
For practical use of the UDI library, you will need to provide an 
communication layer so that native calls are converted to UDI conventions, 
and that matching replies are converted back to native ones, for each of the
metalanguages you intend to provide support for. The core provides functions
that facilitate conversion steps.

A partial list of requirements for the core functions include:
* malloc
* free 
* memcpy
* memset
* uint[8|16|32]_t
* int[8|16|32]_t