diff --git a/apis/20230220/inner_api-en/core/hdf_device_class.h b/apis/20230220/inner_api-en/core/hdf_device_class.h new file mode 100644 index 0000000000000000000000000000000000000000..d6bbc874f48654179bca29531790117d6cf915b9 --- /dev/null +++ b/apis/20230220/inner_api-en/core/hdf_device_class.h @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * + * HDF is dual licensed: you can use it either under the terms of + * the GPL, or the BSD license, at your option. + * See the LICENSE file in the root of this repository for complete details. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Provides Hardware Driver Foundation (HDF) APIs. + * + * The HDF implements driver framework capabilities such as driver loading, service management, + * and driver message model. You can develop drivers based on the HDF. + * + * @since 1.0 + */ + +/** + * @file hdf_device_class.h + * + * @brief Defines device types by service. Service modules can listen for services of the specific device type. + * + * @since 1.0 + */ + +#ifndef HDF_DEVICE_CLASS_H +#define HDF_DEVICE_CLASS_H + +/** + * @brief Enumerates the driver device types. + * + * @since 1.0 + */ +typedef enum { + DEVICE_CLASS_DEFAULT = 0x1 << 0, /** Default device type */ + DEVICE_CLASS_PLAT = 0x1 << 1, /** Platform device */ + DEVICE_CLASS_SENSOR = 0x1 << 2, /** Sensor device */ + DEVICE_CLASS_INPUT = 0x1 << 3, /** Input device */ + DEVICE_CLASS_DISPLAY = 0x1 << 4, /** Display device */ + DEVICE_CLASS_AUDIO = 0x1 << 5, /** Audio device */ + DEVICE_CLASS_CAMERA = 0x1 << 6, /** Camera device */ + DEVICE_CLASS_USB = 0x1 << 7, /** USB device */ + DEVICE_CLASS_USERAUTH = 0x1 << 8, /** User authentication device */ + DEVICE_CLASS_MAX = 0x1 << 9, /** Maximum value of the device class */ +} DeviceClass; + +#endif /* HDF_DEVICE_CLASS_H */ +/** @} */ diff --git a/apis/20230220/inner_api-en/core/hdf_service_status.h b/apis/20230220/inner_api-en/core/hdf_service_status.h new file mode 100644 index 0000000000000000000000000000000000000000..0511ad19fe1f243bdc0e1cd69810475772e61549 --- /dev/null +++ b/apis/20230220/inner_api-en/core/hdf_service_status.h @@ -0,0 +1,95 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * + * HDF is dual licensed: you can use it either under the terms of + * the GPL, or the BSD license, at your option. + * See the LICENSE file in the root of this repository for complete details. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Provides Hardware Driver Foundation (HDF) APIs. + * + * The HDF implements driver framework capabilities such as driver loading, service management, + * and driver message model. You can develop drivers based on the HDF. + * + * @since 1.0 + */ + +/** + * @file hdf_service_status.h + * + * @brief Defines data structs for the service status and service status listener callback. + * + * @since 1.0 + */ + +#ifndef HDF_SERVICE_STATUS_H +#define HDF_SERVICE_STATUS_H + +#include "hdf_types.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +struct ServiceStatusListener; + +/** + * @brief Enumerates the service status. + * + * @since 1.0 + */ +enum ServiceStatusType { + /** The service is started. */ + SERVIE_STATUS_START, + /** The service status changes. */ + SERVIE_STATUS_CHANGE, + /** The service is stopped. */ + SERVIE_STATUS_STOP, + /** Maximum value of the service status. */ + SERVIE_STATUS_MAX, +}; + +/** + * @brief Defines the service status struct. The HDF uses this struct to notify the service module of the service status. + * + * @since 1.0 + */ +struct ServiceStatus { + /** Service name */ + std::string serviceName; + /** Device type */ + uint16_t deviceClass; + /** Service status */ + uint16_t status; + /** Service information */ + std::string info; +}; + +/** + * @brief Defines the function for service status listening. + * + * @param listener Indicates the pointer to the service status listener. + * @param status Indicates the pointer to the service status obtained. + */ +typedef void (*OnServiceStatusReceived)(struct ServiceStatusListener *listener, struct ServiceStatus *status); + +/** + * @brief Defines the service status listener struct. + * + * @since 1.0 + */ +struct ServiceStatusListener { + /** Callback invoked to return the service status */ + OnServiceStatusReceived callback; + /** Pointer to the private parameter of the service module. The service module can pass this parameter to the callback to convert the HDF service status to the required type. */ + void *priv; +}; + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif /* HDF_SERVICE_STATUS_H */ diff --git a/apis/20230220/inner_api-en/hdi/base/buffer_handle.h b/apis/20230220/inner_api-en/hdi/base/buffer_handle.h new file mode 100644 index 0000000000000000000000000000000000000000..73f4d74c324412794b3f07927063a5ce5ee123e7 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/buffer_handle.h @@ -0,0 +1,70 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * +* @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file buffer_handle.h + * + * @brief Defines the common data struct for graphics processing. The BufferHandle must comply with the IDL syntax. + * You only need to define the struct in IDL for the service module. The HDI module implements serialization and deserialization of this struct. + * + * @since 1.0 + */ + +#ifndef INCLUDE_BUFFER_HANDLE_H +#define INCLUDE_BUFFER_HANDLE_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines the BufferHandle struct. + * + * @since 1.0 + */ +typedef struct { + int32_t fd; /**< Buffer file descriptor (FD). The value -1 indicates a invalid FD. */ + int32_t width; /**< Width of the image */ + int32_t stride; /**< Stride of the image */ + int32_t height; /**< Height of the image */ + int32_t size; /* < Size of the buffer */ + int32_t format; /**< Format of the image */ + uint64_t usage; /**< Usage of the buffer */ + void *virAddr; /**< Virtual address of the buffer */ + uint64_t phyAddr; /**< Physical address */ + int32_t key; /**< Shared memory key */ + uint32_t reserveFds; /**< Number of the reserved FDs */ + uint32_t reserveInts; /**< Number of the reserved integers */ + int32_t reserve[0]; /**< Data */ +} BufferHandle; + +#ifdef __cplusplus +} +#endif + +#endif // INCLUDE_BUFFER_HANDLE_H diff --git a/apis/20230220/inner_api-en/hdi/base/buffer_util.h b/apis/20230220/inner_api-en/hdi/base/buffer_util.h new file mode 100644 index 0000000000000000000000000000000000000000..ea8b65cef11b631058b0de362811967abb9aba50 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/buffer_util.h @@ -0,0 +1,117 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file buffer_util.h + * + * @brief Provides the APIs for allocating, releasing, serializing, and deserializing the BufferHandle object. + * + * @since 1.0 + */ + +#ifndef HDI_BUFFER_UTIL_H +#define HDI_BUFFER_UTIL_H + +#include "buffer_handle.h" +#include "hdf_sbuf.h" + +/** + * @brief Defines the maximum value of the reserveFds in BufferHandle. + */ +#define MAX_RESERVE_FDS 1024 + +/** + * @brief Defines the maximum value of the reserveInts in BufferHandle. + */ +#define MAX_RESERVE_INTS 1024 + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Allocates a BufferHandle object. + * + * You can use this API to create the default BufferHandle object based on the specified reserveFds and reserveInts. + * + * @param reserveFds Indicates the file descriptor (FD) count (0 to MAX_RESERVE_FDS) in reserve[0]. + * @param reserveInts Indicates the integer count (0 to MAX_RESERVE_FDS) in reserve[reserveFds]. + * @return Returns the pointer to the BufferHandle allocated if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *AllocateNativeBufferHandle(uint32_t reserveFds, uint32_t reserveInts); + +/** + * @brief Clones a BufferHandle object. + * + * You can use this API to create a BufferHandle object from a given BufferHandle object. + * + * @param other Indicates the pointer to the BufferHandle object to clone. + * @return Returns the pointer to the BufferHandle created if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *CloneNativeBufferHandle(const BufferHandle *other); + +/** + * @brief Releases a BufferHandle object. + * + * @param handle Indicates the pointer to the BufferHandle object to release. + * + * @since 1.0 + */ +void FreeNativeBufferHandle(BufferHandle *handle); + +/** + * @brief Serializes a BufferHandle object. + * + * You can use this API to write a BufferHandle object to a HdfSBuf object. HdfSbufWriteNativeBufferHandle and HdfSbufReadNativeBufferHandle are used in pairs. + * + * @param data Indicates the pointer to the HdfSBuf object. + * @param handle Indicates the pointer to the BufferHandle object to serialize. + * + * @since 1.0 + */ +bool HdfSbufWriteNativeBufferHandle(struct HdfSBuf *data, const BufferHandle *handle); + +/** + * @brief Deserializes a BufferHandle object. + * + * You can use this API to read a BufferHandle object from a HdfSBuf object according to the serialization format and create a new BufferHandle object. HdfSbufWriteNativeBufferHandle and HdfSbufReadNativeBufferHandle are used in pairs. + * + * @param data Indicates the pointer to the HdfSBuf object. + * @return Returns the pointer to the BufferHandle obtained if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *HdfSbufReadNativeBufferHandle(struct HdfSBuf *data); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif // HDI_BUFFER_UTIL_H diff --git a/apis/20230220/inner_api-en/hdi/base/hdi_smq.h b/apis/20230220/inner_api-en/hdi/base/hdi_smq.h new file mode 100644 index 0000000000000000000000000000000000000000..cbe05dfef3e9b1b46c1c4c43ec34d3472039c59c --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/hdi_smq.h @@ -0,0 +1,677 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * +* @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file hdi_smq.h + * + * @brief Provides APIs for the shared memory queue (SMQ). + * The SMQ is a common mechanism for inter-process communication. The SMQ must comply with the IDL syntax. You only need to define the SMQ struct in IDL for the service module. The HDI module provides common operations for reading and writing the SMQ. + * + * @since 1.0 + */ + +#ifndef HDI_SHARED_MEM_QUEUE_INF_H +#define HDI_SHARED_MEM_QUEUE_INF_H + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + + +#ifndef PAGE_SIZE +#define PAGE_SIZE 4096 +#endif + +#ifndef HDF_LOG_TAG +#define HDF_LOG_TAG smq +#endif + +namespace OHOS { +namespace HDI { +namespace Base { +/** + * @brief Defines the SharedMemQueue class. + * + * The SMQ is a message queue used for simplex communication between processes. It allows data write from one end and read at the other end, in either blocking or non-blocking mode. + * + * @since 1.0 + */ +template +class SharedMemQueue { +public: + /** + * @brief A constructor used to create a SharedMemQueue object. + * + * @param elementCount Indicates the queue size, that is, the maximum number of elements allowed in the queue. + * @param type Indicates whether the SMQ is synchronous (SYNCED_SMQ) or asynchronous (UNSYNC_SMQ). + * + * @since 1.0 + */ + SharedMemQueue(uint32_t elementCount, SmqType type); + + /** + * @brief A function used to copy the SharedMemQueue object. + * + * @since 1.0 + */ + explicit SharedMemQueue(const SharedMemQueueMeta &meta); + ~SharedMemQueue(); + + /** + * @brief Writes an array of elements to the SMQ in blocking mode. + * + * When the SMQ is full, this API is blocked until the queue is writeable. + * + * @param data Indicates the pointer to the array of elements to write. + * @param count Indicates the number of elements to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Write(const T *data, size_t count); + + /** + * @brief Reads an array of elements from the SMQ in blocking mode. + * + * When the SMQ is empty, this API is blocked until the queue is readable. + * + * @param data Indicates the pointer to the buffer for storing the elements read. + * @param count Indicates the number of elements to read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Read(T *data, size_t count); + + /** + * @brief Writes a single element to the SMQ in blocking mode. + * + * When the SMQ is full, this API is blocked until the queue is writeable. + * + * @param data Indicates the pointer to the single element to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Write(const T *data); + + /** + * @brief Reads a single element from the SMQ in blocking mode. + * + * When the SMQ is empty, this API is blocked until the queue is readable. + * + * @param data Indicates the pointer to the buffer for storing the single element read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Read(T *data); + + /** + * @brief Writes a fixed number of elements to the SMQ in blocking mode. + * + * When the SMQ is full, this API is blocked until the queue is writeable or the write operation times out. + * + * @param data Indicates the pointer to the array of elements to write. + * @param count Indicates the number of elements to write. + * @param waitTimeNanoSec Indicates the write operation timeout period, in nanoseconds. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Write(const T *data, size_t count, int64_t waitTimeNanoSec); + + /** + * @brief Reads a fixed number of elements from the SMQ in blocking mode. + * + * When the number of elements in the SMQ is less than the number of elements to read, this API is blocked until the queue is readable or the read operation times out. + * + * @param data Indicates the pointer to the buffer for storing the elements read. + * @param count Indicates the number of elements to read. + * @param waitTimeNanoSec Indicates the read operation timeout period, in nanoseconds. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int Read(T *data, size_t count, int64_t waitTimeNanoSec); + + /** + * @brief Writes a single element to the SMQ in non-blocking mode. + * + * When the SMQ queue is full, the SMPQ overflows. The overflowed element will be overwritten. + * + * @param data Indicates the pointer to the single element to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int WriteNonBlocking(const T *data); + + /** + * @brief Reads a single element from the SMQ in non-blocking mode. + * + * + * + * @param data Indicates the pointer to the buffer for storing the element read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int ReadNonBlocking(T *data); + + /** + * @brief Writes a fixed number of elements to the SMQ in non-blocking mode. + * + * When the SMQ is full, the SMQ overflows. The overflowed elements will be overwritten. + * + * @param data Indicates the pointer to the elements to write. + * @param count Indicates the number of elements to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int WriteNonBlocking(const T *data, size_t count); + + /** + * @brief Reads a fixed number of elements from the SMQ in non-blocking mode. + * + * If the SMQ queue does not have sufficient elements to read, a failure is returned immediately. + * + * @param data Indicates the pointer to the buffer for storing the data read. The number of elements that can be held in the buffer must be greater than the number of elements read. + * @param count Indicates the number of elements to read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. + * + * @since 1.0 + */ + int ReadNonBlocking(T *data, size_t count); + + /** + * @brief Obtains the number of elements that can be written to the SMQ. + * + * @return Returns the number of elements that can be written to the SMQ. + * + * @since 1.0 + */ + size_t GetAvalidWriteSize(); + + /** + * @brief Obtains the number of elements that can be read from the SMQ. + * + * @return Returns the number of elements that can be read from the SMQ. + * + * @since 1.0 + */ + size_t GetAvalidReadSize(); + + /** + * @brief Obtains the size of the SMQ, in bytes. + * + * @return Returns the number of bytes occupied by the SMQ. + * + * @since 1.0 + */ + size_t GetSize(); + + /** + * @brief Obtains the metadata object. + * + * @return Returns the metadata object obtained. + * + * @since 1.0 + */ + std::shared_ptr> GetMeta(); + + /** + * @brief Checks whether the SMQ object is valid. + * + * @return Returns true if the object is valid; returns false otherwise. + * + * @since 1.0 + */ + bool IsGood(); + + /** + * @brief Obtains the current timestamp, in nanoseconds. + * + * + * + * @return Returns the timestamp obtained. + * + * @since 1.0 + */ + static inline int64_t GetNanoTime() + { + struct timespec ts; + clock_gettime(CLOCK_MONOTONIC, &ts); + return (ts.tv_sec * SEC_TO_NANOSEC + ts.tv_nsec); + } + +private: + void Init(bool resetWriteOffset); + uintptr_t MapMemZone(uint32_t zoneType); + void UnMapMemZone(void *addr, uint32_t zoneType); + size_t Align(size_t num, size_t alignSize); + + int32_t status = HDF_FAILURE; + uint8_t *queueBuffer_ = nullptr; + std::atomic *readOffset_ = nullptr; + std::atomic *writeOffset_ = nullptr; + std::atomic *syncerPtr_ = nullptr; + std::unique_ptr syncer_ = nullptr; + std::shared_ptr> meta_ = nullptr; +}; + +template +SharedMemQueue::SharedMemQueue(uint32_t elementCount, SmqType type) +{ + if (elementCount > UINT16_MAX) { + return; + } + + meta_ = std::make_shared>(elementCount, type); + HDF_LOGI("create SharedMemQueue, count=%{public}u, size=%{public}zu", elementCount, meta_->GetSize()); + int ashmemFd = AshmemCreate("hdi_smq", Align(meta_->GetSize(), PAGE_SIZE)); + if (ashmemFd < 0) { + HDF_LOGE("failed to create ashmem"); + return; + } + meta_->SetFd(ashmemFd); + Init(true); +} + +template +SharedMemQueue::SharedMemQueue(const SharedMemQueueMeta &meta) +{ + meta_ = std::make_shared>(meta); + Init(false); +} + +template +SharedMemQueue::~SharedMemQueue() +{ + if (meta_ != nullptr && meta_->GetType() == SYNCED_SMQ && readOffset_ != nullptr) { + UnMapMemZone(readOffset_, SharedMemQueueMeta::MemZoneType::MEMZONE_RPTR); + } else { + delete readOffset_; + readOffset_ = nullptr; + } + + if (writeOffset_ != nullptr) { + UnMapMemZone(writeOffset_, SharedMemQueueMeta::MEMZONE_WPTR); + } + + if (syncerPtr_ != nullptr) { + UnMapMemZone(syncerPtr_, SharedMemQueueMeta::MEMZONE_SYNCER); + } + + if (queueBuffer_ != nullptr) { + UnMapMemZone(queueBuffer_, SharedMemQueueMeta::MEMZONE_DATA); + } +} + +template +void SharedMemQueue::Init(bool resetWriteOffset) +{ + if (meta_ == nullptr) { + HDF_LOGE("invalid smq meta for init"); + return; + } + + if (meta_->GetType() == SYNCED_SMQ) { + readOffset_ = reinterpret_cast *>(MapMemZone(SharedMemQueueMeta::MEMZONE_RPTR)); + } else { + readOffset_ = new std::atomic; + } + + if (readOffset_ == nullptr) { + HDF_LOGE("failed to map read offset"); + return; + } + + writeOffset_ = reinterpret_cast *>(MapMemZone(SharedMemQueueMeta::MEMZONE_WPTR)); + if (writeOffset_ == nullptr) { + HDF_LOGE("failed to map write offset"); + return; + } + + syncerPtr_ = reinterpret_cast *>(MapMemZone(SharedMemQueueMeta::MEMZONE_SYNCER)); + if (syncerPtr_ == nullptr) { + HDF_LOGE("failed to map sync ptr"); + return; + } + + queueBuffer_ = reinterpret_cast(MapMemZone(SharedMemQueueMeta::MEMZONE_DATA)); + if (queueBuffer_ == nullptr) { + HDF_LOGE("failed to map queue buffer"); + return; + } + + syncer_ = std::make_unique(syncerPtr_); + + if (resetWriteOffset) { + writeOffset_->store(0, std::memory_order_release); + } + readOffset_->store(0, std::memory_order_release); + HDF_LOGI("smq init succ"); + status = HDF_SUCCESS; +} + +template +uintptr_t SharedMemQueue::MapMemZone(uint32_t zoneType) +{ + auto memzone = meta_->GetMemZone(zoneType); + if (memzone == nullptr) { + HDF_LOGE("invalid smq mem zone type %{public}u", zoneType); + return reinterpret_cast(nullptr); + } + + int offset = (static_cast(memzone->offset) / PAGE_SIZE) * PAGE_SIZE; + int length = static_cast(memzone->offset) - offset + static_cast(memzone->size); + + void *ptr = mmap(0, length, PROT_READ | PROT_WRITE, MAP_SHARED, meta_->GetFd(), offset); + if (ptr == MAP_FAILED) { + HDF_LOGE( + "failed to map memzone %{public}u, size %{public}u, offset %{public}u , fd %{public}d, errnor=%{public}d", + zoneType, length, offset, meta_->GetFd(), errno); + return reinterpret_cast(nullptr); + } + return (reinterpret_cast(ptr) + (static_cast(memzone->offset) - offset)); +} + +template +void SharedMemQueue::UnMapMemZone(void *addr, uint32_t zoneType) +{ + auto memzone = meta_->GetMemZone(zoneType); + if (memzone == nullptr) { + return; + } + int offset = (static_cast(memzone->offset) / PAGE_SIZE) * PAGE_SIZE; + int length = static_cast(memzone->offset) - offset + static_cast(memzone->size); + uint8_t *ptr = reinterpret_cast(addr) - (static_cast(memzone->offset) - offset); + if (ptr == nullptr) { + return; + } + munmap(ptr, length); +} + +template +bool SharedMemQueue::IsGood() +{ + return status == HDF_SUCCESS; +} + +template +size_t SharedMemQueue::Align(size_t num, size_t alignSize) +{ + return (num + alignSize - 1) & ~(alignSize - 1); +} + +template +int SharedMemQueue::Write(const T *data, size_t count) +{ + return Write(data, count, 0); +} + +template +int SharedMemQueue::Read(T *data, size_t count) +{ + return Read(data, count, 0); +} + +template +int SharedMemQueue::Write(const T *data) +{ + return Write(data, 1, 0); +} + +template +int SharedMemQueue::Read(T *data) +{ + return Read(data, 1, 0); +} + +template +int SharedMemQueue::Write(const T *data, size_t count, int64_t waitTimeNanoSec) +{ + if (meta_->GetType() != SmqType::SYNCED_SMQ) { + HDF_LOGE("unsynecd smq not support blocking write"); + return HDF_ERR_NOT_SUPPORT; + } + + if (WriteNonBlocking(data, count) == 0) { + return syncer_->Wake(SharedMemQueueSyncer::SYNC_WORD_READ); + } + + int ret = 0; + auto startTime = GetNanoTime(); + int64_t currentTime = startTime; + while (true) { + if (waitTimeNanoSec != 0) { + currentTime = GetNanoTime(); + waitTimeNanoSec -= (currentTime - startTime); + startTime = currentTime; + if (waitTimeNanoSec <= 0) { + ret = WriteNonBlocking(data, count); + break; + } + } + ret = syncer_->Wait(SharedMemQueueSyncer::SYNC_WORD_WRITE, waitTimeNanoSec); + if (ret != 0 && ret != -ETIMEDOUT) { + break; + } + + ret = WriteNonBlocking(data, count); + if (ret == 0) { + break; + } + HDF_LOGE("failed to write %{public}zu, retry", count); + } + + if (ret == 0) { + ret = syncer_->Wake(SharedMemQueueSyncer::SYNC_WORD_READ); + } else { + HDF_LOGE("failed to write %{public}zu, ret=%{public}d", count, ret); + } + + return ret; +} + +template +int SharedMemQueue::Read(T *data, size_t count, int64_t waitTimeNanoSec) +{ + if (meta_->GetType() != SmqType::SYNCED_SMQ) { + HDF_LOGE("unsynecd smq not support blocking read"); + return HDF_ERR_NOT_SUPPORT; + } + + if (ReadNonBlocking(data, count) == 0) { + return syncer_->Wake(SharedMemQueueSyncer::SYNC_WORD_WRITE); + } + + int ret = -ENODATA; + auto startTime = GetNanoTime(); + int64_t currentTime; + while (true) { + if (waitTimeNanoSec != 0) { + currentTime = GetNanoTime(); + waitTimeNanoSec -= (currentTime - startTime); + startTime = currentTime; + if (waitTimeNanoSec <= 0) { + ret = ReadNonBlocking(data, count); + break; + } + } + ret = syncer_->Wait(SharedMemQueueSyncer::SYNC_WORD_READ, waitTimeNanoSec); + if (ret != 0 && ret != -ETIMEDOUT) { + break; + } + + ret = ReadNonBlocking(data, count); + if (ret == 0) { + break; + } + } + if (ret == 0) { + ret = syncer_->Wake(SharedMemQueueSyncer::SYNC_WORD_WRITE); + } else { + HDF_LOGE("failed to read %{public}zu, ret=%{public}d", count, ret); + } + + return ret; +} + +template +int SharedMemQueue::WriteNonBlocking(const T *data) +{ + return WriteNonBlocking(data, 1); +} + +template +int SharedMemQueue::ReadNonBlocking(T *data) +{ + return ReadNonBlocking(data, 1); +} + +template +int SharedMemQueue::WriteNonBlocking(const T *data, size_t count) +{ + auto avalidWrite = GetAvalidWriteSize(); + if (count >= avalidWrite && meta_->GetType() == SmqType::SYNCED_SMQ) { + // synced smq can not overflow write + return -E2BIG; + } + + auto wOffset = writeOffset_->load(std::memory_order_acquire); + auto rOffset = readOffset_->load(std::memory_order_acquire); + uint64_t newWriteOffset; + auto qCount = meta_->GetElementCount(); + if (wOffset + count <= qCount) { + if (memcpy_s(queueBuffer_ + (wOffset * sizeof(T)), (qCount - wOffset) * sizeof(T), + data, count * sizeof(T)) != EOK) { + return HDF_FAILURE; + }; + newWriteOffset = (wOffset + count) % qCount; + } else { + size_t firstPartSize = qCount - wOffset; + size_t secParcSize = count - firstPartSize; + if (memcpy_s(queueBuffer_ + (wOffset * sizeof(T)), (qCount - wOffset) * sizeof(T), + data, firstPartSize * sizeof(T)) != EOK) { + return HDF_FAILURE; + } + if (memcpy_s(queueBuffer_, qCount * sizeof(T), data + firstPartSize, secParcSize * sizeof(T)) != EOK) { + return HDF_FAILURE; + } + newWriteOffset = secParcSize; + } + + writeOffset_->store(newWriteOffset, std::memory_order_release); + if (wOffset < rOffset && newWriteOffset >= rOffset) { + HDF_LOGW("warning:smp ring buffer overflow"); + } + return 0; +} + +template +int SharedMemQueue::ReadNonBlocking(T *data, size_t count) +{ + if (count == 0) { + return -EINVAL; + } + + if (count > GetAvalidReadSize()) { + return -ENODATA; + } + + auto qCount = meta_->GetElementCount(); + auto rOffset = readOffset_->load(std::memory_order_acquire); + if (rOffset + count <= qCount) { + if (memcpy_s(data, count * sizeof(T), queueBuffer_ + (rOffset * sizeof(T)), count * sizeof(T)) != EOK) { + return HDF_FAILURE; + } + readOffset_->store((rOffset + count) % qCount, std::memory_order_release); + return 0; + } + + size_t firstPartSize = qCount - rOffset; + size_t secPartSize = count - firstPartSize; + + if (memcpy_s(data, count * sizeof(T), queueBuffer_ + (rOffset * sizeof(T)), firstPartSize * sizeof(T)) != EOK) { + return HDF_FAILURE; + } + if (memcpy_s(data + firstPartSize, (count - firstPartSize) * sizeof(T), + queueBuffer_, secPartSize * sizeof(T)) != EOK) { + return HDF_FAILURE; + }; + readOffset_->store(secPartSize, std::memory_order_release); + + return 0; +} + +template +size_t SharedMemQueue::GetAvalidWriteSize() +{ + return meta_->GetElementCount() - GetAvalidReadSize(); +} + +template +size_t SharedMemQueue::GetAvalidReadSize() +{ + auto wOffset = writeOffset_->load(std::memory_order_acquire); + auto rOffset = readOffset_->load(std::memory_order_acquire); + auto size = wOffset >= rOffset ? (wOffset - rOffset) : (wOffset + meta_->GetElementCount() - rOffset); + return size; +} + +template +size_t SharedMemQueue::GetSize() +{ + return meta_->GetSize(); +} + +template +std::shared_ptr> SharedMemQueue::GetMeta() +{ + return meta_; +} +} // namespace Base +} // namespace HDI +} // namespace OHOS + +#ifdef HDF_LOG_TAG +#undef HDF_LOG_TAG +#endif + +#endif /* HDI_SHARED_MEM_QUEUEHDI_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/base/hdi_smq_meta.h b/apis/20230220/inner_api-en/hdi/base/hdi_smq_meta.h new file mode 100644 index 0000000000000000000000000000000000000000..a57e0dad6a0f7ef864e10e5f1ec69dfe1745c410 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/hdi_smq_meta.h @@ -0,0 +1,493 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file hdi_smq_meta.h + * + * @brief Defines the metadata struct of the shared memory queue (SMQ) and provides APIs for obtaining the data struct members and serializing and deserializing the metadata struct. + * + * @since 1.0 + */ + +#ifndef HDI_SHARED_MEM_QUEUE_META_H +#define HDI_SHARED_MEM_QUEUE_META_H + +#include +#include +#include +#include +#include +#include "securec.h" + +#ifndef HDF_LOG_TAG +#define HDF_LOG_TAG smq +#endif + +namespace OHOS { +namespace HDI { +namespace Base { + +/** + * @brief Enumerates the SMQ types. + * + * @since 1.0 + */ +enum SmqType : uint32_t { + /** SMQ for synchronous communication */ + SYNCED_SMQ = 0x01, + /** SMQ for asynchronous communication */ + UNSYNC_SMQ = 0x02, +}; + +/** + * @brief Defines the MemZone struct. + * + * @since 1.0 + */ +struct MemZone { + /** Memory zone size */ + uint32_t size; + /** Memory zone offset */ + uint32_t offset; +}; + +/** + * @brief Defines the metadata template type of the SMQ. + * + * @since 1.0 + */ +template +class SharedMemQueueMeta { +public: + /** + * @brief Default constructor used to create a SharedMemQueueMeta object. + * + * @since 1.0 + */ + SharedMemQueueMeta() : SharedMemQueueMeta(-1, 0, 0) {} + /** + * @brief A constructor used to create a SharedMemQueueMeta object. + * + * @param elementCount Indicates the queue size. + * @param type Indicates the SMQ type. + * + * @since 1.0 + */ + SharedMemQueueMeta(size_t elementCount, SmqType type) : SharedMemQueueMeta(-1, elementCount, type) {} + + /** + * @brief A constructor used to create a SharedMemQueueMeta object. + * + * @param fd Indicates the file descriptor (FD) of the shared memory file. + * @param elementCount Indicates the queue size. + * @param type Indicates the SMQ type. + * + * @since 1.0 + */ + SharedMemQueueMeta(int fd, size_t elementCount, SmqType type); + /** + * @brief A constructor used to copy a SharedMemQueueMeta object. + * + * @param other Indicates the SharedMemQueueMeta object to copy. + * + * @since 1.0 + */ + SharedMemQueueMeta(const SharedMemQueueMeta &other); + ~SharedMemQueueMeta() = default; + + /** + * @brief A constructor used to assign values to the SharedMemQueueMeta object. + * + * @param other Indicates the SharedMemQueueMeta object to copy. + * + * @since 1.0 + */ + SharedMemQueueMeta &operator=(const SharedMemQueueMeta &other); + + /** + * @brief Sets an FD. + * + * @param fd Indicates the FD to set. + * + * @since 1.0 + */ + void SetFd(int fd); + + /** + * @brief Obtains the FD. + * + * @return Returns the FD obtained. + * + * @since 1.0 + */ + int GetFd(); + + /** + * @brief Obtains the shared memory size. + * + * @return Returns the shared memory size obtained. + * + * @since 1.0 + */ + size_t GetSize(); + + /** + * @brief Obtains the SMQ type. + * + * @return Returns the SMQ type obtained. + * + * @since 1.0 + */ + uint32_t GetType(); + + /** + * @brief Obtains the number of elements in the SMQ. + * + * @return Returns the number of elements in the SMQ obtained. + * + * @since 1.0 + */ + size_t GetElementCount(); + + /** + * @brief Obtains the size of a single element in the SMQ. + * + * @return Returns the size of a single element obtained. + * + * @since 1.0 + */ + size_t GetElemenetSize() const; + + /** + * @brief Enumerates the shared memory zone types. + * + * @since 1.0 + */ + enum MemZoneType : uint32_t { + /** Read pointer */ + MEMZONE_RPTR, + /** Write pointer */ + MEMZONE_WPTR, + /** Syncword */ + MEMZONE_SYNCER, + /** Data */ + MEMZONE_DATA, + /** Number of shared memory zones */ + MEMZONE_COUNT, + }; + + /** + * @brief Obtains the memory zone of the specified type. + * + * @param type Indicates the type of the shared memory zone. + * @return Returns the shared memory zone obtained. + * + * @since 1.0 + */ + MemZone *GetMemZone(uint32_t type); + + /** + * @brief Writes the SMQ to a MessageParcel object. + * + * @param parcel Indicates the MessageParcel object. + * @return Returns true if the operation is successful; returns false otherwise. + * + * @since 1.0 + */ + bool Marshalling(MessageParcel &parcel); + + /** + * @brief Reads the SMQ from a MessageParcel object. + * + * @param parcel Indicates the MessageParcel object from which the SMQ is to read. + * + * @return Returns a SharedMemQueueMeta object, which can be used to create an SQM object. + * + * @since 1.0 + */ + static std::shared_ptr> UnMarshalling(MessageParcel &parcel); + + /** + * @brief Aligns the buffer by 8 bytes. + * + * @param num Indicates the number of bytes for aligning the buffer. + * @return Returns the number of bytes after alignment. + * + * @since 1.0 + */ + size_t AlignToWord(size_t num) + { + constexpr uint32_t alignByteSize = 8; + return (num + alignByteSize - 1) & (~(alignByteSize - 1)); + } + +private: + /** FD of the shared memory file */ + int ashmemFd_; + + /** Size of the shared memory */ + size_t size_; + + /** Number of elements in the SMQ */ + size_t elementCount_; + + /** Size of an element in the SMQ */ + size_t elementSize_; + + /** SMQ type */ + SmqType type_; + + /** Number of shared memory zones */ + MemZone memzone_[MEMZONE_COUNT]; +}; + +/** + * @brief A constructor used to assign values to the SharedMemQueueMeta object. + * + * @param other Indicates the SharedMemQueueMeta object to copy. + * @since 1.0 + * + */ +template +SharedMemQueueMeta &SharedMemQueueMeta::operator=(const SharedMemQueueMeta &other) +{ + if (this != &other) { + if (ashmemFd_ >= 0) { + close(ashmemFd_); + } + ashmemFd_ = dup(other.ashmemFd_); + size_ = other.size_; + elementCount_ = other.elementCount_; + elementSize_ = other.elementSize_; + type_ = other.type_; + if (memcpy_s(memzone_, sizeof(memzone_), other.memzone_, sizeof(other.memzone_)) != EOK) { + HDF_LOGW("failed to memcpy_s overload memzone_"); + } + } + + return *this; +} + +template +SharedMemQueueMeta::SharedMemQueueMeta(int fd, size_t elementCount, SmqType type) + : ashmemFd_(fd), size_(0), elementCount_(elementCount), elementSize_(sizeof(T)), type_(type) +{ + // max size UIN32_MAX byte + if (elementCount_ > UINT32_MAX / elementSize_) { + return; + } + + size_t dataSize = elementCount_ * elementSize_; + size_t memZoneSize[] = { + sizeof(uint64_t), // read ptr + sizeof(uint64_t), // write ptr + sizeof(uint32_t), // sync word + dataSize, + }; + + size_t offset = 0; + for (size_t i = 0; i < MEMZONE_COUNT; offset += memZoneSize[i++]) { + memzone_[i].offset = AlignToWord(offset); + memzone_[i].size = memZoneSize[i]; + } + + size_ = memzone_[MEMZONE_DATA].offset + memzone_[MEMZONE_DATA].size; +} + +template +SharedMemQueueMeta::SharedMemQueueMeta(const SharedMemQueueMeta &other) +{ + if (ashmemFd_ >= 0) { + close(ashmemFd_); + } + + ashmemFd_ = dup(other.ashmemFd_); + if (ashmemFd_ < 0) { + HDF_LOGW("failed to dup ashmem fd for smq"); + } + elementCount_ = other.elementCount_; + elementSize_ = other.elementSize_; + size_ = other.size_; + type_ = other.type_; + if (memcpy_s(memzone_, sizeof(memzone_), other.memzone_, sizeof(other.memzone_)) != EOK) { + HDF_LOGW("failed to memcpy_s memzone_"); + } +} + +/** + * @brief Sets an FD. + * + * @param fd Indicates the FD to set. + * + * @since 1.0 + */ +template +void SharedMemQueueMeta::SetFd(int fd) +{ + if (ashmemFd_ >= 0) { + close(ashmemFd_); + } + ashmemFd_ = fd; +} + +/** + * @brief Obtains the FD. + * + * @return Returns the FD obtained. + * + * @since 1.0 + */ +template +int SharedMemQueueMeta::GetFd() +{ + return ashmemFd_; +} + +/** + * @brief Obtains the shared memory size. + * + * @return Returns the shared memory size obtained. + * + * @since 1.0 + */ +template +size_t SharedMemQueueMeta::GetSize() +{ + return size_; +} + +/** + * @brief Obtains the SMQ type. + * + * @return Returns the SMQ type obtained. + * + * @since 1.0 + */ +template +uint32_t SharedMemQueueMeta::GetType() +{ + return type_; +} + +/** + * @brief Obtains the number of elements in the SMQ. + * + * @return Returns the number of elements in the SMQ obtained. + * + * @since 1.0 + */ +template +size_t SharedMemQueueMeta::GetElementCount() +{ + return elementCount_; +} + +/** + * @brief Obtains the size of a single element in the SMQ. + * + * @return Returns the size of a single element obtained. + * + * @since 1.0 + */ +template +size_t SharedMemQueueMeta::GetElemenetSize() const +{ + return elementSize_; +} + +/** + * @brief Obtains the memory zone of the specified type. + * + * @param type Indicates the type of the shared memory zone. + * @return Returns the shared memory zone obtained. + * + * @since 1.0 + */ +template +MemZone *SharedMemQueueMeta::GetMemZone(uint32_t type) +{ + if (type >= MEMZONE_COUNT) { + return nullptr; + } + + return &memzone_[type]; +} + +/** + * @brief Marshals the SMQ into a MessageParcel object. + * + * @param parcel Indicates the MessageParcel object after marshalling. + * @return Returns true if the operation is successful; returns false otherwise. + * + * @since 1.0 + */ +template +bool SharedMemQueueMeta::Marshalling(MessageParcel &parcel) +{ + if (!parcel.WriteBuffer(this, sizeof(SharedMemQueueMeta))) { + return false; + } + + return parcel.WriteFileDescriptor(ashmemFd_); +} + +/** + * @brief Unmarshals the SMQ from a MessageParcel object. + * + * @param parcel Indicates the MessageParcel object to unmarshal. + * @return Returns a SharedMemQueueMeta object, which can be used to create an SQM object. + * + * @since 1.0 + */ +template +std::shared_ptr> SharedMemQueueMeta::UnMarshalling(MessageParcel &parcel) +{ + auto readMeta = reinterpret_cast *>(parcel.ReadBuffer(sizeof(SharedMemQueueMeta))); + if (readMeta == nullptr) { + HDF_LOGE("read invalid smq meta"); + return nullptr; + } + + auto fd = parcel.ReadFileDescriptor(); + if (fd < 0) { + HDF_LOGE("read invalid smq fd"); + return nullptr; + } + + auto meta = std::make_shared>(*readMeta); + meta->SetFd(fd); + + return meta; +} +} // namespace Base +} // namespace HDI +} // namespace OHOS + +#ifdef HDF_LOG_TAG +#undef HDF_LOG_TAG +#endif + +#endif /* HDI_SHARED_MEM_QUEUE_META_H */ diff --git a/apis/20230220/inner_api-en/hdi/base/hdi_smq_syncer.h b/apis/20230220/inner_api-en/hdi/base/hdi_smq_syncer.h new file mode 100644 index 0000000000000000000000000000000000000000..c34fa078fcd92cea98a33afc71de4c91a8b683a6 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/hdi_smq_syncer.h @@ -0,0 +1,111 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file native_buffer.h + * + * @brief Provides communication mechanisms, including the wait() and wake() APIs, for the shared memory queue (SMQ). + * + * @since 1.0 + */ + +#ifndef HDI_SHARED_MEM_QUEUE_SYNCER_H +#define HDI_SHARED_MEM_QUEUE_SYNCER_H + +#include +#include +#include + +namespace OHOS { +namespace HDI { +namespace Base { +/** + * @brief Defines the SharedMemQueueSyncer class. + * + * @since 1.0 + */ +class SharedMemQueueSyncer { +public: + explicit SharedMemQueueSyncer(std::atomic *syncerPtr); + ~SharedMemQueueSyncer() = default; + /** + * @brief Enumerates the synchronization types. + * + * @since 1.0 + */ + enum SyncWord : uint32_t { + /** Synchronous write */ + SYNC_WORD_WRITE = 0x01, + /** Synchronous read */ + SYNC_WORD_READ = 0x02, + }; + /** + * @brief Waits until a certain condition becomes true. This API will invoke the private member function FutexWait. + * + * @param bitset Indicates the synchronization type. + * @param timeoutNanoSec Indicates the time to wait, in nanoseconds. + * @return Returns 0 if the caller is woken up. + * + * @since 1.0 + */ + int Wait(uint32_t bitset, int64_t timeoutNanoSec); + /** + * @brief Wakes up a waiter. + * + * @param bitset Indicates the synchronization type. + * @return Returns 0 if the waiter is woken up. + * + * @since 1.0 + */ + int Wake(uint32_t bitset); + +private: + /** + * @brief Waits until a certain condition becomes true. + * + * @param bitset Indicates the synchronization type. + * @param timeoutNanoSec Indicates the time to wait, in nanoseconds. + * @return Returns 0 if the caller is woken up. + * + * @since 1.0 + */ + int FutexWait(uint32_t bitset, int64_t timeoutNanoSec); + /** + * @brief Converts the wait time to real time. + * + * @param timeout Indicates the wait time. + * @param realtime Indicates the real time. + * + * @since 1.0 + */ + void TimeoutToRealtime(int64_t timeout, struct timespec &realtime); + std::atomic *syncAddr_; +}; +} // namespace Base +} // namespace HDI +} // namespace OHOS + +#endif /* HDI_SHARED_MEM_QUEUE_SYNCER_H */ diff --git a/apis/20230220/inner_api-en/hdi/base/native_buffer.h b/apis/20230220/inner_api-en/hdi/base/native_buffer.h new file mode 100644 index 0000000000000000000000000000000000000000..c22d4870b91eeb7b655b19527710db65dda6e515 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/base/native_buffer.h @@ -0,0 +1,159 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file native_buffer.h + * + * @brief Provides C++ interfaces for NativeBuffer. + * + * NativeBuffer is the wrapper of BufferHandle. It manages the BufferHandle objects and applies to the HDI layer. + * + * @since 1.0 + */ + +#ifndef HDI_NATIVE_BUFFER_H +#define HDI_NATIVE_BUFFER_H + +#include +#include "buffer_handle.h" + +namespace OHOS { +namespace HDI { +namespace Base { +using OHOS::MessageParcel; +using OHOS::Parcelable; + +/** + * @brief Defines the NativeBuffer class. + * + */ +class NativeBuffer : public Parcelable { +public: + NativeBuffer(); + virtual ~NativeBuffer(); + explicit NativeBuffer(const BufferHandle *handle); + + NativeBuffer(const NativeBuffer &other); + NativeBuffer(NativeBuffer &&other) noexcept; + + NativeBuffer &operator=(const NativeBuffer &other); + NativeBuffer &operator=(NativeBuffer &&other) noexcept; + + /** + * @brief Marshals this NativeBuffer object into a MessageParcel object. + * + * Marshalling() and Unmarshalling() are used in pairs. + * + * @param parcel Indicates the MessageParcel object to which the NativeBuffer object is marshalled. + * @return Returns true if the operation is successful; returns false otherwise. + * + * @since 1.0 + */ + bool Marshalling(Parcel &parcel) const override; + + /** + * @brief Unmarshals a NativeBuffer object from a MessageParcel object. + * + * Marshalling() and Unmarshalling() are used in pairs. + * + * @param parcel Indicates the MessageParcel object from which the BufferHandle object is unmarshalled. + * @return Returns the NativeBuffer object obtained if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + static sptr Unmarshalling(Parcel &parcel); + + /** + * @brief Clones a BufferHandle object. + * + * You can use this API to clone the BufferHandle object held by a NativeBuffer object. + * + * @return Returns the pointer to the BufferHandle cloned if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *Clone(); + + /** + * @brief Moves this BufferHandle object. + * + * This API transfers the ownership of the BufferHandle object held by the NativeBuffer object. After the ownership is transferred, + * you need to use FreeNativeBufferHandle to release the BufferHandle object. + * + * @return Returns the pointer to the BufferHandle object after the move if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *Move() noexcept; + + /** + * @brief Sets a BufferHandle object. + * + * You can use this API to set the owner of a BufferHandle object. + * + * @param handle Indicates the BufferHandle object to set. + * @param isOwner Indicates whether the BufferHandle object is managed by a NativeBuffer object. The value true means the BufferHandle object is managed by theNativeBuffer object; + * the value false means the opposite. The default value is false. + * @param destructor Indicates the function used to release the BufferHandle object. By default, FreeNativeBufferHandle is used. + * + * @since 1.0 + */ + void SetBufferHandle(BufferHandle *handle, bool isOwner = false, + std::function destructor = nullptr); + + /** + * @brief Obtains this BufferHandle object. + * + * The NativeBuffer object still hold the BufferHandle object. + * + * @return Returns the pointer to the BufferHandle object obtained if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *GetBufferHandle() noexcept; + + /** + * @brief Prints dump information. + * + * @return Returns dump information about this BufferHandle object. + * + * @since 1.0 + */ + std::string Dump() const; +private: + bool ExtractFromParcel(Parcel &parcel); + static bool WriteReserveData(MessageParcel &messageParcel, const BufferHandle &handle); + static bool ReadReserveData(MessageParcel &messageParcel, BufferHandle &handle); + void DestroyBuffer(); + BufferHandle *handle_; + bool isOwner_; + std::function bufferDestructor_; +}; +} // namespace Base +} // namespace HDI +} // namespace OHOS + +#endif // HDI_NATIVE_BUFFER_H diff --git a/apis/20230220/inner_api-en/hdi/devmgr_hdi.h b/apis/20230220/inner_api-en/hdi/devmgr_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..a04c96704aceb376350c4ee24b6a2b25b15a1bad --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/devmgr_hdi.h @@ -0,0 +1,165 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file devmgr_hdi.h + * + * @brief Defines the data structs and interface types related to device management based on the C language. + * + * @since 1.0 + */ + +#ifndef HDI_DEVICE_MANAGER_INF_H +#define HDI_DEVICE_MANAGER_INF_H + +#include "hdf_base.h" +#include "hdf_dlist.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +struct HdfRemoteService; + +/** + * @brief Enumerates the types of device services. + * + * @since 1.0 + */ +enum HDF_DEVICE_TYPE { + /** Local service */ + HDF_LOCAL_SERVICE, + /** Remote service */ + HDF_REMOTE_SERVICE, +}; + +/** + * @brief Defines the device information struct. + * + * @since 1.0 + */ +struct DeviceInfoNode { + /** Device service name */ + char *svcName; + /** Device type */ + enum HDF_DEVICE_TYPE deviceType; + /** Device information node, which is used to add device information to the device linked list */ + struct DListHead node; +}; + +/** + * @brief Defines the device linked list struct. + * + * @since 1.0 + */ +struct DeviceInfoList { + /** Number of devices in the linked list */ + uint32_t deviceCnt; + /** Device information linked list */ + struct DListHead list; +}; + +/** + * @brief Defines the HDI APIs for device management. + * Developers using the C language can use these APIs to obtain device information and load or unload a device. + * @since 1.0 + */ +struct HDIDeviceManager { + /** Remote service object */ + struct HdfRemoteService *remote; + /** + * @brief Releases the device linked list obtained. + * You can use this API to release the device linked list obtained by using QueryUsableDeviceInfo or QueryUnusableDeviceInfo(). + * @param self Indicates the pointer to the device manager object. + * @param list Indicates the pointer to the the device linked list to release. + * + * @since 1.0 + */ + void (*FreeQueryDeviceList)(struct HDIDeviceManager *self, struct DeviceInfoList *list); + + /** + * @brief Queries information about available devices. + * Use FreeQueryDeviceList() to release the device linked list after the device information is used. + * @param self Indicates the pointer to the device manager object. + * @param list Indicates the pointer to the device linked list, which contains the device information. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * + * @since 1.0 + */ + int32_t (*QueryUsableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); + + /** + * @brief Queries information about unavailable devices. + * Use FreeQueryDeviceList() to release the device linked list after the device information is used. + * @param self Indicates the pointer to the device manager object. + * @param list Indicates the pointer to the device linked list, which contains the device information. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * + * @since 1.0 + */ + int32_t (*QueryUnusableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); + + /** + * @brief Loads a device driver. + * @param self Indicates the pointer to the device manager object. + * @param serviceName Indicates the pointer to the service name of the device to load. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * + * @since 1.0 + */ + int32_t (*LoadDevice)(struct HDIDeviceManager *self, const char *serviceName); + + /** + * @brief Unloads a device driver. + * @param self Indicates the pointer to the device manager object. + * @param serviceName Indicates the pointer to the service name of the device to unload. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * + * @since 1.0 + */ + int32_t (*UnloadDevice)(struct HDIDeviceManager *self, const char *serviceName); +}; + +/** + * @brief Obtains an HDI device manager object. + * @return Returns the device manager object obtained. + * + * @since 1.0 + */ +struct HDIDeviceManager *HDIDeviceManagerGet(void); + +/** + * @brief Release an HDI device management object. + * @param devmgr Indicates the pointer to the device manager object to release. + * + * @since 1.0 + */ +void HDIDeviceManagerRelease(struct HDIDeviceManager *devmgr); +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDI_DEVICE_MANAGER_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/hdi_base.h b/apis/20230220/inner_api-en/hdi/hdi_base.h new file mode 100644 index 0000000000000000000000000000000000000000..e6787fdfd30a1fd9c200cc40090f9e9b76cdb3a2 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/hdi_base.h @@ -0,0 +1,68 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file hdi_base.h + * + * @brief Defines the HDI base class for managing HDI objects. + * + * @since 1.0 + */ + +#ifndef HDI_BASE_INTERFACE_H +#define HDI_BASE_INTERFACE_H + +#include +#include + +namespace OHOS { +namespace HDI { +/** + * @brief Defines the HDI base class for managing HDI objects. + * @since 1.0 + */ +class HdiBase : virtual public OHOS::RefBase { +public: + HdiBase() = default; + virtual ~HdiBase() = default; +}; + +/** + * @brief Defines an HDI interface descriptor macro. + * @param DESCRIPTOR Indicates the interface descriptor. + * @since 1.0 + */ + +#define DECLARE_HDI_DESCRIPTOR(DESCRIPTOR) \ + const static inline std::u16string metaDescriptor_ = {DESCRIPTOR}; \ + const static inline std::u16string &GetDescriptor() \ + { \ + return metaDescriptor_; \ + } +} // namespace HDI +} // namespace OHOS + +#endif // HDI_BASE_INTERFACE_H diff --git a/apis/20230220/inner_api-en/hdi/hdi_support.h b/apis/20230220/inner_api-en/hdi/hdi_support.h new file mode 100644 index 0000000000000000000000000000000000000000..e6dcd0874e4cfb0239294e47b2e6e33d59891a6d --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/hdi_support.h @@ -0,0 +1,66 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file hdi_support.h + * + * @brief Defines APIs for loading and unloading an HDI driver. + * + * @since 1.0 + */ + +#ifndef HDF_HDI_SUPPORT_H +#define HDF_HDI_SUPPORT_H + +#include "hdf_base.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ +/** + * @brief Loads the HDI driver of a service module. + * This API obtains the driver name based on the interface descriptor and service name, and then loads the device driver to the system. + * @param desc Indicates the pointer to the HDI descriptor. + * @param serviceName Indicates the service name of the driver to load. + * @return Returns the HDI driver object. + */ + +void *LoadHdiImpl(const char *desc, const char *serviceName); + +/** + * @brief Unloads the HDI driver of a service module. + * This API obtains the driver name based on the interface descriptor and service name, and then calls unload() of the driver to unload the driver. + * @param desc Indicates the pointer to the HDI descriptor. + * @param serviceName Indicates the service name of the driver to unload. + * @param impl Indicates the pointer to the HDI driver object to unload. + */ + +void UnloadHdiImpl(const char *desc, const char *serviceName, void *impl); +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDF_HDI_SUPPORT_H */ diff --git a/apis/20230220/inner_api-en/hdi/idevmgr_hdi.h b/apis/20230220/inner_api-en/hdi/idevmgr_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..911abe2be8c5dad08f8247755d0e098b735938bd --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/idevmgr_hdi.h @@ -0,0 +1,118 @@ +/* + * Copyright (c) 2021-2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file idevmgr_hdi.h + * + * @brief Defines the data structs and interface types related to device management based on the C++ language. + * + * @since 1.0 + */ +#ifndef HDI_DEVICE_MANAGER_HDI_INF_H +#define HDI_DEVICE_MANAGER_HDI_INF_H + +#include +#include + +namespace OHOS { +namespace HDI { +namespace DeviceManager { +namespace V1_0 { +/** + * @brief Defines the device information struct. + * @since 1.0 + */ + +struct DevInfo { + /** Device ID */ + uint32_t devId; + /** Service name */ + std::string servName; + /** Device name */ + std::string deviceName; +}; + +/** + * @brief Defines the device linked list struct. + * @since 1.0 + */ +struct HdiDevHostInfo { + /** Host name */ + std::string hostName; + /** Host ID */ + uint32_t hostId; + /** List of devices managed by the host */ + std::vector devInfo; +}; + +/** + * @brief Defines the HDI APIs for device management. Developers using C++ can use these APIs to obtain device information and load or unload a device. + * @since 1.0 + */ +class IDeviceManager : public HdiBase { +public: + /** HDI interface descriptor, which is used to verify the permission for accessing the HDI interface. */ + DECLARE_HDI_DESCRIPTOR(u"HDI.IDeviceManager.V1_0"); + IDeviceManager() = default; + virtual ~IDeviceManager() = default; + + /** + * @brief Obtains a device manager object. + * @return Returns the device manager object obtained. + * @since 1.0 + */ + static ::OHOS::sptr Get(); + /** + * @brief Loads a device driver. + * @param serviceName Indicates the service name of the device to load. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + + virtual int32_t LoadDevice(const std::string &serviceName) = 0; + + /** + * @brief Unloads a device driver. + * @param serviceName Indicates the service name of the device to unload. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + virtual int32_t UnloadDevice(const std::string &serviceName) = 0; + + /** + * @brief Obtains information about all loaded devices. + * @param deviceInfos Indicates information about all loaded devices. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + virtual int32_t ListAllDevice(std::vector &deviceInfos) = 0; +}; +} // namespace V1_0 +} // namespace DeviceManager +} // namespace HDI +} // namespace OHOS + +#endif /* HDI_DEVICE_MANAGER_HDI_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/iservmgr_hdi.h b/apis/20230220/inner_api-en/hdi/iservmgr_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..fe8676ba6cc7111be5fa2b7330e7933f7ffbcb2b --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/iservmgr_hdi.h @@ -0,0 +1,128 @@ +/* + * Copyright (c) 2021-2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file iservmgr_hdi.h + * + * @brief Defines the data structs and interface types related to service management based on the C++ language. + * + * @since 1.0 + */ + +#ifndef HDI_ISERVICE_MANAGER_INF_H +#define HDI_ISERVICE_MANAGER_INF_H + +#include +#include +#include +#include + +#include "iservstat_listener_hdi.h" + +namespace OHOS { +namespace HDI { +namespace ServiceManager { +namespace V1_0 { +/** + * @brief Defines the HDI service information struct. + * + * @since 1.0 + */ + +struct HdiServiceInfo { + /** HDI service name */ + std::string serviceName; + /** Device type */ + uint16_t devClass; + /** Device ID */ + uint32_t devId; +}; + +/** + * @brief Defines the HDI APIs for service management. Developers using C++ can use the APIs to obtain a service or service set and register a service status listener. + * + * @since 1.0 + */ +class IServiceManager : public HdiBase { +public: + /** HDI interface descriptor, which is used to verify the permission for accessing the HDI interface. */ + DECLARE_HDI_DESCRIPTOR(u"HDI.IServiceManager.V1_0"); + + /** + * @brief Obtains a service manager object. + * @return Returns the service manager object obtained. + * @since 1.0 + */ + static ::OHOS::sptr Get(); + + /** + * @brief Obtain an HDI service. + * @param serviceName Indicates the pointer to the HDI service name to obtain. + * @return Returns the HDI service obtained. + * @since 1.0 + */ + virtual ::OHOS::sptr GetService(const char *serviceName) = 0; + + /** + * @brief Obtains information about all loaded HDI services. + * @param serviceInfos Indicates information about all loaded services. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + virtual int32_t ListAllService(std::vector &serviceInfos) = 0; + + /** + * @brief Registers a listener for observing the service status. + * @param listener Indicates the listener object to register. + * @param deviceClass Indicates the service type of the device to be observed. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + + virtual int32_t RegisterServiceStatusListener(::OHOS::sptr listener, uint16_t deviceClass) = 0; + /** + * @brief Unregisters a service status listener. + * @param listener Indicates the listener object to unregister. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + virtual int32_t UnregisterServiceStatusListener(::OHOS::sptr listener) = 0; + + /** + * @brief Queries HDI services based on the specified interface descriptor. + * @param serviceNames Indicates the service names obtained. + * @param interfaceDesc Indicates the interface descriptor. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ + virtual int32_t ListServiceByInterfaceDesc(std::vector &serviceNames, const char *interfaceDesc) = 0; +}; +} // namespace V1_0 +} // namespace ServiceManager +} // namespace HDI +} // namespace OHOS + +#endif /* HDI_ISERVICE_MANAGER_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/iservstat_listener_hdi.h b/apis/20230220/inner_api-en/hdi/iservstat_listener_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..04f3686dac8388b64b44cd36c979713a1cb1b150 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/iservstat_listener_hdi.h @@ -0,0 +1,137 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file iservstat_listener_hdi.h + * + * @brief Defines the data structs and interface types related to service status listening based on C++. + * + * @since 1.0 + */ + +#ifndef HDI_SERVICE_STATUS_LISTENER_INF_H +#define HDI_SERVICE_STATUS_LISTENER_INF_H + +#include +#include +#include + +#include "hdf_device_class.h" + +namespace OHOS { +namespace HDI { +namespace ServiceManager { +namespace V1_0 { + +/** + * @brief Enumerates the service statuses. + * + * @since 1.0 + */ +enum ServiceStatusType { + /** The service is started. */ + SERVIE_STATUS_START, + /** The service status changes. */ + SERVIE_STATUS_CHANGE, + /** The service is stopped. */ + SERVIE_STATUS_STOP, + /** Maximum value of the service status. */ + SERVIE_STATUS_MAX, +}; + +/** + * @brief Defines the service status struct. The HDF uses this struct to notify the service module of the service status. + * + * @since 1.0 + */ +struct ServiceStatus { + /** Service name */ + std::string serviceName; + /** Device type */ + uint16_t deviceClass; + /** Service status */ + uint16_t status; + /** Service information */ + std::string info; +}; + +/** + * @brief Defines the ServStatListener class. + * + * @since 1.0 + */ +class IServStatListener : public ::OHOS::IRemoteBroker { +public: + /** HDI interface descriptor, which is used to verify the permission for accessing the HDI interface. */ + DECLARE_INTERFACE_DESCRIPTOR(u"HDI.IServiceStatusListener.V1_0"); + + /** + * @brief Callback of the listener. You need to implement this callback for the service module. + * @param status Indicates the service status obtained. + * @since 1.0 + */ + virtual void OnReceive(const ServiceStatus &status) = 0; +}; + +/** + * @brief Defines the listener stub class to implement serialization and deserialization of interface parameters. The listener implementation class must inherit this class and implement OnReceive(). + */ +class ServStatListenerStub : public ::OHOS::IRemoteStub { +public: + ServStatListenerStub() = default; + virtual ~ServStatListenerStub() {} + + /** + * @brief Distributes messages based on the invoking ID. This API calls the private function ServStatListenerStubOnReceive(). + * @param code Indicates the distribution command word called by the IPC. + * @param data Indicates the input parameter, through which the HDF returns the service status information to the service module. + * @param reply Indicates the data returned by the service module to the HDF. + * @param option Indicates the call type. + * @return Returns HDF_SUCCESS if the operation is successful. Otherwise, the operation fails. + * @since 1.0 + */ + int OnRemoteRequest(uint32_t code, ::OHOS::MessageParcel &data, ::OHOS::MessageParcel &reply, + ::OHOS::MessageOption &option) override; + +private: + /** + * @brief Marshals or unmarshals OnReceive() parameters. + * @param code Indicates the distribution command word called by the IPC. + * @param data Indicates the input parameter, through which the HDF returns the service status information to the service module. + * @param reply Indicates the data returned by the service module to the HDF. + * @param option Indicates the call type. + * @return Returns HDF_SUCCESS if the operation is successful. Otherwise, the operation fails. + * @since 1.0 + */ + int32_t ServStatListenerStubOnReceive( + ::OHOS::MessageParcel &data, ::OHOS::MessageParcel &reply, ::OHOS::MessageOption &option); +}; +} // namespace V1_0 +} // namespace ServiceManager +} // namespace HDI +} // namespace OHOS + +#endif /* HDI_SERVICE_STATUS_LISTENER_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/object_collector.h b/apis/20230220/inner_api-en/hdi/object_collector.h new file mode 100644 index 0000000000000000000000000000000000000000..eadc26f3c06e5a65fb50db6d08e8b928e5ccb471 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/object_collector.h @@ -0,0 +1,137 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access HDI driver services. + * + * @since 1.0 + */ + +/** + * @file object_collector.h + * + * @brief Defines an object collector for the hdi-gen tool to manage constructors and objects. + * When generating a class, the hdi-gen tool defines a static inline object of the ObjectDelegator type and registers the interface name and constructor with the object collector. + * When the service module driver is initialized, the registered constructor (obtained based on the interface name) is used to create and register the IPC stub object. + * + * + * @since 1.0 + */ + +#ifndef HDI_OBJECT_COLLECTOR_H +#define HDI_OBJECT_COLLECTOR_H + +#include +#include +#include +#include +#include +#include + +namespace OHOS { +namespace HDI { +/** + * @brief Defines the ObjectCollector class for the hdi-gen tool to manage constructors and objects. + * + * @since 1.0 + */ +class ObjectCollector { +public: + /** Define the constructor interface type. */ + using Constructor = std::function(const sptr &interface)>; + /** Obtain the object instance managed by the ObjectCollector. */ + static ObjectCollector &GetInstance(); + /** Register a constructor based on the interface name. */ + bool ConstructorRegister(const std::u16string &interfaceName, const Constructor &constructor); + /** Unregister a constructor based on the interface name. */ + void ConstructorUnRegister(const std::u16string &interfaceName); + /** Create an object based on the interface name and implementation. */ + sptr NewObject(const sptr &interface, const std::u16string &interfaceName); + /** Create or obtain an object based on the interface name and implementation. */ + sptr GetOrNewObject(const sptr &interface, const std::u16string &interfaceName); + /** Remove an object based on the interface implementation. */ + bool RemoveObject(const sptr &interface); + +private: + ObjectCollector() = default; + /** Create an object based on the interface name and implementation. */ + sptr NewObjectLocked(const sptr &interface, const std::u16string &interfaceName); + /** Instance of the object managed by the ObjectCollector. */ + static ObjectCollector *instance_; + /** Define the mapping between the interface name and the constructor. */ + std::map constructorMapper_; + /** Define the mapping between the interface implementation and the object. */ + std::map interfaceObjectCollector_; + /** Define a mutex to support concurrent access to the ObjectCollector. */ + std::mutex mutex_; +}; + +/** + * @brief Defines a ObjectDelegator template, which is used to register and unregister a template object constructor. + * + * @since 1.0 + */ +template +class ObjectDelegator { +public: + /** Constructor, which registers a template object constructor through the ObjectCollector. */ + ObjectDelegator(); + /** Destructor, which unregisters a template object constructor through the ObjectCollector. */ + ~ObjectDelegator(); + +private: + ObjectDelegator(const ObjectDelegator &) = delete; + ObjectDelegator(ObjectDelegator &&) = delete; + ObjectDelegator &operator=(const ObjectDelegator &) = delete; + ObjectDelegator &operator=(ObjectDelegator &&) = delete; +}; + +/** + * @brief A constructor used to register an object constructor of the ObjectDelegator template through the ObjectCollector. + * + * @param OBJECT Indicates the type of the object to create. + * @param INTERFACE Indicates the HDI interface of the service module. + * @since 1.0 + */ +template +ObjectDelegator::ObjectDelegator() +{ + ObjectCollector::GetInstance().ConstructorRegister( + INTERFACE::GetDescriptor(), [](const sptr &interface) -> sptr { + return new OBJECT(static_cast(interface.GetRefPtr())); + }); +} + +/** + * @brief A destructor used to unregister an object constructor of the ObjectDelegator template through the ObjectCollector. + * + * @param OBJECT Indicates the type of the object. + * @param INTERFACE Indicates the HDI interface of the service module. + * @since 1.0 + */ +template +ObjectDelegator::~ObjectDelegator() +{ + ObjectCollector::GetInstance().ConstructorUnRegister(INTERFACE::GetDescriptor()); +} +} // namespace HDI +} // namespace OHOS + +#endif // HDI_OBJECT_MAPPER_H diff --git a/apis/20230220/inner_api-en/hdi/servmgr_hdi.h b/apis/20230220/inner_api-en/hdi/servmgr_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..6d702887a3b35ad60dc2883ba636b9205c55b61e --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/servmgr_hdi.h @@ -0,0 +1,115 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file servmgr_hdi.h + * + * @brief Defines the data structs and interface types related to service management based on C. + * + * @since 1.0 + */ + +#ifndef HDI_SERVICE_MANAGER_INF_H +#define HDI_SERVICE_MANAGER_INF_H + +#include "hdf_remote_service.h" +#include "servstat_listener_hdi.h" +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Defines a set of HDI services for system abilities. + */ +struct HdiServiceSet { + /** HDI service names */ + const char **serviceNames; + /** Number of HDI services. */ + uint32_t count; +}; + +/** + * @brief Defines the HDI APIs for service management. Developers using C can use the APIs to obtain a service or service set and register a service status listener. + */ +struct HDIServiceManager { + /** + * @brief Obtain an HDI service. + * @param self Indicates the pointer to the service manager object. + * @param serviceName Indicates the pointer to the HDI service name to obtain. + * @return Returns the HDI service name obtained. + */ + + struct HdfRemoteService *(*GetService)(struct HDIServiceManager *self, const char *serviceName); + /** + * @brief Registers a listener for observing the service status. + * @param self Indicates the pointer to the service manager object. + * @param listener Indicates the listener object to register. + * @param deviceClass Indicates the service type of the device to be observed. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + */ + + int32_t (*RegisterServiceStatusListener)( + struct HDIServiceManager *self, struct ServiceStatusListener *listener, uint16_t deviceClass); + /** + * @brief Unregisters a service status listener. + * @param self Indicates the pointer to the service manager object. + * @param listener Indicates the pointer to the listener object to unregister. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + */ + + int32_t (*UnregisterServiceStatusListener)(struct HDIServiceManager *self, struct ServiceStatusListener *listener); + /** + * @brief Obtains the HDI service set based on the interface descriptor. + * @param interfaceName Indicates the pointer to the interface descriptor. + * @return Returns the service names obtained. + */ + + struct HdiServiceSet *(*ListServiceByInterfaceDesc)(struct HDIServiceManager *self, const char *interfaceName); +}; + +/** + * @brief Obtain the HDIServiceManager object. + * @return Returns the HDIServiceManager object obtained. + */ + +struct HDIServiceManager *HDIServiceManagerGet(void); +/** + * @brief Releases an HDIServiceManager object. + * @param servmgr Indicates the HDIServiceManager object to release. + */ + +void HDIServiceManagerRelease(struct HDIServiceManager *servmgr); +/** + * @brief Releases an HdiServiceSet object. + * @return Returns 0 if the operation is successful; returns a negative number otherwise. + */ +int32_t HdiServiceSetRelease(struct HdiServiceSet *serviceSet); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDI_SERVICE_MANAGER_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/servstat_listener_hdi.h b/apis/20230220/inner_api-en/hdi/servstat_listener_hdi.h new file mode 100644 index 0000000000000000000000000000000000000000..35f5b959d1cedb9eccbabbae243d5d55062e806b --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/servstat_listener_hdi.h @@ -0,0 +1,60 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file servstat_listener_hdi.h + * + * @brief Defines the data structs and interface types related to service status listening based on C. + * + * @since 1.0 + */ + +#ifndef HDI_SERVICE_STATUS_LISTENER_INF_H +#define HDI_SERVICE_STATUS_LISTENER_INF_H +#include "hdf_types.h" +#include "hdf_service_status.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ +/** + * @brief Creates an HDI service status listener object. You can set the function for receiving the service status and use RegisterServiceStatusListener() to register the listener object. + * @return Returns the pointer to the listener object created. + */ + +struct ServiceStatusListener *HdiServiceStatusListenerNewInstance(void); +/** + * @brief Releases an HDI service status listener object. + * @param listener Indicates the pointer to the listener object to release. + */ +void HdiServiceStatusListenerFree(struct ServiceStatusListener *listener); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + + +#endif /* HDI_SERVICE_STATUS_LISTENER_INF_H */ diff --git a/apis/20230220/inner_api-en/hdi/stub_collector.h b/apis/20230220/inner_api-en/hdi/stub_collector.h new file mode 100644 index 0000000000000000000000000000000000000000..223b5a80c8e745b4651ea9e14c6255603a4ec327 --- /dev/null +++ b/apis/20230220/inner_api-en/hdi/stub_collector.h @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). + * + * The HDF and the IDL code generated allow system abilities to access the HDI driver service. + * + * @since 1.0 + */ + +/** + * @file stub_collector.h + * + * @brief Defines a stub collector for the hdi-gen tool to manage constructors and objects. + * The service module registers the constructor with the object collector based on the interface name, and then creates a stub object based on the interface name and registered constructor. + * + * @since 1.0 + */ +#ifndef HDI_STUB_COLLECTOR_H +#define HDI_STUB_COLLECTOR_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Defines the StubConstructor struct. + * + * @since 1.0 + */ +struct StubConstructor { + /** Define the interface type of the stub object constructor. */ + struct HdfRemoteService **(*constructor)(void *); + /** Define the interface type of the stub object destructor. */ + void (*destructor)(struct HdfRemoteService **); +}; + +/** + * @brief Registers a stub constructor. + * @param ifDesc Indicates the pointer to the interface descriptor of the stub object. + * @param constructor Indicate the pointer to the constructor of the stub object. + * @since 1.0 + */ +void StubConstructorRegister(const char *ifDesc, struct StubConstructor *constructor); + +/** + * @brief Unregisters a stub constructor. + * @param ifDesc Indicates the pointer to the interface descriptor of the stub object. + * @param constructor Indicate the pointer to the constructor of the stub object. + * @since 1.0 + */ +void StubConstructorUnregister(const char *ifDesc, const struct StubConstructor *constructor); + +/** + * @brief Creates a stub object and adds it to the object manager. + * @param ifDesc Indicates the pointer to the interface descriptor of the stub object. + * @param servPtr Indicates the pointer to the constructor object. + * @return Returns the stub object created. + * @since 1.0 + */ +struct HdfRemoteService **StubCollectorGetOrNewObject(const char *ifDesc, void *servPtr); + +/** + * @brief Removes a stub object from the object manager. + * @param ifDesc Indicates the pointer to the interface descriptor of the stub object. + * @param servPtr Indicates the pointer to the constructor object. + * @since 1.0 + */ +void StubCollectorRemoveObject(const char *ifDesc, void *servPtr); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif // HDI_STUB_COLLECTOR_H diff --git a/apis/20230220/inner_api-en/ipc/hdf_dump_reg.h b/apis/20230220/inner_api-en/ipc/hdf_dump_reg.h new file mode 100644 index 0000000000000000000000000000000000000000..834159adc09f40ec0063e33b9dd05d9cdfb59e01 --- /dev/null +++ b/apis/20230220/inner_api-en/ipc/hdf_dump_reg.h @@ -0,0 +1,66 @@ +/* + * Copyright (c) 2023 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup HDF_IPC_ADAPTER + * @{ + * + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). + * + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service object, and implementing the dump mechanism. + * + * @since 1.0 + */ + +/** + * @file hdf_dump_reg.h + * + * @brief Provides the dump feature in C based on the IPC dump over C++. + * + * @since 1.0 + */ + +#ifndef HDF_DUMP_REG_H +#define HDF_DUMP_REG_H + +#include "hdf_sbuf.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Implements IPC dump. + * @param data Indicates the pointer to the input parameter, which is obtained from the command line. + * @param reply Indicates the pointer to the output parameter, which is returned by the service module to the command line for display. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * + * @since 1.0 + */ +typedef int32_t (*DevHostDumpFunc)(struct HdfSBuf *data, struct HdfSBuf *reply); + +/** + * @brief Registers the dump function. + * @param dump Indicates the dump function to register. + * + * @since 1.0 + */ +void HdfRegisterDumpFunc(DevHostDumpFunc dump); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif // HDF_DUMP_REG_H diff --git a/apis/20230220/inner_api-en/ipc/hdf_remote_service.h b/apis/20230220/inner_api-en/ipc/hdf_remote_service.h new file mode 100644 index 0000000000000000000000000000000000000000..880e07ce29b3916b8f1de1e7b7ca984b23cc5c08 --- /dev/null +++ b/apis/20230220/inner_api-en/ipc/hdf_remote_service.h @@ -0,0 +1,161 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup HDF_IPC_ADAPTER + * @{ + * + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). + * + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service, and implementing the dump mechanism. + * + * @since 1.0 + */ + +/** + * @file hdf_remote_service.h + * + * @brief Provides IPC interface capabilities in C. + * + * @since 1.0 + */ +#ifndef HDF_REMOTE_SERVICE_H +#define HDF_REMOTE_SERVICE_H + +#include "hdf_object.h" +#include "hdf_sbuf.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Defines the HdfRemoteDispatcher struct. + * @since 1.0 + */ +struct HdfRemoteDispatcher { + /** Interface for synchronous message dispatching */ + int (*Dispatch)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); + /** Interface for asynchronous message dispatching */ + int (*DispatchAsync)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); +}; + +/** + * @brief Defines the HdfDeathRecipient struct. + * @since 1.0 + */ +struct HdfDeathRecipient { + /** Interface for listening for the death notification of a service. */ + void (*OnRemoteDied)(struct HdfDeathRecipient *, struct HdfRemoteService *); +}; + +/** + * @brief Defines the HdfRemoteService struct. + * @since 1.0 + */ +struct HdfRemoteService { + /** Remote service object */ + struct HdfObject object; + /** Target object to which the remote service object points */ + struct HdfObject *target; + /** Message dispatching interface of the remote service object */ + struct HdfRemoteDispatcher *dispatcher; + /** Address of the IPC object */ + uint64_t index; +}; + +/** + * @brief Obtains a remote service. + * @param object Indicates the pointer to the service. + * @param dispatcher Indicates the pointer to the message dispatching interface of the service. + * @return Returns the remote service obtained if the operation is successful; returns a null pointer otherwise. + * @since 1.0 + */ +struct HdfRemoteService *HdfRemoteServiceObtain( + struct HdfObject *object, struct HdfRemoteDispatcher *dispatcher); + +/** + * @brief Recycles a remote service. + * @param object Indicates the pointer to the remote service to recycle. + * @since 1.0 + */ +void HdfRemoteServiceRecycle(struct HdfRemoteService *service); + +/** + * @brief Adds a function for processing the the death notification of a service. + * @param service Indicates the pointer to the service to be listened for. + * @param recipient Indicates the pointer to the callback object containing the code to be executed when the death notification is received. + * @since 1.0 + */ +void HdfRemoteServiceAddDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); + +/** + * @brief Removes the function for processing the the death notification of a service. + * @param service Indicates the pointer to the target service. + * @param recipient Indicates the pointer to the callback object to remove. + * @since 1.0 + */ +void HdfRemoteServiceRemoveDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); + +/** + * @brief Registers a service. + * @param serviceId Indicates the ID of the service to add. + * @param service Indicates the pointer to the service. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ +int HdfRemoteServiceRegister(int32_t serviceId, struct HdfRemoteService *service); + +/** + * @brief Obtains a service. + * @param serviceId Indicates the ID of the service to obtain. + * @return Returns the service object obtained if the operation is successful; returns a null pointer otherwise. + * @since 1.0 + */ +struct HdfRemoteService *HdfRemoteServiceGet(int32_t serviceId); + +/** + * @brief Sets an interface descriptor for a service. + * @param service Indicates the pointer to the target service. + * @param descriptor Indicates the interface descriptor to set. + * @return Returns true if the operation is successful; returns false otherwise. + * @since 1.0 + */ +bool HdfRemoteServiceSetInterfaceDesc(struct HdfRemoteService *service, const char *descriptor); + +/** + * @brief Sets an interface token for an HdfSBuf with the interface descriptor of a service. + * @param service Indicates the pointer to the service. + * @param data Indicates the pointer to the targetHdfSBuf object to be set with an interface token. + * @return Returns true if the operation is successful; returns false otherwise. + * @since 1.0 + */ +bool HdfRemoteServiceWriteInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); + +/** + * @brief Checks the interface tokens of a service and an HdfSBuf for consistency. + * @param service Indicates the pointer to the service. + * @param data Indicates the pointer to the HdfSBuf. + * @return Returns true if the two interface tokens are the same; returns true otherwise. + * @since 1.0 + */ +bool HdfRemoteServiceCheckInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDF_REMOTE_SERVICE_H */ diff --git a/apis/20230220/inner_api-en/ipc/hdf_sbuf_ipc.h b/apis/20230220/inner_api-en/ipc/hdf_sbuf_ipc.h new file mode 100644 index 0000000000000000000000000000000000000000..18287d415f273be879d2c96de0a7d9fc84a107a0 --- /dev/null +++ b/apis/20230220/inner_api-en/ipc/hdf_sbuf_ipc.h @@ -0,0 +1,66 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup HDF_IPC_ADAPTER + * @{ + * + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). + * + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service, and implementing the dump mechanism. + * + * @since 1.0 + */ + +/** + * @file hdf_sbuf_ipc.h + * + * @brief Provides APIs for converting between the MessageParcel objects (in C++) and HdfSBuf objects (in C). + * + * @since 1.0 + */ + +#ifndef HDF_SBUF_IPC_IMPL_H +#define HDF_SBUF_IPC_IMPL_H + +#include +#include "hdf_sbuf.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Converts a MessageParcel object into an HdfSBuf object. + * @param parcel Indicates the pointer to the MessageParcel object to convert. + * @return Returns the HdfSBuf object obtained. + * @since 1.0 + */ +struct HdfSBuf *ParcelToSbuf(OHOS::MessageParcel *parcel); + +/** + * @brief Converts an HdfSBuf object into a MessageParcel object. + * @param sbuf Indicates the pointer to the HdfSBuf object to convert. + * @param parcel Indicates the pointer to the MessageParcel object obtained. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. + * @since 1.0 + */ +int32_t SbufToParcel(struct HdfSBuf *sbuf, OHOS::MessageParcel **parcel); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif // HDF_SBUF_IPC_IMPL_H diff --git a/apis/20230220/inner_api-en/osal/uhdf/hdf_log_adapter.h b/apis/20230220/inner_api-en/osal/uhdf/hdf_log_adapter.h new file mode 100644 index 0000000000000000000000000000000000000000..ea399cd1560b62895896e5b68a5be21457abbceb --- /dev/null +++ b/apis/20230220/inner_api-en/osal/uhdf/hdf_log_adapter.h @@ -0,0 +1,88 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @addtogroup DriverUtils + * @{ + * + * @brief Defines common macros and interfaces of the driver module. + * + * This module provides interfaces for log printing, doubly linked list operations, and work queues. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file hdf_log_adapter.h + * + * @brief Provides the implementation of hdf_log. HiLog macros are used to implement the functions of macros, such as HDF_LOGV. Service modules do not use this file. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef HDF_LOG_ADAPTER_H +#define HDF_LOG_ADAPTER_H + +#include "hilog/log.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Defines the log domain of the HDF. + */ +#undef LOG_DOMAIN +#define LOG_DOMAIN 0xD002500 + +/** + * @brief Defines the default log label of the HDF. + */ +#ifndef LOG_TAG +#define LOG_TAG HDF +#endif + +/** + * @brief Adapts to printing information of the verbose level of the HiLog module. + */ +#define HDF_LOGV_WRAPPER(fmt, arg...) HILOG_DEBUG(LOG_CORE, fmt, ##arg) + +/** + * @brief Adapts to printing information of the debug level of the HiLog module. + */ +#define HDF_LOGD_WRAPPER(fmt, arg...) HILOG_DEBUG(LOG_CORE, fmt, ##arg) + +/** + * @brief Adapts to printing information of the info level of the HiLog module. + */ +#define HDF_LOGI_WRAPPER(fmt, arg...) HILOG_INFO(LOG_CORE, fmt, ##arg) + +/** + @brief Adapts to printing information of the warning level of the HiLog module. + */ +#define HDF_LOGW_WRAPPER(fmt, arg...) HILOG_WARN(LOG_CORE, fmt, ##arg) + +/** + * @brief Adapts to printing information of the error level of the HiLog module. + */ +#define HDF_LOGE_WRAPPER(fmt, arg...) HILOG_ERROR(LOG_CORE, fmt, ##arg) + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDF_LOG_ADAPTER_H */ diff --git a/apis/20230220/inner_api-en/osal/uhdf/hdf_types.h b/apis/20230220/inner_api-en/osal/uhdf/hdf_types.h new file mode 100644 index 0000000000000000000000000000000000000000..5e32b24c1be947ccd60ef2e3d72f3b216c62b169 --- /dev/null +++ b/apis/20230220/inner_api-en/osal/uhdf/hdf_types.h @@ -0,0 +1,25 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * 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 HDF_TYPE_H +#define HDF_TYPE_H + +#include +#include +#include +#include +#include + +#endif /* HDF_TYPE_H */ diff --git a/apis/20230220/inner_api-en/utils/hdf_base.h b/apis/20230220/inner_api-en/utils/hdf_base.h new file mode 100644 index 0000000000000000000000000000000000000000..ab9247ad1147f96e5fe4dd8b11f4c2703c1e9e71 --- /dev/null +++ b/apis/20230220/inner_api-en/utils/hdf_base.h @@ -0,0 +1,92 @@ +/* + * Copyright (c) 2020-2023 Huawei Device Co., Ltd. + * + * HDF is dual licensed: you can use it either under the terms of + * the GPL, or the BSD license, at your option. + * See the LICENSE file in the root of this repository for complete details. + */ + +/** + * @addtogroup DriverUtils + * @{ + * + * @brief Defines common macros and interfaces of the driver module. + * + * This module provides interfaces for log printing, doubly linked list operations, and work queues. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file hdf_base.h + * + * @brief Declares driver common types, including the enumerated values returned by the function + * and the macro for obtaining the array size. + * + * @since 1.0 + * @version 1.0 + */ +#ifndef HDF_BASE_TYPE_H +#define HDF_BASE_TYPE_H + +#include "hdf_types.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +#ifdef __LITEOS__ +/** + * @brief Declares the full path of the HDF module library. + */ +#define HDF_LIBRARY_FULL_PATH(x) "/usr/lib/" x ".so" +/** + * @brief Declares the directory of the HDF module library. + */ +#define HDF_LIBRARY_DIR "/usr/lib" +/** + * @brief Declares the directory of the HDF module configuration files. + */ +#define HDF_ETC_DIR "/etc" +/** + * @brief Declares the configuration directory of the HDF module. + */ +#define HDF_CONFIG_DIR "/etc" +#else +/** + * @brief Declares the full path of the HDF module library. + */ +#ifdef __aarch64__ +#define HDF_LIBRARY_FULL_PATH(x) "/vendor/lib64/" x ".z.so" +#else +#define HDF_LIBRARY_FULL_PATH(x) "/vendor/lib/" x ".z.so" +#endif +/** + * @brief Declares the directory of the HDF module library. + */ +#define HDF_LIBRARY_DIR "/vendor/lib" +/** + * @brief Declares the directory of the HDF module configuration files. + */ +#define HDF_ETC_DIR "/vendor/etc" +/** + * @brief Declares the configuration directory of the HDF module. + */ +#define HDF_CONFIG_DIR "/vendor/etc/hdfconfig" +/** + * @brief Declares the directory of the HCS configuration file of the HDF. + */ +#define HDF_CHIP_PROD_CONFIG_DIR "/chip_prod/etc/hdfconfig" +/** + * @brief Declares the installation directory of the HDF kernel-mode service module driver. + */ +#define HDF_MODULE_DIR "/vendor/modules/" +#endif + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* HDF_BASE_TYPE_H */ +/** @} */