drivers/firmware/ti_sci.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /*
   3  * Texas Instruments System Control Interface (TISCI) Protocol
   4  *
   5  * Communication protocol with TI SCI hardware
   6  * The system works in a message response protocol
   7  * See: http://processors.wiki.ti.com/index.php/TISCI for details
   8  *
   9  * Copyright (C)  2018 Texas Instruments Incorporated - http://www.ti.com/
  10  * Based on drivers/firmware/ti_sci.h from Linux.
  11  *
  12  */
  13
  14 #ifndef __TI_SCI_H
  15 #define __TI_SCI_H
  16
  17 /* Generic Messages */
  18 #define TI_SCI_MSG_ENABLE_WDT           0x0000
  19 #define TI_SCI_MSG_WAKE_RESET           0x0001
  20 #define TI_SCI_MSG_VERSION              0x0002
  21 #define TI_SCI_MSG_WAKE_REASON          0x0003
  22 #define TI_SCI_MSG_GOODBYE              0x0004
  23 #define TI_SCI_MSG_SYS_RESET            0x0005
  24 #define TI_SCI_MSG_BOARD_CONFIG         0x000b
  25 #define TI_SCI_MSG_BOARD_CONFIG_RM      0x000c
  26 #define TI_SCI_MSG_BOARD_CONFIG_SECURITY  0x000d
  27 #define TI_SCI_MSG_BOARD_CONFIG_PM      0x000e
  28
  29 /* Device requests */
  30 #define TI_SCI_MSG_SET_DEVICE_STATE     0x0200
  31 #define TI_SCI_MSG_GET_DEVICE_STATE     0x0201
  32 #define TI_SCI_MSG_SET_DEVICE_RESETS    0x0202
  33
  34 /**
  35  * struct ti_sci_msg_hdr - Generic Message Header for All messages and responses
  36  * @type:       Type of messages: One of TI_SCI_MSG* values
  37  * @host:       Host of the message
  38  * @seq:        Message identifier indicating a transfer sequence
  39  * @flags:      Flag for the message
  40  */
  41 struct ti_sci_msg_hdr {
  42         u16 type;
  43         u8 host;
  44         u8 seq;
  45 #define TI_SCI_MSG_FLAG(val)                    (1 << (val))
  46 #define TI_SCI_FLAG_REQ_GENERIC_NORESPONSE      0x0
  47 #define TI_SCI_FLAG_REQ_ACK_ON_RECEIVED         TI_SCI_MSG_FLAG(0)
  48 #define TI_SCI_FLAG_REQ_ACK_ON_PROCESSED        TI_SCI_MSG_FLAG(1)
  49 #define TI_SCI_FLAG_RESP_GENERIC_NACK           0x0
  50 #define TI_SCI_FLAG_RESP_GENERIC_ACK            TI_SCI_MSG_FLAG(1)
  51         /* Additional Flags */
  52         u32 flags;
  53 } __packed;
  54
  55 /**
  56  * struct ti_sci_secure_msg_hdr - Header that prefixes all TISCI messages sent
  57  *                                via secure transport.
  58  * @checksum:   crc16 checksum for the entire message
  59  * @reserved:   Reserved for future use.
  60  */
  61 struct ti_sci_secure_msg_hdr {
  62         u16 checksum;
  63         u16 reserved;
  64 } __packed;
  65
  66 /**
  67  * struct ti_sci_msg_resp_version - Response for a message
  68  * @hdr:                Generic header
  69  * @firmware_description: String describing the firmware
  70  * @firmware_revision:  Firmware revision
  71  * @abi_major:          Major version of the ABI that firmware supports
  72  * @abi_minor:          Minor version of the ABI that firmware supports
  73  *
  74  * In general, ABI version changes follow the rule that minor version increments
  75  * are backward compatible. Major revision changes in ABI may not be
  76  * backward compatible.
  77  *
  78  * Response to a generic message with message type TI_SCI_MSG_VERSION
  79  */
  80 struct ti_sci_msg_resp_version {
  81         struct ti_sci_msg_hdr hdr;
  82         char firmware_description[32];
  83         u16 firmware_revision;
  84         u8 abi_major;
  85         u8 abi_minor;
  86 } __packed;
  87
  88 /**
  89  * struct ti_sci_msg_board_config - Board configuration message
  90  * @hdr:                Generic Header
  91  * @boardcfgp_low:      Lower 32 bit of the pointer pointing to the board
  92  *                      configuration data
  93  * @boardcfgp_high:     Upper 32 bit of the pointer pointing to the board
  94  *                      configuration data
  95  * @boardcfg_size:      Size of board configuration data object
  96  * Request type is TI_SCI_MSG_BOARD_CONFIG, responded with a generic
  97  * ACK/NACK message.
  98  */
  99 struct ti_sci_msg_board_config {
 100         struct ti_sci_msg_hdr hdr;
 101         u32 boardcfgp_low;
 102         u32 boardcfgp_high;
 103         u16 boardcfg_size;
 104 } __packed;
 105
 106 /**
 107  * struct ti_sci_msg_req_set_device_state - Set the desired state of the device
 108  * @hdr:                Generic header
 109  * @id: Indicates which device to modify
 110  * @reserved: Reserved space in message, must be 0 for backward compatibility
 111  * @state: The desired state of the device.
 112  *
 113  * Certain flags can also be set to alter the device state:
 114  * + MSG_FLAG_DEVICE_WAKE_ENABLED - Configure the device to be a wake source.
 115  * The meaning of this flag will vary slightly from device to device and from
 116  * SoC to SoC but it generally allows the device to wake the SoC out of deep
 117  * suspend states.
 118  * + MSG_FLAG_DEVICE_RESET_ISO - Enable reset isolation for this device.
 119  * + MSG_FLAG_DEVICE_EXCLUSIVE - Claim this device exclusively. When passed
 120  * with STATE_RETENTION or STATE_ON, it will claim the device exclusively.
 121  * If another host already has this device set to STATE_RETENTION or STATE_ON,
 122  * the message will fail. Once successful, other hosts attempting to set
 123  * STATE_RETENTION or STATE_ON will fail.
 124  *
 125  * Request type is TI_SCI_MSG_SET_DEVICE_STATE, responded with a generic
 126  * ACK/NACK message.
 127  */
 128 struct ti_sci_msg_req_set_device_state {
 129         /* Additional hdr->flags options */
 130 #define MSG_FLAG_DEVICE_WAKE_ENABLED    TI_SCI_MSG_FLAG(8)
 131 #define MSG_FLAG_DEVICE_RESET_ISO       TI_SCI_MSG_FLAG(9)
 132 #define MSG_FLAG_DEVICE_EXCLUSIVE       TI_SCI_MSG_FLAG(10)
 133         struct ti_sci_msg_hdr hdr;
 134         u32 id;
 135         u32 reserved;
 136
 137 #define MSG_DEVICE_SW_STATE_AUTO_OFF    0
 138 #define MSG_DEVICE_SW_STATE_RETENTION   1
 139 #define MSG_DEVICE_SW_STATE_ON          2
 140         u8 state;
 141 } __packed;
 142
 143 /**
 144  * struct ti_sci_msg_req_get_device_state - Request to get device.
 145  * @hdr:                Generic header
 146  * @id:         Device Identifier
 147  *
 148  * Request type is TI_SCI_MSG_GET_DEVICE_STATE, responded device state
 149  * information
 150  */
 151 struct ti_sci_msg_req_get_device_state {
 152         struct ti_sci_msg_hdr hdr;
 153         u32 id;
 154 } __packed;
 155
 156 /**
 157  * struct ti_sci_msg_resp_get_device_state - Response to get device request.
 158  * @hdr:                Generic header
 159  * @context_loss_count: Indicates how many times the device has lost context. A
 160  *      driver can use this monotonic counter to determine if the device has
 161  *      lost context since the last time this message was exchanged.
 162  * @resets: Programmed state of the reset lines.
 163  * @programmed_state:   The state as programmed by set_device.
 164  *                      - Uses the MSG_DEVICE_SW_* macros
 165  * @current_state:      The actual state of the hardware.
 166  *
 167  * Response to request TI_SCI_MSG_GET_DEVICE_STATE.
 168  */
 169 struct ti_sci_msg_resp_get_device_state {
 170         struct ti_sci_msg_hdr hdr;
 171         u32 context_loss_count;
 172         u32 resets;
 173         u8 programmed_state;
 174 #define MSG_DEVICE_HW_STATE_OFF         0
 175 #define MSG_DEVICE_HW_STATE_ON          1
 176 #define MSG_DEVICE_HW_STATE_TRANS       2
 177         u8 current_state;
 178 } __packed;
 179
 180 /**
 181  * struct ti_sci_msg_req_set_device_resets - Set the desired resets
 182  *                              configuration of the device
 183  * @hdr:                Generic header
 184  * @id: Indicates which device to modify
 185  * @resets: A bit field of resets for the device. The meaning, behavior,
 186  *      and usage of the reset flags are device specific. 0 for a bit
 187  *      indicates releasing the reset represented by that bit while 1
 188  *      indicates keeping it held.
 189  *
 190  * Request type is TI_SCI_MSG_SET_DEVICE_RESETS, responded with a generic
 191  * ACK/NACK message.
 192  */
 193 struct ti_sci_msg_req_set_device_resets {
 194         struct ti_sci_msg_hdr hdr;
 195         u32 id;
 196         u32 resets;
 197 } __packed;
 198
 199 #endif /* __TI_SCI_H */