drivers/staging/greybus/operation.h

   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
  14 struct 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
  25 enum 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  */
  47 struct 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  */
  86 typedef void (*gb_operation_callback)(struct gb_operation *);
  87 struct 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
 111 static inline bool
 112 gb_operation_is_incoming(struct gb_operation *operation)
 113 {
 114         return operation->flags & GB_OPERATION_FLAG_INCOMING;
 115 }
 116
 117 static inline bool
 118 gb_operation_is_unidirectional(struct gb_operation *operation)
 119 {
 120         return operation->flags & GB_OPERATION_FLAG_UNIDIRECTIONAL;
 121 }
 122
 123 static inline bool
 124 gb_operation_short_response_allowed(struct gb_operation *operation)
 125 {
 126         return operation->flags & GB_OPERATION_FLAG_SHORT_RESPONSE;
 127 }
 128
 129 static inline bool gb_operation_is_core(struct gb_operation *operation)
 130 {
 131         return operation->flags & GB_OPERATION_FLAG_CORE;
 132 }
 133
 134 void gb_connection_recv(struct gb_connection *connection,
 135                                         void *data, size_t size);
 136
 137 int gb_operation_result(struct gb_operation *operation);
 138
 139 size_t gb_operation_get_payload_size_max(struct gb_connection *connection);
 140 struct gb_operation *
 141 gb_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
 146 static inline struct gb_operation *
 147 gb_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
 155 struct gb_operation *
 156 gb_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
 161 void gb_operation_get(struct gb_operation *operation);
 162 void gb_operation_put(struct gb_operation *operation);
 163
 164 bool gb_operation_response_alloc(struct gb_operation *operation,
 165                                         size_t response_size, gfp_t gfp);
 166
 167 int gb_operation_request_send(struct gb_operation *operation,
 168                                 gb_operation_callback callback,
 169                                 unsigned int timeout,
 170                                 gfp_t gfp);
 171 int gb_operation_request_send_sync_timeout(struct gb_operation *operation,
 172                                                 unsigned int timeout);
 173 static inline int
 174 gb_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
 180 void gb_operation_cancel(struct gb_operation *operation, int errno);
 181 void gb_operation_cancel_incoming(struct gb_operation *operation, int errno);
 182
 183 void greybus_message_sent(struct gb_host_device *hd,
 184                                 struct gb_message *message, int status);
 185
 186 int 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);
 190 int gb_operation_unidirectional_timeout(struct gb_connection *connection,
 191                                 int type, void *request, int request_size,
 192                                 unsigned int timeout);
 193
 194 static 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
 203 static 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
 210 static inline void *gb_operation_get_data(struct gb_operation *operation)
 211 {
 212         return operation->private;
 213 }
 214
 215 static inline void gb_operation_set_data(struct gb_operation *operation,
 216                                          void *data)
 217 {
 218         operation->private = data;
 219 }
 220
 221 int gb_operation_init(void);
 222 void gb_operation_exit(void);
 223
 224 #endif /* !__OPERATION_H */