Skip to content

Commit

Permalink
virtqueue: improve documentation
Browse files Browse the repository at this point in the history 
Move method docs to trait definition and remove references to methods that were removed.
  • Loading branch information
@cagatay-y
cagatay-y committed Feb 21, 2024
1 parent 63d6dad commit ecbedf1
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 74 deletions.
27 changes: 23 additions & 4 deletions src/drivers/virtio/virtqueue/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,16 +131,35 @@ pub trait Virtq {
/// * All finished `TransferTokens` will have a state of `TransferState::Finished`.
fn poll(&self);

/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
fn dispatch_batch(&self, tkns: Vec<TransferToken>, notif: bool);

/// Dispatches a batch of TransferTokens. The Transfers will be placed in to the `await_queue`
/// upon finish.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
///
/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// Tokens to get a reference to the provided await_queue, where they will be placed upon finish.
fn dispatch_batch_await(
&self,
tkns: Vec<TransferToken>,
await_queue: Rc<RefCell<VecDeque<Transfer>>>,
notif: bool,
);

/// Creates a new Virtq of the specified (VqSize)[VqSize] and the (VqIndex)[VqIndex].
/// Creates a new Virtq of the specified [VqSize] and the [VqIndex].
/// The index represents the "ID" of the virtqueue.
/// Upon creation the virtqueue is "registered" at the device via the `ComCfg` struct.
///
Expand Down Expand Up @@ -422,8 +441,8 @@ pub fn dispatch_batch_await(
}
}

