Enum CpuAccess 

#[repr(u32)]
pub enum CpuAccess {
    None = 0,
    Read = 1,
    Write = 2,
    ReadWrite = 3,
}

Declared CPU involvement for a tensor, chosen at allocation.

The declaration covers all CPU access to the buffer: the caller’s maps, pins and sync brackets, and the HAL’s own CPU work (the CPU image backend’s converts and draws, codec decodes, decoder reads and writes). Hardware access (ISP, codec, GPU, NPU, G2D, a compositor) needs no declaration and is always allowed.

The HAL enforces it. A CPU map, pin or sync whose direction the declaration does not cover fails with Error::CpuAccessDenied on every backend, before the memory is touched. The HAL’s own CPU passes go through the same check, so, for example, a CPU draw that would blend over a Write image, or a CPU convert that would read a None source, is refused instead of running.

Level	CPU may	Memory selected
None	nothing	Linux DMA-BUF: uncached CMA where available. Android: no CPU usage bits, so tile compression stays possible.
Read	read	cached; read-direction syncs only
Write	write whole passes	Linux DMA-BUF: uncached CMA where available, written write-combined
ReadWrite (default)	read and write	cached

Why uncached. A device that maps a cached buffer has to clean and invalidate the CPU cache over all of it on every access: a compositor blitting a client’s buffer every frame pays that for the whole buffer each time. An uncached buffer needs no cache maintenance. CPU reads of uncached memory are slow, which is why only declarations that exclude CPU reads select it; with the declaration enforced, nothing reads such a buffer on the CPU. On Linux a None or Write DMA-BUF comes from /dev/dma_heap/linux,cma-uncached when the system has it, and from the cached heaps otherwise. A write-only pass must write the whole buffer (see TensorTrait::map_for_write).

On Android the ReadWrite default asks gralloc for CPU_READ_OFTEN | CPU_WRITE_OFTEN, which may give linear, CPU-cached memory. Pass None for a buffer that is never mapped on the CPU, so gralloc can keep a tiled or compressed allocation.

Examples

A CPU-drawn overlay: written whole every frame, never read back.

use edgefirst_tensor::{
    CpuAccess, Error, PixelFormat, Tensor, TensorMapTrait, TensorMemory, TensorTrait,
};

let overlay = Tensor::<u8>::image(
    640,
    480,
    PixelFormat::Rgba,
    Some(TensorMemory::DmaBuf),
    CpuAccess::Write,
)?;
overlay.map_for_write()?.as_mut_slice().fill(0);
assert!(matches!(overlay.map_read(), Err(Error::CpuAccessDenied { .. })));

CpuAccess::code is the wire code the C header’s ef_cpu_access enumerators are asserted against.

Variants

None = 0

Hardware-only buffer: no CPU access. Required for vendor tile compression on platforms with compressed layouts; uncached CMA for a Linux DMA-BUF where available.

Read = 1

CPU reads only (verification, CPU consumers) — cached mapping.

Write = 2

CPU writes only, whole-buffer passes (decode targets, CPU-drawn overlays) — write-combined mapping; uncached CMA for a Linux DMA-BUF where available.

ReadWrite = 3

CPU reads and writes (the default).

Implementations

impl CpuAccess

pub const fn code(self) -> u32

The shared code for this variant. Identical on every surface.

const, deliberately: a downstream binding that cannot write Variant = OtherEnum::Variant.code() in a #[pyclass] discriminant position (PyO3 requires a literal there) can still pin that literal to this value with a const _: () = assert!(...) – a build-time check instead of a hand-synced comment. See PyTensorMemory/PyPixelFormat in crates/python-common/src/tensor.rs for the consumer.

pub fn from_code(code: u32) -> Option<Self>

Reject an unknown code rather than guessing at one.

pub fn as_str(self) -> &'static str

The wire string form – stable, unlike Debug.

pub fn from_str_code(s: &str) -> Option<Self>

Reject an unknown string rather than guessing at one.

pub fn all() -> &'static [Self]

Every variant, for exhaustive cross-surface tests.

impl CpuAccess

pub fn reads(self) -> bool

Whether this declaration includes CPU reads.

pub fn writes(self) -> bool

Whether this declaration includes CPU writes.

pub fn covers(self, requested: CpuAccess) -> bool

Whether this declaration covers requested (every direction the request needs is declared).

pub fn union(self, other: CpuAccess) -> CpuAccess

The declaration covering every direction of both self and other.

use edgefirst_tensor::CpuAccess;
assert_eq!(CpuAccess::Read.union(CpuAccess::Write), CpuAccess::ReadWrite);
assert_eq!(CpuAccess::None.union(CpuAccess::Write), CpuAccess::Write);

pub fn intersection(self, other: CpuAccess) -> CpuAccess

The declaration covering only the directions both self and other cover.

use edgefirst_tensor::CpuAccess;
assert_eq!(CpuAccess::ReadWrite.intersection(CpuAccess::Write), CpuAccess::Write);
assert_eq!(CpuAccess::Read.intersection(CpuAccess::Write), CpuAccess::None);

pub fn require(self, requested: CpuAccess) -> Result<()>

Ok when this declaration covers requested, otherwise Error::CpuAccessDenied naming both.

use edgefirst_tensor::{CpuAccess, Error};
assert!(CpuAccess::ReadWrite.require(CpuAccess::Write).is_ok());
assert!(matches!(
    CpuAccess::Read.require(CpuAccess::Write),
    Err(Error::CpuAccessDenied { .. })
));

Trait Implementations

impl Clone for CpuAccess

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for CpuAccess

impl Debug for CpuAccess

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

Formats the value using the given formatter.

impl Default for CpuAccess

fn default() -> Self

Returns the “default value” for a type.

impl Eq for CpuAccess

impl Hash for CpuAccess

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for CpuAccess

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for CpuAccess