EXTERNAL_HEADERS/img4/image.h

   1 /*!
   2  * @header
   3  * Interfaces for manipulating Image4 firmware images.
   4  */
   5 #ifndef __IMG4_IMAGE_H
   6 #define __IMG4_IMAGE_H
   7
   8 #ifndef __IMG4_INDIRECT
   9 #error "Please #include <img4/firmware.h> instead of this file directly"
  10 #endif // __IMG4_INDIRECT
  11
  12 #if IMG4_TAPI
  13 #include "tapi.h"
  14 #endif
  15
  16 OS_ASSUME_NONNULL_BEGIN
  17
  18 /*!
  19  * @function img4_image_get_bytes
  20  * Returns the authenticated payload from an Image4 image.
  21  *
  22  * @param image
  23  * The image to query.
  24  *
  25  * @result
  26  * A buffer which describes the authenticated payload.
  27  */
  28 #if !XNU_KERNEL_PRIVATE
  29 IMG4_API_AVAILABLE_20200508
  30 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
  31 const img4_buff_t *
  32 img4_image_get_bytes(img4_image_t image);
  33 #else
  34 #define img4_image_get_bytes(...) (img4if->i4if_v7.image_get_bytes(__VA_ARGS__))
  35 #endif
  36
  37 /*!
  38  * @function img4_image_get_property_bool
  39  * Retrieves the Boolean value for the requested image property.
  40  *
  41  * @param image
  42  * The image to query.
  43  *
  44  * @param _4cc
  45  * The 4cc of the desired image property.
  46  *
  47  * @param storage
  48  * A pointer to storage for a Boolean value.
  49  *
  50  * @result
  51  * If the property is present for the image, a pointer to the storage provided
  52  * in {@link storage}. If the property is not present in the image or its value
  53  * is not a Boolean, NULL is returned.
  54  *
  55  * @discussion
  56  * If the property is present for the image, a pointer to the storage provided
  57  * in {@link storage}. If the property is not present in the image or its value
  58  * is not a Boolean, NULL is returned.
  59  */
  60 #if !XNU_KERNEL_PRIVATE
  61 IMG4_API_AVAILABLE_20200508
  62 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
  63 const bool *
  64 img4_image_get_property_bool(img4_image_t image,
  65                 img4_4cc_t _4cc,
  66                 bool *storage);
  67 #else
  68 #define img4_image_get_property_bool(...) \
  69                 (img4if->i4if_v7.image_get_property_bool(__VA_ARGS__))
  70 #endif
  71
  72 /*!
  73  * @function img4_image_get_property_uint32
  74  * Retrieves the unsigned 32-bit integer value for the requested image property.
  75  *
  76  * @param image
  77  * The image to query.
  78  *
  79  * @param _4cc
  80  * The 4cc of the desired image property.
  81  *
  82  * @param storage
  83  * A pointer to storage for a 32-bit unsigned integer value.
  84  *
  85  * @result
  86  * If the property is present for the image, a pointer to the storage provided
  87  * in {@link storage}. If the property is not present in the image or its value
  88  * is not an unsigned 32-bit integer, NULL is returned.
  89  */
  90 #if !XNU_KERNEL_PRIVATE
  91 IMG4_API_AVAILABLE_20200508
  92 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
  93 const uint32_t *
  94 img4_image_get_property_uint32(img4_image_t image,
  95                 img4_4cc_t _4cc,
  96                 uint32_t *storage);
  97 #else
  98 #define img4_image_get_property_uint32(...) \
  99                 (img4if->i4if_v7.image_get_property_uint32(__VA_ARGS__))
 100 #endif
 101
 102 /*!
 103  * @function img4_image_get_property_uint64
 104  * Retrieves the unsigned 64-bit integer value for the requested image property.
 105  *
 106  * @param image
 107  * The image to query.
 108  *
 109  * @param _4cc
 110  * The 4cc of the desired image property.
 111  *
 112  * @param storage
 113  * A pointer to storage for a 64-bit unsigned integer value.
 114  *
 115  * @result
 116  * If the property is present for the image, a pointer to the storage provided
 117  * in {@link storage}. If the property is not present in the image or its value
 118  * is not an unsigned 64-bit integer, NULL is returned.
 119  */
 120 #if !XNU_KERNEL_PRIVATE
 121 IMG4_API_AVAILABLE_20200508
 122 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
 123 const uint64_t *
 124 img4_image_get_property_uint64(img4_image_t image,
 125                 img4_4cc_t _4cc,
 126                 uint64_t *storage);
 127 #else
 128 #define img4_image_get_property_uint64(...) \
 129                 (img4if->i4if_v7.image_get_property_uint64(__VA_ARGS__))
 130 #endif
 131
 132 /*!
 133  * @function img4_image_get_property_data
 134  * Retrieves the buffer value for the requested image property.
 135  *
 136  * @param image
 137  * The image to query.
 138  *
 139  * @param _4cc
 140  * The 4cc of the desired image property.
 141  *
 142  * @param storage
 143  * A pointer to storage for a buffer value.
 144  *
 145  * @result
 146  * If the property is present for the image, a pointer to the storage provided
 147  * in {@link storage}. If the property is not present in the image or its value
 148  * is not a data, NULL is returned.
 149  */
 150 #if !XNU_KERNEL_PRIVATE
 151 IMG4_API_AVAILABLE_20200508
 152 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
 153 const img4_buff_t *
 154 img4_image_get_property_data(img4_image_t image,
 155                 img4_4cc_t _4cc,
 156                 img4_buff_t *storage);
 157 #else
 158 #define img4_image_get_property_data(...) \
 159                 (img4if->i4if_v7.image_get_property_data(__VA_ARGS__))
 160 #endif
 161
 162 OS_ASSUME_NONNULL_END
 163
 164 #endif // __IMG4_IMAGE_H