Line data Source code
1 0 : /*
2 : * Copyright (c) 2024 Antmicro <www.antmicro.com>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_VIRTIO_VIRTIO_H_
8 : #define ZEPHYR_VIRTIO_VIRTIO_H_
9 : #include <zephyr/device.h>
10 : #include "virtio/virtqueue.h"
11 :
12 : #ifdef __cplusplus
13 : extern "C" {
14 : #endif
15 :
16 : /**
17 : * @brief Virtio Interface
18 : * @defgroup virtio_interface Virtio Interface
19 : * @ingroup io_interfaces
20 : * @{
21 : */
22 :
23 : /**
24 : * Callback used during virtqueue enumeration
25 : *
26 : * @param queue_idx index of currently inspected queue
27 : * @param max_queue_size maximum permitted size of currently inspected queue
28 : * @param opaque pointer to user provided data
29 : * @return the size of currently inspected virtqueue we want to set
30 : */
31 1 : typedef uint16_t (*virtio_enumerate_queues)(
32 : uint16_t queue_idx, uint16_t max_queue_size, void *opaque
33 : );
34 :
35 : /**
36 : * @brief Virtio api structure
37 : */
38 1 : __subsystem struct virtio_driver_api {
39 : struct virtq *(*get_virtqueue)(const struct device *dev, uint16_t queue_idx);
40 0 : void (*notify_virtqueue)(const struct device *dev, uint16_t queue_idx);
41 0 : void *(*get_device_specific_config)(const struct device *dev);
42 0 : bool (*read_device_feature_bit)(const struct device *dev, int bit);
43 0 : int (*write_driver_feature_bit)(const struct device *dev, int bit, bool value);
44 0 : int (*commit_feature_bits)(const struct device *dev);
45 0 : int (*init_virtqueues)(
46 : const struct device *dev, uint16_t num_queues, virtio_enumerate_queues cb,
47 : void *opaque
48 : );
49 0 : void (*finalize_init)(const struct device *dev);
50 : };
51 :
52 : /**
53 : * Returns virtqueue at given idx
54 : *
55 : * @param dev virtio device it operates on
56 : * @param queue_idx index of virtqueue to get
57 : * @return pointer to virtqueue or NULL if not present
58 : */
59 1 : static inline struct virtq *virtio_get_virtqueue(const struct device *dev, uint16_t queue_idx)
60 : {
61 : const struct virtio_driver_api *api = dev->api;
62 :
63 : return api->get_virtqueue(dev, queue_idx);
64 : }
65 :
66 : /**
67 : * Notifies virtqueue
68 : *
69 : * Note that according to spec 2.7.13.3 the device may access the buffers as soon
70 : * as the avail->idx is increased, which is done by virtq_add_buffer_chain, so the
71 : * device may access the buffers even without notifying it with virtio_notify_virtqueue
72 : *
73 : * @param dev virtio device it operates on
74 : * @param queue_idx virtqueue to be notified
75 : */
76 1 : static inline void virtio_notify_virtqueue(const struct device *dev, uint16_t queue_idx)
77 : {
78 : const struct virtio_driver_api *api = dev->api;
79 :
80 : api->notify_virtqueue(dev, queue_idx);
81 : }
82 :
83 : /**
84 : * Returns device specific config
85 : *
86 : * @param dev virtio device it operates on
87 : * @return pointer to the device specific config or NULL if its not present
88 : */
89 1 : static inline void *virtio_get_device_specific_config(const struct device *dev)
90 : {
91 : const struct virtio_driver_api *api = dev->api;
92 :
93 : return api->get_device_specific_config(dev);
94 : }
95 :
96 : /**
97 : * Returns feature bit offered by virtio device
98 : *
99 : * @param dev virtio device it operates on
100 : * @param bit selected bit
101 : * @return value of the offered feature bit
102 : */
103 1 : static inline bool virtio_read_device_feature_bit(const struct device *dev, int bit)
104 : {
105 : const struct virtio_driver_api *api = dev->api;
106 :
107 : return api->read_device_feature_bit(dev, bit);
108 : }
109 :
110 : /**
111 : * Sets feature bit
112 : *
113 : * @param dev virtio device it operates on
114 : * @param bit selected bit
115 : * @param value bit value to write
116 : * @return 0 on success or negative error code on failure
117 : */
118 1 : static inline int virtio_write_driver_feature_bit(const struct device *dev, int bit, bool value)
119 : {
120 : const struct virtio_driver_api *api = dev->api;
121 :
122 : return api->write_driver_feature_bit(dev, bit, value);
123 : }
124 :
125 : /**
126 : * Commits feature bits
127 : *
128 : * @param dev virtio device it operates on
129 : * @return 0 on success or negative error code on failure
130 : */
131 1 : static inline int virtio_commit_feature_bits(const struct device *dev)
132 : {
133 : const struct virtio_driver_api *api = dev->api;
134 :
135 : return api->commit_feature_bits(dev);
136 : }
137 :
138 : /**
139 : * Initializes virtqueues
140 : *
141 : * @param dev virtio device it operates on
142 : * @param num_queues number of queues to initialize
143 : * @param cb callback called for each available virtqueue
144 : * @param opaque pointer to user provided data that will be passed to the callback
145 : * @return 0 on success or negative error code on failure
146 : */
147 1 : static inline int virtio_init_virtqueues(
148 : const struct device *dev, uint16_t num_queues, virtio_enumerate_queues cb, void *opaque)
149 : {
150 : const struct virtio_driver_api *api = dev->api;
151 :
152 : return api->init_virtqueues(dev, num_queues, cb, opaque);
153 : }
154 :
155 : /**
156 : * Finalizes initialization of the virtio device
157 : *
158 : * @param dev virtio device it operates on
159 : */
160 0 : static inline void virtio_finalize_init(const struct device *dev)
161 : {
162 : const struct virtio_driver_api *api = dev->api;
163 :
164 : api->finalize_init(dev);
165 : }
166 :
167 : /**
168 : * @}
169 : */
170 :
171 : #ifdef __cplusplus
172 : }
173 : #endif
174 :
175 : #endif /* ZEPHYR_VIRTIO_VIRTIO_H_ */
|
