Struct Context

pub struct Context { /* private fields */ }

Represents a specific device context to execute jobs.

This struct wraps a FFI pointer to the C++ pxl::runtime::Context class. It provides methods for managing device-specific execution contexts, allocating memory, and creating jobs for execution.

Implementations

impl Context

Implementation of the Context struct.

pub fn get(&self) -> *mut Context

Returns a raw pointer to the underlying FFI Context object. This is called in runtime wrapper APIs requiring a raw pointer.

Safety

Caller must ensure that FFI object is valid.

pub fn create_job(&mut self) -> Job

Create a new job with the remaining sub-devices.

This method creates a job that automatically allocates all available sub-devices in the context, maximizing resource utilization for the job execution.

Returns

A Job object representing the newly created job with all available sub-devices allocated.

Safety

Caller must ensure that the context is valid and that the job is properly managed.

Example

let mut context = Context::new(0);
let job = context.create_job(); // Create a job using all available sub-devices
// Use the job for execution...
context.destroy_job(job); // Clean up when done

pub fn create_job_with_sub(&mut self, num_sub: u32) -> Job

Creates a new job in the context with the specified number of sub-devices.

Arguments

• num_sub - The number of sub-devices to allocate for the job.

Returns

A Job object representing the newly created job.

Safety

Caller must ensure that the context is valid and that the job is properly managed.

Example

let context = Context::new(0);
let job = context.create_job_with_sub(2); // Create a job with 2 sub-devices

pub fn destroy_job(&mut self, job: Job)

Destroys Job object.

Arguments

• job - The Job object to destroy.

Safety

Caller must ensure that the job is valid and that the job is properly destroyed.

Example

let context = Context::new(0);
let job = context.create_job_with_sub(2); // Create a job with 2 `Sub`
context.destroy_job(&job); // Destroy the job

pub fn mem_alloc(&mut self, size: usize) -> *mut c_void

Retrieves the total size of device memory available in the context. Allocates memory of the specified size in the context.

Arguments

• size - The size of the memory to allocate, in bytes.

Returns

A raw pointer to the allocated memory.

Safety

Caller must ensure that the context is valid and that the memory is properly managed.

Example

let context = Context::new(0);
let memory = context.mem_alloc(1024); // Allocate 1024 bytes

pub fn mem_calloc(&mut self, num: usize, size: usize) -> *mut c_void

Allocates zero-initialized memory on the device.

This function allocates an array of num elements, each of size size, and initializes all bytes in the allocated storage to zero.

Arguments

• num - The number of elements to allocate.
• size - The size of each element.

Returns

A raw pointer to the allocated and zero-initialized memory.

Safety

Caller must ensure that the context is valid and that the memory is properly managed.

Example

let mut context = Context::new(0);
let memory = context.mem_calloc(10, 4); // Allocate 10 elements of 4 bytes each

pub fn io_mem_alloc(&mut self, size: usize) -> *mut c_void

Allocates .io memory on the device.

Arguments

• size - The size of the memory to allocate, in bytes.

Returns

A raw pointer to the allocated .io memory.

Safety

Caller must ensure that the context is valid and that the memory is properly managed.

Example

let mut context = Context::new(0);
let io_memory = context.io_mem_alloc(1024); // Allocate 1024 bytes of .io memory

pub fn mem_free(&mut self, ptr: *const c_void)

Frees memory previously allocated by mem_alloc.

Arguments

• ptr - The pointer to the memory to free.

Safety

Caller must ensure that the pointer is valid and that the memory is properly freed.

Example

let context = Context::new(0);
let memory = context.mem_alloc(1024); // Allocate 1024 bytes
context.mem_free(memory); // Free the memory

pub fn copy_to_device( &mut self, device_ptr: *const c_void, host_ptr: *const c_void, size: usize, ) -> PxlResult

Copies data from the host memory to the device memory region.

Arguments

• device_ptr - A pointer to the destination on the device.
• host_ptr - A pointer to the source memory on the host.
• size - The size of the data to be copied.

Returns

PxlResult indicating the success or failure of the operation.

Safety

Caller must ensure that the pointers are valid and that the memory regions are accessible.

Example

let mut context = Context::new(0);
let size = 1024;
let host_data = vec![0u8; size];
let device_ptr = context.mem_alloc(size);

let result = context.copy_to_device(device_ptr, host_data.as_ptr() as *const c_void, size);
// Handle result...

pub fn copy_from_device( &mut self, host_ptr: *const c_void, device_ptr: *const c_void, size: usize, ) -> PxlResult

Copies data from the device to the host.

Arguments

