Line data    Source code

       1            1 : /*
       2              :  * Copyright 2024 NXP
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief SCMI protocol generic functions and structures
      10              :  */
      11              : 
      12              : #ifndef _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_PROTOCOL_H_
      13              : #define _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_PROTOCOL_H_
      14              : 
      15              : #include <zephyr/device.h>
      16              : #include <zephyr/drivers/firmware/scmi/util.h>
      17              : #include <stdint.h>
      18              : #include <errno.h>
      19              : 
      20              : /**
      21              :  * @brief Build an SCMI message header
      22              :  *
      23              :  * Builds an SCMI message header based on the
      24              :  * fields that make it up.
      25              :  *
      26              :  * @param id message ID
      27              :  * @param type message type
      28              :  * @param proto protocol ID
      29              :  * @param token message token
      30              :  */
      31            1 : #define SCMI_MESSAGE_HDR_MAKE(id, type, proto, token)   \
      32              :         (SCMI_FIELD_MAKE(id, GENMASK(7, 0), 0)     |    \
      33              :          SCMI_FIELD_MAKE(type, GENMASK(1, 0), 8)   |    \
      34              :          SCMI_FIELD_MAKE(proto, GENMASK(7, 0), 10) |    \
      35              :          SCMI_FIELD_MAKE(token, GENMASK(9, 0), 18))
      36              : 
      37              : struct scmi_channel;
      38              : 
      39              : /**
      40              :  * @brief SCMI message type
      41              :  */
      42            1 : enum scmi_message_type {
      43              :         /** command message */
      44              :         SCMI_COMMAND = 0x0,
      45              :         /** delayed reply message */
      46              :         SCMI_DELAYED_REPLY = 0x2,
      47              :         /** notification message */
      48              :         SCMI_NOTIFICATION = 0x3,
      49              : };
      50              : 
      51              : /**
      52              :  * @brief SCMI status codes
      53              :  */
      54            0 : enum scmi_status_code {
      55              :         SCMI_SUCCESS = 0,
      56              :         SCMI_NOT_SUPPORTED = -1,
      57              :         SCMI_INVALID_PARAMETERS = -2,
      58              :         SCMI_DENIED = -3,
      59              :         SCMI_NOT_FOUND = -4,
      60              :         SCMI_OUT_OF_RANGE = -5,
      61              :         SCMI_BUSY = -6,
      62              :         SCMI_COMMS_ERROR = -7,
      63              :         SCMI_GENERIC_ERROR = -8,
      64              :         SCMI_HARDWARE_ERROR = -9,
      65              :         SCMI_PROTOCOL_ERROR = -10,
      66              :         SCMI_IN_USE = -11,
      67              : };
      68              : 
      69              : /**
      70              :  * @struct scmi_protocol
      71              :  *
      72              :  * @brief SCMI protocol structure
      73              :  */
      74            1 : struct scmi_protocol {
      75              :         /** protocol ID */
      76            1 :         uint32_t id;
      77              :         /** TX channel */
      78            1 :         struct scmi_channel *tx;
      79              :         /** transport layer device */
      80            1 :         const struct device *transport;
      81              :         /** protocol private data */
      82            1 :         void *data;
      83              : };
      84              : 
      85              : /**
      86              :  * @struct scmi_message
      87              :  *
      88              :  * @brief SCMI message structure
      89              :  */
      90            1 : struct scmi_message {
      91            0 :         uint32_t hdr;
      92            0 :         uint32_t len;
      93            0 :         void *content;
      94              : };
      95              : 
      96              : /**
      97              :  * @brief Convert an SCMI status code to its Linux equivalent (if possible)
      98              :  *
      99              :  * @param scmi_status SCMI status code as shown in `enum scmi_status_code`
     100              :  *
     101              :  * @retval Linux equivalent status code
     102              :  */
     103            1 : int scmi_status_to_errno(int scmi_status);
     104              : 
     105              : /**
     106              :  * @brief Send an SCMI message and wait for its reply
     107              :  *
     108              :  * Blocking function used to send an SCMI message over
     109              :  * a given channel and wait for its reply
     110              :  *
     111              :  * @param proto pointer to SCMI protocol
     112              :  * @param msg pointer to SCMI message to send
     113              :  * @param reply pointer to SCMI message in which the reply is to be
     114              :  * written
     115              :  *
     116              :  * @retval 0 if successful
     117              :  * @retval negative errno if failure
     118              :  * @param use_polling Specifies the communication mechanism used by the scmi
     119              :  * platform to interact with agents.
     120              :  * - true: Polling mode — the platform actively checks the message status
     121              :  *   to determine if it has been processed
     122              :  * - false: Interrupt mode — the platform relies on SCMI interrupts to
     123              :  *   detect when a message has been handled.
     124              :  */
     125            1 : int scmi_send_message(struct scmi_protocol *proto,
     126              :                       struct scmi_message *msg, struct scmi_message *reply,
     127              :                       bool use_polling);
     128              : 
     129              : #endif /* _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_PROTOCOL_H_ */