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