Commit d37a39f6 authored by Abdiel Janulgue's avatar Abdiel Janulgue Committed by Danilo Krummrich
Browse files

rust: dma: add as_slice/write functions for CoherentAllocation 



Add unsafe accessors for the region for reading or writing large
blocks of data.

Reviewed-by: default avatarAndreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: default avatarAbdiel Janulgue <abdiel.janulgue@gmail.com>
Reviewed-by: default avatarAlexandre Courbot <acourbot@nvidia.com>
Link: https://lore.kernel.org/r/20250602085444.1925053-4-abdiel.janulgue@gmail.com


[ Fix line length and slightly reword safety comment in doc-test of
  CoherentAllocation::write(); fix formatting issue. - Danilo ]
Signed-off-by: default avatarDanilo Krummrich <dakr@kernel.org>
parent fe584659

rust/kernel/dma.rs

+87 −0
Original line number Diff line number Diff line
@@ -218,6 +218,93 @@ pub fn dma_handle(&self) -> bindings::dma_addr_t { 
        self.dma_handle

    }



    /// Common helper to validate a range applied from the allocated region in the CPU's virtual

    /// address space.

    fn validate_range(&self, offset: usize, count: usize) -> Result {

        if offset.checked_add(count).ok_or(EOVERFLOW)? > self.count {

            return Err(EINVAL);

        }

        Ok(())

    }



    /// Returns the data from the region starting from `offset` as a slice.

    /// `offset` and `count` are in units of `T`, not the number of bytes.

    ///

    /// For ringbuffer type of r/w access or use-cases where the pointer to the live data is needed,

    /// [`CoherentAllocation::start_ptr`] or [`CoherentAllocation::start_ptr_mut`] could be used

    /// instead.

    ///

    /// # Safety

    ///

    /// * Callers must ensure that the device does not read/write to/from memory while the returned

    ///   slice is live.

    /// * Callers must ensure that this call does not race with a write to the same region while

    ///   the returned slice is live.

    pub unsafe fn as_slice(&self, offset: usize, count: usize) -> Result<&[T]> {

        self.validate_range(offset, count)?;

        // SAFETY:

        // - The pointer is valid due to type invariant on `CoherentAllocation`,

        //   we've just checked that the range and index is within bounds. The immutability of the

        //   data is also guaranteed by the safety requirements of the function.

        // - `offset + count` can't overflow since it is smaller than `self.count` and we've checked

        //   that `self.count` won't overflow early in the constructor.

        Ok(unsafe { core::slice::from_raw_parts(self.cpu_addr.add(offset), count) })

    }



    /// Performs the same functionality as [`CoherentAllocation::as_slice`], except that a mutable

    /// slice is returned.

    ///

    /// # Safety

    ///

    /// * Callers must ensure that the device does not read/write to/from memory while the returned

    ///   slice is live.

    /// * Callers must ensure that this call does not race with a read or write to the same region

    ///   while the returned slice is live.

    pub unsafe fn as_slice_mut(&self, offset: usize, count: usize) -> Result<&mut [T]> {

        self.validate_range(offset, count)?;

        // SAFETY:

        // - The pointer is valid due to type invariant on `CoherentAllocation`,

        //   we've just checked that the range and index is within bounds. The immutability of the

        //   data is also guaranteed by the safety requirements of the function.

        // - `offset + count` can't overflow since it is smaller than `self.count` and we've checked

        //   that `self.count` won't overflow early in the constructor.

        Ok(unsafe { core::slice::from_raw_parts_mut(self.cpu_addr.add(offset), count) })

    }



    /// Writes data to the region starting from `offset`. `offset` is in units of `T`, not the

    /// number of bytes.

    ///

    /// # Safety

    ///

    /// * Callers must ensure that the device does not read/write to/from memory while the returned

    ///   slice is live.

    /// * Callers must ensure that this call does not race with a read or write to the same region

    ///   that overlaps with this write.

    ///

    /// # Examples

    ///

    /// ```

    /// # fn test(alloc: &mut kernel::dma::CoherentAllocation<u8>) -> Result {

    /// let somedata: [u8; 4] = [0xf; 4];

    /// let buf: &[u8] = &somedata;

    /// // SAFETY: There is no concurrent HW operation on the device and no other R/W access to the

    /// // region.

    /// unsafe { alloc.write(buf, 0)?; }

    /// # Ok::<(), Error>(()) }

    /// ```

    pub unsafe fn write(&self, src: &[T], offset: usize) -> Result {

        self.validate_range(offset, src.len())?;

        // SAFETY:

        // - The pointer is valid due to type invariant on `CoherentAllocation`

        //   and we've just checked that the range and index is within bounds.

        // - `offset + count` can't overflow since it is smaller than `self.count` and we've checked

        //   that `self.count` won't overflow early in the constructor.

        unsafe {

            core::ptr::copy_nonoverlapping(src.as_ptr(), self.cpu_addr.add(offset), src.len())

        };

        Ok(())

    }



    /// Returns a pointer to an element from the region with bounds checking. `offset` is in

    /// units of `T`, not the number of bytes.

    ///