| /* |
| * Copyright 2022 Intel Corporation |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| #ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_ |
| #define ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_ |
| |
| /** |
| * @brief I3C In-Band Interrupts |
| * @defgroup i3c_ibi I3C In-Band Interrupts |
| * @ingroup i3c_interface |
| * @{ |
| */ |
| |
| #include <zephyr/device.h> |
| #include <zephyr/kernel.h> |
| #include <zephyr/types.h> |
| #include <zephyr/sys/util.h> |
| |
| #ifndef CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE |
| #define CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE 0 |
| #endif |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| struct i3c_device_desc; |
| |
| /** |
| * @brief IBI Types. |
| */ |
| enum i3c_ibi_type { |
| /** Target interrupt */ |
| I3C_IBI_TARGET_INTR, |
| |
| /** Controller Role Request */ |
| I3C_IBI_CONTROLLER_ROLE_REQUEST, |
| |
| /** Hot Join Request */ |
| I3C_IBI_HOTJOIN, |
| |
| I3C_IBI_TYPE_MAX = I3C_IBI_HOTJOIN, |
| |
| /** |
| * Not an actual IBI type, but simply used by |
| * the IBI workq for generic callbacks. |
| */ |
| I3C_IBI_WORKQUEUE_CB, |
| }; |
| |
| /** |
| * @brief Struct for IBI request. |
| */ |
| struct i3c_ibi { |
| /** Type of IBI. */ |
| enum i3c_ibi_type ibi_type; |
| |
| /** Pointer to payload of IBI. */ |
| uint8_t *payload; |
| |
| /** Length in bytes of the IBI payload. */ |
| uint8_t payload_len; |
| }; |
| |
| /** |
| * @brief Structure of payload buffer for IBI. |
| * |
| * This is used for the IBI callback. |
| */ |
| struct i3c_ibi_payload { |
| /** |
| * Length of available data in the payload buffer. |
| */ |
| uint8_t payload_len; |
| |
| /** |
| * Pointer to byte array as payload buffer. |
| */ |
| uint8_t payload[CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE]; |
| }; |
| |
| /** |
| * @brief Node about a queued IBI. |
| */ |
| struct i3c_ibi_work { |
| /** |
| * @cond INTERNAL_HIDDEN |
| * |
| * Used for keeping track of work in a queue. |
| */ |
| sys_snode_t node; |
| /** @endcond */ |
| |
| /** |
| * k_work struct. |
| */ |
| struct k_work work; |
| |
| /** |
| * IBI type. |
| */ |
| enum i3c_ibi_type type; |
| |
| union { |
| /** |
| * Use for @see I3C_IBI_HOTJOIN. |
| */ |
| const struct device *controller; |
| |
| /** |
| * Use for @see I3C_IBI_TARGET_INTR, |
| * and @see I3C_IBI_CONTROLLER_ROLE_REQUEST. |
| */ |
| struct i3c_device_desc *target; |
| }; |
| |
| union { |
| /** |
| * IBI payload. |
| */ |
| struct i3c_ibi_payload payload; |
| |
| /** |
| * Generic workqueue callback when |
| * type is I3C_IBI_WORKQUEUE_CB. |
| */ |
| k_work_handler_t work_cb; |
| }; |
| }; |
| |
| /** |
| * @brief Function called when In-Band Interrupt received from target device. |
| * |
| * This function is invoked by the controller when the controller |
| * receives an In-Band Interrupt from the target device. |
| * |
| * A success return shall cause the controller to ACK the next byte |
| * received. An error return shall cause the controller to NACK the |
| * next byte received. |
| * |
| * @param target the device description structure associated with the |
| * device to which the operation is addressed. |
| * @param payload Payload associated with the IBI. NULL if there is |
| * no payload. |
| * |
| * @return 0 if the IBI is accepted, or a negative error code. |
| */ |
| typedef int (*i3c_target_ibi_cb_t)(struct i3c_device_desc *target, |
| struct i3c_ibi_payload *payload); |
| |
| |
| /** |
| * @brief Queue an IBI work item for future processing. |
| * |
| * This queues up an IBI work item in the IBI workqueue |
| * for future processing. |
| * |
| * Note that this will copy the @p ibi_work struct into |
| * internal structure. If there is not enough space to |
| * copy the @p ibi_work struct, this returns -ENOMEM. |
| * |
| * @param ibi_work Pointer to the IBI work item struct. |
| * |
| * @retval 0 If work item is successfully queued. |
| * @retval -ENOMEM If no more free internal node to |
| * store IBI work item. |
| * @retval Others @see k_work_submit_to_queue |
| */ |
| int i3c_ibi_work_enqueue(struct i3c_ibi_work *ibi_work); |
| |
| /** |
| * @brief Queue a target interrupt IBI for future processing. |
| * |
| * This queues up a target interrupt IBI in the IBI workqueue |
| * for future processing. |
| * |
| * @param target Pointer to target device descriptor. |
| * @param payload Pointer to IBI payload byte array. |
| * @param payload_len Length of payload byte array. |
| * |
| * @retval 0 If work item is successfully queued. |
| * @retval -ENOMEM If no more free internal node to |
| * store IBI work item. |
| * @retval Others @see k_work_submit_to_queue |
| */ |
| int i3c_ibi_work_enqueue_target_irq(struct i3c_device_desc *target, |
| uint8_t *payload, size_t payload_len); |
| |
| /** |
| * @brief Queue a hot join IBI for future processing. |
| * |
| * This queues up a hot join IBI in the IBI workqueue |
| * for future processing. |
| * |
| * @param dev Pointer to controller device driver instance. |
| * |
| * @retval 0 If work item is successfully queued. |
| * @retval -ENOMEM If no more free internal node to |
| * store IBI work item. |
| * @retval Others @see k_work_submit_to_queue |
| */ |
| int i3c_ibi_work_enqueue_hotjoin(const struct device *dev); |
| |
| /** |
| * @brief Queue a generic callback for future processing. |
| * |
| * This queues up a generic callback in the IBI workqueue |
| * for future processing. |
| * |
| * @param dev Pointer to controller device driver instance. |
| * @param work_cb Callback function. |
| * |
| * @retval 0 If work item is successfully queued. |
| * @retval -ENOMEM If no more free internal node to |
| * store IBI work item. |
| * @retval Others @see k_work_submit_to_queue |
| */ |
| int i3c_ibi_work_enqueue_cb(const struct device *dev, |
| k_work_handler_t work_cb); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| /** |
| * @} |
| */ |
| |
| #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_ */ |