mojo/system/options_validation.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Functions to help with verifying various |Mojo...Options| structs from the
   6 // (public, C) API. These are "extensible" structs, which all have |struct_size|
   7 // as their first member. All fields (other than |struct_size|) are optional,
   8 // but any |flags| specified must be known to the system (otherwise, an error of
   9 // |MOJO_RESULT_UNIMPLEMENTED| should be returned).
  10
  11 #ifndef MOJO_SYSTEM_OPTIONS_VALIDATION_H_
  12 #define MOJO_SYSTEM_OPTIONS_VALIDATION_H_
  13
  14 #include <stddef.h>
  15 #include <stdint.h>
  16
  17 #include "base/macros.h"
  18 #include "mojo/public/c/system/types.h"
  19 #include "mojo/system/memory.h"
  20 #include "mojo/system/system_impl_export.h"
  21
  22 namespace mojo {
  23 namespace system {
  24
  25 // Checks that |buffer| appears to contain a valid Options struct, namely
  26 // properly aligned and with a |struct_size| field (which must the first field
  27 // of the struct and be a |uint32_t|) containing a plausible size.
  28 template <class Options>
  29 bool IsOptionsStructPointerAndSizeValid(const void* buffer) {
  30   COMPILE_ASSERT(offsetof(Options, struct_size) == 0,
  31                  Options_struct_size_not_first_member);
  32   // TODO(vtl): With C++11, use |sizeof(Options::struct_size)| instead.
  33   COMPILE_ASSERT(sizeof(static_cast<const Options*>(buffer)->struct_size) ==
  34                      sizeof(uint32_t),
  35                  Options_struct_size_not_32_bits);
  36
  37   // Note: Use |MOJO_ALIGNOF()| here to match the exact macro used in the
  38   // declaration of Options structs.
  39   if (!internal::VerifyUserPointerHelper<sizeof(uint32_t),
  40                                          MOJO_ALIGNOF(Options)>(buffer))
  41     return false;
  42
  43   return static_cast<const Options*>(buffer)->struct_size >= sizeof(uint32_t);
  44 }
  45
  46 // Checks that the Options struct in |buffer| has a member with the given offset
  47 // and size. This may be called only if |IsOptionsStructPointerAndSizeValid()|
  48 // returned true.
  49 //
  50 // You may want to use the macro |HAS_OPTIONS_STRUCT_MEMBER()| instead.
  51 template <class Options, size_t offset, size_t size>
  52 bool HasOptionsStructMember(const void* buffer) {
  53   // We assume that |offset| and |size| are reasonable, since they should come
  54   // from |offsetof(Options, some_member)| and |sizeof(Options::some_member)|,
  55   // respectively.
  56   return static_cast<const Options*>(buffer)->struct_size >=
  57       offset + size;
  58 }
  59
  60 // Macro to invoke |HasOptionsStructMember()| parametrized by member name
  61 // instead of offset and size.
  62 //
  63 // (We can't just give |HasOptionsStructMember()| a member pointer template
  64 // argument instead, since there's no good/strictly-correct way to get an offset
  65 // from that.)
  66 //
  67 // TODO(vtl): With C++11, use |sizeof(Options::member)| instead.
  68 #define HAS_OPTIONS_STRUCT_MEMBER(Options, member, buffer) \
  69     (HasOptionsStructMember< \
  70         Options, \
  71         offsetof(Options, member), \
  72         sizeof(static_cast<const Options*>(buffer)->member)>(buffer))
  73
  74 // Checks that the (standard) |flags| member consists of only known flags. This
  75 // should only be called if |HAS_OPTIONS_STRUCT_MEMBER()| returned true for the
  76 // |flags| field.
  77 //
  78 // The rationale for *not* ignoring these flags is that the caller should have a
  79 // way of specifying that certain options not be ignored. E.g., one may have a
  80 // |MOJO_..._OPTIONS_FLAG_DONT_IGNORE_FOO| flag and a |foo| member; if the flag
  81 // is set, it will guarantee that the version of the system knows about the
  82 // |foo| member (and won't ignore it).
  83 template <class Options>
  84 bool AreOptionsFlagsAllKnown(const void* buffer, uint32_t known_flags) {
  85   return (static_cast<const Options*>(buffer)->flags & ~known_flags) == 0;
  86 }
  87
  88 // Does basic cursory checks on |in_options| (|struct_size| and |flags|; |flags|
  89 // must immediately follow |struct_size|); |in_options| must be non-null. The
  90 // following should be done before calling this:
  91 //   - Set |out_options| to the default options.
  92 //   - If |in_options| is null, don't continue (success).
  93 // This function then:
  94 //   - Checks if (according to |IsOptionsStructPointerAndSizeValid()|),
  95 //     |struct_size| is valid; if not returns |MOJO_RESULT_INVALID_ARGUMENT|.
  96 //   - If |in_options| has a |flags| field, checks that it only has
  97 //     |known_flags| set; if so copies it to |out_options->flags|, and if not
  98 //     returns |MOJO_RESULT_UNIMPLEMENTED|.
  99 //   - At this point, returns |MOJO_RESULT_OK|.
 100 template <class Options>
 101 MojoResult ValidateOptionsStructPointerSizeAndFlags(
 102     const Options* in_options,
 103     uint32_t known_flags,
 104     Options* out_options) {
 105   COMPILE_ASSERT(offsetof(Options, flags) == sizeof(uint32_t),
 106                  Options_flags_doesnt_immediately_follow_struct_size);
 107
 108   if (!IsOptionsStructPointerAndSizeValid<Options>(in_options))
 109     return MOJO_RESULT_INVALID_ARGUMENT;
 110
 111   if (HAS_OPTIONS_STRUCT_MEMBER(Options, flags, in_options)) {
 112     if (!AreOptionsFlagsAllKnown<Options>(in_options, known_flags))
 113       return MOJO_RESULT_UNIMPLEMENTED;
 114     out_options->flags = in_options->flags;
 115   }
 116
 117   return MOJO_RESULT_OK;
 118 }
 119
 120 }  // namespace system
 121 }  // namespace mojo
 122
 123 #endif  // MOJO_SYSTEM_OPTIONS_VALIDATION_H_