objc2_paravirtualized_graphics/generated/

PGDevice.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;
#[cfg(feature = "objc2-metal")]
use objc2_metal::*;

use crate::*;

/// A struct for a guest physical memory range
/// Field: physicalAddress The starting physical address of the range
/// Field: physicalLength The length of the range
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgphysicalmemoryrange_s?language=objc)
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PGPhysicalMemoryRange_s {
    pub physicalAddress: u64,
    pub physicalLength: u64,
}

unsafe impl Encode for PGPhysicalMemoryRange_s {
    const ENCODING: Encoding = Encoding::Struct(
        "PGPhysicalMemoryRange_s",
        &[<u64>::ENCODING, <u64>::ENCODING],
    );
}

unsafe impl RefEncode for PGPhysicalMemoryRange_s {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// A struct for a guest physical memory range
/// Field: physicalAddress The starting physical address of the range
/// Field: physicalLength The length of the range
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgphysicalmemoryrange_t?language=objc)
pub type PGPhysicalMemoryRange_t = PGPhysicalMemoryRange_s;

/// A block that is invoked to raise an interrupt to the guest.
///
/// Parameter `vector`: The MSI vector to raise an interrupt on.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgraiseinterrupt?language=objc)
#[cfg(feature = "block2")]
pub type PGRaiseInterrupt = *mut block2::DynBlock<dyn Fn(u32)>;

/// A block that will be invoked by the device client code when a trace handler fires.  The device client code should watch the memory identified
/// by each installed trace range and notify the device when the memory has been changed.  The client is encouraged to coalesce the handling of these notifications
/// over the course of several milliseconds.  This functionality is used to provide a low overhead framebuffer implementation that is used by the device before the guest
/// OS has fully booted and entered accelerated rendering and display.
///
/// Parameter `dirty`: The range of memory that was detected to be dirtied by the guest.
///
/// The returned range may be larger than the range that was actually written, for example, if the client can only determine at page granularity the memory that was
/// affected by guest writes, then it may report a larger region.  Clients are also encouraged to coalesce writes over a period of time into a single notification of activity.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgtracerangehandler?language=objc)
#[cfg(feature = "block2")]
pub type PGTraceRangeHandler = *mut block2::DynBlock<dyn Fn(NonNull<PGPhysicalMemoryRange_t>)>;

extern_class!(
    /// [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgdevicedescriptor?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct PGDeviceDescriptor;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for PGDeviceDescriptor {}
);

impl PGDeviceDescriptor {
    extern_methods!(
        #[cfg(feature = "objc2-metal")]
        /// The metal device to use to back the PGDevice
        #[unsafe(method(device))]
        #[unsafe(method_family = none)]
        pub unsafe fn device(&self) -> Option<Retained<ProtocolObject<dyn MTLDevice>>>;

        #[cfg(feature = "objc2-metal")]
        /// Setter for [`device`][Self::device].
        #[unsafe(method(setDevice:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDevice(&self, device: Option<&ProtocolObject<dyn MTLDevice>>);

        /// The length, of the memory that backs the APPLEGPU_BAR_MMIO
        ///
        /// By default, the value of mmioLength will be the recommended default size for
        /// the MMIO memory.
        #[unsafe(method(mmioLength))]
        #[unsafe(method_family = none)]
        pub unsafe fn mmioLength(&self) -> usize;

        /// Setter for [`mmioLength`][Self::mmioLength].
        #[unsafe(method(setMmioLength:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setMmioLength(&self, mmio_length: usize);

        #[cfg(feature = "block2")]
        /// The block to invoke to raise an interrupt to the guest.  May be raised from a dispatch queue
        /// must be thread safe.
        #[unsafe(method(raiseInterrupt))]
        #[unsafe(method_family = none)]
        pub unsafe fn raiseInterrupt(&self) -> PGRaiseInterrupt;

        #[cfg(feature = "block2")]
        /// Setter for [`raiseInterrupt`][Self::raiseInterrupt].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        ///
        /// # Safety
        ///
        /// `raise_interrupt` must be a valid pointer or null.
        #[unsafe(method(setRaiseInterrupt:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setRaiseInterrupt(&self, raise_interrupt: PGRaiseInterrupt);

        /// The number of PGDisplay ports configured into the VM.
        ///
        /// By default, the value of displayPortCount will be 1.  Valid values range from 1 to the value returned by PGMaxDisplayPortCount().
        #[unsafe(method(displayPortCount))]
        #[unsafe(method_family = none)]
        pub unsafe fn displayPortCount(&self) -> u32;

        /// Setter for [`displayPortCount`][Self::displayPortCount].
        #[unsafe(method(setDisplayPortCount:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDisplayPortCount(&self, display_port_count: u32);
    );
}

