I'm seeing what appears to be race conditions in the tests, so
we're not out of the woods yet. I think I just need to introduce
a lock for the cptr cache. It wasn't originally designed to be
thread safe since only one thread at a time was using it. But we
need it now.

There are a few other miscellaneous changes:

  - Moves cptr manipulation into public header. Doc cleanup.
  - cptr_init returns an integer now (non-zero signals failure).
  - Adds CAP_BUG macro. Library code invokes this to abort or signal
    a serious internal library error (e.g., unexpected switch case).

              kernel:   CAP_BUG ==> BUG
              user:     CAP_BUG ==> abort

  - Aside from the cptr cache code updates for the modified struct,
    separates cptr cache initialization into two parts: alloc and init.
    Motivation: Some users of libcap will have already allocated the
    cptr cache (e.g., declared it as a static global), and only need
    it initialized. So, to fully initialize a cptr cache, you now need
    to do, e.g.,

                int ret;
                cptr_cache *cache;

                ret = cptr_cache_alloc(&cache);
                if (ret)
                      ... handle error ...

                ret = cptr_cache_init(cache);
                if (ret) {
                      cptr_cache_free(cache);
                      ... handle error ...
                }

  - Updates test apps to use new cptr cache API (alloc then init). Adds
    some extra error handling/clean up code.