ljca.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * Copyright (c) 2023, Intel Corporation. All rights reserved.
  4 */
  5#ifndef _LINUX_USB_LJCA_H_
  6#define _LINUX_USB_LJCA_H_
  7
  8#include <linux/auxiliary_bus.h>
  9#include <linux/list.h>
 10#include <linux/spinlock.h>
 11#include <linux/types.h>
 12
 13#define LJCA_MAX_GPIO_NUM 64
 14
 15#define auxiliary_dev_to_ljca_client(auxiliary_dev)			\
 16		container_of(auxiliary_dev, struct ljca_client, auxdev)
 17
 18struct ljca_adapter;
 19
 20/**
 21 * typedef ljca_event_cb_t - event callback function signature
 22 *
 23 * @context: the execution context of who registered this callback
 24 * @cmd: the command from device for this event
 25 * @evt_data: the event data payload
 26 * @len: the event data payload length
 27 *
 28 * The callback function is called in interrupt context and the data payload is
 29 * only valid during the call. If the user needs later access of the data, it
 30 * must copy it.
 31 */
 32typedef void (*ljca_event_cb_t)(void *context, u8 cmd, const void *evt_data, int len);
 33
 34/**
 35 * struct ljca_client - represent a ljca client device
 36 *
 37 * @type: ljca client type
 38 * @id: ljca client id within same client type
 39 * @link: ljca client on the same ljca adapter
 40 * @auxdev: auxiliary device object
 41 * @adapter: ljca adapter the ljca client sit on
 42 * @context: the execution context of the event callback
 43 * @event_cb: ljca client driver register this callback to get
 44 *	firmware asynchronous rx buffer pending notifications
 45 * @event_cb_lock: spinlock to protect event callback
 46 */
 47struct ljca_client {
 48	u8 type;
 49	u8 id;
 50	struct list_head link;
 51	struct auxiliary_device auxdev;
 52	struct ljca_adapter *adapter;
 53
 54	void *context;
 55	ljca_event_cb_t event_cb;
 56	/* lock to protect event_cb */
 57	spinlock_t event_cb_lock;
 58};
 59
 60/**
 61 * struct ljca_gpio_info - ljca gpio client device info
 62 *
 63 * @num: ljca gpio client device pin number
 64 * @valid_pin_map: ljca gpio client device valid pin mapping
 65 */
 66struct ljca_gpio_info {
 67	unsigned int num;
 68	DECLARE_BITMAP(valid_pin_map, LJCA_MAX_GPIO_NUM);
 69};
 70
 71/**
 72 * struct ljca_i2c_info - ljca i2c client device info
 73 *
 74 * @id: ljca i2c client device identification number
 75 * @capacity: ljca i2c client device capacity
 76 * @intr_pin: ljca i2c client device interrupt pin number if exists
 77 */
 78struct ljca_i2c_info {
 79	u8 id;
 80	u8 capacity;
 81	u8 intr_pin;
 82};
 83
 84/**
 85 * struct ljca_spi_info - ljca spi client device info
 86 *
 87 * @id: ljca spi client device identification number
 88 * @capacity: ljca spi client device capacity
 89 */
 90struct ljca_spi_info {
 91	u8 id;
 92	u8 capacity;
 93};
 94
 95/**
 96 * ljca_register_event_cb - register a callback function to receive events
 97 *
 98 * @client: ljca client device
 99 * @event_cb: callback function
100 * @context: execution context of event callback
101 *
102 * Return: 0 in case of success, negative value in case of error
103 */
104int ljca_register_event_cb(struct ljca_client *client, ljca_event_cb_t event_cb, void *context);
105
106/**
107 * ljca_unregister_event_cb - unregister the callback function for an event
108 *
109 * @client: ljca client device
110 */
111void ljca_unregister_event_cb(struct ljca_client *client);
112
113/**
114 * ljca_transfer - issue a LJCA command and wait for a response
115 *
116 * @client: ljca client device
117 * @cmd: the command to be sent to the device
118 * @obuf: the buffer to be sent to the device; it can be NULL if the user
119 *	doesn't need to transmit data with this command
120 * @obuf_len: the size of the buffer to be sent to the device; it should
121 *	be 0 when obuf is NULL
122 * @ibuf: any data associated with the response will be copied here; it can be
123 *	NULL if the user doesn't need the response data
124 * @ibuf_len: must be initialized to the input buffer size
125 *
126 * Return: the actual length of response data for success, negative value for errors
127 */
128int ljca_transfer(struct ljca_client *client, u8 cmd, const u8 *obuf,
129		  u8 obuf_len, u8 *ibuf, u8 ibuf_len);
130
131/**
132 * ljca_transfer_noack - issue a LJCA command without a response
133 *
134 * @client: ljca client device
135 * @cmd: the command to be sent to the device
136 * @obuf: the buffer to be sent to the device; it can be NULL if the user
137 *	doesn't need to transmit data with this command
138 * @obuf_len: the size of the buffer to be sent to the device
139 *
140 * Return: 0 for success, negative value for errors
141 */
142int ljca_transfer_noack(struct ljca_client *client, u8 cmd, const u8 *obuf,
143			u8 obuf_len);
144
145#endif