Skip to content

Commit ee5dac3

Browse files
CopilotBernardXiong
Copilot
and
BernardXiong
committed
[virtio] Add comprehensive documentation and maintain backward compatibility
- Added README.md with usage guide and migration instructions - Updated Kconfig to keep RT_USING_VIRTIO10 as alias for backward compatibility - Documented key differences between legacy and modern VirtIO - Added troubleshooting and contributing guidelines Co-authored-by: BernardXiong <[email protected]>
1 parent 81d0c2a commit ee5dac3

File tree

3 files changed

+175
-1
lines changed

3 files changed

+175
-1
lines changed

‎components/drivers/virtio/Kconfig‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ menuconfig RT_USING_VIRTIO
1313
Support for VirtIO legacy interface (version 0x1).
1414
This is the older version compatible with most existing QEMU versions.
1515

16+
config RT_USING_VIRTIO10
17+
bool "VirtIO Legacy (v1.0 - alias for compatibility)"
18+
help
19+
Alias for RT_USING_VIRTIO_LEGACY for backward compatibility.
20+
Support for VirtIO legacy interface (version 0x1).
21+
1622
config RT_USING_VIRTIO_MODERN
1723
bool "VirtIO Modern (v1.0+)"
1824
help

‎components/drivers/virtio/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# VirtIO Driver for RT-Thread
2+
3+
## Overview
4+
5+
The VirtIO driver provides support for virtual I/O devices in RT-Thread, primarily used in virtualized environments like QEMU.
6+
7+
## Supported Versions
8+
9+
The driver now supports both legacy and modern VirtIO specifications:
10+
11+
- **Legacy VirtIO (v0.95)**: Version field 0x1, compatible with older QEMU versions
12+
- **Modern VirtIO (v1.0+)**: Version field 0x2, supports VirtIO 1.0, 1.1, and 1.2 specifications
13+
14+
## Supported Devices
15+
16+
- **VirtIO Block (virtio-blk)**: Virtual block device
17+
- **VirtIO Network (virtio-net)**: Virtual network interface
18+
- **VirtIO Console (virtio-console)**: Virtual serial console
19+
- **VirtIO GPU (virtio-gpu)**: Virtual graphics device
20+
- **VirtIO Input (virtio-input)**: Virtual input device (keyboard, mouse, tablet)
21+
22+
## Configuration
23+
24+
Use `menuconfig` to configure VirtIO support:
25+
26+
```
27+
RT-Thread Components → Device Drivers → Using VirtIO device drivers
28+
```
29+
30+
### Version Selection
31+
32+
Choose between legacy and modern VirtIO:
33+
34+
```
35+
RT-Thread Components → Device Drivers → Using VirtIO device drivers → VirtIO Version
36+
```
37+
38+
Options:
39+
- **VirtIO Legacy (v0.95)**: For compatibility with older QEMU versions (default)
40+
- **VirtIO Modern (v1.0+)**: For newer QEMU versions (2.4+) with enhanced features
41+
42+
### Device Selection
43+
44+
Enable individual VirtIO devices:
45+
46+
```
47+
RT-Thread Components → Device Drivers → Using VirtIO device drivers
48+
```
49+
50+
- `RT_USING_VIRTIO_BLK`: VirtIO block device support
51+
- `RT_USING_VIRTIO_NET`: VirtIO network device support
52+
- `RT_USING_VIRTIO_CONSOLE`: VirtIO console device support
53+
- `RT_USING_VIRTIO_GPU`: VirtIO GPU device support
54+
- `RT_USING_VIRTIO_INPUT`: VirtIO input device support
55+
56+
## Key Differences Between Legacy and Modern VirtIO
57+
58+
### Legacy VirtIO (v0.95)
59+
- 32-bit feature negotiation
60+
- Single queue descriptor area
61+
- Simple status flags
62+
- Guest page size configuration
63+
64+
### Modern VirtIO (v1.0+)
65+
- 64-bit feature negotiation (supports more features)
66+
- Separate descriptor/driver/device queue areas
67+
- Enhanced status flow with FEATURES_OK check
68+
- Better memory alignment and atomicity guarantees
69+
- Config generation field for atomic configuration reads
70+
71+
## Migration Guide
72+
73+
### From Legacy to Modern
74+
75+
1. Update your QEMU command line to use modern VirtIO devices (most recent QEMU versions default to modern)
76+
2. Change the VirtIO version in menuconfig:
77+
```
78+
RT-Thread Components → Device Drivers → Using VirtIO device drivers → VirtIO Version
79+
→ Select "VirtIO Modern (v1.0+)"
80+
```
81+
3. Rebuild your application
82+
4. The driver will automatically negotiate the VERSION_1 feature with the device
83+
84+
### Backward Compatibility
85+
86+
The driver automatically detects the device version from the MMIO config and adapts its behavior accordingly. Both legacy (version 0x1) and modern (version 0x2) devices are supported in the same build.
87+
88+
## BSP Support
89+
90+
The following BSPs have been updated to support both legacy and modern VirtIO:
91+
92+
- `qemu-virt64-riscv`: QEMU RISC-V 64-bit
93+
- `qemu-virt64-aarch64`: QEMU ARM64 (AArch64)
94+
95+
## Reference Specifications
96+
97+
- [VirtIO Specification v1.0](https://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html)
98+
- [VirtIO Specification v1.1](https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html)
99+
- [VirtIO Specification v1.2](https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html)
100+
101+
## Implementation Details
102+
103+
### Feature Negotiation
104+
105+
Modern VirtIO uses 64-bit feature negotiation:
106+
- Device exposes features via `device_features` register (selected by `device_features_sel`)
107+
- Driver acknowledges features via `driver_features` register (selected by `driver_features_sel`)
108+
- For modern devices, the driver must negotiate `VIRTIO_F_VERSION_1` (feature bit 32)
109+
110+
### Queue Initialization
111+
112+
**Legacy VirtIO:**
113+
- Uses single `queue_pfn` register pointing to the start of the queue area
114+
- Guest page size configured via `guest_page_size`
115+
116+
**Modern VirtIO:**
117+
- Uses separate registers for descriptor, driver (avail), and device (used) areas:
118+
- `queue_desc_low`/`queue_desc_high`: Descriptor table address
119+
- `queue_driver_low`/`queue_driver_high`: Available ring address
120+
- `queue_device_low`/`queue_device_high`: Used ring address
121+
- Queue activated via `queue_ready` register
122+
123+
### Status Flow
124+
125+
**Modern VirtIO adds FEATURES_OK check:**
126+
1. Reset device (status = 0)
127+
2. Set ACKNOWLEDGE and DRIVER status bits
128+
3. Read and negotiate features
129+
4. Write negotiated features to device
130+
5. Set FEATURES_OK status bit
131+
6. Re-read status to verify FEATURES_OK (device may reject features)
132+
7. If accepted, proceed with queue setup and set DRIVER_OK
133+
134+
## Troubleshooting
135+
136+
### Device Not Detected
137+
138+
Check that:
139+
1. QEMU is configured with VirtIO devices
140+
2. The VirtIO version matches your QEMU configuration
141+
3. The device memory region is correctly mapped
142+
143+
### Build Errors
144+
145+
Ensure:
146+
1. The Kconfig is properly configured
147+
2. All VirtIO header files are included
148+
3. The BSP supports VirtIO (check `BSP_USING_VIRTIO`)
149+
150+
### Runtime Issues
151+
152+
Debug tips:
153+
1. Check device version in MMIO config
154+
2. Verify feature negotiation succeeded
155+
3. Check queue initialization (descriptor, avail, used ring addresses)
156+
4. Monitor interrupt status and acknowledgment
157+
158+
## Contributing
159+
160+
When adding new VirtIO devices or features:
161+
1. Support both legacy and modern versions
162+
2. Use the helper functions for feature negotiation (`virtio_get_features`, `virtio_set_features`)
163+
3. Use version checking (`dev->version`) for version-specific code
164+
4. Test on both legacy and modern QEMU configurations
165+
166+
## License
167+
168+
Apache-2.0

‎components/drivers/virtio/virtio.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
#endif
2626

2727
/* VirtIO version configuration */
28-
#ifdef RT_USING_VIRTIO_LEGACY
28+
#if defined(RT_USING_VIRTIO_LEGACY) || defined(RT_USING_VIRTIO10)
2929
#define RT_USING_VIRTIO_VERSION 0x1 /* Legacy interface */
3030
#elif defined(RT_USING_VIRTIO_MODERN)
3131
#define RT_USING_VIRTIO_VERSION 0x2 /* Modern interface (1.0+) */

0 commit comments

Comments
 (0)