From 9dbeb6268b8edb60950ed39bd3363133c72ec1b7 Mon Sep 17 00:00:00 2001 From: huangyuchen Date: Fri, 27 Jan 2023 15:47:40 +0800 Subject: [PATCH] Add guide.md for ashmem.h Issue:I6BA6M Test:NA Change-Id: I8d00d0a3dff3e747f19a12134e8eb570e5a61345 Signed-off-by: huangyuchen --- docs/zh-cn/c-utils-guide-ashmem.md | 78 ++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/zh-cn/c-utils-guide-ashmem.md diff --git a/docs/zh-cn/c-utils-guide-ashmem.md b/docs/zh-cn/c-utils-guide-ashmem.md new file mode 100644 index 0000000..84bb807 --- /dev/null +++ b/docs/zh-cn/c-utils-guide-ashmem.md @@ -0,0 +1,78 @@ +# 使用匿名共享内存(Ashmem, Anonymous Shared Memory) + +## 概述 + +使用linux内核提供的驱动`dev/ashmem`，申请内核空间中的一块内存区域并映射至用户空间。利用其共享机制，可以实现较大数据量的进程间通信。 + +## 涉及功能 +### OHOS::Ashmem + +C++公共基础库中的Ashmem实现，用于操作匿名共享内存(Ashmem)。 + +#### 具体描述 + +```cpp +class OHOS::Ashmem; +``` +具体操作包括创建并映射一块ashmem内存区域并对其进行读写等。 +**提示**: 尽管被智能指针管理，Ashmem对象仍需手动解除映射并关闭。 + + +`#include ` + +继承自 OHOS::RefBase + +#### Public Functions + +| 返回类型 | 名称 | +| -------------- | -------------- | +| sptr< Ashmem > | **CreateAshmem**(const char* name, int32_t size)
使用指定名称及大小创建Ashmem对象。 | +| | **Ashmem**(int fd, int32_t size)
构造Ashmem对象。 | +| | **~Ashmem**() override | +| void | **CloseAshmem**()
通过文件描述符关闭当前ashmem。 | +| int | **GetAshmemFd**() const
获取内核中对应ashmem的文件描述符。 | +| int32_t | **GetAshmemSize**()
获取内核中ashmem区域的大小。 | +| int | **GetProtection**()
获取内核中的ashmem区域的保护权限值。 | +| bool | **MapAshmem**(int mapType)
将内核中的ashmem内存区域映射至用户空间。 | +| bool | **MapReadAndWriteAshmem**()
以读/写模式映射ashmem内存区域。 | +| bool | **MapReadOnlyAshmem**()
以只读模式映射ashmem内存区域。 | +| const void * | **ReadFromAshmem**(int32_t size, int32_t offset)
从ashmem内存区域`offset`处读出数据。 | +| bool | **SetProtection**(int protectionType)
设置内核中的ashmem区域的保护权限。 | +| void | **UnmapAshmem**()
解除ashmem映射。 | +| bool | **WriteToAshmem**(const void* data, int32_t size, int32_t offset)
在ashmem内存区域`offset`处写入数据。 | + + +## 使用示例 + +1. 使用方法(伪代码) + +```c++ +sptr ashmem = Ashmem::CreateAshmem(MEMORY_NAME.c_str(), MEMORY_SIZE); +if (ashmem != nullptr) { + bool ret = ashmem->MapAshmem(PROT_READ | PROT_WRITE); +} + +... + +// 当使用结束时不要忘记解映射和关闭ashmem +ashmem->UnmapAshmem(); +ashmem->CloseAshmem(); +``` + +2. 测试用例编译运行方法 + +- 测试用例代码参见 base/test/unittest/common/utils_ashmem_test.cpp + +- 使用开发者自测试框架，使用方法参见：[开发自测试执行框架-测试用例执行](https://gitee.com/openharmony/testfwk_developer_test#%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E6%89%A7%E8%A1%8C) + +- 使用以下具体命令以运行`ashmem.h`对应测试用例 + +```bash +run -t UT -tp utils -ts UtilsAshmemTest +``` + +## 常见问题 + +1. Ashmem对象使用结束后**需要手动解除映射并关闭** + * 智能指针仅管理Ashmem对象的析构，而Ashmem对象析构时不会解除内存空间的映射并关闭。 + * 使用`UnmapAshmem()`解除映射并使用`CloseAshmem()`关闭。 -- Gitee