/// Methods declared on superclass `NSObject`.
impl PGDeviceDescriptor {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_protocol!(
    /// The PGDevice protocol represents a paravirtualized GPU device.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgdevice?language=objc)
    pub unsafe trait PGDevice: NSObjectProtocol {
        /// Perform an MMIO read from the device.
        ///
        /// Parameter `offset`: The offset into the MMIO BAR to read from.
        ///
        /// Returns: The 32-bit value for the read.
        #[unsafe(method(mmioReadAtOffset:))]
        #[unsafe(method_family = none)]
        unsafe fn mmioReadAtOffset(&self, offset: usize) -> u32;

        /// Perform an MMIO write to the device.
        ///
        /// Parameter `offset`: The offset into the MMIO bar to write to.
        ///
        /// Parameter `value`: The 32-bit value to write to the device.
        #[unsafe(method(mmioWriteAtOffset:value:))]
        #[unsafe(method_family = none)]
        unsafe fn mmioWriteAtOffset_value(&self, offset: usize, value: u32);

        #[cfg(feature = "PGDisplay")]
        /// Create a display based on the given descriptor and uniquifying parameters.
        ///
        /// Parameter `descriptor`: Description of desired display object.
        ///
        /// Parameter `port`: Port number that display will plug into (one display per port - and it must be less than the displayPortCount that PGDevice was created with).
        ///
        /// Parameter `serialNum`: Serial Number of display (should be unique so Guest compositor can maintain persistent layout of displays on desktop across boots).
        ///
        /// New display won't hot-plug until first modeList is established.  Releasing this object emulates a hot-unplug.
        #[unsafe(method(newDisplayWithDescriptor:port:serialNum:))]
        #[unsafe(method_family = new)]
        unsafe fn newDisplayWithDescriptor_port_serialNum(
            &self,
            descriptor: &PGDisplayDescriptor,
            port: NSUInteger,
            serial_num: u32,
        ) -> Option<Retained<ProtocolObject<dyn PGDisplay>>>;

        /// Notify the device that it will suspend.  This will quiesce the device but not begin resource serialization. Upon return from this method,
        /// no new interrupts will be generated by the device.  The device will stop accepting commands from the guest.
        ///
        /// Note: Mac guests have several wall-clock time limits on command buffer completion so the guest CPUs need to be halted within a short interval
        /// after this method is called.
        #[unsafe(method(willSuspend))]
        #[unsafe(method_family = none)]
        unsafe fn willSuspend(&self);

        /// Finish the suspend.  This method may take an arbitrary amount of time as the device needs to complete any GPU work that is in flight.
        ///
        /// Returns: The suspend state data.  This data should be serialized and returned to the device on resume.  Returns nil on suspend failure.
        ///
        /// Note: It is not legal to perform any further operations on this device after finishSuspend is called, the device must be released.
        #[unsafe(method(finishSuspend))]
        // required for soundness, method has `returns_retained` attribute.
        #[unsafe(method_family = copy)]
        unsafe fn finishSuspend(&self) -> Option<Retained<NSData>>;

        /// Begin the resume.  This method will set up the device to appear in the same state as it was in before the suspend.  At this point, the guest CPUs should not
        /// yet be running and no guest memory accesses will be attempted.
        ///
        /// Parameter `suspendState`: The suspend state recorded during the finishSuspend:.
        ///
        /// Parameter `error`: An error out parameter, will be populated on resume failure.  Error will be in PGResumeErrorDomain and will have an error code from the PGResumeErrorCode enum.
        ///
        /// Returns: Returns YES on success.  On failure will return NO and populate error.
        ///
        /// Note: Suspended displays should be reattached after this method has been called, but before -[PGDevice didResume:] is invoked.
        ///
        /// Note: For resume, this method must be invoked before any calls to `-[PGDevice mmioWriteAtOffset:value:]` or `-[PGDevice mmioReadAtOffset:]` are made.
        #[unsafe(method(willResumeWithSuspendState:error:_))]
        #[unsafe(method_family = none)]
        unsafe fn willResumeWithSuspendState_error(
            &self,
            suspend_state: &NSData,
        ) -> Result<(), Retained<NSError>>;

        /// Complete the resume.  After this method is invoked, new interrupts may be generated by the device.  Guest memory must be accessible at the time this method is invoked.
        ///
        /// Note: An initial interrupt may be generated during the duration of this call.
        #[unsafe(method(didResume))]
        #[unsafe(method_family = none)]
        unsafe fn didResume(&self);

        /// Pause the device, completing all pending operations and writes to guest memory.
        ///
        /// Note: This is a lighter weight operation than suspend.  Guest CPUs should be suspended while the device is paused.
        #[unsafe(method(pause))]
        #[unsafe(method_family = none)]
        unsafe fn pause(&self);

        /// Resume the device from pause state, allowing operations to continue.
        ///
        /// Note: An initial interrupt may be generated during the duration of this call.
        #[unsafe(method(unpause))]
        #[unsafe(method_family = none)]
        unsafe fn unpause(&self);

        /// Stop the device entirely, releasing all the guest memory.
        ///
        /// Note: Guest CPUs should be suspended or stopped when this method is called.
        #[unsafe(method(stop))]
        #[unsafe(method_family = none)]
        unsafe fn stop(&self);

        /// Reset the device to a clean state.  This will block until work is quiesced.
        #[unsafe(method(reset))]
        #[unsafe(method_family = none)]
        unsafe fn reset(&self);
    }
);

/// Create a new PGDevice implementation object based on the provided descriptor.
///
/// Parameter `descriptor`: The device descriptor for the new device.
#[inline]
pub unsafe extern "C-unwind" fn PGNewDeviceWithDescriptor(
    descriptor: &PGDeviceDescriptor,
) -> Option<Retained<ProtocolObject<dyn PGDevice>>> {
    extern "C-unwind" {
        fn PGNewDeviceWithDescriptor(
            descriptor: &PGDeviceDescriptor,
        ) -> *mut ProtocolObject<dyn PGDevice>;
    }
    let ret = unsafe { PGNewDeviceWithDescriptor(descriptor) };
    unsafe { Retained::retain_autoreleased(ret) }
}

/// Create a new PGDevice implementation object based on the provided descriptor.
///
/// Parameter `descriptor`: The device descriptor for the new device.
#[inline]
pub unsafe extern "C-unwind" fn PGCreateDeviceWithDescriptor(
    descriptor: &PGDeviceDescriptor,
) -> Option<Retained<ProtocolObject<dyn PGDevice>>> {
    extern "C-unwind" {
        fn PGCreateDeviceWithDescriptor(
            descriptor: &PGDeviceDescriptor,
        ) -> *mut ProtocolObject<dyn PGDevice>;
    }
    let ret = unsafe { PGCreateDeviceWithDescriptor(descriptor) };
    unsafe { Retained::from_raw(ret) }
}

extern "C-unwind" {
    /// Returns the maximum number of PGDisplay ports that a PGDevice can be configured with.
    ///
    /// Note: See PGDeviceDescriptor's displayPortCount property.
    pub fn PGMaxDisplayPortCount() -> u32;
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgresumeerrordomain?language=objc)
    pub static PGResumeErrorDomain: &'static NSErrorDomain;
}

