1 /*
2 * Copyright (c) 2022 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Private API for USB host controller (UHC) drivers
10 */
11
12 #ifndef ZEPHYR_INCLUDE_UHC_COMMON_H
13 #define ZEPHYR_INCLUDE_UHC_COMMON_H
14
15 #include <zephyr/drivers/usb/uhc.h>
16
17 /**
18 * @brief Get driver's private data
19 *
20 * @param[in] dev Pointer to device struct of the driver instance
21 *
22 * @return pointer to driver's private data
23 */
uhc_get_private(const struct device * dev)24 static inline void *uhc_get_private(const struct device *dev)
25 {
26 struct uhc_data *data = dev->data;
27
28 return data->priv;
29 }
30
31 /**
32 * @brief Locking function for the drivers.
33 *
34 * @param[in] dev Pointer to device struct of the driver instance
35 * @param[in] timeout Timeout
36 *
37 * @return values provided by k_mutex_lock()
38 */
uhc_lock_internal(const struct device * dev,k_timeout_t timeout)39 static inline int uhc_lock_internal(const struct device *dev,
40 k_timeout_t timeout)
41 {
42 struct uhc_data *data = dev->data;
43
44 return k_mutex_lock(&data->mutex, timeout);
45 }
46
47 /**
48 * @brief Unlocking function for the drivers.
49 *
50 * @param[in] dev Pointer to device struct of the driver instance
51 *
52 * @return values provided by k_mutex_lock()
53 */
uhc_unlock_internal(const struct device * dev)54 static inline int uhc_unlock_internal(const struct device *dev)
55 {
56 struct uhc_data *data = dev->data;
57
58 return k_mutex_unlock(&data->mutex);
59 }
60
61 /**
62 * @brief Helper function to return UHC transfer to a higher level.
63 *
64 * Function to dequeue transfer and send UHC event to a higher level.
65 *
66 * @param[in] dev Pointer to device struct of the driver instance
67 * @param[in] xfer Pointer to UHC transfer
68 * @param[in] err Transfer error
69 */
70 void uhc_xfer_return(const struct device *dev,
71 struct uhc_transfer *const xfer,
72 const int err);
73
74 /**
75 * @brief Helper to get next transfer to process.
76 *
77 * This is currently a draft, and simple picks a transfer
78 * from the lists.
79 *
80 * @param[in] dev Pointer to device struct of the driver instance
81 * @return pointer to the next transfer or NULL on error.
82 */
83 struct uhc_transfer *uhc_xfer_get_next(const struct device *dev);
84
85 /**
86 * @brief Helper to append a transfer to internal list.
87 *
88 * @param[in] dev Pointer to device struct of the driver instance
89 * @param[in] xfer Pointer to UHC transfer
90 *
91 * @return 0 on success, all other values should be treated as error.
92 * @retval -ENOMEM if there is no buffer in the queue
93 */
94 int uhc_xfer_append(const struct device *dev,
95 struct uhc_transfer *const xfer);
96
97 /**
98 * @brief Helper function to send UHC event to a higher level.
99 *
100 * The callback would typically sends UHC even to a message queue (k_msgq).
101 *
102 * @param[in] dev Pointer to device struct of the driver instance
103 * @param[in] type Event type
104 * @param[in] status Event status
105 *
106 * @return 0 on success, all other values should be treated as error.
107 * @retval -EPERM controller is not initialized
108 */
109 int uhc_submit_event(const struct device *dev,
110 const enum uhc_event_type type,
111 const int status);
112
113 #endif /* ZEPHYR_INCLUDE_UHC_COMMON_H */
114
