High-Level API

[ramsdell@mitre.org (John D. Ramsdell)]

> From: Harry Butterworth <harry@hebutterworth.freeserve.co.uk>
...
> But, whatever the low-level API, whether grant-tables or something
> which has better support for revocation and n-way communication, I
> think there needs to be a small library to implement a higher level
> API that is more convenient for driver authors to use directly.

Harry,

I curious to know what abstractions you would want to collected
together in a high-level API.  Is there a common pattern of usage that
can be easily packaged as a high-level API?  I tried the think of a
generic, but high-level API for establishing communication between
domains, which I have enclosed.  Is this the kind of API you're
talking about?  Rather than dwelling on my proposal, perhaps it would
be most interesting if you proposed an API at the same level of detail.

John

Name: advertise_endpoint

Inputs:
    domid_t buddy      // The domain with which to share information
    void (*a_handler)(domid_t buddy, void *data) // Handler invoked 
    // when a notification is received on the read port
    void *data         // Application specific data given to handlers

Outputs:
    void *write_page   // Page written in this domain, and read by the buddy
    evtchn_port_t read_port  // port used to notify the buddy that data
    // in the read page has been read.

Implementation:
    The write_page and an unbound port is allocated.  A grant ref is
    generated for the write page, and the ref and the port is
    published using XenBus.
    
Name: connect_to_endpoint

Inputs:
    domid_t buddy      // The domain with which to share information
    void (*a_handler)(domid_t buddy, void *data) // Handler invoked 
    // when a notification is received on the write port
    void *data         // Application specific data given to handlers

Outputs:
    void *read_page    // Page read in this domain, and written by the buddy
    evtchn_port_t write_port  // port used to notify that data is ready
    // for the other domain in the write page
    grant_handle_t handle    // Handle for mapped read page

Implementation:
    A grant ref and port associated with the buddy domain is obtained
    via XenBus.  The mapped page is returned as the read page, and the
    result of performing an interdomain bind is the write port.