/// Resume error codes
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/paravirtualizedgraphics/pgresumeerrorcode?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct PGResumeErrorCode(pub NSUInteger);
impl PGResumeErrorCode {
    #[doc(alias = "PGResumeErrorCodeInternalFault")]
    pub const InternalFault: Self = Self(0);
    #[doc(alias = "PGResumeErrorCodeInvalidSuspendStateVersion")]
    pub const InvalidSuspendStateVersion: Self = Self(1);
    #[doc(alias = "PGResumeErrorCodeInvalidContent")]
    pub const InvalidContent: Self = Self(2);
    #[doc(alias = "PGResumeErrorCodeInvalidGuestVersion")]
    pub const InvalidGuestVersion: Self = Self(3);
    #[doc(alias = "PGResumeErrorCodeIncompatibleDevice")]
    pub const IncompatibleDevice: Self = Self(4);
    #[doc(alias = "PGResumeErrorCodeInvalidDisplayPortCount")]
    pub const InvalidDisplayPortCount: Self = Self(5);
}

unsafe impl Encode for PGResumeErrorCode {
    const ENCODING: Encoding = NSUInteger::ENCODING;
}

unsafe impl RefEncode for PGResumeErrorCode {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// Copy the URL of the option ROM to be used by the device.  The URL will be a local file path to a flat ROM image.  The client code should
/// pad the ROM image out to a power of 2 size with a zero-filled trailer and present the resulting bytes as read only memory to the PCI option ROM BAR for
/// the device.
///
/// Returns: The URL.
#[inline]
pub unsafe extern "C-unwind" fn PGCopyOptionROMURL() -> Retained<NSURL> {
    extern "C-unwind" {
        fn PGCopyOptionROMURL() -> *mut NSURL;
    }
    let ret = unsafe { PGCopyOptionROMURL() };
    unsafe { Retained::from_raw(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}