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