Explorar el Código

[virtio] Add VirtIO specification references document

- Added SPECIFICATIONS.md with official VirtIO spec links
- Documented v1.0, v1.1, and v1.2 specifications
- Included QEMU documentation references
- Added feature bits and status bits reference tables
- Addresses issue comment requesting specification links

Co-authored-by: BernardXiong <1241087+BernardXiong@users.noreply.github.com>
copilot-swe-agent[bot] hace 3 meses
padre
commit
28683c8fec
Se han modificado 1 ficheros con 194 adiciones y 0 borrados
  1. 194 0
      components/drivers/virtio/SPECIFICATIONS.md

+ 194 - 0
components/drivers/virtio/SPECIFICATIONS.md

@@ -0,0 +1,194 @@
+# VirtIO Specification References
+
+## Official VirtIO Specifications
+
+### Latest Version (v1.2)
+**VirtIO 1.2 Specification** (2022-07-14)
+- **Official Link**: https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
+- **PDF**: https://docs.oasis-open.org/virtio/virtio/v1.2/csd01/virtio-v1.2-csd01.pdf
+- **Status**: OASIS Committee Specification Draft 01
+- **Key Features**: 
+  - All features from v1.1
+  - New devices: Audio, File System, PMEM, RPMB, Video Encoder/Decoder, SCMI, GPIO, RDMA
+  - Enhanced device specifications
+  - Better security and performance features
+
+### VirtIO 1.1 Specification (2019-01-29)
+- **Official Link**: https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
+- **PDF**: https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.pdf
+- **Status**: OASIS Committee Specification Public Review Draft 01
+- **Key Features**:
+  - All features from v1.0
+  - Packed ring support (VIRTIO_F_RING_PACKED)
+  - New devices: Socket, Crypto, Signal Distribution Module, IOMMU, Memory
+  - Order-independent feature negotiation
+
+### VirtIO 1.0 Specification (2016-03-08)
+- **Official Link**: https://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html
+- **PDF**: https://docs.oasis-open.org/virtio/virtio/v1.0/cs04/virtio-v1.0-cs04.pdf
+- **Status**: OASIS Committee Specification 04
+- **Key Features**:
+  - Modern interface (version field = 0x2)
+  - 64-bit feature negotiation
+  - Separate queue descriptor/driver/device areas
+  - FEATURES_OK status check
+  - Better memory alignment requirements
+
+### Legacy VirtIO (v0.95)
+- **Reference**: Part of Linux kernel documentation
+- **Link**: https://wiki.libvirt.org/VirtIO.html
+- **Status**: Legacy interface (version field = 0x1)
+- **Note**: Used by older QEMU versions and some embedded systems
+
+## OASIS VirtIO Technical Committee
+
+- **Website**: https://www.oasis-open.org/committees/virtio/
+- **Charter**: Defines standard interfaces for virtual I/O devices
+- **Mailing List**: virtio@lists.oasis-open.org
+- **Git Repository**: https://github.com/oasis-tcs/virtio-spec
+
+## Implementation in RT-Thread
+
+RT-Thread now supports:
+- ✅ **Legacy VirtIO (v0.95)**: Version field 0x1, 32-bit features, legacy queue setup
+- ✅ **Modern VirtIO (v1.0+)**: Version field 0x2, 64-bit features, modern queue setup
+
+The implementation follows the VirtIO 1.2 specification for modern devices while maintaining backward compatibility with legacy devices.
+
+## Device-Specific Specifications
+
+### VirtIO Block Device
+- **Section**: 5.2 in VirtIO 1.2 spec
+- **Features**: Basic block I/O, multiple queues, discard support
+- **Status**: Fully implemented in RT-Thread
+
+### VirtIO Network Device  
+- **Section**: 5.1 in VirtIO 1.2 spec
+- **Features**: Ethernet interface, checksum offload, multiple queues
+- **Status**: Fully implemented in RT-Thread
+
+### VirtIO Console Device
+- **Section**: 5.3 in VirtIO 1.2 spec
+- **Features**: Serial console, multiple ports, control messages
+- **Status**: Fully implemented in RT-Thread
+
+### VirtIO GPU Device
+- **Section**: 5.7 in VirtIO 1.2 spec
+- **Features**: 2D graphics, scanout, resource management
+- **Status**: Fully implemented in RT-Thread
+
+### VirtIO Input Device
+- **Section**: 5.8 in VirtIO 1.2 spec
+- **Features**: Keyboard, mouse, tablet input events
+- **Status**: Fully implemented in RT-Thread
+
+## QEMU VirtIO Implementation
+
+### QEMU Documentation
+- **VirtIO Devices**: https://qemu.readthedocs.io/en/latest/system/devices/virtio-net.html
+- **MMIO Transport**: https://qemu.readthedocs.io/en/latest/specs/virtio-mmio.html
+
+### QEMU Version Requirements
+- **Legacy VirtIO**: QEMU 1.0+
+- **Modern VirtIO**: QEMU 2.4+ (recommended 2.6+)
+
+### QEMU Command Line Examples
+
+**Legacy Mode:**
+```bash
+qemu-system-riscv64 -M virt \
+  -device virtio-blk-device,disable-modern=on,drive=blk0
+```
+
+**Modern Mode:**
+```bash
+qemu-system-riscv64 -M virt \
+  -device virtio-blk-device,disable-legacy=on,drive=blk0
+```
+
+**Auto-detect (Default):**
+```bash
+qemu-system-riscv64 -M virt \
+  -device virtio-blk-device,drive=blk0
+```
+
+## Feature Bits Reference
+
+### Common Features (Section 6 in VirtIO 1.2 spec)
+
+| Bit | Name | Description |
+|-----|------|-------------|
+| 24 | VIRTIO_F_NOTIFY_ON_EMPTY | Notify on empty available ring |
+| 27 | VIRTIO_F_ANY_LAYOUT | Flexible descriptor layout |
+| 28 | VIRTIO_F_RING_INDIRECT_DESC | Indirect descriptors |
+| 29 | VIRTIO_F_RING_EVENT_IDX | Event index for notifications |
+| 32 | VIRTIO_F_VERSION_1 | Compliance with VirtIO 1.0+ |
+| 34 | VIRTIO_F_RING_PACKED | Packed ring layout (1.1+) |
+
+### Device-Specific Features
+
+**Block Device:**
+- Bit 0: VIRTIO_BLK_F_BARRIER - Legacy barrier support
+- Bit 1: VIRTIO_BLK_F_SIZE_MAX - Maximum segment size
+- Bit 2: VIRTIO_BLK_F_SEG_MAX - Maximum segments
+- Bit 5: VIRTIO_BLK_F_RO - Read-only device
+- Bit 9: VIRTIO_BLK_F_FLUSH - Cache flush support
+
+**Network Device:**
+- Bit 0: VIRTIO_NET_F_CSUM - Checksum offload
+- Bit 1: VIRTIO_NET_F_GUEST_CSUM - Guest checksum
+- Bit 5: VIRTIO_NET_F_MAC - MAC address
+- Bit 6: VIRTIO_NET_F_GSO - Generic segmentation offload
+
+## Status Bits Reference
+
+| Bit | Name | Description |
+|-----|------|-------------|
+| 0 | ACKNOWLEDGE | Driver has found the device |
+| 1 | DRIVER | Driver knows how to drive the device |
+| 2 | DRIVER_OK | Driver is set up and ready |
+| 3 | FEATURES_OK | Feature negotiation complete |
+| 6 | NEEDS_RESET | Device experienced unrecoverable error |
+| 7 | FAILED | Driver gave up on device |
+
+## Additional Resources
+
+### Linux Kernel VirtIO Implementation
+- **Source**: https://github.com/torvalds/linux/tree/master/drivers/virtio
+- **Documentation**: https://www.kernel.org/doc/Documentation/virtual/
+
+### KVM/QEMU VirtIO
+- **KVM Forum**: https://www.linux-kvm.org/page/Virtio
+- **QEMU Wiki**: https://wiki.qemu.org/Features/VirtIO
+
+### Books and Papers
+- **"Hardware Virtualization: Platforms and Applications"** - Covers VirtIO design
+- **"Virtual Machines: Versatile Platforms for Systems and Processes"** - Chapter on I/O virtualization
+
+## RT-Thread Specific Documentation
+
+- **[README.md](README.md)**: RT-Thread VirtIO usage guide
+- **[TESTING.md](TESTING.md)**: Testing procedures for both legacy and modern modes
+
+## Version History
+
+| Date | Version | RT-Thread Support | Notes |
+|------|---------|------------------|-------|
+| 2022-07-14 | 1.2 | ✅ Yes | Latest specification |
+| 2019-01-29 | 1.1 | ✅ Yes | Packed ring support |
+| 2016-03-08 | 1.0 | ✅ Yes | Modern interface |
+| ~2013 | 0.95 | ✅ Yes | Legacy interface (default) |
+
+## Contact and Support
+
+- **RT-Thread Forum**: https://club.rt-thread.io/
+- **GitHub Issues**: https://github.com/RT-Thread/rt-thread/issues
+- **VirtIO Mailing List**: virtio@lists.oasis-open.org
+
+## License
+
+VirtIO specifications are licensed under:
+- OASIS Open Source License (VirtIO 1.0+)
+
+RT-Thread VirtIO driver is licensed under:
+- Apache License 2.0