1// SPDX-License-Identifier: GPL-2.0
  2/*
  3 * Greybus operations
  4 *
  5 * Copyright 2014 Google Inc.
  6 * Copyright 2014 Linaro Ltd.
  7 */
  8
  9#ifndef __OPERATION_H
 10#define __OPERATION_H
 11
 12#include <linux/completion.h>
 13
 14struct gb_operation;
 15
 16/* The default amount of time a request is given to complete */
 17#define GB_OPERATION_TIMEOUT_DEFAULT	1000	/* milliseconds */
 18
 19/*
 20 * The top bit of the type in an operation message header indicates
 21 * whether the message is a request (bit clear) or response (bit set)
 22 */
 23#define GB_MESSAGE_TYPE_RESPONSE	((u8)0x80)
 24
 25enum gb_operation_result {
 26	GB_OP_SUCCESS		= 0x00,
 27	GB_OP_INTERRUPTED	= 0x01,
 28	GB_OP_TIMEOUT		= 0x02,
 29	GB_OP_NO_MEMORY		= 0x03,
 30	GB_OP_PROTOCOL_BAD	= 0x04,
 31	GB_OP_OVERFLOW		= 0x05,
 32	GB_OP_INVALID		= 0x06,
 33	GB_OP_RETRY		= 0x07,
 34	GB_OP_NONEXISTENT	= 0x08,
 35	GB_OP_UNKNOWN_ERROR	= 0xfe,
 36	GB_OP_MALFUNCTION	= 0xff,
 37};
 38
 39#define GB_OPERATION_MESSAGE_SIZE_MIN	sizeof(struct gb_operation_msg_hdr)
 40#define GB_OPERATION_MESSAGE_SIZE_MAX	U16_MAX
 41
 42/*
 43 * Protocol code should only examine the payload and payload_size fields, and
 44 * host-controller drivers may use the hcpriv field. All other fields are
 45 * intended to be private to the operations core code.
 46 */
 47struct gb_message {
 48	struct gb_operation		*operation;
 49	struct gb_operation_msg_hdr	*header;
 50
 51	void				*payload;
 52	size_t				payload_size;
 53
 54	void				*buffer;
 55
 56	void				*hcpriv;
 57};
 58
 59#define GB_OPERATION_FLAG_INCOMING		BIT(0)
 60#define GB_OPERATION_FLAG_UNIDIRECTIONAL	BIT(1)
 61#define GB_OPERATION_FLAG_SHORT_RESPONSE	BIT(2)
 62#define GB_OPERATION_FLAG_CORE			BIT(3)
 63
 64#define GB_OPERATION_FLAG_USER_MASK	(GB_OPERATION_FLAG_SHORT_RESPONSE | \
 65					 GB_OPERATION_FLAG_UNIDIRECTIONAL)
 66
 67/*
 68 * A Greybus operation is a remote procedure call performed over a
 69 * connection between two UniPro interfaces.
 70 *
 71 * Every operation consists of a request message sent to the other
 72 * end of the connection coupled with a reply message returned to
 73 * the sender.  Every operation has a type, whose interpretation is
 74 * dependent on the protocol associated with the connection.
 75 *
 76 * Only four things in an operation structure are intended to be
 77 * directly usable by protocol handlers:  the operation's connection
 78 * pointer; the operation type; the request message payload (and
 79 * size); and the response message payload (and size).  Note that a
 80 * message with a 0-byte payload has a null message payload pointer.
 81 *
 82 * In addition, every operation has a result, which is an errno
 83 * value.  Protocol handlers access the operation result using
 84 * gb_operation_result().
 85 */
 86typedef void (*gb_operation_callback)(struct gb_operation *);
 87struct gb_operation {
 88	struct gb_connection	*connection;
 89	struct gb_message	*request;
 90	struct gb_message	*response;
 91
 92	unsigned long		flags;
 93	u8			type;
 94	u16			id;
 95	int			errno;		/* Operation result */
 96
 97	struct work_struct	work;
 98	gb_operation_callback	callback;
 99	struct completion	completion;
100	struct timer_list	timer;
101
102	struct kref		kref;
103	atomic_t		waiters;
104
105	int			active;
106	struct list_head	links;		/* connection->operations */
107
108	void			*private;
109};
110
111static inline bool
112gb_operation_is_incoming(struct gb_operation *operation)
113{
114	return operation->flags & GB_OPERATION_FLAG_INCOMING;
115}
116
117static inline bool
118gb_operation_is_unidirectional(struct gb_operation *operation)
119{
120	return operation->flags & GB_OPERATION_FLAG_UNIDIRECTIONAL;
121}
122
123static inline bool
124gb_operation_short_response_allowed(struct gb_operation *operation)
125{
126	return operation->flags & GB_OPERATION_FLAG_SHORT_RESPONSE;
127}
128
129static inline bool gb_operation_is_core(struct gb_operation *operation)
130{
131	return operation->flags & GB_OPERATION_FLAG_CORE;
132}
133
134void gb_connection_recv(struct gb_connection *connection,
135					void *data, size_t size);
136
137int gb_operation_result(struct gb_operation *operation);
138
139size_t gb_operation_get_payload_size_max(struct gb_connection *connection);
140struct gb_operation *
141gb_operation_create_flags(struct gb_connection *connection,
142				u8 type, size_t request_size,
143				size_t response_size, unsigned long flags,
144				gfp_t gfp);
145
146static inline struct gb_operation *
147gb_operation_create(struct gb_connection *connection,
148				u8 type, size_t request_size,
149				size_t response_size, gfp_t gfp)
150{
151	return gb_operation_create_flags(connection, type, request_size,
152						response_size, 0, gfp);
153}
154
155struct gb_operation *
156gb_operation_create_core(struct gb_connection *connection,
157				u8 type, size_t request_size,
158				size_t response_size, unsigned long flags,
159				gfp_t gfp);
160
161void gb_operation_get(struct gb_operation *operation);
162void gb_operation_put(struct gb_operation *operation);
163
164bool gb_operation_response_alloc(struct gb_operation *operation,
165					size_t response_size, gfp_t gfp);
166
167int gb_operation_request_send(struct gb_operation *operation,
168				gb_operation_callback callback,
169				unsigned int timeout,
170				gfp_t gfp);
171int gb_operation_request_send_sync_timeout(struct gb_operation *operation,
172						unsigned int timeout);
173static inline int
174gb_operation_request_send_sync(struct gb_operation *operation)
175{
176	return gb_operation_request_send_sync_timeout(operation,
177			GB_OPERATION_TIMEOUT_DEFAULT);
178}
179
180void gb_operation_cancel(struct gb_operation *operation, int errno);
181void gb_operation_cancel_incoming(struct gb_operation *operation, int errno);
182
183void greybus_message_sent(struct gb_host_device *hd,
184				struct gb_message *message, int status);
185
186int gb_operation_sync_timeout(struct gb_connection *connection, int type,
187				void *request, int request_size,
188				void *response, int response_size,
189				unsigned int timeout);
190int gb_operation_unidirectional_timeout(struct gb_connection *connection,
191				int type, void *request, int request_size,
192				unsigned int timeout);
193
194static inline int gb_operation_sync(struct gb_connection *connection, int type,
195		      void *request, int request_size,
196		      void *response, int response_size)
197{
198	return gb_operation_sync_timeout(connection, type,
199			request, request_size, response, response_size,
200			GB_OPERATION_TIMEOUT_DEFAULT);
201}
202
203static inline int gb_operation_unidirectional(struct gb_connection *connection,
204				int type, void *request, int request_size)
205{
206	return gb_operation_unidirectional_timeout(connection, type,
207			request, request_size, GB_OPERATION_TIMEOUT_DEFAULT);
208}
209
210static inline void *gb_operation_get_data(struct gb_operation *operation)
211{
212	return operation->private;
213}
214
215static inline void gb_operation_set_data(struct gb_operation *operation,
216					 void *data)
217{
218	operation->private = data;
219}
220
221int gb_operation_init(void);
222void gb_operation_exit(void);
223
224#endif /* !__OPERATION_H */