Proposed API for querying information about (e.g. shared) buffers.

mojo/public/c/system/buffer.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This file contains types/constants and functions specific to buffers (and in
 // particular shared buffers).
 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions
 // from (shared) buffer creation.
 //
 // Note: This header should be compilable as C.
@@ skipping 23 matching lines @@
 
 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
 struct MOJO_ALIGNAS(8) MojoCreateSharedBufferOptions {
   uint32_t struct_size;
   MojoCreateSharedBufferOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8,
                    "MojoCreateSharedBufferOptions has wrong size");
 
 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating
-// access to a shared buffer to |MojoDuplicateBufferHandle()|.
+// access to a buffer to |MojoDuplicateBufferHandle()|.
 //   |uint32_t struct_size|: Set to the size of the
 //       |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future
 //       extensions.)
 //   |MojoDuplicateBufferHandleOptionsFlags flags|: Reserved for future use.
 //       |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE|: No flags; default
 //       mode.
 //
 // TODO(vtl): Add flags to remove writability (and executability)? Also, COW?
 
 typedef uint32_t MojoDuplicateBufferHandleOptionsFlags;
 
 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \
   ((MojoDuplicateBufferHandleOptionsFlags)0)
 
-struct MojoDuplicateBufferHandleOptions {
+struct MOJO_ALIGNAS(8) MojoDuplicateBufferHandleOptions {

[viettrungluu, 2016/03/01 20:36:20]

This is an ABI-breaking change, but luckily, no one actually creates/uses this
struct currently. Phew.

   uint32_t struct_size;
   MojoDuplicateBufferHandleOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8,
                    "MojoDuplicateBufferHandleOptions has wrong size");
 
+// |MojoBufferInformation|: Used to provide information about a buffer (see
+// |MojoGetBufferInformation()|.
+//   |uint32_t struct_size|: Set to the size of the |MojoBufferInformation|
+//       struct. (Used to allow for future extensions.)
+//   |MojoBufferInformationFlags flags|: Reserved for future use.
+//   |uint64_t num_bytes|: Size of the buffer.
+//
+// TODO(vtl): Add flags to indicate writability, etc.? Also, type of buffer?
+
+typedef uint32_t MojoBufferInformationFlags;
+
+#define MOJO_BUFFER_INFORMATION_FLAG_NONE ((MojoBufferInformationFlags)0)
+
+struct MOJO_ALIGNAS(8) MojoBufferInformation {
+  uint32_t struct_size;
+  MojoBufferInformationFlags flags;
+  uint64_t num_bytes;
+};
+MOJO_STATIC_ASSERT(sizeof(MojoBufferInformation) == 16,
+                   "MojoBufferInformation has wrong size");
+
 // |MojoMapBufferFlags|: Used to specify different modes to |MojoMapBuffer()|.
 //   |MOJO_MAP_BUFFER_FLAG_NONE| - No flags; default mode.
 
 typedef uint32_t MojoMapBufferFlags;
 
 #define MOJO_MAP_BUFFER_FLAG_NONE ((MojoMapBufferFlags)0)
 
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ skipping 42 matching lines @@
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or |*options| is invalid).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 MojoResult MojoDuplicateBufferHandle(
     MojoHandle buffer_handle,
     const struct MojoDuplicateBufferHandleOptions* options,  // Optional.
     MojoHandle* new_buffer_handle);                          // Out.
 
+// Gets information about the buffer with handle |buffer_handle|. |info| should
+// be non-null and point to a buffer of size |info_num_bytes|; |info_num_bytes|
+// should be at least the size of |struct MojoBufferInformation| (if/when the
+// definition of this struct is extended, sizes of previous definitions will
+// still be accepted and |*info| filled accordingly).
+//
+// On success, |*info| will be filled with information about the given buffer.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
+//       |buffer_handle| is not a valid buffer handle, |*info| is null, or
+//       |info_num_bytes| is too small).

[jamesr, 2016/03/07 19:26:36]

hm, buffer too small is a MOJO_RESULT_RESOURCE_EXHAUSTED return code for
MojoReadMessage. if the implementation has a larger definition of the buffer in
mind than the caller how does the caller get access to the fields they
understand? seems impossible with this setup unless the caller guesses larger
and larger buffer sizes to allocate for MojoBufferInformation until they get
MOJO_RESULT_OK, only then to read out the fields they know

what if the caller had to populate |info->struct_size| before calling the
function and the callee populated the fields up to that size, or if the
implementation always filled up to min(sizeof(implementation's
MojoBufferInformation), |info_num_bytes|) into the passed-in struct?

[viettrungluu, 2016/03/07 20:44:22]

See the parenthetical comment in the first paragraph of the comment (this will
accept and populate according to old valid sizes).
I thought about that, but opted to not do it, since in a kernel impl it'd mean
having to read in from userspace just to get a uint32_t.
We could do that. I just wonder if, e.g., setting |info_num_bytes| to 0 (or
worse, 1; or maybe more plausibly bad, 5) is valid. Or what "filled up to"
means. (The easiest implementation would be to partially memcpy a "full" struct,
and set info->struct_size to that amount copied, but that seems a little
sketchy.)

[jamesr, 2016/03/07 21:42:35]

Do we have any definition for what "old valid sizes" are?
Aside: with this scheme it seems impossible to add fields to the struct unless
they grow the size, which means if we want to add a 4-byte value (like another
flags field or something) we need to grow the struct by 8 bytes or we wouldn't
be able to add another 4-byte value later on

Maybe an explicit version field along with documented values for the size of
each version would have been better, but it's kinda late for that now.

How about we just document what values of |info_num_bytes| we support and
populate, i.e.

16: struct_size, flags, num_bytes

then sometime in the future

24: struct_size, flags, num_bytes, alignment (or whatever) the next field is

and then say that if info_num_bytes is >= any value the implementation
understands it fills in the largest value it understands and sets that in
struct_size, otherwise if info_num_bytes is not equal to one the values the
implementation understands it returns INVALID_ARGUMENT, otherwise it fills in
that exact version.

+MojoResult MojoGetBufferInformation(MojoHandle buffer_handle,
+                                    struct MojoBufferInformation* info,  // Out.
+                                    uint32_t info_num_bytes);            // In.

[jamesr, 2016/03/07 19:26:36]

inparams before outparams?

[viettrungluu, 2016/03/07 20:44:23]

I'm following existing (arguably-bad[*]) precedent (e.g., in MojoReadMessage).

[*] Except that it'd get violated anyway, since MojoReadMessage has multiple
buffers, and having the size next to the buffer seems more desirable than
following the in-then-out order. (Though MojoReadMessage's size params are
in/out, not just in.)

[jamesr, 2016/03/07 21:42:35]

Read's params are in/out except for flags which comes at the end. blah!

the other crappy thing about this ordering is that it's 32 bit, 64 bit, then 32
bit. if it was 32/32/64 it could potentially pack better

+
 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given
 // by |buffer_handle| into memory, with options specified by |flags|. |offset +
 // num_bytes| must be less than or equal to the size of the buffer. On success,
 // |*buffer| points to memory with the requested part of the buffer. (On
 // failure, it is not modified.)
 //
 // A single buffer handle may have multiple active mappings (possibly depending
 // on the buffer type). The permissions (e.g., writable or executable) of the
 // returned memory may depend on the properties of the buffer and properties
 // attached to the buffer handle as well as |flags|.
@@ skipping 24 matching lines @@
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the
 //       result of |MojoMapBuffer()| or has already been unmapped).
 MojoResult MojoUnmapBuffer(void* buffer);  // In.
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_