From a0a1d1c3dff6bb45218781a91ea10d18c90bc9ce Mon Sep 17 00:00:00 2001 From: Sachin Date: Sun, 11 Sep 2022 03:07:59 +0530 Subject: [PATCH] Description of SimpleHandler --- docs/vmm-reference-simple-handler.md | 136 +++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/vmm-reference-simple-handler.md diff --git a/docs/vmm-reference-simple-handler.md b/docs/vmm-reference-simple-handler.md new file mode 100644 index 0000000..7bbd1e6 --- /dev/null +++ b/docs/vmm-reference-simple-handler.md @@ -0,0 +1,136 @@ +# [Simple Handler](./../src/devices/src/virtio/net/simple_handler.rs) + +`SimpleHandler` contains methods for handling Tx/Rx queues. This handler is generalized over the implementaton of queues (does not make any assumptions the way queues are implemented). + +```rs +pub struct SimpleHandler { + pub driver_notify: S, + pub rxq: Queue, + pub rxbuf_current: usize, + pub rxbuf: [u8; MAX_BUFFER_SIZE], + pub txq: Queue, + pub txbuf: [u8; MAX_BUFFER_SIZE], + pub tap: Tap, +} + +``` + +__A brief overview of all the struct variables:__ + +1. `driver_notify:` + + A SignalUsedQueue object to model the operation of signalling the driver about used events. It should implement a method named `signal_used_queue` that takes parameter `index` and notifies the driver about index. Index values used here in SimpleHandler are `RXQ_INDEX` (for receiving) and `TXQ_INDEX` (for transmitting). + +2. `rxq:` Recieving queue of `GuestAddressSpace` +3. `rxbuf_current:` Number of bytes in `rxbuf` +4. `rxbuf:` Recieving buffer of maximum size `MAX_BUFFER_SIZE` +5. `txq:` Transmit queue of `GuestAddressSpace` +6. `txbuf:` Transmit buffer of maximum size `MAX_BUFFER_SIZE` +7. `tap:` Object of Tap struct that wraps the file descriptor for the tap device so methods can run ioctls on the interface + +```rs +const MAX_BUFFER_SIZE: usize = 65562; +``` + + + + + + + + + + + + +
+Incomping Packet Size +
+   + vitio +     +      + ethernet header + UDP/TCP Packet +
+ +        +        +      +
+ 12 bits +       +       +       +       +       + 65550 bits +
+
65562 bits +
+ +__A brief overview of all the struct methods:__ + +1. `Constructor:` + +```rs +pub fn new(driver_notify: S, rxq: Queue, txq: Queue, tap: Tap) -> Self +``` +Creates a SimpleHandler with provided driver_notify, rxq, txq and tap. Sets rxbuf_current and all entries of Tx and Rx buffers to 0. + +2. `write_frame_to_guest:` + +```rs +fn write_frame_to_guest(&mut self) -> result::Result +``` +Writes elements in Rx buffer to Rx queue. Also performs multiple checks in between like: +* Returns Ok(false) if unable to create iterator of Rx queue +* Throws `GuestMemory` Error if unable to write +* Warns about Rx frame being too large if buffer size is smaller then sum of size of all elements in queue + +3. `process_tap:` +```rs +pub fn process_tap(&mut self) -> result::Result<(), Error> +``` + +While any of write_frame_to_guest or enable_notification from Rx queue is true, it sets rxbuf_current to value read by tap from Rx buffer (only if rxbuf_current is 0). Finally notifies driver_notify with index as `RXQ_INDEX` if Rx queue needs notification + +4. `send_frame_from_chain:` +```rs +fn send_frame_from_chain( + &mut self, + chain: &mut DescriptorChain, + ) -> result::Result +``` +Reads elements of Tx queue to Tx buffer sequentially and finally writes Tx buffer to tap. + +5. `process_txq:` +```rs +pub fn process_txq(&mut self) -> result::Result<(), Error> +``` +In a loop it does the following: +* Disable notification of Tx queue +* Call send_frame_from_chain on Iterator of Tx queue +* Notifies driver_notify with index as `TXQ_INDEX` if Tx queue needs notification +* Returns Ok if notification of Tx queue is disabled +6. `process_rxq:` +```rs +pub fn process_rxq(&mut self) -> result::Result<(), Error> +``` + +Disables notification on Rx queue and calls process_tap + +__USAGE:__ + +1. [QueueHandler](./../src/devices/src/virtio/net/queue_handler.rs) +```rs +pub struct QueueHandler { + pub inner: SimpleHandler, +``` +Used to call process methods on tap and queues (`process_tap`, `process_rxq`, `process_txq`) and get appropriate error if thrown while execution of those methods + +2. [Net](./../src/devices/src/virtio/net/device.rs) +```rs +fn activate(&mut self) -> Result<()> { +.. +let inner = SimpleHandler::new(driver_notify, rxq, txq, tap); +``` \ No newline at end of file