| // Copyright 2021 The Fuchsia Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| #ifndef SRC_DEVICES_BIN_DRIVER_RUNTIME_HANDLE_H_ | |
| #define SRC_DEVICES_BIN_DRIVER_RUNTIME_HANDLE_H_ | |
| #include <lib/fdf/types.h> | |
| #include <lib/fit/nullable.h> | |
| #include <stdint.h> | |
| #include <array> | |
| #include <memory> | |
| #include <utility> | |
| #include <fbl/auto_lock.h> | |
| #include <fbl/intrusive_single_list.h> | |
| #include <fbl/ref_ptr.h> | |
| #include "src/devices/bin/driver_runtime/object.h" | |
| namespace driver_runtime { | |
| class Handle; | |
| // Callable object for destroying uniquely owned handles. | |
| struct HandleDestroyer { | |
| inline void operator()(Handle* handle); | |
| }; | |
| // HandleOwner wraps a Handle in a unique_ptr that has single | |
| // ownership of the Handle and deletes it whenever it falls out of scope. | |
| using HandleOwner = std::unique_ptr<Handle, HandleDestroyer>; | |
| // A handle is how a process refers to runtime objects such as fdf_channels. | |
| class Handle : public fbl::SinglyLinkedListable<Handle*> { | |
| public: | |
| // Returns a unique reference to a newly created handle. | |
| // Takes ownership of |object|. | |
| static HandleOwner Create(fbl::RefPtr<Object> object); | |
| // Returns whether the handle exists in the handle table. | |
| static bool HandleExists(fdf_handle_t value); | |
| // Returns whether |handle_value| is of type fdf_handle_t. | |
| // Does not do any validation on whether it is a valid fdf handle. | |
| static bool IsFdfHandle(zx_handle_t handle_value); | |
| // Returns the object corresponding to |handle_value|. | |
| template <typename T> | |
| static zx_status_t GetObject(fdf_handle_t handle_value, fbl::RefPtr<T>* out_object); | |
| // Returns the handle value which refers to this object. | |
| fdf_handle_t handle_value() const { return value_; } | |
| // This needs to be public for |HandleTableArena|'s std::array usage. | |
| explicit Handle(fbl::RefPtr<Object> object = nullptr, fdf_handle_t value = FDF_HANDLE_INVALID) | |
| : object_(std::move(object)), value_(value) {} | |
| private: | |
| friend class HandleTableArena; | |
| // Clears handle state specific to this lifetime. | |
| // The handle |value| is preserved, as it is used to generate a new handle value | |
| // referring to the same handle object. | |
| void Reset() { object_ = nullptr; } | |
| HandleOwner TakeOwnership() { return HandleOwner(this); } | |
| // Returns the object this handle refers to. | |
| fbl::RefPtr<Object> object() { return object_; } | |
| bool has_object() const { return object_ != nullptr; } | |
| fbl::RefPtr<Object> object_; | |
| fdf_handle_t value_; | |
| }; | |
| // HandleTableArena provides the memory backing the Handle objects. | |
| // This class is thread-safe. | |
| class HandleTableArena { | |
| public: | |
| // TODO(https://fxbug.dev/42167621): fine-tune this numbers, they were randomly selected. | |
| static constexpr size_t kMaxNumHandles = 64ull * 1024; | |
| // The number of tables stored in |handle_table_dir_|. | |
| static constexpr size_t kNumTables = 64; | |
| // The number of handles per table. | |
| static constexpr size_t kHandlesPerTable = kMaxNumHandles / kNumTables; | |
| HandleTableArena() : handle_table_dir_{&initial_handles_} {} | |
| ~HandleTableArena() { | |
| // fbl::SinglyLinkedList does not like deleting non-empty lists containing | |
| // unmanaged pointers. We don't need to free the handle pointers, | |
| // as the tables backing them will be deleted. | |
| free_handles_.clear(); | |
| for (const auto& table : handle_table_dir_) { | |
| // Make sure we don't accidentally delete the |handles_| array that was | |
| // allocated as part of the class. | |
| if (table && table != &initial_handles_) { | |
| delete table; | |
| } | |
| } | |
| } | |
| // Alloc returns storage for a handle. | |
| // |out_handle_value| is the generated handle value referring to the returned Handle object. | |
| Handle* Alloc(fbl::RefPtr<Object> object, fdf_handle_t* out_handle_value); | |
| // Clears handle state specific to this lifetime and adds the handle to the free | |
| // list for re-use. | |
| void Delete(Handle* handle) { | |
| fbl::RefPtr<Object> object_to_destroy; | |
| { | |
| fbl::AutoLock lock(&lock_); | |
| object_to_destroy = handle->object(); | |
| handle->Reset(); | |
| free_handles_.push_front(handle); | |
| num_allocated_--; | |
| } | |
| } | |
| // Returns the object corresponding to |handle_value|. | |
| // Returns nullptr if the handle is invalid or has no object. | |
| fbl::RefPtr<Object> GetObject(fdf_handle_t handle_value); | |
| // Takes ownership of the handle, resetting its object and returning the HandleOwner and the | |
| // object. Returns nullptr HandleOwner if the handle is invalid or has no object. | |
| std::pair<HandleOwner, fbl::RefPtr<Object>> TakeOwnership(fdf_handle_t handle_value); | |
| // Returns whether the handle exists in the handle table. | |
| bool Contains(fdf_handle_t handle_value); | |
| // Returns the number of handles currently allocated (does not include freed handles). | |
| uint32_t num_allocated() { | |
| fbl::AutoLock lock(&lock_); | |
| return num_allocated_; | |
| } | |
| private: | |
| Handle* GetHandleLocked(fdf_handle_t handle_value) __TA_REQUIRES(&lock_); | |
| // Returns a pointer to memory that can be used to construct a Handle object. | |
| // |out_table| and |out_index| describes the location of that memory. | |
| Handle* AllocHandleMemoryLocked(uint32_t* out_table, uint32_t* out_index) __TA_REQUIRES(&lock_); | |
| fbl::Mutex lock_; | |
| // The first handle table allocated as part of the class. | |
| std::array<Handle, kHandlesPerTable> initial_handles_ __TA_GUARDED(&lock_); | |
| // Directory which holds all the handle tables, including |initial_handles_|. | |
| // More handle tables are allocated and added to this as needed. | |
| std::array<std::array<Handle, kHandlesPerTable>*, kNumTables> handle_table_dir_ | |
| __TA_GUARDED(&lock_); | |
| // Indexes pointing to the next available memory that can be used for handle allocation. | |
| // Index into |handle_table_dir_|. | |
| uint32_t dir_index_ __TA_GUARDED(&lock_) = 0; | |
| // Index into the handle table referred to by|dir_index_|. | |
| uint32_t handles_index_ __TA_GUARDED(&lock_) = 0; | |
| // Handles that have been freed are recycled into |free_handles_|. | |
| fbl::SinglyLinkedList<Handle*> free_handles_ __TA_GUARDED(&lock_); | |
| // Number of handles currently allocated (does not include freed handles). | |
| uint32_t num_allocated_ __TA_GUARDED(&lock_) = 0; | |
| }; | |
| extern HandleTableArena gHandleTableArena; | |
| template <typename T> | |
| inline zx_status_t Handle::GetObject(fdf_handle_t handle_value, fbl::RefPtr<T>* out_object) { | |
| fbl::RefPtr<Object> object = gHandleTableArena.GetObject(handle_value); | |
| if (!object) { | |
| return ZX_ERR_BAD_HANDLE; | |
| } | |
| *out_object = fbl::RefPtr<T>::Downcast(std::move(object)); | |
| if (!*out_object) { | |
| return ZX_ERR_WRONG_TYPE; | |
| } | |
| return ZX_OK; | |
| } | |
| // This can't be defined directly in the HandleDestroyer struct definition | |
| // because Handle is an incomplete type at that point. | |
| inline void HandleDestroyer::operator()(Handle* handle) { gHandleTableArena.Delete(handle); } | |
| } // namespace driver_runtime | |
| #endif // SRC_DEVICES_BIN_DRIVER_RUNTIME_HANDLE_H_ |