Re: RFC/Proposal: Partial `libxenctrl` API/ABI stabilisation

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 18/05/15 16:30, Ian Campbell wrote:
> # Major External Consumers of `libxenctrl`
>
> * qemu
> * kexec tools
> * in guest tools e.g. users of `libxenstore`, `libvchan`, and by
>   extension `grant table` and `event channel` functionality. NB:
>   `libxenstore` is already `SSU` or `SSS` (XXX?)
>
> # `libxenctrl` symbols
>
> Gathered by:
>
>     nm tools/libxc/libxenctrl.so | grep ' [Tt] ' | cut -f 3 -d \ | sort -u
>
> `libxenctrl` today exposes many symbols which look to be internal. We
> should consider also reducing that set by using
> `__attribute__((visibility("hidden")))`.

Don't forget libxenguest.so which is built sharing some of the same
source.  I suspect that quite a few of the libxenctrl symbols could move to

>
> The following proposes some functional groupings via some proposed
> split library names. In some cases we may also wish to consider
> replacing an API with one which can be properly maintained going
> forwards. e.g.:
>
> - perhaps replacing domctl's used by qemu with new stable
>   hypercall ABIs and reflecting that in new library APIs.
> - perhaps exposing more constrained versions of some broad interfaces
>   for external users.
>
> XXX: Change `xc_*` namespacing as well as library names?
>
> ## `libxenhypercall`
>
> Core open/close interface, "make a hypercall" functionality, hypercall
> buffers.
>
> All other libraries likely depend on this. Applications do as well in
> order to access open/close interface at least.
>
>     - xc_interface_close
>     - xc_interface_is_fake (???)

This is used when running something wanting libxc on a non xen system. 
e.g. readnotes which invokes the Xen elf parsing on a binary, but
doesn't have any actual hypervisor interaction.

>     - xc_interface_open
>     - xc_hypercall_buffer_array_create
>     - xc_hypercall_buffer_array_destroy

There are surely more than this when it comes to hypercall buffers?

One issue I have found with libxc in general is that a surprising
quantity of code is in static inlines in header files, which ends up
moving into the includee's code. (I had a particular problem with
do_domctl() and the Xen Interface Version for a project I did a while back)

At some point with some copious free time, I want to see about doing an
ioctl to get lowmem pages out of the kernel, which would be large
benifit for longer-running operations using hypercalls.  The logdirty
bitmap for example is large, used frequently during migrate, and are
currently allocated, double bounced, and deallocated on every individual
call.


>
> ## `libxenevtchn`
>
> Interacting with `/dev/xen/evtchn`
>
>     - xc_evtchn_alloc_unbound
>     - xc_evtchn_bind_interdomain
>     - xc_evtchn_bind_unbound_port
>     - xc_evtchn_bind_virq
>     - xc_evtchn_close
>     - xc_evtchn_fd
>     - xc_evtchn_notify
>     - xc_evtchn_open
>     - xc_evtchn_pending
>     - xc_evtchn_reset
>     - xc_evtchn_status
>     - xc_evtchn_unbind
>     - xc_evtchn_unmask
>
> ## `libxengnttab`
>
> Interacting with `/dev/xen/gnt{shr,alloc}`
>
> XXX two libs or one?
>
>     - xc_gntshr_close
>     - xc_gntshr_munmap
>     - xc_gntshr_open
>     - xc_gntshr_share_page_notify
>     - xc_gntshr_share_pages
>     - xc_gnttab_close
>     - xc_gnttab_get_version
>     - xc_gnttab_map_domain_grant_refs
>     - xc_gnttab_map_grant_ref
>     - xc_gnttab_map_grant_ref_notify
>     - xc_gnttab_map_grant_refs
>     - xc_gnttab_map_table_v1
>     - xc_gnttab_map_table_v2
>     - xc_gnttab_munmap
>     - xc_gnttab_op
>     - xc_gnttab_open
>     - xc_gnttab_set_max_grants

One probably, given how small it would be.

~Andrew