base/include/hidl/MQDescriptor.h - platform/system/libhidl - Git at Google

 /*
  * Copyright (C) 2016 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef _FMSGQ_DESCRIPTOR_H
 #define _FMSGQ_DESCRIPTOR_H

 #include <unistd.h>

 #include <cutils/native_handle.h>
 #include <hidl/HidlInternal.h>
 #include <hidl/HidlSupport.h>

 namespace android {
 namespace hardware {

 typedef uint64_t RingBufferPosition;

 struct GrantorDescriptor {
     uint32_t flags __attribute__ ((aligned(4)));
     uint32_t fdIndex __attribute__ ((aligned(4)));
     uint32_t offset __attribute__ ((aligned(4)));
     uint64_t extent __attribute__ ((aligned(8)));
 };

 static_assert(offsetof(GrantorDescriptor, flags) == 0, "wrong offset");
 static_assert(offsetof(GrantorDescriptor, fdIndex) == 4, "wrong offset");
 static_assert(offsetof(GrantorDescriptor, offset) == 8, "wrong offset");
 static_assert(offsetof(GrantorDescriptor, extent) == 16, "wrong offset");
 static_assert(sizeof(GrantorDescriptor) == 24, "wrong size");
 static_assert(__alignof(GrantorDescriptor) == 8, "wrong alignment");

 enum MQFlavor : uint32_t {
   /*
    * kSynchronizedReadWrite represents the wait-free synchronized flavor of the
    * FMQ. It is intended to be have a single reader and single writer.
    * Attempts to overflow/underflow returns a failure.
    */
   kSynchronizedReadWrite = 0x01,
   /*
    * kUnsynchronizedWrite represents the flavor of FMQ where writes always
    * succeed. This flavor allows one writer and many readers. A read operation
    * can detect an overwrite and reset the read counter.
    */
   kUnsynchronizedWrite = 0x02
 };

 template <typename T, MQFlavor flavor>
 struct MQDescriptor {
     // Takes ownership of handle
     MQDescriptor(
             const std::vector<GrantorDescriptor>& grantors,
             native_handle_t* nHandle, size_t size);

     // Takes ownership of handle
     MQDescriptor(size_t bufferSize, native_handle_t* nHandle,
                  size_t messageSize, bool configureEventFlag = false);

     MQDescriptor();
     ~MQDescriptor();

     explicit MQDescriptor(const MQDescriptor& other) : MQDescriptor() { *this = other; }
     MQDescriptor& operator=(const MQDescriptor& other);

     size_t getSize() const;

     size_t getQuantum() const;

     int32_t getFlags() const;

     bool isHandleValid() const { return mHandle != nullptr; }
     size_t countGrantors() const { return mGrantors.size(); }

     inline const ::android::hardware::hidl_vec<GrantorDescriptor> &grantors() const {
         return mGrantors;
     }

     inline ::android::hardware::hidl_vec<GrantorDescriptor> &grantors() {
         return mGrantors;
     }

     inline const ::native_handle_t *handle() const {
         return mHandle;
     }

     inline ::native_handle_t *handle() {
         return mHandle;
     }

     static const size_t kOffsetOfGrantors;
     static const size_t kOffsetOfHandle;
     enum GrantorType : int { READPTRPOS = 0, WRITEPTRPOS, DATAPTRPOS, EVFLAGWORDPOS };

     /*
      * There should at least be GrantorDescriptors for the read counter, write
      * counter and data buffer. A GrantorDescriptor for an EventFlag word is
      * not required if there is no need for blocking FMQ operations.
      */
     static constexpr int32_t kMinGrantorCount = DATAPTRPOS + 1;

     /*
      * Minimum number of GrantorDescriptors required if EventFlag support is
      * needed for blocking FMQ operations.
      */
     static constexpr int32_t kMinGrantorCountForEvFlagSupport = EVFLAGWORDPOS + 1;

     //TODO(b/34160777) Identify a better solution that supports remoting.
     static inline size_t alignToWordBoundary(size_t length) {
         constexpr size_t kAlignmentSize = 64;
         if (kAlignmentSize % __WORDSIZE != 0) {
             details::logAlwaysFatal("Incompatible word size");
         }

         /*
          * Check if alignment to word boundary would cause an overflow.
          */
         if (length > SIZE_MAX - kAlignmentSize/8 + 1) {
             details::logAlwaysFatal("Queue size too large");
         }

         return (length + kAlignmentSize/8 - 1) & ~(kAlignmentSize/8 - 1U);
     }

     static inline size_t isAlignedToWordBoundary(size_t offset) {
         constexpr size_t kAlignmentSize = 64;
         return (offset & (kAlignmentSize/8 - 1)) == 0;
     }
 private:
     ::android::hardware::hidl_vec<GrantorDescriptor> mGrantors;
     ::android::hardware::details::hidl_pointer<native_handle_t> mHandle;
     uint32_t mQuantum;
     uint32_t mFlags;
 };

 template<typename T, MQFlavor flavor>
 const size_t MQDescriptor<T, flavor>::kOffsetOfGrantors = offsetof(MQDescriptor, mGrantors);

 template<typename T, MQFlavor flavor>
 const size_t MQDescriptor<T, flavor>::kOffsetOfHandle = offsetof(MQDescriptor, mHandle);

 /*
  * MQDescriptorSync will describe the wait-free synchronized
  * flavor of FMQ.
  */
 template<typename T>
 using MQDescriptorSync = MQDescriptor<T, kSynchronizedReadWrite>;

 /*
  * MQDescriptorUnsync will describe the unsynchronized write
  * flavor of FMQ.
  */
 template<typename T>
 using MQDescriptorUnsync = MQDescriptor<T, kUnsynchronizedWrite>;

 template<typename T, MQFlavor flavor>
 MQDescriptor<T, flavor>::MQDescriptor(
         const std::vector<GrantorDescriptor>& grantors,
         native_handle_t* nhandle,
         size_t size)
     : mHandle(nhandle),
       mQuantum(size),
       mFlags(flavor) {
     mGrantors.resize(grantors.size());
     for (size_t i = 0; i < grantors.size(); ++i) {
         if (isAlignedToWordBoundary(grantors[i].offset) == false) {
             details::logAlwaysFatal("Grantor offsets need to be aligned");
         }
         mGrantors[i] = grantors[i];
     }
 }

 template<typename T, MQFlavor flavor>
 MQDescriptor<T, flavor>::MQDescriptor(size_t bufferSize, native_handle_t *nHandle,
                                    size_t messageSize, bool configureEventFlag)
     : mHandle(nHandle), mQuantum(messageSize), mFlags(flavor) {
     /*
      * If configureEventFlag is true, allocate an additional spot in mGrantor
      * for containing the fd and offset for mmapping the EventFlag word.
      */
     mGrantors.resize(configureEventFlag? kMinGrantorCountForEvFlagSupport : kMinGrantorCount);

     size_t memSize[] = {
         sizeof(RingBufferPosition),  /* memory to be allocated for read pointer counter */
         sizeof(RingBufferPosition),  /* memory to be allocated for write pointer counter */
         bufferSize,                  /* memory to be allocated for data buffer */
         sizeof(std::atomic<uint32_t>)/* memory to be allocated for EventFlag word */
     };

     /*
      * Create a default grantor descriptor for read, write pointers and
      * the data buffer. fdIndex parameter is set to 0 by default and
      * the offset for each grantor is contiguous.
      */
     for (size_t grantorPos = 0, offset = 0;
          grantorPos < mGrantors.size();
          offset += memSize[grantorPos++]) {
         mGrantors[grantorPos] = {
             0 /* grantor flags */,
             0 /* fdIndex */,
             static_cast<uint32_t>(alignToWordBoundary(offset)),
             memSize[grantorPos]
         };
     }
 }

 template <typename T, MQFlavor flavor>
 MQDescriptor<T, flavor>& MQDescriptor<T, flavor>::operator=(const MQDescriptor& other) {
     mGrantors = other.mGrantors;
     if (mHandle != nullptr) {
         native_handle_close(mHandle);
         native_handle_delete(mHandle);
         mHandle = nullptr;
     }
     mQuantum = other.mQuantum;
     mFlags = other.mFlags;

     if (other.mHandle != nullptr) {
         mHandle = native_handle_create(
                 other.mHandle->numFds, other.mHandle->numInts);

         for (int i = 0; i < other.mHandle->numFds; ++i) {
             mHandle->data[i] = dup(other.mHandle->data[i]);
         }

         memcpy(&mHandle->data[other.mHandle->numFds],
                &other.mHandle->data[other.mHandle->numFds],
                other.mHandle->numInts * sizeof(int));
     }

     return *this;
 }

 template<typename T, MQFlavor flavor>
 MQDescriptor<T, flavor>::MQDescriptor() : MQDescriptor(
         std::vector<android::hardware::GrantorDescriptor>(),
         nullptr /* nHandle */,
         0 /* size */) {}

 template<typename T, MQFlavor flavor>
 MQDescriptor<T, flavor>::~MQDescriptor() {
     if (mHandle != nullptr) {
         native_handle_close(mHandle);
         native_handle_delete(mHandle);
     }
 }

 template<typename T, MQFlavor flavor>
 size_t MQDescriptor<T, flavor>::getSize() const {
   return mGrantors[DATAPTRPOS].extent;
 }

 template<typename T, MQFlavor flavor>
 size_t MQDescriptor<T, flavor>::getQuantum() const { return mQuantum; }

 template<typename T, MQFlavor flavor>
 int32_t MQDescriptor<T, flavor>::getFlags() const { return mFlags; }

 template<typename T, MQFlavor flavor>
 std::string toString(const MQDescriptor<T, flavor> &q) {
     std::string os;
     if (flavor & kSynchronizedReadWrite) {
         os += "fmq_sync";
     }
     if (flavor & kUnsynchronizedWrite) {
         os += "fmq_unsync";
     }
     os += " {"
        + toString(q.grantors().size()) + " grantor(s), "
        + "size = " + toString(q.getSize())
        + ", .handle = " + toString(q.handle())
        + ", .quantum = " + toString(q.getQuantum()) + "}";
     return os;
 }

 }  // namespace hardware
 }  // namespace android

 #endif  // FMSGQ_DESCRIPTOR_H
	/*
	* Copyright (C) 2016 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef _FMSGQ_DESCRIPTOR_H
	#define _FMSGQ_DESCRIPTOR_H

	#include <unistd.h>

	#include <cutils/native_handle.h>
	#include <hidl/HidlInternal.h>
	#include <hidl/HidlSupport.h>

	namespace android {
	namespace hardware {

	typedef uint64_t RingBufferPosition;

	struct GrantorDescriptor {
	uint32_t flags __attribute__ ((aligned(4)));
	uint32_t fdIndex __attribute__ ((aligned(4)));
	uint32_t offset __attribute__ ((aligned(4)));
	uint64_t extent __attribute__ ((aligned(8)));
	};

	static_assert(offsetof(GrantorDescriptor, flags) == 0, "wrong offset");
	static_assert(offsetof(GrantorDescriptor, fdIndex) == 4, "wrong offset");
	static_assert(offsetof(GrantorDescriptor, offset) == 8, "wrong offset");
	static_assert(offsetof(GrantorDescriptor, extent) == 16, "wrong offset");
	static_assert(sizeof(GrantorDescriptor) == 24, "wrong size");
	static_assert(__alignof(GrantorDescriptor) == 8, "wrong alignment");

	enum MQFlavor : uint32_t {
	/*
	* kSynchronizedReadWrite represents the wait-free synchronized flavor of the
	* FMQ. It is intended to be have a single reader and single writer.
	* Attempts to overflow/underflow returns a failure.
	*/
	kSynchronizedReadWrite = 0x01,
	/*
	* kUnsynchronizedWrite represents the flavor of FMQ where writes always
	* succeed. This flavor allows one writer and many readers. A read operation
	* can detect an overwrite and reset the read counter.
	*/
	kUnsynchronizedWrite = 0x02
	};

	template <typename T, MQFlavor flavor>
	struct MQDescriptor {
	// Takes ownership of handle
	MQDescriptor(
	const std::vector<GrantorDescriptor>& grantors,
	native_handle_t* nHandle, size_t size);

	// Takes ownership of handle
	MQDescriptor(size_t bufferSize, native_handle_t* nHandle,
	size_t messageSize, bool configureEventFlag = false);

	MQDescriptor();
	~MQDescriptor();

	explicit MQDescriptor(const MQDescriptor& other) : MQDescriptor() { *this = other; }
	MQDescriptor& operator=(const MQDescriptor& other);

	size_t getSize() const;

	size_t getQuantum() const;

	int32_t getFlags() const;

	bool isHandleValid() const { return mHandle != nullptr; }
	size_t countGrantors() const { return mGrantors.size(); }

	inline const ::android::hardware::hidl_vec<GrantorDescriptor> &grantors() const {
	return mGrantors;
	}

	inline ::android::hardware::hidl_vec<GrantorDescriptor> &grantors() {
	return mGrantors;
	}

	inline const ::native_handle_t *handle() const {
	return mHandle;
	}

	inline ::native_handle_t *handle() {
	return mHandle;
	}

	static const size_t kOffsetOfGrantors;
	static const size_t kOffsetOfHandle;
	enum GrantorType : int { READPTRPOS = 0, WRITEPTRPOS, DATAPTRPOS, EVFLAGWORDPOS };

	/*
	* There should at least be GrantorDescriptors for the read counter, write
	* counter and data buffer. A GrantorDescriptor for an EventFlag word is
	* not required if there is no need for blocking FMQ operations.
	*/
	static constexpr int32_t kMinGrantorCount = DATAPTRPOS + 1;

	/*
	* Minimum number of GrantorDescriptors required if EventFlag support is
	* needed for blocking FMQ operations.
	*/
	static constexpr int32_t kMinGrantorCountForEvFlagSupport = EVFLAGWORDPOS + 1;

	//TODO(b/34160777) Identify a better solution that supports remoting.
	static inline size_t alignToWordBoundary(size_t length) {
	constexpr size_t kAlignmentSize = 64;
	if (kAlignmentSize % __WORDSIZE != 0) {
	details::logAlwaysFatal("Incompatible word size");
	}

	/*
	* Check if alignment to word boundary would cause an overflow.
	*/
	if (length > SIZE_MAX - kAlignmentSize/8 + 1) {
	details::logAlwaysFatal("Queue size too large");
	}

	return (length + kAlignmentSize/8 - 1) & ~(kAlignmentSize/8 - 1U);
	}

	static inline size_t isAlignedToWordBoundary(size_t offset) {
	constexpr size_t kAlignmentSize = 64;
	return (offset & (kAlignmentSize/8 - 1)) == 0;
	}
	private:
	::android::hardware::hidl_vec<GrantorDescriptor> mGrantors;
	::android::hardware::details::hidl_pointer<native_handle_t> mHandle;
	uint32_t mQuantum;
	uint32_t mFlags;
	};

	template<typename T, MQFlavor flavor>
	const size_t MQDescriptor<T, flavor>::kOffsetOfGrantors = offsetof(MQDescriptor, mGrantors);

	template<typename T, MQFlavor flavor>
	const size_t MQDescriptor<T, flavor>::kOffsetOfHandle = offsetof(MQDescriptor, mHandle);

	/*
	* MQDescriptorSync will describe the wait-free synchronized
	* flavor of FMQ.
	*/
	template<typename T>
	using MQDescriptorSync = MQDescriptor<T, kSynchronizedReadWrite>;

	/*
	* MQDescriptorUnsync will describe the unsynchronized write
	* flavor of FMQ.
	*/
	template<typename T>
	using MQDescriptorUnsync = MQDescriptor<T, kUnsynchronizedWrite>;

	template<typename T, MQFlavor flavor>
	MQDescriptor<T, flavor>::MQDescriptor(
	const std::vector<GrantorDescriptor>& grantors,
	native_handle_t* nhandle,
	size_t size)
	: mHandle(nhandle),
	mQuantum(size),
	mFlags(flavor) {
	mGrantors.resize(grantors.size());
	for (size_t i = 0; i < grantors.size(); ++i) {
	if (isAlignedToWordBoundary(grantors[i].offset) == false) {
	details::logAlwaysFatal("Grantor offsets need to be aligned");
	}
	mGrantors[i] = grantors[i];
	}
	}

	template<typename T, MQFlavor flavor>
	MQDescriptor<T, flavor>::MQDescriptor(size_t bufferSize, native_handle_t *nHandle,
	size_t messageSize, bool configureEventFlag)
	: mHandle(nHandle), mQuantum(messageSize), mFlags(flavor) {
	/*
	* If configureEventFlag is true, allocate an additional spot in mGrantor
	* for containing the fd and offset for mmapping the EventFlag word.
	*/
	mGrantors.resize(configureEventFlag? kMinGrantorCountForEvFlagSupport : kMinGrantorCount);

	size_t memSize[] = {
	sizeof(RingBufferPosition), /* memory to be allocated for read pointer counter */
	sizeof(RingBufferPosition), /* memory to be allocated for write pointer counter */
	bufferSize, /* memory to be allocated for data buffer */
	sizeof(std::atomic<uint32_t>)/* memory to be allocated for EventFlag word */
	};

	/*
	* Create a default grantor descriptor for read, write pointers and
	* the data buffer. fdIndex parameter is set to 0 by default and
	* the offset for each grantor is contiguous.
	*/
	for (size_t grantorPos = 0, offset = 0;
	grantorPos < mGrantors.size();
	offset += memSize[grantorPos++]) {
	mGrantors[grantorPos] = {
	0 /* grantor flags */,
	0 /* fdIndex */,
	static_cast<uint32_t>(alignToWordBoundary(offset)),
	memSize[grantorPos]
	};
	}
	}

	template <typename T, MQFlavor flavor>
	MQDescriptor<T, flavor>& MQDescriptor<T, flavor>::operator=(const MQDescriptor& other) {
	mGrantors = other.mGrantors;
	if (mHandle != nullptr) {
	native_handle_close(mHandle);
	native_handle_delete(mHandle);
	mHandle = nullptr;
	}
	mQuantum = other.mQuantum;
	mFlags = other.mFlags;

	if (other.mHandle != nullptr) {
	mHandle = native_handle_create(
	other.mHandle->numFds, other.mHandle->numInts);

	for (int i = 0; i < other.mHandle->numFds; ++i) {
	mHandle->data[i] = dup(other.mHandle->data[i]);
	}

	memcpy(&mHandle->data[other.mHandle->numFds],
	&other.mHandle->data[other.mHandle->numFds],
	other.mHandle->numInts * sizeof(int));
	}

	return *this;
	}

	template<typename T, MQFlavor flavor>
	MQDescriptor<T, flavor>::MQDescriptor() : MQDescriptor(
	std::vector<android::hardware::GrantorDescriptor>(),
	nullptr /* nHandle */,
	0 /* size */) {}

	template<typename T, MQFlavor flavor>
	MQDescriptor<T, flavor>::~MQDescriptor() {
	if (mHandle != nullptr) {
	native_handle_close(mHandle);
	native_handle_delete(mHandle);
	}
	}

	template<typename T, MQFlavor flavor>
	size_t MQDescriptor<T, flavor>::getSize() const {
	return mGrantors[DATAPTRPOS].extent;
	}

	template<typename T, MQFlavor flavor>
	size_t MQDescriptor<T, flavor>::getQuantum() const { return mQuantum; }

	template<typename T, MQFlavor flavor>
	int32_t MQDescriptor<T, flavor>::getFlags() const { return mFlags; }

	template<typename T, MQFlavor flavor>
	std::string toString(const MQDescriptor<T, flavor> &q) {
	std::string os;
	if (flavor & kSynchronizedReadWrite) {
	os += "fmq_sync";
	}
	if (flavor & kUnsynchronizedWrite) {
	os += "fmq_unsync";
	}
	os += " {"
	+ toString(q.grantors().size()) + " grantor(s), "
	+ "size = " + toString(q.getSize())
	+ ", .handle = " + toString(q.handle())
	+ ", .quantum = " + toString(q.getQuantum()) + "}";
	return os;
	}

	} // namespace hardware
	} // namespace android

	#endif // FMSGQ_DESCRIPTOR_H