Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add grant-handling code to OS.Xen #9

Merged
merged 1 commit into from Mar 21, 2019

Conversation

Projects
None yet
2 participants
@talex5
Copy link
Contributor

commented Mar 18, 2019

The xen-gnt library provides a single OCaml module that tries to provide grant handling on Unix (for Unix domains running under the Xen hypervisor) and Xen (for unikernels using Mini-OS). However, these
platforms are really quite different: many of the functions provided in the xen-gnt API will raise an exception if called on the wrong platform, and many of the implementations call a C function to find out which platform is being used and then choose one of two implementations based on that. It is not possible to depend on Unix or Xen specific libraries in xen-gnt because a single implementation must work on both. Instead, everything platform-specific happens in the C stubs. The Unix stubs are in the xen-gnt repository, while the Xen ones are in mirage-xen, making it very hard to change anything safely.

This commit adds a new Xen-unikernel-only implmentation and API. It is based on xen-gnt's Gnt API, but specialised to Xen and cleaned up:

  • All Unix code has been removed.
  • The unused interface arguments have gone. This was just unit on Xen. The grant table is now always initialised at boot. The open and close functions are no longer needed and have gone.
  • C stubs that do nothing are no longer called (but they do remain, to avoid breaking xen-gnt, which still links against them).
  • share_pages and share_pages_exn now use labelled arguments (they take two integers and a bool and the meanings are not obvious).
  • All writable parameters are now labelled for clarity.
  • Gntref is now a module with an abstract type t. There are functions to parse and print grant refs.
  • Many functions now indicate errors by returning a result (and don't throw away the error message, as many did by returning None for any error).
  • I renamed Gnttab and Gntshr to Import and Export. This is partly because I always forget which is which, and partly so we can export the main type as t without it sounding like it represents a table.
  • Gnttab.grant is now Import.t.
  • Gntshr.share is now Export.t and is abstract.
  • To improve safety, we now keep a table of exported pages. Sharing a page first adds it to this table. Unsharing removes it from the table on success. This prevents pages from being GC'd and reused while another domain still has access to them (which could otherwise happen if the unikernel is buggy).
  • Various unsharing functions now take a release_refs flag that releases the grant refs after unsharing the pages (otherwise, it's easy to forget).
  • We no longer call Gnt.suspend and Gnt.resume. These both simply call back to C stubs in mirage-xen, neither of which does anything.
  • Operations on local mappings (unmap_exn and unmap) are now inside the Local_mapping module.
  • with_mapping no longer passes None to the user function if the mapping fails. It just returns the error directly.

We still depend on xen-gnt. This is needed because it keeps track of free grant table entries and we can't duplicate that here as long as any library is still using xen-gnt.

My intention is that the Unix-specific parts of xen-gnt can be moved out to xen-gnt-unix (which is currently just C stubs). The kernel-specific parts can be removed. The ocaml-vchan library contains its own grant
abstraction (Unix, Xen, and an in-memory test backend) which I think makes more sense for high-level cross-platform grant usage.

Add grant-handling code to OS.Xen
The xen-gnt library provides a single OCaml module that tries to provide
grant handling on Unix (for Unix domains running under the Xen
hypervisor) and Xen (for unikernels using Mini-OS). However, these
platforms are really quite different: many of the functions provided in
the xen-gnt API will raise an exception if called on the wrong platform,
and many of the implementations call a C function to find out which
platform is being used and then choose one of two implementations based
on that. It is not possible to depend on Unix or Xen specific libraries
in xen-gnt because a single implementation must work on both. Instead,
everything platform-specific happens in the C stubs. The Unix stubs are
in the xen-gnt repository, while the Xen ones are in mirage-xen, making
it very hard to change anything safely.

This commit adds a new Xen-unikernel-only implmentation and API. It is
based on xen-gnt's Gnt API, but specialised to Xen and cleaned up:

- All Unix code has been removed.
- The unused `interface` arguments have gone. This was just `unit` on
  Xen. The grant table is now always initialised at boot.
  The open and close functions are no longer needed.
- C stubs that do nothing are no longer called (but they do remain, to
  avoid breaking xen-gnt, which still links against them).
- `share_pages` and `share_pages_exn` now use labelled arguments (they
  take two integers and a bool and the meanings are not obvious).
- All `writable` parameters are now labelled for clarity.
- Gntref is now a module with an abstract type `t`. There are functions
  to parse and print grant refs.
- Many functions now indicate errors by returning a `result` (and don't
  throw away the error message, as many did by returning `None` for any
  error).
- I renamed `Gnttab` and `Gntshr` to `Import` and `Export`.
  This is partly because I always forget which is which, and partly so
  we can export the main type as `t` without it sounding like it
  represents a table.
- `Gnttab.grant` is now `Import.t`.
- `Gntshr.share` is now `Export.t` and is abstract.
- To improve safety, we now keep a table of exported pages.
  Sharing a page first adds it to this table. Unsharing removes it from
  the table on success. This prevents pages from being GC'd and reused
  while another domain still has access to them (which could otherwise
  happen if the unikernel is buggy).
- Various unsharing functions now take a `release_refs` flag that
  releases the grant refs after unsharing the pages (otherwise, it's
  easy to forget).
- We no longer call `Gnt.suspend` and `Gnt.resume`. These both simply
  call back to C stubs in mirage-xen, neither of which does anything.
- Operations on local mappings (`unmap_exn` and `unmap`) are now inside
  the `Local_mapping` module.
- `with_mapping` no longer passes `None` to the user function if the
  mapping fails. It just returns the error directly.

We still depend on xen-gnt. This is needed because it keeps track of
free grant table entries and we can't duplicate that here as long as any
library is still using xen-gnt.

My intention is that the Unix-specific parts of xen-gnt can be moved out
to xen-gnt-unix (which is currently just C stubs). The kernel-specific
parts can be removed. The ocaml-vchan library contains its own grant
abstraction (Unix, Xen, and an in-memory test backend) which I think
makes more sense for high-level cross-platform grant usage.

@talex5 talex5 requested review from yomimono and djs55 and removed request for djs55 Mar 18, 2019

@yomimono

This comment has been minimized.

Copy link
Member

commented Mar 21, 2019

I like these changes. Thanks, @talex5 !

@yomimono yomimono merged commit f86e173 into mirage:master Mar 21, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@talex5 talex5 deleted the talex5:xen-gnt branch Mar 22, 2019

@talex5 talex5 referenced this pull request May 4, 2019

Open

Update to new grant API #33

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.