• host_ptr - A pointer to the destination memory on the host.
• device_ptr - A pointer to the source memory on the device memory region.
• size - The size of the data to be copied.

Returns

PxlResult indicating the success or failure of the operation.

Safety

Caller must ensure that the pointers are valid and that the memory regions are accessible.

Example

let mut context = Context::new(0);
let size = 1024;
let mut host_data = vec![0u8; size];
let device_ptr = context.mem_alloc(size);

let result = context.copy_from_device(host_data.as_mut_ptr() as *const c_void, device_ptr, size);
// Handle result...

pub fn sync_to_device( &mut self, device_ptr: *const c_void, size: usize, ) -> PxlResult

Syncs data from the host memory which mapped with device .io memory region to the device.

Arguments

• device_ptr - A pointer to the device .io memory region.
• size - The size of the data to be synced.

Returns

PxlResult indicating the success or failure of the operation.

Safety

Caller must ensure that the pointer is valid and points to .io memory.

Example

let mut context = Context::new(0);
let size = 1024;
let io_ptr = context.io_mem_alloc(size);

// Modify data through mapped memory...

let result = context.sync_to_device(io_ptr, size);
// Handle result...

pub fn sync_from_device( &mut self, device_ptr: *const c_void, size: usize, ) -> PxlResult

Syncs data from the device to the host memory which mapped with device .io memory region.

Arguments

• device_ptr - A pointer to the device .io memory region.
• size - The size of the data to be synced.

Returns

PxlResult indicating the success or failure of the operation.

Safety

Caller must ensure that the pointer is valid and points to .io memory.

Example

let mut context = Context::new(0);
let size = 1024;
let io_ptr = context.io_mem_alloc(size);

let result = context.sync_from_device(io_ptr, size);
// Access data through mapped memory...

pub fn device_id(&self) -> u32

Retrieves the device ID associated with this context.

Returns

Device ID as a u32.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);
let device_id = context.device_id();
println!("Device ID: {}", device_id);

pub fn stream(&self) -> *mut Stream

Returns the default stream associated with the context.

Returns

Pointer to the default stream.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);
let stream = context.stream();
if !stream.is_null() {
    // Use the stream...
}

pub fn available_sub_count(&self) -> u32

Returns the available number of Sub.

Returns

Available number of Sub.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);
let available_sub = context.available_sub_count();
println!("Available sub-devices: {}", available_sub);

pub fn available_mem_size(&self) -> u64

Retrieves the available size of device memory available in the context.

Returns

The available size of device memory available in the context.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);
let available_memory_size = context.available_mem_size();
println!("Available device memory size: {}", available_memory_size);

pub fn available_io_mem_size(&self) -> u64

Retrieves the available size of .io memory available in the context.

Returns

The available size of .io memory available in the context.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);
let available_io_memory_size = context.available_io_mem_size();
println!("Available .io memory size: {}", available_io_memory_size);

pub fn get_attribute(&self, attr: DeviceAttr, value: &mut u64) -> PxlResult

Retrieves a device attribute value using the unified getAttribute interface.

Arguments

• attr - The device attribute to query.
• value - Mutable reference to store the attribute value.

Returns

PxlResult indicating the success or failure of the operation.

Safety

Caller must ensure that the context is valid.

Example

let context = Context::new(0);

// Query total sub-devices
let mut count: u64 = 0;
match context.get_attribute(DeviceAttr::TotalSubCount, &mut count) {
    PxlResult::Success => println!("Total sub-devices: {}", count),
    err => println!("Error: {:?}", err),
}

// Query CXL enabled status
let mut enabled: u64 = 0;
match context.get_attribute(DeviceAttr::CxlEnabled, &mut enabled) {
    PxlResult::Success => println!("CXL enabled: {}", enabled != 0),
    err => println!("Error: {:?}", err),
}

// Query memory capacity
let mut capacity: u64 = 0;
match context.get_attribute(DeviceAttr::CxlMemoryCapacity, &mut capacity) {
    PxlResult::Success => println!("CXL memory capacity: {} bytes", capacity),
    err => println!("Error: {:?}", err),
}

pub fn get_mem_info(&mut self, host_ptr: *const c_void) -> MemInfo_t

Returns memory information of the given pointer.

Arguments

• host_ptr - Pointer to the memory.

Returns

Memory information of the given pointer (type, size).

Safety

Caller must ensure that the pointer is valid.

Example

let mut context = Context::new(0);
let ptr = context.mem_alloc(1024);
let mem_info = context.get_mem_info(ptr);
// Check mem_info.r#type and mem_info.size...