From ca2ac2176692289b9d18debe5e2cc2671830564d Mon Sep 17 00:00:00 2001 From: huangyuchen Date: Sat, 14 Jan 2023 19:53:50 +0800 Subject: [PATCH] Add doc comments for ashmem.h Issue:I6B44S Test:NA Signed-off-by: huangyuchen Change-Id: I3f72d2b4b1b777dbbcfefc6f0046b448a30356c3 --- base/include/ashmem.h | 156 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 152 insertions(+), 4 deletions(-) diff --git a/base/include/ashmem.h b/base/include/ashmem.h index b0460ed..f7d855e 100644 --- a/base/include/ashmem.h +++ b/base/include/ashmem.h @@ -13,6 +13,13 @@ * limitations under the License. */ + /** + * @file ashmem.h + * + * @brief Provide class Ashmem implemented in c_utils to operate the + * Anonymous Shared Memory(Ashmem). + */ + #ifndef UTILS_BASE_ASHMEM_H #define UTILS_BASE_ASHMEM_H @@ -22,35 +29,176 @@ #include "parcel.h" namespace OHOS { +/** + * @brief Create ashmem in kernel with specified name and size. + * + * @param name Name for identifying the ashmem in kernel. + * @param size Size of the ashmem region. + * @return File descriptor of the ashmem. + */ int AshmemCreate(const char *name, size_t size); + +/** + * @brief Set protection flag of specified ashmem region in kernel. + + * @param fd Corresponding file descriptor. + * @param prot Value of protection flag. + * @return Return 0 on success, -1 on failure. + */ int AshmemSetProt(int fd, int prot); + +/** + * @brief Get size of specified ashmem region in kernel. + * + * @param fd Corresponding file descriptor. + * @return Size of ashmem. + */ int AshmemGetSize(int fd); +/** + * @brief Ashmem implemented in c_utils, to operate the + * Anonymous Shared Memory(Ashmem). + * + * Including create, map an ashmem region and thus write/read to/from it, etc. + * + * @note Ashmem object should be unmapped and closed manually, though managed + * by smart pointer. + */ class Ashmem : public virtual RefBase { public: + /** + * @brief Create an Ashmem object with specified name and region size. + * + * File '/dev/ashmem' will be opened whose file descriptor will be held by + * this Ashmem object. + * + * @param name Name for identifying the ashmem in kernel. + * @param size Size of the ashmem region. + * @return An Ashmem object referenced by a smart pointer. + * @note Memory has not been mapped, use `MapAshmem()` before + * writing/reading. + */ static sptr CreateAshmem(const char *name, int32_t size); + + /** + * @brief Close the ashmem(i.e. close it via file descriptor). + * + * All inner parameters will be cleared. + * + * @note An ashmem will be unmapped first by `UnmapAshmem()` before close. + */ void CloseAshmem(); + + /** + * @brief Map the ashmem region in the kernel to user space. + * + * @param mapType Protection flag of the mapped region in user space. + * @return True if mapping successful. + */ bool MapAshmem(int mapType); + + /** + * @brief Map the ashmem region in Read/Write mode. + * + * It calls `MapAshmem(PROT_READ | PROT_WRITE)`. + * + * @return True if mapping successful. + */ bool MapReadAndWriteAshmem(); + + /** + * @brief Map the ashmem region in Read-Only mode. + * + * It calls `MapAshmem(PROT_READ)`. + * + * @return True if mapping successful. + */ bool MapReadOnlyAshmem(); + + /** + * @brief Unmap the ashmem. + * + * Unmap when mapped ashmem exists, protection flag will be cleared + * meanwhile. + */ void UnmapAshmem(); + + /** + * @brief Set the protection flag of ashmem region in kernel. + * + * @param protectionType Value of protection flag. + * @return True if set successful. + */ bool SetProtection(int protectionType); + + /** + * @brief Get the protection flag of ashmem region in kernel. + * + * @return Value of protection flag. Refer to linux manual. + */ int GetProtection(); + + /** + * @brief Get the size of ashmem region in kernel. + * + * @return Value of size. + */ int32_t GetAshmemSize(); + + /** + * @brief Write data to the `offset` position of ashmem region. + * + * Bounds and protection flag will be checked. + * + * @param data Pointer to input data. + * @param size Size of the input data(bytes). + * @param offset Offset from beginning of the region. + * @return True if writting successful. False if data to be write overflows + * or protection flag is illegal. + * @note Require write authority of both ashmem in kernel and the mapped + * one in user space. + */ bool WriteToAshmem(const void *data, int32_t size, int32_t offset); + + /** + * @brief Read data from the `offset` position of ashmem region. + * + * Bounds and protection flag will be checked. + * + * @param size Size of data to be read(bytes). + * @param offset Offset from beginning of the region. + * @return Void-type pointer to the data. `nullptr` returns if data to be + * read overflows or protection flag is illegal. + * @note Require read authority of both ashmem in kernel and the mapped one + * in user space. + */ const void *ReadFromAshmem(int32_t size, int32_t offset); + + /** + * @brief Construct a new Ashmem object. + * + * @param fd File descriptor of an ashmem in kenrel. + * @param size Size of the corresponding ashmem region in kernel. + */ Ashmem(int fd, int32_t size); ~Ashmem() override; + + /** + * @brief Get file descriptor of the corresponding ashmem in kernel. + * + * @return Corresponding file descriptor of this Ashmem object. It will be + * 0 when ashmem is closed. + */ int GetAshmemFd() const { return memoryFd_; }; private: - int memoryFd_; - int32_t memorySize_; - int flag_; - void *startAddr_; + int memoryFd_; // corresponding file descriptor of ashmem. + int32_t memorySize_; // size of ashmem. + int flag_; // protection flag of ashmem in user space. + void *startAddr_; // start address of ashmem region. bool CheckValid(int32_t size, int32_t offset, int cmd); }; } // namespace OHOS -- Gitee