firmware/arm_scmi/common.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * System Control and Management Interface (SCMI) Message Protocol
0004  * driver common header file containing some definitions, structures
0005  * and function prototypes used in all the different SCMI protocols.
0006  *
0007  * Copyright (C) 2018-2022 ARM Ltd.
0008  */
0009 #ifndef _SCMI_COMMON_H
0010 #define _SCMI_COMMON_H
0011
0012 #include <linux/bitfield.h>
0013 #include <linux/completion.h>
0014 #include <linux/device.h>
0015 #include <linux/errno.h>
0016 #include <linux/kernel.h>
0017 #include <linux/hashtable.h>
0018 #include <linux/list.h>
0019 #include <linux/module.h>
0020 #include <linux/refcount.h>
0021 #include <linux/scmi_protocol.h>
0022 #include <linux/spinlock.h>
0023 #include <linux/types.h>
0024
0025 #include <asm/unaligned.h>
0026
0027 #include "protocols.h"
0028 #include "notify.h"
0029
0030 #define MSG_ID_MASK     GENMASK(7, 0)
0031 #define MSG_XTRACT_ID(hdr)  FIELD_GET(MSG_ID_MASK, (hdr))
0032 #define MSG_TYPE_MASK       GENMASK(9, 8)
0033 #define MSG_XTRACT_TYPE(hdr)    FIELD_GET(MSG_TYPE_MASK, (hdr))
0034 #define MSG_TYPE_COMMAND    0
0035 #define MSG_TYPE_DELAYED_RESP   2
0036 #define MSG_TYPE_NOTIFICATION   3
0037 #define MSG_PROTOCOL_ID_MASK    GENMASK(17, 10)
0038 #define MSG_XTRACT_PROT_ID(hdr) FIELD_GET(MSG_PROTOCOL_ID_MASK, (hdr))
0039 #define MSG_TOKEN_ID_MASK   GENMASK(27, 18)
0040 #define MSG_XTRACT_TOKEN(hdr)   FIELD_GET(MSG_TOKEN_ID_MASK, (hdr))
0041 #define MSG_TOKEN_MAX       (MSG_XTRACT_TOKEN(MSG_TOKEN_ID_MASK) + 1)
0042
0043 /*
0044  * Size of @pending_xfers hashtable included in @scmi_xfers_info; ideally, in
0045  * order to minimize space and collisions, this should equal max_msg, i.e. the
0046  * maximum number of in-flight messages on a specific platform, but such value
0047  * is only available at runtime while kernel hashtables are statically sized:
0048  * pick instead as a fixed static size the maximum number of entries that can
0049  * fit the whole table into one 4k page.
0050  */
0051 #define SCMI_PENDING_XFERS_HT_ORDER_SZ      9
0052
0053 /**
0054  * pack_scmi_header() - packs and returns 32-bit header
0055  *
0056  * @hdr: pointer to header containing all the information on message id,
0057  *  protocol id, sequence id and type.
0058  *
0059  * Return: 32-bit packed message header to be sent to the platform.
0060  */
0061 static inline u32 pack_scmi_header(struct scmi_msg_hdr *hdr)
0062 {
0063     return FIELD_PREP(MSG_ID_MASK, hdr->id) |
0064         FIELD_PREP(MSG_TYPE_MASK, hdr->type) |
0065         FIELD_PREP(MSG_TOKEN_ID_MASK, hdr->seq) |
0066         FIELD_PREP(MSG_PROTOCOL_ID_MASK, hdr->protocol_id);
0067 }
0068
0069 /**
0070  * unpack_scmi_header() - unpacks and records message and protocol id
0071  *
0072  * @msg_hdr: 32-bit packed message header sent from the platform
0073  * @hdr: pointer to header to fetch message and protocol id.
0074  */
0075 static inline void unpack_scmi_header(u32 msg_hdr, struct scmi_msg_hdr *hdr)
0076 {
0077     hdr->id = MSG_XTRACT_ID(msg_hdr);
0078     hdr->protocol_id = MSG_XTRACT_PROT_ID(msg_hdr);
0079     hdr->type = MSG_XTRACT_TYPE(msg_hdr);
0080 }
0081
0082 /*
0083  * An helper macro to lookup an xfer from the @pending_xfers hashtable
0084  * using the message sequence number token as a key.
0085  */
0086 #define XFER_FIND(__ht, __k)                    \
0087 ({                              \
0088     typeof(__k) k_ = __k;                   \
0089     struct scmi_xfer *xfer_ = NULL;             \
0090                                 \
0091     hash_for_each_possible((__ht), xfer_, node, k_)     \
0092         if (xfer_->hdr.seq == k_)           \
0093             break;                  \
0094     xfer_;                          \
0095 })
0096
0097 struct scmi_revision_info *
0098 scmi_revision_area_get(const struct scmi_protocol_handle *ph);
0099 int scmi_handle_put(const struct scmi_handle *handle);
0100 struct scmi_handle *scmi_handle_get(struct device *dev);
0101 void scmi_set_handle(struct scmi_device *scmi_dev);
0102 void scmi_setup_protocol_implemented(const struct scmi_protocol_handle *ph,
0103                      u8 *prot_imp);
0104
0105 int __init scmi_bus_init(void);
0106 void __exit scmi_bus_exit(void);
0107
0108 const struct scmi_protocol *scmi_protocol_get(int protocol_id);
0109 void scmi_protocol_put(int protocol_id);
0110
0111 int scmi_protocol_acquire(const struct scmi_handle *handle, u8 protocol_id);
0112 void scmi_protocol_release(const struct scmi_handle *handle, u8 protocol_id);
0113
0114 /* SCMI Transport */
0115 /**
0116  * struct scmi_chan_info - Structure representing a SCMI channel information
0117  *
0118  * @dev: Reference to device in the SCMI hierarchy corresponding to this
0119  *   channel
0120  * @handle: Pointer to SCMI entity handle
0121  * @no_completion_irq: Flag to indicate that this channel has no completion
0122  *             interrupt mechanism for synchronous commands.
0123  *             This can be dynamically set by transports at run-time
0124  *             inside their provided .chan_setup().
0125  * @transport_info: Transport layer related information
0126  */
0127 struct scmi_chan_info {
0128     struct device *dev;
0129     struct scmi_handle *handle;
0130     bool no_completion_irq;
0131     void *transport_info;
0132 };
0133
0134 /**
0135  * struct scmi_transport_ops - Structure representing a SCMI transport ops
0136  *
0137  * @link_supplier: Optional callback to add link to a supplier device
0138  * @chan_available: Callback to check if channel is available or not
0139  * @chan_setup: Callback to allocate and setup a channel
0140  * @chan_free: Callback to free a channel
0141  * @get_max_msg: Optional callback to provide max_msg dynamically
0142  *       Returns the maximum number of messages for the channel type
0143  *       (tx or rx) that can be pending simultaneously in the system
0144  * @send_message: Callback to send a message
0145  * @mark_txdone: Callback to mark tx as done
0146  * @fetch_response: Callback to fetch response
0147  * @fetch_notification: Callback to fetch notification
0148  * @clear_channel: Callback to clear a channel
0149  * @poll_done: Callback to poll transfer status
0150  */
0151 struct scmi_transport_ops {
0152     int (*link_supplier)(struct device *dev);
0153     bool (*chan_available)(struct device *dev, int idx);
0154     int (*chan_setup)(struct scmi_chan_info *cinfo, struct device *dev,
0155               bool tx);
0156     int (*chan_free)(int id, void *p, void *data);
0157     unsigned int (*get_max_msg)(struct scmi_chan_info *base_cinfo);
0158     int (*send_message)(struct scmi_chan_info *cinfo,
0159                 struct scmi_xfer *xfer);
0160     void (*mark_txdone)(struct scmi_chan_info *cinfo, int ret,
0161                 struct scmi_xfer *xfer);
0162     void (*fetch_response)(struct scmi_chan_info *cinfo,
0163                    struct scmi_xfer *xfer);
0164     void (*fetch_notification)(struct scmi_chan_info *cinfo,
0165                    size_t max_len, struct scmi_xfer *xfer);
0166     void (*clear_channel)(struct scmi_chan_info *cinfo);
0167     bool (*poll_done)(struct scmi_chan_info *cinfo, struct scmi_xfer *xfer);
0168 };
0169
0170 int scmi_protocol_device_request(const struct scmi_device_id *id_table);
0171 void scmi_protocol_device_unrequest(const struct scmi_device_id *id_table);
0172 struct scmi_device *scmi_child_dev_find(struct device *parent,
0173                     int prot_id, const char *name);
0174
0175 /**
0176  * struct scmi_desc - Description of SoC integration
0177  *
0178  * @transport_init: An optional function that a transport can provide to
0179  *          initialize some transport-specific setup during SCMI core
0180  *          initialization, so ahead of SCMI core probing.
0181  * @transport_exit: An optional function that a transport can provide to
0182  *          de-initialize some transport-specific setup during SCMI core
0183  *          de-initialization, so after SCMI core removal.
0184  * @ops: Pointer to the transport specific ops structure
0185  * @max_rx_timeout_ms: Timeout for communication with SoC (in Milliseconds)
0186  * @max_msg: Maximum number of messages for a channel type (tx or rx) that can
0187  *  be pending simultaneously in the system. May be overridden by the
0188  *  get_max_msg op.
0189  * @max_msg_size: Maximum size of data per message that can be handled.
0190  * @force_polling: Flag to force this whole transport to use SCMI core polling
0191  *         mechanism instead of completion interrupts even if available.
0192  * @sync_cmds_completed_on_ret: Flag to indicate that the transport assures
0193  *              synchronous-command messages are atomically
0194  *              completed on .send_message: no need to poll
0195  *              actively waiting for a response.
0196  *              Used by core internally only when polling is
0197  *              selected as a waiting for reply method: i.e.
0198  *              if a completion irq was found use that anyway.
0199  * @atomic_enabled: Flag to indicate that this transport, which is assured not
0200  *          to sleep anywhere on the TX path, can be used in atomic mode
0201  *          when requested.
0202  */
0203 struct scmi_desc {
0204     int (*transport_init)(void);
0205     void (*transport_exit)(void);
0206     const struct scmi_transport_ops *ops;
0207     int max_rx_timeout_ms;
0208     int max_msg;
0209     int max_msg_size;
0210     const bool force_polling;
0211     const bool sync_cmds_completed_on_ret;
0212     const bool atomic_enabled;
0213 };
0214
0215 #ifdef CONFIG_ARM_SCMI_TRANSPORT_MAILBOX
0216 extern const struct scmi_desc scmi_mailbox_desc;
0217 #endif
0218 #ifdef CONFIG_ARM_SCMI_TRANSPORT_SMC
0219 extern const struct scmi_desc scmi_smc_desc;
0220 #endif
0221 #ifdef CONFIG_ARM_SCMI_TRANSPORT_VIRTIO
0222 extern const struct scmi_desc scmi_virtio_desc;
0223 #endif
0224 #ifdef CONFIG_ARM_SCMI_TRANSPORT_OPTEE
0225 extern const struct scmi_desc scmi_optee_desc;
0226 #endif
0227
0228 void scmi_rx_callback(struct scmi_chan_info *cinfo, u32 msg_hdr, void *priv);
0229 void scmi_free_channel(struct scmi_chan_info *cinfo, struct idr *idr, int id);
0230
0231 /* shmem related declarations */
0232 struct scmi_shared_mem;
0233
0234 void shmem_tx_prepare(struct scmi_shared_mem __iomem *shmem,
0235               struct scmi_xfer *xfer);
0236 u32 shmem_read_header(struct scmi_shared_mem __iomem *shmem);
0237 void shmem_fetch_response(struct scmi_shared_mem __iomem *shmem,
0238               struct scmi_xfer *xfer);
0239 void shmem_fetch_notification(struct scmi_shared_mem __iomem *shmem,
0240                   size_t max_len, struct scmi_xfer *xfer);
0241 void shmem_clear_channel(struct scmi_shared_mem __iomem *shmem);
0242 bool shmem_poll_done(struct scmi_shared_mem __iomem *shmem,
0243              struct scmi_xfer *xfer);
0244
0245 /* declarations for message passing transports */
0246 struct scmi_msg_payld;
0247
0248 /* Maximum overhead of message w.r.t. struct scmi_desc.max_msg_size */
0249 #define SCMI_MSG_MAX_PROT_OVERHEAD (2 * sizeof(__le32))
0250
0251 size_t msg_response_size(struct scmi_xfer *xfer);
0252 size_t msg_command_size(struct scmi_xfer *xfer);
0253 void msg_tx_prepare(struct scmi_msg_payld *msg, struct scmi_xfer *xfer);
0254 u32 msg_read_header(struct scmi_msg_payld *msg);
0255 void msg_fetch_response(struct scmi_msg_payld *msg, size_t len,
0256             struct scmi_xfer *xfer);
0257 void msg_fetch_notification(struct scmi_msg_payld *msg, size_t len,
0258                 size_t max_len, struct scmi_xfer *xfer);
0259
0260 void scmi_notification_instance_data_set(const struct scmi_handle *handle,
0261                      void *priv);
0262 void *scmi_notification_instance_data_get(const struct scmi_handle *handle);
0263 #endif /* _SCMI_COMMON_H */