| 1 |
/* SPDX-License-Identifier: GPL-2.0 */ |
| 2 |
/* |
| 3 |
* System Control and Management Interface (SCMI) Message Protocol |
| 4 |
* protocols common header file containing some definitions, structures |
| 5 |
* and function prototypes used in all the different SCMI protocols. |
| 6 |
* |
| 7 |
* Copyright (C) 2022 ARM Ltd. |
| 8 |
*/ |
| 9 |
#ifndef _SCMI_PROTOCOLS_H |
| 10 |
#define _SCMI_PROTOCOLS_H |
| 11 |
|
| 12 |
#include <linux/bitfield.h> |
| 13 |
#include <linux/completion.h> |
| 14 |
#include <linux/device.h> |
| 15 |
#include <linux/errno.h> |
| 16 |
#include <linux/kernel.h> |
| 17 |
#include <linux/hashtable.h> |
| 18 |
#include <linux/list.h> |
| 19 |
#include <linux/module.h> |
| 20 |
#include <linux/refcount.h> |
| 21 |
#include <linux/scmi_protocol.h> |
| 22 |
#include <linux/spinlock.h> |
| 23 |
#include <linux/types.h> |
| 24 |
|
| 25 |
#include <linux/unaligned.h> |
| 26 |
|
| 27 |
#define PROTOCOL_REV_MINOR_MASK GENMASK(15, 0) |
| 28 |
#define PROTOCOL_REV_MAJOR_MASK GENMASK(31, 16) |
| 29 |
#define PROTOCOL_REV_MAJOR(x) ((u16)(FIELD_GET(PROTOCOL_REV_MAJOR_MASK, (x)))) |
| 30 |
#define PROTOCOL_REV_MINOR(x) ((u16)(FIELD_GET(PROTOCOL_REV_MINOR_MASK, (x)))) |
| 31 |
|
| 32 |
#define SCMI_PROTOCOL_VENDOR_BASE 0x80 |
| 33 |
|
| 34 |
#define MSG_SUPPORTS_FASTCHANNEL(x) ((x) & BIT(0)) |
| 35 |
|
| 36 |
enum scmi_common_cmd { |
| 37 |
PROTOCOL_VERSION = 0x0, |
| 38 |
PROTOCOL_ATTRIBUTES = 0x1, |
| 39 |
PROTOCOL_MESSAGE_ATTRIBUTES = 0x2, |
| 40 |
NEGOTIATE_PROTOCOL_VERSION = 0x10, |
| 41 |
}; |
| 42 |
|
| 43 |
/** |
| 44 |
* struct scmi_msg_resp_prot_version - Response for a message |
| 45 |
* |
| 46 |
* @minor_version: Minor version of the ABI that firmware supports |
| 47 |
* @major_version: Major version of the ABI that firmware supports |
| 48 |
* |
| 49 |
* In general, ABI version changes follow the rule that minor version increments |
| 50 |
* are backward compatible. Major revision changes in ABI may not be |
| 51 |
* backward compatible. |
| 52 |
* |
| 53 |
* Response to a generic message with message type SCMI_MSG_VERSION |
| 54 |
*/ |
| 55 |
struct scmi_msg_resp_prot_version { |
| 56 |
__le16 minor_version; |
| 57 |
__le16 major_version; |
| 58 |
}; |
| 59 |
|
| 60 |
/** |
| 61 |
* struct scmi_msg - Message(Tx/Rx) structure |
| 62 |
* |
| 63 |
* @buf: Buffer pointer |
| 64 |
* @len: Length of data in the Buffer |
| 65 |
*/ |
| 66 |
struct scmi_msg { |
| 67 |
void *buf; |
| 68 |
size_t len; |
| 69 |
}; |
| 70 |
|
| 71 |
/** |
| 72 |
* struct scmi_msg_hdr - Message(Tx/Rx) header |
| 73 |
* |
| 74 |
* @id: The identifier of the message being sent |
| 75 |
* @protocol_id: The identifier of the protocol used to send @id message |
| 76 |
* @type: The SCMI type for this message |
| 77 |
* @seq: The token to identify the message. When a message returns, the |
| 78 |
* platform returns the whole message header unmodified including the |
| 79 |
* token |
| 80 |
* @status: Status of the transfer once it's complete |
| 81 |
* @poll_completion: Indicate if the transfer needs to be polled for |
| 82 |
* completion or interrupt mode is used |
| 83 |
*/ |
| 84 |
struct scmi_msg_hdr { |
| 85 |
u8 id; |
| 86 |
u8 protocol_id; |
| 87 |
u8 type; |
| 88 |
u16 seq; |
| 89 |
u32 status; |
| 90 |
bool poll_completion; |
| 91 |
}; |
| 92 |
|
| 93 |
/** |
| 94 |
* struct scmi_xfer - Structure representing a message flow |
| 95 |
* |
| 96 |
* @transfer_id: Unique ID for debug & profiling purpose |
| 97 |
* @hdr: Transmit message header |
| 98 |
* @tx: Transmit message |
| 99 |
* @rx: Receive message, the buffer should be pre-allocated to store |
| 100 |
* message. If request-ACK protocol is used, we can reuse the same |
| 101 |
* buffer for the rx path as we use for the tx path. |
| 102 |
* @done: command message transmit completion event |
| 103 |
* @async_done: pointer to delayed response message received event completion |
| 104 |
* @pending: True for xfers added to @pending_xfers hashtable |
| 105 |
* @node: An hlist_node reference used to store this xfer, alternatively, on |
| 106 |
* the free list @free_xfers or in the @pending_xfers hashtable |
| 107 |
* @users: A refcount to track the active users for this xfer. |
| 108 |
* This is meant to protect against the possibility that, when a command |
| 109 |
* transaction times out concurrently with the reception of a valid |
| 110 |
* response message, the xfer could be finally put on the TX path, and |
| 111 |
* so vanish, while on the RX path scmi_rx_callback() is still |
| 112 |
* processing it: in such a case this refcounting will ensure that, even |
| 113 |
* though the timed-out transaction will anyway cause the command |
| 114 |
* request to be reported as failed by time-out, the underlying xfer |
| 115 |
* cannot be discarded and possibly reused until the last one user on |
| 116 |
* the RX path has released it. |
| 117 |
* @busy: An atomic flag to ensure exclusive write access to this xfer |
| 118 |
* @state: The current state of this transfer, with states transitions deemed |
| 119 |
* valid being: |
| 120 |
* - SCMI_XFER_SENT_OK -> SCMI_XFER_RESP_OK [ -> SCMI_XFER_DRESP_OK ] |
| 121 |
* - SCMI_XFER_SENT_OK -> SCMI_XFER_DRESP_OK |
| 122 |
* (Missing synchronous response is assumed OK and ignored) |
| 123 |
* @flags: Optional flags associated to this xfer. |
| 124 |
* @lock: A spinlock to protect state and busy fields. |
| 125 |
* @priv: A pointer for transport private usage. |
| 126 |
*/ |
| 127 |
struct scmi_xfer { |
| 128 |
int transfer_id; |
| 129 |
struct scmi_msg_hdr hdr; |
| 130 |
struct scmi_msg tx; |
| 131 |
struct scmi_msg rx; |
| 132 |
struct completion done; |
| 133 |
struct completion *async_done; |
| 134 |
bool pending; |
| 135 |
struct hlist_node node; |
| 136 |
refcount_t users; |
| 137 |
#define SCMI_XFER_FREE 0 |
| 138 |
#define SCMI_XFER_BUSY 1 |
| 139 |
atomic_t busy; |
| 140 |
#define SCMI_XFER_SENT_OK 0 |
| 141 |
#define SCMI_XFER_RESP_OK 1 |
| 142 |
#define SCMI_XFER_DRESP_OK 2 |
| 143 |
int state; |
| 144 |
#define SCMI_XFER_FLAG_IS_RAW BIT(0) |
| 145 |
#define SCMI_XFER_IS_RAW(x) ((x)->flags & SCMI_XFER_FLAG_IS_RAW) |
| 146 |
#define SCMI_XFER_FLAG_CHAN_SET BIT(1) |
| 147 |
#define SCMI_XFER_IS_CHAN_SET(x) \ |
| 148 |
((x)->flags & SCMI_XFER_FLAG_CHAN_SET) |
| 149 |
int flags; |
| 150 |
/* A lock to protect state and busy fields */ |
| 151 |
spinlock_t lock; |
| 152 |
void *priv; |
| 153 |
}; |
| 154 |
|
| 155 |
struct scmi_xfer_ops; |
| 156 |
struct scmi_proto_helpers_ops; |
| 157 |
|
| 158 |
/** |
| 159 |
* struct scmi_protocol_handle - Reference to an initialized protocol instance |
| 160 |
* |
| 161 |
* @dev: A reference to the associated SCMI instance device (handle->dev). |
| 162 |
* @version: The protocol version currently effectively in use by this |
| 163 |
* initialized instance of the protocol as determined at the end of |
| 164 |
* any possibly needed negotiations performed by the core. |
| 165 |
* @xops: A reference to a struct holding refs to the core xfer operations that |
| 166 |
* can be used by the protocol implementation to generate SCMI messages. |
| 167 |
* @set_priv: A method to set protocol private data for this instance. |
| 168 |
* @get_priv: A method to get protocol private data previously set. |
| 169 |
* |
| 170 |
* This structure represents a protocol initialized against specific SCMI |
| 171 |
* instance and it will be used as follows: |
| 172 |
* - as a parameter fed from the core to the protocol initialization code so |
| 173 |
* that it can access the core xfer operations to build and generate SCMI |
| 174 |
* messages exclusively for the specific underlying protocol instance. |
| 175 |
* - as an opaque handle fed by an SCMI driver user when it tries to access |
| 176 |
* this protocol through its own protocol operations. |
| 177 |
* In this case this handle will be returned as an opaque object together |
| 178 |
* with the related protocol operations when the SCMI driver tries to access |
| 179 |
* the protocol. |
| 180 |
*/ |
| 181 |
struct scmi_protocol_handle { |
| 182 |
struct device *dev; |
| 183 |
unsigned int version; |
| 184 |
const struct scmi_xfer_ops *xops; |
| 185 |
const struct scmi_proto_helpers_ops *hops; |
| 186 |
int (*set_priv)(const struct scmi_protocol_handle *ph, void *priv); |
| 187 |
void *(*get_priv)(const struct scmi_protocol_handle *ph); |
| 188 |
}; |
| 189 |
|
| 190 |
/** |
| 191 |
* struct scmi_iterator_state - Iterator current state descriptor |
| 192 |
* @desc_index: Starting index for the current multi-part request. |
| 193 |
* @num_returned: Number of returned items in the last multi-part reply. |
| 194 |
* @num_remaining: Number of remaining items in the multi-part message. |
| 195 |
* @max_resources: Maximum acceptable number of items, configured by the caller |
| 196 |
* depending on the underlying resources that it is querying. |
| 197 |
* @loop_idx: The iterator loop index in the current multi-part reply. |
| 198 |
* @rx_len: Size in bytes of the currently processed message; it can be used by |
| 199 |
* the user of the iterator to verify a reply size. |
| 200 |
* @priv: Optional pointer to some additional state-related private data setup |
| 201 |
* by the caller during the iterations. |
| 202 |
*/ |
| 203 |
struct scmi_iterator_state { |
| 204 |
unsigned int desc_index; |
| 205 |
unsigned int num_returned; |
| 206 |
unsigned int num_remaining; |
| 207 |
unsigned int max_resources; |
| 208 |
unsigned int loop_idx; |
| 209 |
size_t rx_len; |
| 210 |
void *priv; |
| 211 |
}; |
| 212 |
|
| 213 |
/** |
| 214 |
* struct scmi_iterator_ops - Custom iterator operations |
| 215 |
* @prepare_message: An operation to provide the custom logic to fill in the |
| 216 |
* SCMI command request pointed by @message. @desc_index is |
| 217 |
* a reference to the next index to use in the multi-part |
| 218 |
* request. |
| 219 |
* @update_state: An operation to provide the custom logic to update the |
| 220 |
* iterator state from the actual message response. |
| 221 |
* @process_response: An operation to provide the custom logic needed to process |
| 222 |
* each chunk of the multi-part message. |
| 223 |
*/ |
| 224 |
struct scmi_iterator_ops { |
| 225 |
void (*prepare_message)(void *message, unsigned int desc_index, |
| 226 |
const void *priv); |
| 227 |
int (*update_state)(struct scmi_iterator_state *st, |
| 228 |
const void *response, void *priv); |
| 229 |
int (*process_response)(const struct scmi_protocol_handle *ph, |
| 230 |
const void *response, |
| 231 |
struct scmi_iterator_state *st, void *priv); |
| 232 |
}; |
| 233 |
|
| 234 |
struct scmi_fc_db_info { |
| 235 |
int width; |
| 236 |
u64 set; |
| 237 |
u64 mask; |
| 238 |
void __iomem *addr; |
| 239 |
}; |
| 240 |
|
| 241 |
struct scmi_fc_info { |
| 242 |
void __iomem *set_addr; |
| 243 |
void __iomem *get_addr; |
| 244 |
struct scmi_fc_db_info *set_db; |
| 245 |
u32 rate_limit; |
| 246 |
}; |
| 247 |
|
| 248 |
/** |
| 249 |
* struct scmi_proto_helpers_ops - References to common protocol helpers |
| 250 |
* @extended_name_get: A common helper function to retrieve extended naming |
| 251 |
* for the specified resource using the specified command. |
| 252 |
* Result is returned as a NULL terminated string in the |
| 253 |
* pre-allocated area pointed to by @name with maximum |
| 254 |
* capacity of @len bytes. |
| 255 |
* @iter_response_init: A common helper to initialize a generic iterator to |
| 256 |
* parse multi-message responses: when run the iterator |
| 257 |
* will take care to send the initial command request as |
| 258 |
* specified by @msg_id and @tx_size and then to parse the |
| 259 |
* multi-part responses using the custom operations |
| 260 |
* provided in @ops. |
| 261 |
* @iter_response_run: A common helper to trigger the run of a previously |
| 262 |
* initialized iterator. |
| 263 |
* @protocol_msg_check: A common helper to check is a specific protocol message |
| 264 |
* is supported. |
| 265 |
* @fastchannel_init: A common helper used to initialize FC descriptors by |
| 266 |
* gathering FC descriptions from the SCMI platform server. |
| 267 |
* @fastchannel_db_ring: A common helper to ring a FC doorbell. |
| 268 |
* @get_max_msg_size: A common helper to get the maximum message size. |
| 269 |
*/ |
| 270 |
struct scmi_proto_helpers_ops { |
| 271 |
int (*extended_name_get)(const struct scmi_protocol_handle *ph, |
| 272 |
u8 cmd_id, u32 res_id, u32 *flags, char *name, |
| 273 |
size_t len); |
| 274 |
void *(*iter_response_init)(const struct scmi_protocol_handle *ph, |
| 275 |
struct scmi_iterator_ops *ops, |
| 276 |
unsigned int max_resources, u8 msg_id, |
| 277 |
size_t tx_size, void *priv); |
| 278 |
int (*iter_response_run)(void *iter); |
| 279 |
int (*protocol_msg_check)(const struct scmi_protocol_handle *ph, |
| 280 |
u32 message_id, u32 *attributes); |
| 281 |
void (*fastchannel_init)(const struct scmi_protocol_handle *ph, |
| 282 |
u8 describe_id, u32 message_id, |
| 283 |
u32 valid_size, u32 domain, |
| 284 |
void __iomem **p_addr, |
| 285 |
struct scmi_fc_db_info **p_db, |
| 286 |
u32 *rate_limit); |
| 287 |
void (*fastchannel_db_ring)(struct scmi_fc_db_info *db); |
| 288 |
int (*get_max_msg_size)(const struct scmi_protocol_handle *ph); |
| 289 |
}; |
| 290 |
|
| 291 |
/** |
| 292 |
* struct scmi_xfer_ops - References to the core SCMI xfer operations. |
| 293 |
* @xfer_get_init: Initialize one struct xfer if any xfer slot is free. |
| 294 |
* @reset_rx_to_maxsz: Reset rx size to max transport size. |
| 295 |
* @do_xfer: Do the SCMI transfer. |
| 296 |
* @do_xfer_with_response: Do the SCMI transfer waiting for a response. |
| 297 |
* @xfer_put: Free the xfer slot. |
| 298 |
* |
| 299 |
* Note that all this operations expect a protocol handle as first parameter; |
| 300 |
* they then internally use it to infer the underlying protocol number: this |
| 301 |
* way is not possible for a protocol implementation to forge messages for |
| 302 |
* another protocol. |
| 303 |
*/ |
| 304 |
struct scmi_xfer_ops { |
| 305 |
int (*xfer_get_init)(const struct scmi_protocol_handle *ph, u8 msg_id, |
| 306 |
size_t tx_size, size_t rx_size, |
| 307 |
struct scmi_xfer **p); |
| 308 |
void (*reset_rx_to_maxsz)(const struct scmi_protocol_handle *ph, |
| 309 |
struct scmi_xfer *xfer); |
| 310 |
int (*do_xfer)(const struct scmi_protocol_handle *ph, |
| 311 |
struct scmi_xfer *xfer); |
| 312 |
int (*do_xfer_with_response)(const struct scmi_protocol_handle *ph, |
| 313 |
struct scmi_xfer *xfer); |
| 314 |
void (*xfer_put)(const struct scmi_protocol_handle *ph, |
| 315 |
struct scmi_xfer *xfer); |
| 316 |
}; |
| 317 |
|
| 318 |
typedef int (*scmi_prot_init_ph_fn_t)(const struct scmi_protocol_handle *); |
| 319 |
|
| 320 |
/** |
| 321 |
* struct scmi_protocol - Protocol descriptor |
| 322 |
* @id: Protocol ID. |
| 323 |
* @owner: Module reference if any. |
| 324 |
* @instance_init: Mandatory protocol initialization function. |
| 325 |
* @instance_deinit: Optional protocol de-initialization function. |
| 326 |
* @ops: Optional reference to the operations provided by the protocol and |
| 327 |
* exposed in scmi_protocol.h. |
| 328 |
* @events: An optional reference to the events supported by this protocol. |
| 329 |
* @supported_version: The highest version currently supported for this |
| 330 |
* protocol by the agent. Each protocol implementation |
| 331 |
* in the agent is supposed to downgrade to match the |
| 332 |
* protocol version supported by the platform. |
| 333 |
* @vendor_id: A firmware vendor string for vendor protocols matching. |
| 334 |
* Ignored when @id identifies a standard protocol, cannot be NULL |
| 335 |
* otherwise. |
| 336 |
* @sub_vendor_id: A firmware sub_vendor string for vendor protocols matching. |
| 337 |
* Ignored if NULL or when @id identifies a standard protocol. |
| 338 |
* @impl_ver: A firmware implementation version for vendor protocols matching. |
| 339 |
* Ignored if zero or if @id identifies a standard protocol. |
| 340 |
* |
| 341 |
* Note that vendor protocols matching at load time is performed by attempting |
| 342 |
* the closest match first against the tuple (vendor, sub_vendor, impl_ver) |
| 343 |
*/ |
| 344 |
struct scmi_protocol { |
| 345 |
const u8 id; |
| 346 |
struct module *owner; |
| 347 |
const scmi_prot_init_ph_fn_t instance_init; |
| 348 |
const scmi_prot_init_ph_fn_t instance_deinit; |
| 349 |
const void *ops; |
| 350 |
const struct scmi_protocol_events *events; |
| 351 |
unsigned int supported_version; |
| 352 |
char *vendor_id; |
| 353 |
char *sub_vendor_id; |
| 354 |
u32 impl_ver; |
| 355 |
}; |
| 356 |
|
| 357 |
#define DEFINE_SCMI_PROTOCOL_REGISTER_UNREGISTER(name, proto) \ |
| 358 |
static const struct scmi_protocol *__this_proto = &(proto); \ |
| 359 |
\ |
| 360 |
int __init scmi_##name##_register(void) \ |
| 361 |
{ \ |
| 362 |
return scmi_protocol_register(__this_proto); \ |
| 363 |
} \ |
| 364 |
\ |
| 365 |
void __exit scmi_##name##_unregister(void) \ |
| 366 |
{ \ |
| 367 |
scmi_protocol_unregister(__this_proto); \ |
| 368 |
} |
| 369 |
|
| 370 |
#define DECLARE_SCMI_REGISTER_UNREGISTER(func) \ |
| 371 |
int __init scmi_##func##_register(void); \ |
| 372 |
void __exit scmi_##func##_unregister(void) |
| 373 |
DECLARE_SCMI_REGISTER_UNREGISTER(base); |
| 374 |
DECLARE_SCMI_REGISTER_UNREGISTER(clock); |
| 375 |
DECLARE_SCMI_REGISTER_UNREGISTER(perf); |
| 376 |
DECLARE_SCMI_REGISTER_UNREGISTER(pinctrl); |
| 377 |
DECLARE_SCMI_REGISTER_UNREGISTER(power); |
| 378 |
DECLARE_SCMI_REGISTER_UNREGISTER(reset); |
| 379 |
DECLARE_SCMI_REGISTER_UNREGISTER(sensors); |
| 380 |
DECLARE_SCMI_REGISTER_UNREGISTER(voltage); |
| 381 |
DECLARE_SCMI_REGISTER_UNREGISTER(system); |
| 382 |
DECLARE_SCMI_REGISTER_UNREGISTER(powercap); |
| 383 |
|
| 384 |
#endif /* _SCMI_PROTOCOLS_H */ |