linux/greybus/operation.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Greybus operations
0004  *
0005  * Copyright 2014 Google Inc.
0006  * Copyright 2014 Linaro Ltd.
0007  */
0008
0009 #ifndef __OPERATION_H
0010 #define __OPERATION_H
0011
0012 #include <linux/completion.h>
0013 #include <linux/kref.h>
0014 #include <linux/timer.h>
0015 #include <linux/types.h>
0016 #include <linux/workqueue.h>
0017
0018 struct gb_host_device;
0019 struct gb_operation;
0020
0021 /* The default amount of time a request is given to complete */
0022 #define GB_OPERATION_TIMEOUT_DEFAULT    1000    /* milliseconds */
0023
0024 /*
0025  * The top bit of the type in an operation message header indicates
0026  * whether the message is a request (bit clear) or response (bit set)
0027  */
0028 #define GB_MESSAGE_TYPE_RESPONSE    ((u8)0x80)
0029
0030 enum gb_operation_result {
0031     GB_OP_SUCCESS       = 0x00,
0032     GB_OP_INTERRUPTED   = 0x01,
0033     GB_OP_TIMEOUT       = 0x02,
0034     GB_OP_NO_MEMORY     = 0x03,
0035     GB_OP_PROTOCOL_BAD  = 0x04,
0036     GB_OP_OVERFLOW      = 0x05,
0037     GB_OP_INVALID       = 0x06,
0038     GB_OP_RETRY     = 0x07,
0039     GB_OP_NONEXISTENT   = 0x08,
0040     GB_OP_UNKNOWN_ERROR = 0xfe,
0041     GB_OP_MALFUNCTION   = 0xff,
0042 };
0043
0044 #define GB_OPERATION_MESSAGE_SIZE_MIN   sizeof(struct gb_operation_msg_hdr)
0045 #define GB_OPERATION_MESSAGE_SIZE_MAX   U16_MAX
0046
0047 /*
0048  * Protocol code should only examine the payload and payload_size fields, and
0049  * host-controller drivers may use the hcpriv field. All other fields are
0050  * intended to be private to the operations core code.
0051  */
0052 struct gb_message {
0053     struct gb_operation     *operation;
0054     struct gb_operation_msg_hdr *header;
0055
0056     void                *payload;
0057     size_t              payload_size;
0058
0059     void                *buffer;
0060
0061     void                *hcpriv;
0062 };
0063
0064 #define GB_OPERATION_FLAG_INCOMING      BIT(0)
0065 #define GB_OPERATION_FLAG_UNIDIRECTIONAL    BIT(1)
0066 #define GB_OPERATION_FLAG_SHORT_RESPONSE    BIT(2)
0067 #define GB_OPERATION_FLAG_CORE          BIT(3)
0068
0069 #define GB_OPERATION_FLAG_USER_MASK (GB_OPERATION_FLAG_SHORT_RESPONSE | \
0070                      GB_OPERATION_FLAG_UNIDIRECTIONAL)
0071
0072 /*
0073  * A Greybus operation is a remote procedure call performed over a
0074  * connection between two UniPro interfaces.
0075  *
0076  * Every operation consists of a request message sent to the other
0077  * end of the connection coupled with a reply message returned to
0078  * the sender.  Every operation has a type, whose interpretation is
0079  * dependent on the protocol associated with the connection.
0080  *
0081  * Only four things in an operation structure are intended to be
0082  * directly usable by protocol handlers:  the operation's connection
0083  * pointer; the operation type; the request message payload (and
0084  * size); and the response message payload (and size).  Note that a
0085  * message with a 0-byte payload has a null message payload pointer.
0086  *
0087  * In addition, every operation has a result, which is an errno
0088  * value.  Protocol handlers access the operation result using
0089  * gb_operation_result().
0090  */
0091 typedef void (*gb_operation_callback)(struct gb_operation *);
0092 struct gb_operation {
0093     struct gb_connection    *connection;
0094     struct gb_message   *request;
0095     struct gb_message   *response;
0096
0097     unsigned long       flags;
0098     u8          type;
0099     u16         id;
0100     int         errno;      /* Operation result */
0101
0102     struct work_struct  work;
0103     gb_operation_callback   callback;
0104     struct completion   completion;
0105     struct timer_list   timer;
0106
0107     struct kref     kref;
0108     atomic_t        waiters;
0109
0110     int         active;
0111     struct list_head    links;      /* connection->operations */
0112
0113     void            *private;
0114 };
0115
0116 static inline bool
0117 gb_operation_is_incoming(struct gb_operation *operation)
0118 {
0119     return operation->flags & GB_OPERATION_FLAG_INCOMING;
0120 }
0121
0122 static inline bool
0123 gb_operation_is_unidirectional(struct gb_operation *operation)
0124 {
0125     return operation->flags & GB_OPERATION_FLAG_UNIDIRECTIONAL;
0126 }
0127
0128 static inline bool
0129 gb_operation_short_response_allowed(struct gb_operation *operation)
0130 {
0131     return operation->flags & GB_OPERATION_FLAG_SHORT_RESPONSE;
0132 }
0133
0134 static inline bool gb_operation_is_core(struct gb_operation *operation)
0135 {
0136     return operation->flags & GB_OPERATION_FLAG_CORE;
0137 }
0138
0139 void gb_connection_recv(struct gb_connection *connection,
0140                     void *data, size_t size);
0141
0142 int gb_operation_result(struct gb_operation *operation);
0143
0144 size_t gb_operation_get_payload_size_max(struct gb_connection *connection);
0145 struct gb_operation *
0146 gb_operation_create_flags(struct gb_connection *connection,
0147                 u8 type, size_t request_size,
0148                 size_t response_size, unsigned long flags,
0149                 gfp_t gfp);
0150
0151 static inline struct gb_operation *
0152 gb_operation_create(struct gb_connection *connection,
0153                 u8 type, size_t request_size,
0154                 size_t response_size, gfp_t gfp)
0155 {
0156     return gb_operation_create_flags(connection, type, request_size,
0157                         response_size, 0, gfp);
0158 }
0159
0160 struct gb_operation *
0161 gb_operation_create_core(struct gb_connection *connection,
0162                 u8 type, size_t request_size,
0163                 size_t response_size, unsigned long flags,
0164                 gfp_t gfp);
0165
0166 void gb_operation_get(struct gb_operation *operation);
0167 void gb_operation_put(struct gb_operation *operation);
0168
0169 bool gb_operation_response_alloc(struct gb_operation *operation,
0170                     size_t response_size, gfp_t gfp);
0171
0172 int gb_operation_request_send(struct gb_operation *operation,
0173                 gb_operation_callback callback,
0174                 unsigned int timeout,
0175                 gfp_t gfp);
0176 int gb_operation_request_send_sync_timeout(struct gb_operation *operation,
0177                         unsigned int timeout);
0178 static inline int
0179 gb_operation_request_send_sync(struct gb_operation *operation)
0180 {
0181     return gb_operation_request_send_sync_timeout(operation,
0182             GB_OPERATION_TIMEOUT_DEFAULT);
0183 }
0184
0185 void gb_operation_cancel(struct gb_operation *operation, int errno);
0186 void gb_operation_cancel_incoming(struct gb_operation *operation, int errno);
0187
0188 void greybus_message_sent(struct gb_host_device *hd,
0189                 struct gb_message *message, int status);
0190
0191 int gb_operation_sync_timeout(struct gb_connection *connection, int type,
0192                 void *request, int request_size,
0193                 void *response, int response_size,
0194                 unsigned int timeout);
0195 int gb_operation_unidirectional_timeout(struct gb_connection *connection,
0196                 int type, void *request, int request_size,
0197                 unsigned int timeout);
0198
0199 static inline int gb_operation_sync(struct gb_connection *connection, int type,
0200               void *request, int request_size,
0201               void *response, int response_size)
0202 {
0203     return gb_operation_sync_timeout(connection, type,
0204             request, request_size, response, response_size,
0205             GB_OPERATION_TIMEOUT_DEFAULT);
0206 }
0207
0208 static inline int gb_operation_unidirectional(struct gb_connection *connection,
0209                 int type, void *request, int request_size)
0210 {
0211     return gb_operation_unidirectional_timeout(connection, type,
0212             request, request_size, GB_OPERATION_TIMEOUT_DEFAULT);
0213 }
0214
0215 static inline void *gb_operation_get_data(struct gb_operation *operation)
0216 {
0217     return operation->private;
0218 }
0219
0220 static inline void gb_operation_set_data(struct gb_operation *operation,
0221                      void *data)
0222 {
0223     operation->private = data;
0224 }
0225
0226 int gb_operation_init(void);
0227 void gb_operation_exit(void);
0228
0229 #endif /* !__OPERATION_H */