Function ll_init

libs/darwin-kperf/src/sampler/ll.rs:149–215

Loads both frameworks, opens the PMC database, and force-acquires counters. # Errors Returns [`SamplerError`] if either framework fails to load, the PMC database cannot be opened, the CPU is not recognized, or counter acquisition fails.

()

/// database cannot be opened, the CPU is not recognized, or counter
/// acquisition fails.
pub(crate) fn ll_init() -> Result<Sampler, SamplerError> {
    let kperf = KPerf::new()?;
    let kperfdata = KPerfData::new()?;

    let kpc_vt = kperf.vtable();
    let kpep_vt = kperfdata.vtable();

    let mut db = ptr::null_mut();
    // SAFETY: passing null name opens the database for the current CPU.
    try_kpep(unsafe { (kpep_vt.kpep_db_create)(ptr::null(), &raw mut db) })?;
    let Some(db) = NonNull::new(db) else {
        return Err(SamplerError::UnexpectedNullPointer);
    };

    let db = DropGuard::new(db, |db| {
        // SAFETY: db was allocated by kpep_db_create above.
        unsafe { (kpep_vt.kpep_db_free)(db.as_ptr()) }
    });

    // SAFETY: db is valid, name receives a pointer into the db's internal storage.
    let name = unsafe { db.as_ref().name };

    // SAFETY: kpep_db_name returns a pointer into the db's internal storage,
    // valid for the lifetime of the db.
    let name = unsafe { CStr::from_ptr(name) };
    let name = name.to_str().map_err(|_err| SamplerError::InvalidCpuName)?;

    let cpu = Cpu::from_db_name(name).ok_or_else(|| SamplerError::UnknownCpu(name.to_owned()))?;

    // Save the previous force_all state so we can restore it on drop.
    let mut saved_force_all = 0;
    try_kpc(
        // SAFETY: reads the current force_all_ctrs sysctl value.
        unsafe { (kpc_vt.kpc_force_all_ctrs_get)(&raw mut saved_force_all) },
        |_| SamplerError::MissingPrivileges,
    )?;

    try_kpc(
        // SAFETY: acquires power counters from the OS Power Manager.
        unsafe { (kpc_vt.kpc_force_all_ctrs_set)(1) },
        SamplerError::FailedToForceAllCounters,
    )?;

    let clear_force = DropGuard::new((), |()| {
        // SAFETY: Value acquired is simply re-set
        let _result = unsafe { (kpc_vt.kpc_force_all_ctrs_set)(saved_force_all) };
    });

    // Verify that the framework's kpep_event stride matches our struct
    // definition. Apple has changed this struct size across macOS versions;
    // a mismatch means our repr(C) definition is stale and direct field
    // access would read corrupt data.
    if cfg!(any(debug_assertions, feature = "runtime-assertions")) {
        verify_event_stride(kpep_vt, db.as_ptr())?;
    }

    DropGuard::dismiss(clear_force);
    let db = DropGuard::dismiss(db);