git.sur5r.net Git - freertos/blob

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2015 Xilinx, Inc.  All rights reserved.
   4 *
   5 * Permission is hereby granted, free of charge, to any person obtaining a copy
   6 * of this software and associated documentation files (the "Software"), to deal
   7 * in the Software without restriction, including without limitation the rights
   8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 * copies of the Software, and to permit persons to whom the Software is
  10 * furnished to do so, subject to the following conditions:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  15 * Use of the Software is limited solely to applications:
  16 * (a) running on a Xilinx device, or
  17 * (b) that interact with a Xilinx device through a bus or interconnect.
  18 *
  19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  22 * XILINX  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25 * SOFTWARE.
  26 *
  27 * Except as contained in this notice, the name of the Xilinx shall not be used
  28 * in advertising or otherwise to promote the sale, use or other dealings in
  29 * this Software without prior written authorization from Xilinx.
  30 *
  31 ******************************************************************************/
  32 /*****************************************************************************/
  33 /**
  34  * @file xipipsu.h
  35  *
  36  * This is the header file for implementation of IPIPSU driver.
  37  * Inter Processor Interrupt (IPI) is used for communication between
  38  * different processors on ZynqMP SoC. Each IPI register set has Trigger, Status
  39  * and Observation registers for communication between processors. Each IPI path
  40  * has a 32 byte buffer associated with it and these buffers are located in the
  41  * XPPU RAM. This driver supports the following operations:
  42  *
  43  * - Trigger IPIs to CPUs on the SoC
  44  * - Write and Read Message buffers
  45  * - Read the status of Observation Register to get status of Triggered IPI
  46  * - Enable/Disable IPIs from selected Masters
  47  * - Read the Status register to get the source of an incoming IPI
  48  *
  49  * <b>Initialization</b>
  50  * The config data for the driver is loaded and is based on the HW build. The
  51  * XIpiPsu_Config data structure contains all the data related to the
  52  * IPI driver instance and also teh available Target CPUs.
  53  *
  54  * <b>Sending an IPI</b>
  55  * The following steps can be followed to send an IPI:
  56  * - Write the Message into Message Buffer using XIpiPsu_WriteMessage()
  57  * - Trigger IPI using XIpiPsu_TriggerIpi()
  58  * - Wait for Ack using XIpiPsu_PollForAck()
  59  * - Read response using XIpiPsu_ReadMessage()
  60  *
  61  * @note        XIpiPsu_GetObsStatus() before sending an IPI to ensure that the
  62  * previous IPI was serviced by the target
  63  *
  64  * <b>Receiving an IPI</b>
  65  * To receive an IPI, the following sequence can be followed:
  66  * - Register an interrupt handler for the IPIs interrupt ID
  67  * - Enable the required sources using XIpiPsu_InterruptEnable()
  68  * - In the interrupt handler, Check for source using XIpiPsu_GetInterruptStatus
  69  * - Read the message form source using XIpiPsu_ReadMessage()
  70  * - Write the response using XIpiPsu_WriteMessage()
  71  * - Ack the IPI using XIpiPsu_ClearInterruptStatus()
  72  *
  73  * @note        XIpiPsu_Reset can be used at startup to clear the status and
  74  * disable all sources
  75  *
  76  */
  77 /*****************************************************************************/
  78 #ifndef XIPIPSU_H_
  79 #define XIPIPSU_H_
  80
  81
  82 /***************************** Include Files *********************************/
  83 #include "xil_io.h"
  84 #include "xstatus.h"
  85 #include "xipipsu_hw.h"
  86
  87 /************************** Constant Definitions *****************************/
  88 #define XIPIPSU_BUF_TYPE_MSG    (0x00000001U)
  89 #define XIPIPSU_BUF_TYPE_RESP   (0x00000002U)
  90 #define XIPIPSU_MAX_MSG_LEN             XIPIPSU_MSG_BUF_SIZE
  91 /**************************** Type Definitions *******************************/
  92 /**
  93  * Data structure used to refer IPI Targets
  94  */
  95 typedef struct {
  96         u32 Mask; /**< Bit Mask for the target */
  97         u32 BufferIndex; /**< Buffer Index used for calculating buffer address */
  98 } XIpiPsu_Target;
  99
 100 /**
 101  * This typedef contains configuration information for the device.
 102  */
 103 typedef struct {
 104         u32 DeviceId; /**< Unique ID  of device */
 105         u32 BaseAddress; /**< Base address of the device */
 106         u32 BitMask; /**< BitMask to be used to identify this CPU */
 107         u32 BufferIndex; /**< Index of the IPI Message Buffer */
 108         u32 IntId; /**< Interrupt ID on GIC **/
 109         u32 TargetCount; /**< Number of available IPI Targets */
 110         XIpiPsu_Target TargetList[XIPIPSU_MAX_TARGETS] ; /** < List of IPI Targets */
 111 } XIpiPsu_Config;
 112
 113 /**
 114  * The XIpiPsu driver instance data. The user is required to allocate a
 115  * variable of this type for each IPI device in the system. A pointer
 116  * to a variable of this type is then passed to the driver API functions.
 117  */
 118 typedef struct {
 119         XIpiPsu_Config Config; /**< Configuration structure */
 120         u32 IsReady; /**< Device is initialized and ready */
 121         u32 Options; /**< Options set in the device */
 122 } XIpiPsu;
 123
 124 /***************** Macros (Inline Functions) Definitions *********************/
 125 /**
 126 *
 127 * Read the register specified by the base address and offset
 128 *
 129 * @param        BaseAddress is the base address of the IPI instance
 130 * @param        RegOffset is the offset of the register relative to base
 131 *
 132 * @return       Value of the specified register
 133 * @note
 134 * C-style signature
 135 *       u32 XIpiPsu_ReadReg(u32 BaseAddress, u32 RegOffset)
 136 *
 137 *****************************************************************************/
 138
 139 #define XIpiPsu_ReadReg(BaseAddress, RegOffset) \
 140                 Xil_In32((BaseAddress) + (RegOffset))
 141
 142 /****************************************************************************/
 143 /**
 144 *
 145 * Write a value into a register specified by base address and offset
 146 *
 147 * @param BaseAddress is the base address of the IPI instance
 148 * @param RegOffset is the offset of the register relative to base
 149 * @param Data is a 32-bit value that is to be written into the specified register
 150 *
 151 * @note
 152 * C-style signature
 153 *       void XIpiPsu_WriteReg(u32 BaseAddress, u32 RegOffset, u32 Data)
 154 *
 155 *****************************************************************************/
 156
 157 #define XIpiPsu_WriteReg(BaseAddress, RegOffset, Data) \
 158                 Xil_Out32(((BaseAddress) + (RegOffset)), (Data))
 159
 160 /****************************************************************************/
 161 /**
 162 *
 163 * Enable interrupts specified in <i>Mask</i>. The corresponding interrupt for
 164 * each bit set to 1 in <i>Mask</i>, will be enabled.
 165 *
 166 * @param        InstancePtr is a pointer to the instance to be worked on.
 167 * @param        Mask contains a bit mask of interrupts to enable. The mask can
 168 *                       be formed using a set of bitwise or'd values of individual CPU masks
 169 *
 170 * @note
 171 * C-style signature
 172 *       void XIpiPsu_InterruptEnable(XIpiPsu *InstancePtr, u32 Mask)
 173 *
 174 *****************************************************************************/
 175 #define XIpiPsu_InterruptEnable(InstancePtr, Mask) \
 176         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 177                 XIPIPSU_IER_OFFSET, \
 178                 ((Mask) & XIPIPSU_ALL_MASK));
 179
 180 /****************************************************************************/
 181 /**
 182 *
 183 * Disable interrupts specified in <i>Mask</i>. The corresponding interrupt for
 184 * each bit set to 1 in <i>Mask</i>, will be disabled.
 185 *
 186 * @param        InstancePtr is a pointer to the instance to be worked on.
 187 * @param        Mask contains a bit mask of interrupts to disable. The mask can
 188 *                       be formed using a set of bitwise or'd values of individual CPU masks
 189 *
 190 * @note
 191 * C-style signature
 192 *       void XIpiPsu_InterruptDisable(XIpiPsu *InstancePtr, u32 Mask)
 193 *
 194 *****************************************************************************/
 195 #define XIpiPsu_InterruptDisable(InstancePtr, Mask)  \
 196         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 197                 XIPIPSU_IDR_OFFSET, \
 198                 ((Mask) & XIPIPSU_ALL_MASK));
 199 /****************************************************************************/
 200 /**
 201 *
 202 * Get the <i>STATUS REGISTER</i> of the current IPI instance.
 203 *
 204 * @param InstancePtr is a pointer to the instance to be worked on.
 205 * @return Returns the Interrupt Status register(ISR) contents
 206 * @note User needs to parse this 32-bit value to check the source CPU
 207 * C-style signature
 208 *       u32 XIpiPsu_GetInterruptStatus(XIpiPsu *InstancePtr)
 209 *
 210 *****************************************************************************/
 211 #define XIpiPsu_GetInterruptStatus(InstancePtr)  \
 212         XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
 213                 XIPIPSU_ISR_OFFSET)
 214 /****************************************************************************/
 215 /**
 216 *
 217 * Clear the <i>STATUS REGISTER</i> of the current IPI instance.
 218 * The corresponding interrupt status for
 219 * each bit set to 1 in <i>Mask</i>, will be cleared
 220 *
 221 * @param InstancePtr is a pointer to the instance to be worked on.
 222 * @param Mask corresponding to the source CPU*
 223 *
 224 * @note This function should be used after handling the IPI.
 225 * Clearing the status will automatically clear the corresponding bit in
 226 * OBSERVATION register of Source CPU
 227 * C-style signature
 228 *       void XIpiPsu_ClearInterruptStatus(XIpiPsu *InstancePtr, u32 Mask)
 229 *
 230 *****************************************************************************/
 231
 232 #define XIpiPsu_ClearInterruptStatus(InstancePtr, Mask)  \
 233         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 234                 XIPIPSU_ISR_OFFSET, \
 235                 ((Mask) & XIPIPSU_ALL_MASK));
 236 /****************************************************************************/
 237 /**
 238 *
 239 * Get the <i>OBSERVATION REGISTER</i> of the current IPI instance.
 240 *
 241 * @param        InstancePtr is a pointer to the instance to be worked on.
 242 * @return       Returns the Observation register(OBS) contents
 243 * @note         User needs to parse this 32-bit value to check the status of
 244 *                       individual CPUs
 245 * C-style signature
 246 *       u32 XIpiPsu_GetObsStatus(XIpiPsu *InstancePtr)
 247 *
 248 *****************************************************************************/
 249 #define XIpiPsu_GetObsStatus(InstancePtr)  \
 250         XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
 251                 XIPIPSU_OBS_OFFSET)
 252 /****************************************************************************/
 253 /************************** Function Prototypes *****************************/
 254
 255 /* Static lookup function implemented in xipipsu_sinit.c */
 256
 257 XIpiPsu_Config *XIpiPsu_LookupConfig(u32 DeviceId);
 258
 259 /* Interface Functions implemented in xipipsu.c */
 260
 261 XStatus XIpiPsu_CfgInitialize(XIpiPsu *InstancePtr, XIpiPsu_Config * CfgPtr,
 262                 UINTPTR EffectiveAddress);
 263
 264 void XIpiPsu_Reset(XIpiPsu *InstancePtr);
 265
 266 XStatus XIpiPsu_TriggerIpi(XIpiPsu *InstancePtr, u32 DestCpuMask);
 267
 268 XStatus XIpiPsu_PollForAck(XIpiPsu *InstancePtr, u32 DestCpuMask,
 269                 u32 TimeOutCount);
 270
 271 XStatus XIpiPsu_ReadMessage(XIpiPsu *InstancePtr, u32 SrcCpuMask, u32 *MsgPtr,
 272                 u32 MsgLength, u8 BufType);
 273
 274 XStatus XIpiPsu_WriteMessage(XIpiPsu *InstancePtr, u32 DestCpuMask, u32 *MsgPtr,
 275                 u32 MsgLength, u8 BufType);
 276
 277 #endif /* XIPIPSU_H_ */