Struct Bitmap 

pub struct Bitmap { /* private fields */ }

Represents a C bitmap. Wraps underlying C bitmap API.

Invariants

Must reference a [c_ulong] long enough to fit data.len() bits. Must not be longer than i32::MAX bits, so offsets and lengths used with Bitmap functions fit in the int and unsigned int arguments of the C bitmap API. This also matches BitmapVec::MAX_LEN.

Implementations

impl Bitmap

pub unsafe fn from_raw<'a>(ptr: *const usize, nbits: usize) -> &'a Bitmap

Borrows a C bitmap.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and nbits exceeds i32::MAX.

Safety

• ptr holds a non-null address of an initialized array of unsigned long that is large enough to hold nbits bits.
• nbits must not exceed i32::MAX.
• the array must not be freed for the lifetime of this Bitmap
• concurrent access only happens through atomic operations

pub unsafe fn from_raw_mut<'a>(ptr: *mut usize, nbits: usize) -> &'a mut Bitmap

Borrows a C bitmap exclusively.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and nbits exceeds i32::MAX.

Safety

• ptr holds a non-null address of an initialized array of unsigned long that is large enough to hold nbits bits.
• nbits must not exceed i32::MAX.
• the array must not be freed for the lifetime of this Bitmap
• no concurrent access may happen.

pub fn as_ptr(&self) -> *const usize

Returns a raw pointer to the backing Bitmap.

pub fn as_mut_ptr(&mut self) -> *mut usize

Returns a mutable raw pointer to the backing Bitmap.

pub fn len(&self) -> usize

Returns length of this Bitmap.

impl Bitmap

pub fn set_bit(&mut self, index: usize)

Set bit with index index.

ATTENTION: set_bit is non-atomic, which differs from the naming convention in C code. The corresponding C function is __set_bit.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and index is greater than or equal to self.nbits, does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and index is greater than or equal to self.nbits.

pub fn set_bit_atomic(&self, index: usize)

Set bit with index index, atomically.

This is a relaxed atomic operation (no implied memory barriers).

ATTENTION: The naming convention differs from C, where the corresponding function is called set_bit.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and index is greater than or equal to self.len(), does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and index is greater than or equal to self.len().

pub fn clear_bit(&mut self, index: usize)

Clear index bit.

ATTENTION: clear_bit is non-atomic, which differs from the naming convention in C code. The corresponding C function is __clear_bit.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and index is greater than or equal to self.len(), does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and index is greater than or equal to self.len().

pub fn clear_bit_atomic(&self, index: usize)

Clear index bit, atomically.

This is a relaxed atomic operation (no implied memory barriers).

ATTENTION: The naming convention differs from C, where the corresponding function is called clear_bit.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and index is greater than or equal to self.len(), does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and index is greater than or equal to self.len().

pub fn copy_and_extend(&mut self, src: &Bitmap)

Copy src into this Bitmap and set any remaining bits to zero.

Examples

use kernel::alloc::{AllocError, flags::GFP_KERNEL};
use kernel::bitmap::BitmapVec;

let mut long_bitmap = BitmapVec::new(256, GFP_KERNEL)?;

assert_eq!(None, long_bitmap.last_bit());

let mut short_bitmap = BitmapVec::new(16, GFP_KERNEL)?;

short_bitmap.set_bit(7);
long_bitmap.copy_and_extend(&short_bitmap);
assert_eq!(Some(7), long_bitmap.last_bit());

pub fn last_bit(&self) -> Option<usize>

Finds last set bit.

Examples

use kernel::alloc::{AllocError, flags::GFP_KERNEL};
use kernel::bitmap::BitmapVec;

let bitmap = BitmapVec::new(64, GFP_KERNEL)?;

match bitmap.last_bit() {
    Some(idx) => {
        pr_info!("The last bit has index {idx}.\n");
    }
    None => {
        pr_info!("All bits in this bitmap are 0.\n");
    }
}

pub fn next_bit(&self, start: usize) -> Option<usize>

Finds next set bit, starting from start.

Returns None if no bits are set on or after the given index. The index start must be in bounds.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and start is out of bounds.

pub fn next_zero_bit(&self, start: usize) -> Option<usize>

Finds next zero bit, starting from start.

Returns None if no bits are zero on or after the given index. The index start must be in bounds.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and start is out of bounds.

pub fn next_zero_area_off( &self, start: usize, nbits: NonZero<usize>, align: Alignment, align_offset: usize, ) -> Option<usize>

Finds a contiguous area of nbits zero bits at or after start, where the area plus align_offset is aligned to align.

Returns the bit index of the start of the area, or None if no such area fitting in the bitmap exists.

The returned index plus align_offset is a multiple of align.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and start is out of bounds.

pub fn next_zero_area( &self, start: usize, nbits: NonZero<usize>, align: Alignment, ) -> Option<usize>

Finds a contiguous area of nbits zero bits at or after start, aligned to align.

Returns the bit index of the start of the area, or None if no such area fitting in the bitmap exists.

The returned index is a multiple of align.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and start is out of bounds.

Examples

use kernel::{
    alloc::{AllocError, flags::GFP_KERNEL},
    bitmap::BitmapVec,
    ptr::Alignment,
    sizes::SizeConstants, //
};

let mut b = BitmapVec::new(64, GFP_KERNEL)?;

assert_eq!(Some(0), b.next_zero_area(0, cv!(8), Alignment::SZ_1));
b.set(0, cv!(5));
assert_eq!(Some(5), b.next_zero_area(0, cv!(8), Alignment::SZ_1));
assert_eq!(Some(8), b.next_zero_area(0, cv!(8), Alignment::SZ_8));
assert_eq!(None, b.next_zero_area(0, cv!(65), Alignment::SZ_1));

pub fn set(&mut self, start: usize, nbits: NonZero<usize>)

Sets a contiguous area of nbits bits starting at start.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and the area start..start + nbits is out of bounds, does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and the area start..start + nbits is out of bounds.

pub fn clear(&mut self, start: usize, nbits: NonZero<usize>)

Clears a contiguous area of nbits bits starting at start.

If CONFIG_RUST_BITMAP_HARDENED is not enabled and the area start..start + nbits is out of bounds, does nothing.

Panics

Panics if CONFIG_RUST_BITMAP_HARDENED is enabled and the area start..start + nbits is out of bounds.