Struct xdpsock::umem::Frame

pub struct Frame<'umem> {
    pub status: FrameStatus,
    // some fields omitted
}

Describes a UMEM frame’s address and size of its current contents.

The addr field is an offset in bytes from the start of the UMEM and corresponds to some point within a frame. The len field describes the length (in bytes) of any data stored in that frame, starting from addr.

If sending data, the len field will need to be set by the user before transmitting via the TxQueue. Otherwise when reading received frames using the RxQueue, the len field will be set by the kernel and dictates the number of bytes the user should read from the UMEM.

Fields

status: FrameStatus

Implementations

impl Frame<'_>

pub fn addr(&self) -> usize

pub fn len(&self) -> usize

pub fn options(&self) -> u32

pub fn set_addr(&mut self, addr: usize)

Set the frame descriptor’s address. This determines where in the UMEM it references.

Manual setting shouldn’t generally be required is likely best avoided since the setting of addresses is handled by the library, however it may be needed if writing straight to a region in UMEM via umem_region_mut or umem_region_mut_checked

pub fn set_len(&mut self, len: usize)

Set the frame descriptor’s length. This should equal the length of the data stored at addr.

Once data has been written to the UMEM region starting at addr, this FrameDesc’s length must be updated before handing it over to the kernel to be transmitted to ensure the correct number of bytes are sent.

Manual setting shouldn’t generally be required and if copying packets to UMEM it’s better to use write_to_umem or write_to_umem_checked which will handle setting the frame descriptor length, however it may be needed if writing to a UMEM region manually (see set_addr) or if, for example, the data you want to send is already at addr and you just need to set the length before transmission.

pub fn set_options(&mut self, options: u32)

Set the frame descriptor options.

pub fn is_access_valid(&self, len: usize) -> Result<(), AccessError>

Check if data is ok to write to the UMEM for transmission.

pub fn is_data_valid(&self, data: &[u8]) -> Result<(), DataError>

Check if data is ok to write to the UMEM for transmission.

pub unsafe fn read_from_umem(&self, len: usize) -> &[u8]

Return a reference to the UMEM region starting at addr of length len.

This does not check that the region accessed makes sense and may cause undefined behaviour if used improperly. An example of potential misuse is referencing a region that extends beyond the end of the UMEM.

Apart from the memory considerations, this function is also unsafe as there is no guarantee the kernel isn’t also reading from or writing to the same region.

pub unsafe fn read_from_umem_checked(
    &self,
    len: usize
) -> Result<&[u8], AccessError>

Checked version of umem_region_ref. Ensures that the referenced region is contained within a single frame of the UMEM.

pub unsafe fn write_to_umem(&mut self, data: &[u8])

Copy data to the region starting at frame_desc.addr, and set frame_desc.len when done.

This does no checking that the region written to makes sense and may cause undefined behaviour if used improperly. An example of potential misuse is writing beyond the end of the UMEM, or if data is large then potentially writing across frame boundaries.

Apart from the considerations around writing to memory, this function is also unsafe as there is no guarantee the kernel isn’t also reading from or writing to the same region.

pub unsafe fn write_to_umem_checked(
    &mut self,
    data: &[u8]
) -> Result<(), WriteError>

Checked version of write_to_umem_frame. Ensures that a successful write is completely contained within a single frame of the UMEM.

pub unsafe fn umem_region_mut(&mut self, len: &usize) -> &mut [u8]

Return a reference to the UMEM region starting at addr of length len.

This does not check that the region accessed makes sense and may cause undefined behaviour if used improperly. An example of potential misuse is referencing a region that extends beyond the end of the UMEM.

Apart from the memory considerations, this function is also unsafe as there is no guarantee the kernel isn’t also reading from or writing to the same region.

If data is written to a frame, the length on the corresponding FrameDesc for addr must be updated before submitting to the TxQueue. This ensures the correct number of bytes are sent. Use write_to_umem or write_to_umem_checked to avoid the overhead of updating the frame descriptor.

pub unsafe fn umem_region_mut_checked(
    &mut self,
    len: usize
) -> Result<&mut [u8], AccessError>

Checked version of umem_region_mut. Ensures the requested region lies within a single frame.

Trait Implementations

impl<'umem> Clone for Frame<'umem>

fn clone(&self) -> Frame<'umem>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'umem> Debug for Frame<'umem>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'umem> PartialEq<Frame<'umem>> for Frame<'umem>

fn eq(&self, other: &Frame<'umem>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Frame<'umem>) -> bool

This method tests for !=.

impl<'umem> StructuralPartialEq for Frame<'umem>