Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 1 | /* |
| 2 | * Greybus operations |
| 3 | * |
| 4 | * Copyright 2014 Google Inc. |
Alex Elder | a46e967 | 2014-12-12 12:08:42 -0600 | [diff] [blame] | 5 | * Copyright 2014 Linaro Ltd. |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 6 | * |
| 7 | * Released under the GPLv2 only. |
| 8 | */ |
| 9 | |
| 10 | #ifndef __OPERATION_H |
| 11 | #define __OPERATION_H |
| 12 | |
| 13 | #include <linux/completion.h> |
| 14 | |
Alex Elder | 3c3cef4 | 2014-11-17 18:08:30 -0600 | [diff] [blame] | 15 | struct gb_operation; |
| 16 | |
Alex Elder | c939c2f | 2014-12-02 17:25:11 -0600 | [diff] [blame] | 17 | /* |
| 18 | * No protocol may define an operation that has numeric value 0x00. |
| 19 | * It is reserved as an explicitly invalid value. |
| 20 | */ |
| 21 | #define GB_OPERATION_TYPE_INVALID ((u8)0x00) |
| 22 | |
| 23 | /* |
| 24 | * The top bit of the type in an operation message header indicates |
| 25 | * whether the message is a request (bit clear) or response (bit set) |
| 26 | */ |
Alex Elder | 6d65337 | 2015-05-07 13:03:52 -0500 | [diff] [blame] | 27 | #define GB_MESSAGE_TYPE_RESPONSE ((u8)0x80) |
Alex Elder | c939c2f | 2014-12-02 17:25:11 -0600 | [diff] [blame] | 28 | |
Alex Elder | 23383de | 2014-11-21 19:29:12 -0600 | [diff] [blame] | 29 | enum gb_operation_result { |
Alex Elder | 57248fa | 2014-12-01 07:53:09 -0600 | [diff] [blame] | 30 | GB_OP_SUCCESS = 0x00, |
| 31 | GB_OP_INTERRUPTED = 0x01, |
| 32 | GB_OP_TIMEOUT = 0x02, |
| 33 | GB_OP_NO_MEMORY = 0x03, |
| 34 | GB_OP_PROTOCOL_BAD = 0x04, |
| 35 | GB_OP_OVERFLOW = 0x05, |
| 36 | GB_OP_INVALID = 0x06, |
| 37 | GB_OP_RETRY = 0x07, |
Alex Elder | aa26351 | 2014-12-10 08:43:33 -0600 | [diff] [blame] | 38 | GB_OP_NONEXISTENT = 0x08, |
Alex Elder | 57248fa | 2014-12-01 07:53:09 -0600 | [diff] [blame] | 39 | GB_OP_UNKNOWN_ERROR = 0xfe, |
| 40 | GB_OP_MALFUNCTION = 0xff, |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 41 | }; |
| 42 | |
Alex Elder | 7cfa699 | 2014-12-03 12:27:44 -0600 | [diff] [blame] | 43 | /* |
Johan Hovold | ac67acd | 2015-04-07 11:27:15 +0200 | [diff] [blame] | 44 | * All operation messages (both requests and responses) begin with |
| 45 | * a header that encodes the size of the message (header included). |
| 46 | * This header also contains a unique identifier, that associates a |
| 47 | * response message with its operation. The header contains an |
| 48 | * operation type field, whose interpretation is dependent on what |
| 49 | * type of protocol is used over the connection. The high bit |
| 50 | * (0x80) of the operation type field is used to indicate whether |
| 51 | * the message is a request (clear) or a response (set). |
| 52 | * |
| 53 | * Response messages include an additional result byte, which |
| 54 | * communicates the result of the corresponding request. A zero |
| 55 | * result value means the operation completed successfully. Any |
| 56 | * other value indicates an error; in this case, the payload of the |
| 57 | * response message (if any) is ignored. The result byte must be |
| 58 | * zero in the header for a request message. |
| 59 | * |
| 60 | * The wire format for all numeric fields in the header is little |
| 61 | * endian. Any operation-specific data begins immediately after the |
| 62 | * header, and is 64-bit aligned. |
| 63 | */ |
| 64 | struct gb_operation_msg_hdr { |
| 65 | __le16 size; /* Size in bytes of header + payload */ |
| 66 | __le16 operation_id; /* Operation unique id */ |
| 67 | __u8 type; /* E.g GB_I2C_TYPE_* or GB_GPIO_TYPE_* */ |
| 68 | __u8 result; /* Result of request (in responses only) */ |
Johan Hovold | da9dd11 | 2015-04-07 11:27:18 +0200 | [diff] [blame] | 69 | __u8 pad[2]; /* must be zero (ignore when read) */ |
Johan Hovold | ac67acd | 2015-04-07 11:27:15 +0200 | [diff] [blame] | 70 | } __aligned(sizeof(u64)); |
| 71 | |
Johan Hovold | c38cf10 | 2015-05-19 11:22:44 +0200 | [diff] [blame] | 72 | #define GB_OPERATION_MESSAGE_SIZE_MAX U16_MAX |
Johan Hovold | d933667 | 2015-05-19 11:22:43 +0200 | [diff] [blame] | 73 | |
Johan Hovold | ac67acd | 2015-04-07 11:27:15 +0200 | [diff] [blame] | 74 | /* |
Alex Elder | 7cfa699 | 2014-12-03 12:27:44 -0600 | [diff] [blame] | 75 | * Protocol code should only examine the payload and payload_size |
| 76 | * fields. All other fields are intended to be private to the |
| 77 | * operations core code. |
| 78 | */ |
Alex Elder | 3690a82 | 2014-11-17 18:08:31 -0600 | [diff] [blame] | 79 | struct gb_message { |
Alex Elder | 0a4e14a | 2014-11-20 16:09:14 -0600 | [diff] [blame] | 80 | struct gb_operation *operation; |
Alex Elder | 0a4e14a | 2014-11-20 16:09:14 -0600 | [diff] [blame] | 81 | void *cookie; |
Alex Elder | 7cfa699 | 2014-12-03 12:27:44 -0600 | [diff] [blame] | 82 | struct gb_operation_msg_hdr *header; |
| 83 | |
| 84 | void *payload; |
| 85 | size_t payload_size; |
Alex Elder | 87d208f | 2014-11-20 16:09:16 -0600 | [diff] [blame] | 86 | |
Johan Hovold | 1e5613b | 2015-04-07 11:27:17 +0200 | [diff] [blame] | 87 | void *buffer; |
Alex Elder | 3690a82 | 2014-11-17 18:08:31 -0600 | [diff] [blame] | 88 | }; |
| 89 | |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 90 | /* |
| 91 | * A Greybus operation is a remote procedure call performed over a |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 92 | * connection between two UniPro interfaces. |
| 93 | * |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 94 | * Every operation consists of a request message sent to the other |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 95 | * end of the connection coupled with a reply message returned to |
| 96 | * the sender. Every operation has a type, whose interpretation is |
| 97 | * dependent on the protocol associated with the connection. |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 98 | * |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 99 | * Only four things in an operation structure are intended to be |
| 100 | * directly usable by protocol handlers: the operation's connection |
| 101 | * pointer; the operation type; the request message payload (and |
| 102 | * size); and the response message payload (and size). Note that a |
| 103 | * message with a 0-byte payload has a null message payload pointer. |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 104 | * |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 105 | * In addition, every operation has a result, which is an errno |
| 106 | * value. Protocol handlers access the operation result using |
| 107 | * gb_operation_result(). |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 108 | */ |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 109 | typedef void (*gb_operation_callback)(struct gb_operation *); |
| 110 | struct gb_operation { |
| 111 | struct gb_connection *connection; |
Alex Elder | c08b1dd | 2014-11-20 16:09:15 -0600 | [diff] [blame] | 112 | struct gb_message *request; |
| 113 | struct gb_message *response; |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 114 | u8 type; |
Alex Elder | 22b320f | 2014-10-16 06:35:31 -0500 | [diff] [blame] | 115 | |
Alex Elder | 82b5e3f | 2014-12-03 12:27:46 -0600 | [diff] [blame] | 116 | u16 id; |
Alex Elder | 23383de | 2014-11-21 19:29:12 -0600 | [diff] [blame] | 117 | int errno; /* Operation result */ |
| 118 | |
Alex Elder | ee637a9 | 2014-11-21 19:29:13 -0600 | [diff] [blame] | 119 | struct work_struct work; |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 120 | gb_operation_callback callback; /* If asynchronous */ |
| 121 | struct completion completion; /* Used if no callback */ |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 122 | |
Alex Elder | c7d0f25 | 2014-11-17 08:08:40 -0600 | [diff] [blame] | 123 | struct kref kref; |
Alex Elder | afb2e13 | 2014-12-03 08:35:07 -0600 | [diff] [blame] | 124 | struct list_head links; /* connection->operations */ |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 125 | }; |
| 126 | |
Alex Elder | 61089e8 | 2014-11-18 13:26:50 -0600 | [diff] [blame] | 127 | void gb_connection_recv(struct gb_connection *connection, |
Alex Elder | d90c25b | 2014-10-16 06:35:33 -0500 | [diff] [blame] | 128 | void *data, size_t size); |
| 129 | |
Alex Elder | ba986b5 | 2014-11-25 11:33:13 -0600 | [diff] [blame] | 130 | int gb_operation_result(struct gb_operation *operation); |
| 131 | |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 132 | struct gb_operation *gb_operation_create(struct gb_connection *connection, |
Alex Elder | 22b320f | 2014-10-16 06:35:31 -0500 | [diff] [blame] | 133 | u8 type, size_t request_size, |
| 134 | size_t response_size); |
Alex Elder | deb4b9e | 2014-11-21 19:29:15 -0600 | [diff] [blame] | 135 | void gb_operation_get(struct gb_operation *operation); |
Alex Elder | c7d0f25 | 2014-11-17 08:08:40 -0600 | [diff] [blame] | 136 | void gb_operation_put(struct gb_operation *operation); |
| 137 | static inline void gb_operation_destroy(struct gb_operation *operation) |
| 138 | { |
| 139 | gb_operation_put(operation); |
| 140 | } |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 141 | |
Alex Elder | 82e26f7 | 2014-12-02 08:30:39 -0600 | [diff] [blame] | 142 | bool gb_operation_response_alloc(struct gb_operation *operation, |
| 143 | size_t response_size); |
| 144 | |
Alex Elder | d90c25b | 2014-10-16 06:35:33 -0500 | [diff] [blame] | 145 | int gb_operation_request_send(struct gb_operation *operation, |
| 146 | gb_operation_callback callback); |
Alex Elder | c25572c | 2014-12-03 08:35:09 -0600 | [diff] [blame] | 147 | int gb_operation_request_send_sync(struct gb_operation *operation); |
Alex Elder | d2d2c0f | 2014-12-02 08:30:36 -0600 | [diff] [blame] | 148 | int gb_operation_response_send(struct gb_operation *operation, int errno); |
Alex Elder | d90c25b | 2014-10-16 06:35:33 -0500 | [diff] [blame] | 149 | |
Alex Elder | f68c05c | 2014-11-21 19:29:17 -0600 | [diff] [blame] | 150 | void gb_operation_cancel(struct gb_operation *operation, int errno); |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 151 | |
Johan Hovold | 7cf7bca | 2015-04-07 11:27:16 +0200 | [diff] [blame] | 152 | void greybus_message_sent(struct greybus_host_device *hd, |
| 153 | struct gb_message *message, int status); |
Alex Elder | d98b52b | 2014-11-20 16:09:17 -0600 | [diff] [blame] | 154 | |
Greg Kroah-Hartman | 10aa801 | 2014-11-24 11:19:13 -0800 | [diff] [blame] | 155 | int gb_operation_sync(struct gb_connection *connection, int type, |
| 156 | void *request, int request_size, |
| 157 | void *response, int response_size); |
| 158 | |
Alex Elder | 2eb585f | 2014-10-16 06:35:34 -0500 | [diff] [blame] | 159 | int gb_operation_init(void); |
| 160 | void gb_operation_exit(void); |
| 161 | |
Alex Elder | e88afa5 | 2014-10-01 21:54:15 -0500 | [diff] [blame] | 162 | #endif /* !__OPERATION_H */ |