git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A53_64-bit_UltraScale_MPSoC/RTOSDemo_A53_bsp/psu_cortexa53_0/libsrc/ipipsu_v2_3/src/xipipsu.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2015 - 2016 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 * @addtogroup ipipsu_v2_3
  36 * @{
  37 * @details
  38  *
  39  * This is the header file for implementation of IPIPSU driver.
  40  * Inter Processor Interrupt (IPI) is used for communication between
  41  * different processors on ZynqMP SoC. Each IPI register set has Trigger, Status
  42  * and Observation registers for communication between processors. Each IPI path
  43  * has a 32 byte buffer associated with it and these buffers are located in the
  44  * XPPU RAM. This driver supports the following operations:
  45  *
  46  * - Trigger IPIs to CPUs on the SoC
  47  * - Write and Read Message buffers
  48  * - Read the status of Observation Register to get status of Triggered IPI
  49  * - Enable/Disable IPIs from selected Masters
  50  * - Read the Status register to get the source of an incoming IPI
  51  *
  52  * <b>Initialization</b>
  53  * The config data for the driver is loaded and is based on the HW build. The
  54  * XIpiPsu_Config data structure contains all the data related to the
  55  * IPI driver instance and also teh available Target CPUs.
  56  *
  57  * <b>Sending an IPI</b>
  58  * The following steps can be followed to send an IPI:
  59  * - Write the Message into Message Buffer using XIpiPsu_WriteMessage()
  60  * - Trigger IPI using XIpiPsu_TriggerIpi()
  61  * - Wait for Ack using XIpiPsu_PollForAck()
  62  * - Read response using XIpiPsu_ReadMessage()
  63  *
  64  * @note        XIpiPsu_GetObsStatus() before sending an IPI to ensure that the
  65  * previous IPI was serviced by the target
  66  *
  67  * <b>Receiving an IPI</b>
  68  * To receive an IPI, the following sequence can be followed:
  69  * - Register an interrupt handler for the IPIs interrupt ID
  70  * - Enable the required sources using XIpiPsu_InterruptEnable()
  71  * - In the interrupt handler, Check for source using XIpiPsu_GetInterruptStatus
  72  * - Read the message form source using XIpiPsu_ReadMessage()
  73  * - Write the response using XIpiPsu_WriteMessage()
  74  * - Ack the IPI using XIpiPsu_ClearInterruptStatus()
  75  *
  76  * @note        XIpiPsu_Reset can be used at startup to clear the status and
  77  * disable all sources
  78  *
  79  * <pre>
  80  * MODIFICATION HISTORY:
  81  *
  82  * Ver  Who Date     Changes
  83  * ---- --- -------- --------------------------------------------------
  84  * 2.2  ms  01/23/17 Modified xil_printf statement in main function for all
  85  *                    examples to ensure that "Successfully ran" and "Failed"
  86  *                    strings are available in all examples. This is a fix
  87  *                    for CR-965028.
  88  *      kvn 02/17/17  Add support for updating ConfigTable at run time
  89  *      ms  03/17/17  Added readme.txt file in examples folder for doxygen
  90  *                    generation.
  91  * 2.3  ms  04/11/17  Modified tcl file to add suffix U for all macro
  92  *                    definitions of ipipsu in xparameters.h
  93  * </pre>
  94  *
  95  *****************************************************************************/
  96 /*****************************************************************************/
  97 #ifndef XIPIPSU_H_
  98 #define XIPIPSU_H_
  99
 100
 101 /***************************** Include Files *********************************/
 102 #include "xil_io.h"
 103 #include "xstatus.h"
 104 #include "xipipsu_hw.h"
 105
 106 /************************** Constant Definitions *****************************/
 107 #define XIPIPSU_BUF_TYPE_MSG    (0x00000001U)
 108 #define XIPIPSU_BUF_TYPE_RESP   (0x00000002U)
 109 #define XIPIPSU_MAX_MSG_LEN             XIPIPSU_MSG_BUF_SIZE
 110 /**************************** Type Definitions *******************************/
 111 /**
 112  * Data structure used to refer IPI Targets
 113  */
 114 typedef struct {
 115         u32 Mask; /**< Bit Mask for the target */
 116         u32 BufferIndex; /**< Buffer Index used for calculating buffer address */
 117 } XIpiPsu_Target;
 118
 119 /**
 120  * This typedef contains configuration information for the device.
 121  */
 122 typedef struct {
 123         u32 DeviceId; /**< Unique ID  of device */
 124         u32 BaseAddress; /**< Base address of the device */
 125         u32 BitMask; /**< BitMask to be used to identify this CPU */
 126         u32 BufferIndex; /**< Index of the IPI Message Buffer */
 127         u32 IntId; /**< Interrupt ID on GIC **/
 128         u32 TargetCount; /**< Number of available IPI Targets */
 129         XIpiPsu_Target TargetList[XIPIPSU_MAX_TARGETS] ; /** < List of IPI Targets */
 130 } XIpiPsu_Config;
 131
 132 /**
 133  * The XIpiPsu driver instance data. The user is required to allocate a
 134  * variable of this type for each IPI device in the system. A pointer
 135  * to a variable of this type is then passed to the driver API functions.
 136  */
 137 typedef struct {
 138         XIpiPsu_Config Config; /**< Configuration structure */
 139         u32 IsReady; /**< Device is initialized and ready */
 140         u32 Options; /**< Options set in the device */
 141 } XIpiPsu;
 142
 143 /***************** Macros (Inline Functions) Definitions *********************/
 144 /**
 145 *
 146 * Read the register specified by the base address and offset
 147 *
 148 * @param        BaseAddress is the base address of the IPI instance
 149 * @param        RegOffset is the offset of the register relative to base
 150 *
 151 * @return       Value of the specified register
 152 * @note
 153 * C-style signature
 154 *       u32 XIpiPsu_ReadReg(u32 BaseAddress, u32 RegOffset)
 155 *
 156 *****************************************************************************/
 157
 158 #define XIpiPsu_ReadReg(BaseAddress, RegOffset) \
 159                 Xil_In32((BaseAddress) + (RegOffset))
 160
 161 /****************************************************************************/
 162 /**
 163 *
 164 * Write a value into a register specified by base address and offset
 165 *
 166 * @param BaseAddress is the base address of the IPI instance
 167 * @param RegOffset is the offset of the register relative to base
 168 * @param Data is a 32-bit value that is to be written into the specified register
 169 *
 170 * @note
 171 * C-style signature
 172 *       void XIpiPsu_WriteReg(u32 BaseAddress, u32 RegOffset, u32 Data)
 173 *
 174 *****************************************************************************/
 175
 176 #define XIpiPsu_WriteReg(BaseAddress, RegOffset, Data) \
 177                 Xil_Out32(((BaseAddress) + (RegOffset)), (Data))
 178
 179 /****************************************************************************/
 180 /**
 181 *
 182 * Enable interrupts specified in <i>Mask</i>. The corresponding interrupt for
 183 * each bit set to 1 in <i>Mask</i>, will be enabled.
 184 *
 185 * @param        InstancePtr is a pointer to the instance to be worked on.
 186 * @param        Mask contains a bit mask of interrupts to enable. The mask can
 187 *                       be formed using a set of bitwise or'd values of individual CPU masks
 188 *
 189 * @note
 190 * C-style signature
 191 *       void XIpiPsu_InterruptEnable(XIpiPsu *InstancePtr, u32 Mask)
 192 *
 193 *****************************************************************************/
 194 #define XIpiPsu_InterruptEnable(InstancePtr, Mask) \
 195         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 196                 XIPIPSU_IER_OFFSET, \
 197                 ((Mask) & XIPIPSU_ALL_MASK));
 198
 199 /****************************************************************************/
 200 /**
 201 *
 202 * Disable interrupts specified in <i>Mask</i>. The corresponding interrupt for
 203 * each bit set to 1 in <i>Mask</i>, will be disabled.
 204 *
 205 * @param        InstancePtr is a pointer to the instance to be worked on.
 206 * @param        Mask contains a bit mask of interrupts to disable. The mask can
 207 *                       be formed using a set of bitwise or'd values of individual CPU masks
 208 *
 209 * @note
 210 * C-style signature
 211 *       void XIpiPsu_InterruptDisable(XIpiPsu *InstancePtr, u32 Mask)
 212 *
 213 *****************************************************************************/
 214 #define XIpiPsu_InterruptDisable(InstancePtr, Mask)  \
 215         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 216                 XIPIPSU_IDR_OFFSET, \
 217                 ((Mask) & XIPIPSU_ALL_MASK));
 218 /****************************************************************************/
 219 /**
 220 *
 221 * Get the <i>STATUS REGISTER</i> of the current IPI instance.
 222 *
 223 * @param InstancePtr is a pointer to the instance to be worked on.
 224 * @return Returns the Interrupt Status register(ISR) contents
 225 * @note User needs to parse this 32-bit value to check the source CPU
 226 * C-style signature
 227 *       u32 XIpiPsu_GetInterruptStatus(XIpiPsu *InstancePtr)
 228 *
 229 *****************************************************************************/
 230 #define XIpiPsu_GetInterruptStatus(InstancePtr)  \
 231         XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
 232                 XIPIPSU_ISR_OFFSET)
 233 /****************************************************************************/
 234 /**
 235 *
 236 * Clear the <i>STATUS REGISTER</i> of the current IPI instance.
 237 * The corresponding interrupt status for
 238 * each bit set to 1 in <i>Mask</i>, will be cleared
 239 *
 240 * @param InstancePtr is a pointer to the instance to be worked on.
 241 * @param Mask corresponding to the source CPU*
 242 *
 243 * @note This function should be used after handling the IPI.
 244 * Clearing the status will automatically clear the corresponding bit in
 245 * OBSERVATION register of Source CPU
 246 * C-style signature
 247 *       void XIpiPsu_ClearInterruptStatus(XIpiPsu *InstancePtr, u32 Mask)
 248 *
 249 *****************************************************************************/
 250
 251 #define XIpiPsu_ClearInterruptStatus(InstancePtr, Mask)  \
 252         XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
 253                 XIPIPSU_ISR_OFFSET, \
 254                 ((Mask) & XIPIPSU_ALL_MASK));
 255 /****************************************************************************/
 256 /**
 257 *
 258 * Get the <i>OBSERVATION REGISTER</i> of the current IPI instance.
 259 *
 260 * @param        InstancePtr is a pointer to the instance to be worked on.
 261 * @return       Returns the Observation register(OBS) contents
 262 * @note         User needs to parse this 32-bit value to check the status of
 263 *                       individual CPUs
 264 * C-style signature
 265 *       u32 XIpiPsu_GetObsStatus(XIpiPsu *InstancePtr)
 266 *
 267 *****************************************************************************/
 268 #define XIpiPsu_GetObsStatus(InstancePtr)  \
 269         XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
 270                 XIPIPSU_OBS_OFFSET)
 271 /****************************************************************************/
 272 /************************** Function Prototypes *****************************/
 273
 274 /* Static lookup function implemented in xipipsu_sinit.c */
 275
 276 XIpiPsu_Config *XIpiPsu_LookupConfig(u32 DeviceId);
 277
 278 /* Interface Functions implemented in xipipsu.c */
 279
 280 XStatus XIpiPsu_CfgInitialize(XIpiPsu *InstancePtr, XIpiPsu_Config * CfgPtr,
 281                 UINTPTR EffectiveAddress);
 282
 283 void XIpiPsu_Reset(XIpiPsu *InstancePtr);
 284
 285 XStatus XIpiPsu_TriggerIpi(XIpiPsu *InstancePtr, u32 DestCpuMask);
 286
 287 XStatus XIpiPsu_PollForAck(XIpiPsu *InstancePtr, u32 DestCpuMask,
 288                 u32 TimeOutCount);
 289
 290 XStatus XIpiPsu_ReadMessage(XIpiPsu *InstancePtr, u32 SrcCpuMask, u32 *MsgPtr,
 291                 u32 MsgLength, u8 BufferType);
 292
 293 XStatus XIpiPsu_WriteMessage(XIpiPsu *InstancePtr, u32 DestCpuMask, u32 *MsgPtr,
 294                 u32 MsgLength, u8 BufferType);
 295 void XIpiPsu_SetConfigTable(u32 DeviceId, XIpiPsu_Config *ConfigTblPtr);
 296
 297 #endif /* XIPIPSU_H_ */
 298 /** @} */