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