/// The trait needs to be implemented on structures which are to be used via the `prep_transfer()` function of virtqueues and for
/// structures which are to be used to write data into buffers of a [BufferToken] via `BufferToken.write()` or
/// The trait needs to be implemented for
/// structures which are to be used to write data into buffers of a [BufferToken] via [BufferToken::write] or
/// `BufferToken.write_seq()`.
///
/// **INFO:*
Expand Down Expand Up @@ -638,7 +657,7 @@ impl Transfer {
/// The returned data is of type `Box<[Box<[u8]>]>`. This function therefore preserves
/// the scattered structure of the buffer,
///
/// If one create this buffer via a `Virtq.prep_transfer()` or `Virtq.prep_transfer_from_raw()`
/// If one creates this buffer via a `Virtq.prep_transfer_from_raw()`
/// call, a casting back to the original structure `T` is NOT possible.
/// In these cases please use `Transfer.ret_cpy()` or use 'BuffSpec::Single' only!
pub fn ret_scat_cpy(
Expand Down
35 changes: 0 additions & 35 deletions src/drivers/virtio/virtqueue/packed.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -974,28 +974,18 @@ pub struct PackedVq {
// This is currently unlikely, as the Tokens hold a Rc<Virtq> for refering to their origin
// queue. This could be eased
impl Virtq for PackedVq {
/// Enables interrupts for this virtqueue upon receiving a transfer
fn enable_notifs(&self) {
self.drv_event.borrow_mut().enable_notif();
}

/// Disables interrupts for this virtqueue upon receiving a transfer
fn disable_notifs(&self) {
self.drv_event.borrow_mut().disable_notif();
}

/// See `Virtq.poll()` documentation
fn poll(&self) {
self.descr_ring.borrow_mut().poll();
}

/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
fn dispatch_batch(&self, tkns: Vec<TransferToken>, notif: bool) {
// Zero transfers are not allowed
assert!(!tkns.is_empty());
Expand Down Expand Up @@ -1029,18 +1019,6 @@ impl Virtq for PackedVq {
}
}

/// Dispatches a batch of TransferTokens. The Transfers will be placed in to the `await_queue`
/// upon finish.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
///
/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// Tokens to get a reference to the provided await_queue, where they will be placed upon finish.
fn dispatch_batch_await(
&self,
mut tkns: Vec<TransferToken>,
Expand Down Expand Up @@ -1084,11 +1062,6 @@ impl Virtq for PackedVq {
}
}

/// See `Virtq.prep_transfer()` documentation.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
fn dispatch(&self, tkn: TransferToken, notif: bool) {
let (next_off, next_wrap) = self.descr_ring.borrow_mut().push(tkn);

Expand Down Expand Up @@ -1119,16 +1092,10 @@ impl Virtq for PackedVq {
}
}

/// See `Virtq.index()` documentation
fn index(&self) -> VqIndex {
self.index
}

/// Creates a new Virtq of the specified (VqSize)[VqSize] and the (VqIndex)[VqIndex].
/// The index represents the "ID" of the virtqueue.
/// Upon creation the virtqueue is "registered" at the device via the `ComCfg` struct.
///
/// Be aware, that devices define a maximum number of queues and a maximal size they can handle.
fn new(
com_cfg: &mut ComCfg,
notif_cfg: &NotifCfg,
Expand Down Expand Up @@ -1229,7 +1196,6 @@ impl Virtq for PackedVq {
})
}

/// See `Virtq.prep_transfer_from_raw()` documentation.
fn prep_transfer_from_raw(
self: Rc<Self>,
send: Option<(&[u8], BuffSpec<'_>)>,
Expand Down Expand Up @@ -1787,7 +1753,6 @@ impl Virtq for PackedVq {
}
}

/// See `Virtq.prep_buffer()` documentation.
fn prep_buffer(
self: Rc<Self>,
send: Option<BuffSpec<'_>>,
Expand Down
35 changes: 0 additions & 35 deletions src/drivers/virtio/virtqueue/split.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -248,44 +248,22 @@ pub struct SplitVq {
}

impl Virtq for SplitVq {
/// Enables interrupts for this virtqueue upon receiving a transfer
fn enable_notifs(&self) {
self.ring.borrow_mut().drv_enable_notif();
}

/// Disables interrupts for this virtqueue upon receiving a transfer
fn disable_notifs(&self) {
self.ring.borrow_mut().drv_disable_notif();
}

/// See `Virtq.poll()` documentation
fn poll(&self) {
self.ring.borrow_mut().poll()
}

/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
fn dispatch_batch(&self, _tkns: Vec<TransferToken>, _notif: bool) {
unimplemented!();
}

/// Dispatches a batch of TransferTokens. The Transfers will be placed in to the `await_queue`
/// upon finish.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
///
/// Dispatches a batch of transfer token. The buffers of the respective transfers are provided to the queue in
/// sequence. After the last buffer has been written, the queue marks the first buffer as available and triggers
/// a device notification if wanted by the device.
///
/// Tokens to get a reference to the provided await_queue, where they will be placed upon finish.
fn dispatch_batch_await(
&self,
_tkns: Vec<TransferToken>,
Expand All @@ -295,11 +273,6 @@ impl Virtq for SplitVq {
unimplemented!()
}

/// See `Virtq.prep_transfer()` documentation.
///
/// The `notif` parameter indicates if the driver wants to have a notification for this specific
/// transfer. This is only for performance optimization. As it is NOT ensured, that the device sees the
/// updated notification flags before finishing transfers!
fn dispatch(&self, tkn: TransferToken, notif: bool) {
let (next_off, next_wrap) = self.ring.borrow_mut().push(tkn);

Expand Down Expand Up @@ -330,16 +303,10 @@ impl Virtq for SplitVq {
}
}

/// See `Virtq.index()` documentation
fn index(&self) -> VqIndex {
self.index
}

/// Creates a new Virtq of the specified (VqSize)[VqSize] and the (VqIndex)[VqIndex].
/// The index represents the "ID" of the virtqueue.
/// Upon creation the virtqueue is "registered" at the device via the `ComCfg` struct.
///
/// Be aware, that devices define a maximum number of queues and a maximal size they can handle.
fn new(
com_cfg: &mut ComCfg,
notif_cfg: &NotifCfg,
Expand Down Expand Up @@ -446,7 +413,6 @@ impl Virtq for SplitVq {
})
}

/// See `Virtq.prep_transfer_from_raw()` documentation.
fn prep_transfer_from_raw(
self: Rc<Self>,
send: Option<(&[u8], BuffSpec<'_>)>,
Expand Down Expand Up @@ -1004,7 +970,6 @@ impl Virtq for SplitVq {
}
}

/// See `Virtq.prep_buffer()` documentation.
fn prep_buffer(
self: Rc<Self>,
send: Option<BuffSpec<'_>>,
Expand Down

0 comments on commit ecbedf1

Please sign in to comment.