1*bc55e131SKamlesh Gurudasani /* 2*bc55e131SKamlesh Gurudasani * Copyright (c) 2025-2026 Texas Instruments Incorporated - https://www.ti.com 3*bc55e131SKamlesh Gurudasani * 4*bc55e131SKamlesh Gurudasani * SPDX-License-Identifier: BSD-3-Clause 5*bc55e131SKamlesh Gurudasani */ 6*bc55e131SKamlesh Gurudasani 7*bc55e131SKamlesh Gurudasani /* 8*bc55e131SKamlesh Gurudasani * Device Preparation API 9*bc55e131SKamlesh Gurudasani * 10*bc55e131SKamlesh Gurudasani * This header provides device preparation functions for power management 11*bc55e131SKamlesh Gurudasani * requests, including validation of device access permissions, exclusive 12*bc55e131SKamlesh Gurudasani * ownership checks, and host index/device lookup resolution. 13*bc55e131SKamlesh Gurudasani */ 14*bc55e131SKamlesh Gurudasani 15*bc55e131SKamlesh Gurudasani #ifndef TI_DEVICE_PREPARE_H 16*bc55e131SKamlesh Gurudasani #define TI_DEVICE_PREPARE_H 17*bc55e131SKamlesh Gurudasani 18*bc55e131SKamlesh Gurudasani #include <stdint.h> 19*bc55e131SKamlesh Gurudasani 20*bc55e131SKamlesh Gurudasani struct ti_device; 21*bc55e131SKamlesh Gurudasani 22*bc55e131SKamlesh Gurudasani /** 23*bc55e131SKamlesh Gurudasani * ti_device_prepare_exclusive() - Prepare to operate on device with exclusive check 24*bc55e131SKamlesh Gurudasani * @host_id: The host ID making the request. 25*bc55e131SKamlesh Gurudasani * @id: The device ID to operate on. 26*bc55e131SKamlesh Gurudasani * @host_idx: Optional output for host index. If non-NULL and lookup 27*bc55e131SKamlesh Gurudasani * succeeds, filled with the host index value. 28*bc55e131SKamlesh Gurudasani * @device_ptr: Optional output for device pointer. If non-NULL and 29*bc55e131SKamlesh Gurudasani * lookup succeeds, filled with the device pointer. 30*bc55e131SKamlesh Gurudasani * 31*bc55e131SKamlesh Gurudasani * This function takes the steps necessary for the PM subsystem to prepare 32*bc55e131SKamlesh Gurudasani * to operate on a device when receiving a power management request. It 33*bc55e131SKamlesh Gurudasani * ensures that if the device is marked exclusive, we are the owner. This 34*bc55e131SKamlesh Gurudasani * version should be used if device properties will be modified. 35*bc55e131SKamlesh Gurudasani * 36*bc55e131SKamlesh Gurudasani * Appropriate trace messages are produced if errors are encountered. 37*bc55e131SKamlesh Gurudasani * 38*bc55e131SKamlesh Gurudasani * Return: 0 if all checks succeeded, less than zero otherwise. 39*bc55e131SKamlesh Gurudasani */ 40*bc55e131SKamlesh Gurudasani int32_t ti_device_prepare_exclusive(uint8_t host_id, uint32_t id, uint8_t *host_idx, 41*bc55e131SKamlesh Gurudasani struct ti_device **device_ptr); 42*bc55e131SKamlesh Gurudasani 43*bc55e131SKamlesh Gurudasani /** 44*bc55e131SKamlesh Gurudasani * ti_device_prepare_nonexclusive() - Prepare to operate on device with non-exclusive check 45*bc55e131SKamlesh Gurudasani * @host_id: The host ID making the request. 46*bc55e131SKamlesh Gurudasani * @id: The device ID to operate on. 47*bc55e131SKamlesh Gurudasani * @host_idx: Optional output for host index. If non-NULL and lookup 48*bc55e131SKamlesh Gurudasani * succeeds, filled with the host index value. 49*bc55e131SKamlesh Gurudasani * @device_ptr: Optional output for device pointer. If non-NULL and 50*bc55e131SKamlesh Gurudasani * lookup succeeds, filled with the device pointer. 51*bc55e131SKamlesh Gurudasani * 52*bc55e131SKamlesh Gurudasani * This function takes the steps necessary for the PM subsystem to prepare 53*bc55e131SKamlesh Gurudasani * to operate on a device when receiving a power management request. No 54*bc55e131SKamlesh Gurudasani * check is made in regard to the exclusive state of the device. This 55*bc55e131SKamlesh Gurudasani * version should only be used if the device properties will not be 56*bc55e131SKamlesh Gurudasani * modified. 57*bc55e131SKamlesh Gurudasani * 58*bc55e131SKamlesh Gurudasani * Appropriate trace messages are produced if errors are encountered. 59*bc55e131SKamlesh Gurudasani * 60*bc55e131SKamlesh Gurudasani * Return: 0 if all checks succeeded, less than zero otherwise. 61*bc55e131SKamlesh Gurudasani */ 62*bc55e131SKamlesh Gurudasani int32_t ti_device_prepare_nonexclusive(uint8_t host_id, uint32_t id, 63*bc55e131SKamlesh Gurudasani uint8_t *host_idx, 64*bc55e131SKamlesh Gurudasani struct ti_device **device_ptr); 65*bc55e131SKamlesh Gurudasani 66*bc55e131SKamlesh Gurudasani #endif /* TI_DEVICE_PREPARE_H */ 67