1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15#ifndef DDK_API_H
16#define DDK_API_H
17
18/**
19 * @addtogroup Ddk
20 * @{
21 *
22 * @brief Provides Base DDK APIs, including creating the shared memory, mapping the shared memory,\n
23 * unmapping the shared memory, and destroying the shared memory.
24 *
25 * @since 12
26 */
27
28/**
29 * @file ddk_api.h
30 *
31 * @brief Declares the Base DDK APIs.
32 *
33 * @library libddk_base.z.so
34 * @kit DriverDevelopmentKit
35 * @syscap SystemCapability.Driver.DDK.Extension
36 * @since 12
37 */
38
39#include <stdint.h>
40#include "ddk_types.h"
41
42#ifdef __cplusplus
43extern "C" {
44#endif /* __cplusplus */
45
46/**
47 * @brief Creates shared memory. To prevent resource leakage, destroy the shared memory that is not required by\n
48 * calling <b>OH_DDK_DestroyAshmem</b>.
49 *
50 * @param name Pointer to the shared memory to create.
51 * @param size Size of the buffer corresponding to the shared memory.
52 * @param ashmem Pointer to the shared memory created.
53 * @return {@link DDK_SUCCESS} the operation is successful.
54 *         {@link DDK_INVALID_PARAMETER} name is NULL, size is 0 or ashmem is NULL.
55 *         {@link DDK_FAILURE} create the shared memory failed or create structure DDK_Ashmem failed.
56 * @since 12
57 */
58DDK_RetCode OH_DDK_CreateAshmem(const uint8_t *name, uint32_t size, DDK_Ashmem **ashmem);
59
60/**
61 * @brief Maps the created shared memory to the user space. Unmap the shared memory that is not required by using\n
62 * <b>OH_DDK_UnmapAshmem</b>.
63 *
64 * @param ashmem Pointer of the shared memory to map.
65 * @param ashmemMapType Protection permission value of the shared memory.
66 * @return {@link DDK_SUCCESS} the operation is successful.
67 *         {@link DDK_NULL_PTR} ashmem is NULL.
68 *         {@link DDK_FAILURE} the fd of ashmem is invalid.
69 *         {@link DDK_INVALID_OPERATION} use function MapAshmem failed.
70 * @since 12
71 */
72DDK_RetCode OH_DDK_MapAshmem(DDK_Ashmem *ashmem, const uint8_t ashmemMapType);
73
74/**
75 * @brief Unmaps shared memory.
76 *
77 * @param ashmem Pointer of the shared memory to unmap.
78 * @return {@link DDK_SUCCESS} the operation is successful.
79 *         {@link DDK_NULL_PTR} ashmem is NULL.
80 *         {@link DDK_FAILURE} the fd of ashmem is invalid.
81 * @since 12
82 */
83DDK_RetCode OH_DDK_UnmapAshmem(DDK_Ashmem *ashmem);
84
85/**
86 * @brief Destroys shared memory.
87 *
88 * @param ashmem Pointer of the shared memory to destroy.
89 * @return {@link DDK_SUCCESS} the operation is successful.
90 *         {@link DDK_NULL_PTR} ashmem is NULL.
91 *         {@link DDK_FAILURE} the fd of ashmem is invalid.
92 * @since 12
93 */
94DDK_RetCode OH_DDK_DestroyAshmem(DDK_Ashmem *ashmem);
95#ifdef __cplusplus
96}
97/** @} */
98#endif /* __cplusplus */
99#endif // DDK_APIS_H