1 /*
2  * Copyright (c) 2020-2021 Huawei Device Co., Ltd.
3  *
4  * HDF is dual licensed: you can use it either under the terms of
5  * the GPL, or the BSD license, at your option.
6  * See the LICENSE file in the root of this repository for complete details.
7  */
8 
9 #ifndef PLATFORM_MANAGER_H
10 #define PLATFORM_MANAGER_H
11 
12 #include "hdf_base.h"
13 #include "hdf_dlist.h"
14 #include "osal_spinlock.h"
15 #include "platform_device.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif /* __cplusplus */
20 
21 struct PlatformManager {
22     struct PlatformDevice device;
23     struct DListHead devices;  /* list to keep all it's device instances */
24     int32_t (*add)(struct PlatformManager *manager, struct PlatformDevice *device);
25     int32_t (*del)(struct PlatformManager *manager, struct PlatformDevice *device);
26 };
27 
28 /**
29  * @brief Create a platform manager.
30  *
31  * Create a platform manager with member initialized.
32  *
33  * @param name Indicates the name of the manager.
34  * @param manager Indicates the double pointer to receive the created manager instance.
35  *
36  * @return Returns 0 if create successfully; returns a negative value otherwise.
37  * @since 1.0
38  */
39 int32_t PlatformManagerCreate(const char *name, struct PlatformManager **manager);
40 
41 /**
42  * @brief Destroy a platform manager.
43  *
44  * @param name Indicates the name of the manager.
45  *
46  * @since 1.0
47  */
48 void PlatformManagerDestroy(struct PlatformManager *manager);
49 
50 /**
51  * @brief Get a platform manager by module type.
52  *
53  * @param module Indicates the module type of the manager.
54  *
55  * @return Returns the pointer to the paltform manager on success; returns NULL otherwise.
56  * @since 1.0
57  */
58 struct PlatformManager *PlatformManagerGet(int module);
59 
60 /**
61  * @brief Add a platform device to a platform manager.
62  *
63  * Add a platform device to make it managed by platform core.
64  *
65  * @param manager Indicates the pointer to the platform manager.
66  * @param device Indicates the pointer to the platform device.
67  *
68  * @return Returns 0 if the devcie added successfully; returns a negative value otherwise.
69  * @since 1.0
70  */
71 int32_t PlatformManagerAddDevice(struct PlatformManager *manager, struct PlatformDevice *device);
72 
73 /**
74  * @brief Remove a platform device from a platform manager.
75  *
76  * Remove a platform device to make it away from management of platform core.
77  *
78  * @param manager Indicates the pointer to the platform manager.
79  * @param device Indicates the pointer to the platform device.
80  *
81  * @return Returns 0 if the remove successfully; returns a negative value otherwise.
82  * @since 1.0
83  */
84 int32_t PlatformManagerDelDevice(struct PlatformManager *manager, struct PlatformDevice *device);
85 
86 /**
87  * @brief Find a particular device from the manager.
88  *
89  * Locate a particular device from the manager by a matching function, witch will be called for
90  * each device, until it returns true indicatting a device is "found".
91  * The device found will be returned with reference count increased.
92  *
93  * @param manager Indicates the pointer to the platform manager.
94  * @param data Indicates the pointer to the data passed to match function.
95  * @param match Indicates the pointer to the match function.
96  *
97  * @return Returns the pointer to the paltform device on success; returns NULL otherwise.
98  * @since 1.0
99  */
100 struct PlatformDevice *PlatformManagerFindDevice(struct PlatformManager *manager, void *data,
101     bool (*match)(struct PlatformDevice *pdevice, void *data));
102 
103 /**
104  * @brief Get a platform device from the manager by number.
105  *
106  * The device got will be returned with reference count increased.
107  *
108  * @param manager Indicates the pointer to the platform manager.
109  * @param number Indicates the number of the target platform device.
110  *
111  * @return Returns the pointer to the paltform device on success; returns NULL otherwise.
112  * @since 1.0
113  */
114 struct PlatformDevice *PlatformManagerGetDeviceByNumber(struct PlatformManager *manager, uint32_t number);
115 
116 /**
117  * @brief Get a platform device from the manager by device name.
118  *
119  * The device got will be returned with reference count increased.
120  *
121  * @param manager Indicates the pointer to the platform manager.
122  * @param number Indicates the name of the target platform device.
123  *
124  * @return Returns the pointer to the paltform device on success; returns NULL otherwise.
125  * @since 1.0
126  */
127 struct PlatformDevice *PlatformManagerGetDeviceByName(struct PlatformManager *manager, const char *name);
128 
129 #ifdef __cplusplus
130 }
131 #endif /* __cplusplus */
132 
133 #endif /* PLATFORM_MANAGER_H */
134