git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_R5_UltraScale_MPSoC/RTOSDemo_R5_bsp/psu_cortexr5_0/libsrc/gpiops_v3_3/src/xgpiops.h

   1
   2 /******************************************************************************
   3 *
   4 * Copyright (C) 2010 - 2015 Xilinx, Inc.  All rights reserved.
   5 *
   6 * Permission is hereby granted, free of charge, to any person obtaining a copy
   7 * of this software and associated documentation files (the "Software"), to deal
   8 * in the Software without restriction, including without limitation the rights
   9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 * copies of the Software, and to permit persons to whom the Software is
  11 * furnished to do so, subject to the following conditions:
  12 *
  13 * The above copyright notice and this permission notice shall be included in
  14 * all copies or substantial portions of the Software.
  15 *
  16 * Use of the Software is limited solely to applications:
  17 * (a) running on a Xilinx device, or
  18 * (b) that interact with a Xilinx device through a bus or interconnect.
  19 *
  20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  23 * XILINX  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  25 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  26 * SOFTWARE.
  27 *
  28 * Except as contained in this notice, the name of the Xilinx shall not be used
  29 * in advertising or otherwise to promote the sale, use or other dealings in
  30 * this Software without prior written authorization from Xilinx.
  31 *
  32 ******************************************************************************/
  33 /*****************************************************************************/
  34 /**
  35 *
  36 * @file xgpiops.h
  37 * @addtogroup gpiops_v3_3
  38 * @{
  39 * @details
  40 *
  41 * The Xilinx PS GPIO driver. This driver supports the Xilinx PS GPIO
  42 * Controller.
  43 *
  44 * The GPIO Controller supports the following features:
  45 *       - 4 banks
  46 *       - Masked writes (There are no masked reads)
  47 *       - Bypass mode
  48 *       - Configurable Interrupts (Level/Edge)
  49 *
  50 * This driver is intended to be RTOS and processor independent. Any needs for
  51 * dynamic memory management, threads or thread mutual exclusion, virtual
  52 * memory, or cache control must be satisfied by the layer above this driver.
  53
  54 * This driver supports all the features listed above, if applicable.
  55 *
  56 * <b>Driver Description</b>
  57 *
  58 * The device driver enables higher layer software (e.g., an application) to
  59 * communicate to the GPIO.
  60 *
  61 * <b>Interrupts</b>
  62 *
  63 * The driver provides interrupt management functions and an interrupt handler.
  64 * Users of this driver need to provide callback functions. An interrupt handler
  65 * example is available with the driver.
  66 *
  67 * <b>Threads</b>
  68 *
  69 * This driver is not thread safe. Any needs for threads or thread mutual
  70 * exclusion must be satisfied by the layer above this driver.
  71 *
  72 * <b>Asserts</b>
  73 *
  74 * Asserts are used within all Xilinx drivers to enforce constraints on argument
  75 * values. Asserts can be turned off on a system-wide basis by defining, at
  76 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
  77 * is recommended that users leave asserts on during development.
  78 *
  79 * <b>Building the driver</b>
  80 *
  81 * The XGpioPs driver is composed of several source files. This allows the user
  82 * to build and link only those parts of the driver that are necessary.
  83 * <br><br>
  84 *
  85 * <pre>
  86 * MODIFICATION HISTORY:
  87 *
  88 * Ver   Who  Date     Changes
  89 * ----- ---- -------- -----------------------------------------------
  90 * 1.00a sv   01/15/10 First Release
  91 * 1.01a sv   04/15/12 Removed the APIs XGpioPs_SetMode, XGpioPs_SetModePin
  92 *                     XGpioPs_GetMode, XGpioPs_GetModePin as they are not
  93 *                     relevant to Zynq device.The interrupts are disabled
  94 *                     for output pins on all banks during initialization.
  95 * 1.02a hk   08/22/13 Added low level reset API
  96 * 2.1   hk   04/29/14 Use Input data register DATA_RO for read. CR# 771667.
  97 * 2.2   sk       10/13/14 Used Pin number in Bank instead of pin number
  98 *                                         passed to APIs. CR# 822636
  99 * 3.00  kvn  02/13/15 Modified code for MISRA-C:2012 compliance.
 100 * 3.1   kvn  04/13/15 Add support for Zynq Ultrascale+ MP. CR# 856980.
 101 *       ms   03/17/17 Added readme.txt file in examples folder for doxygen
 102 *                     generation.
 103 *       ms   04/05/17 Added tabspace for return statements in functions of
 104 *                     gpiops examples for proper documentation while
 105 *                     generating doxygen.
 106 * 3.3   ms   04/17/17 Added notes about gpio input and output pin description
 107 *                     for zcu102 and zc702 boards in polled and interrupt
 108 *                     example, configured Interrupt pin to input pin for
 109 *                     proper functioning of interrupt example.
 110 * </pre>
 111 *
 112 ******************************************************************************/
 113 #ifndef XGPIOPS_H               /* prevent circular inclusions */
 114 #define XGPIOPS_H               /* by using protection macros */
 115
 116 #ifdef __cplusplus
 117 extern "C" {
 118 #endif
 119
 120 /***************************** Include Files *********************************/
 121
 122 #include "xstatus.h"
 123 #include "xgpiops_hw.h"
 124 #include "xplatform_info.h"
 125
 126 /************************** Constant Definitions *****************************/
 127
 128 /** @name Interrupt types
 129  *  @{
 130  * The following constants define the interrupt types that can be set for each
 131  * GPIO pin.
 132  */
 133 #define XGPIOPS_IRQ_TYPE_EDGE_RISING    0x00U  /**< Interrupt on Rising edge */
 134 #define XGPIOPS_IRQ_TYPE_EDGE_FALLING   0x01U  /**< Interrupt Falling edge */
 135 #define XGPIOPS_IRQ_TYPE_EDGE_BOTH      0x02U  /**< Interrupt on both edges */
 136 #define XGPIOPS_IRQ_TYPE_LEVEL_HIGH     0x03U  /**< Interrupt on high level */
 137 #define XGPIOPS_IRQ_TYPE_LEVEL_LOW      0x04U  /**< Interrupt on low level */
 138 /*@}*/
 139
 140 #define XGPIOPS_BANK_MAX_PINS           (u32)32 /**< Max pins in a GPIO bank */
 141 #define XGPIOPS_BANK0                   0x00U  /**< GPIO Bank 0 */
 142 #define XGPIOPS_BANK1                   0x01U  /**< GPIO Bank 1 */
 143 #define XGPIOPS_BANK2                   0x02U  /**< GPIO Bank 2 */
 144 #define XGPIOPS_BANK3                   0x03U  /**< GPIO Bank 3 */
 145
 146 #ifdef XPAR_PSU_GPIO_0_BASEADDR
 147 #define XGPIOPS_BANK4                   0x04U  /**< GPIO Bank 4 */
 148 #define XGPIOPS_BANK5                   0x05U  /**< GPIO Bank 5 */
 149 #endif
 150
 151 #define XGPIOPS_MAX_BANKS_ZYNQMP                0x06U  /**< Max banks in a
 152                                                                                 *       Zynq Ultrascale+ MP GPIO device
 153                                                                                 */
 154 #define XGPIOPS_MAX_BANKS               0x04U  /**< Max banks in a Zynq GPIO device */
 155
 156 #define XGPIOPS_DEVICE_MAX_PIN_NUM_ZYNQMP       (u32)174 /**< Max pins in the
 157                                                   *     Zynq Ultrascale+ MP GPIO device
 158                                               * 0 - 25,  Bank 0
 159                                               * 26 - 51, Bank 1
 160                                               * 52 - 77, Bank 2
 161                                               * 78 - 109, Bank 3
 162                                               * 110 - 141, Bank 4
 163                                               * 142 - 173, Bank 5
 164                                               */
 165 #define XGPIOPS_DEVICE_MAX_PIN_NUM      (u32)118 /**< Max pins in the Zynq GPIO device
 166                                               * 0 - 31,  Bank 0
 167                                               * 32 - 53, Bank 1
 168                                               * 54 - 85, Bank 2
 169                                               * 86 - 117, Bank 3
 170                                               */
 171
 172 /**************************** Type Definitions *******************************/
 173
 174 /****************************************************************************/
 175 /**
 176  * This handler data type allows the user to define a callback function to
 177  * handle the interrupts for the GPIO device. The application using this
 178  * driver is expected to define a handler of this type, to support interrupt
 179  * driven mode. The handler executes in an interrupt context such that minimal
 180  * processing should be performed.
 181  *
 182  * @param       CallBackRef is a callback reference passed in by the upper layer
 183  *              when setting the callback functions for a GPIO bank. It is
 184  *              passed back to the upper layer when the callback is invoked. Its
 185  *              type is not important to the driver component, so it is a void
 186  *              pointer.
 187  * @param       Bank is the bank for which the interrupt status has changed.
 188  * @param       Status is the Interrupt status of the GPIO bank.
 189  *
 190  *****************************************************************************/
 191 typedef void (*XGpioPs_Handler) (void *CallBackRef, u32 Bank, u32 Status);
 192
 193 /**
 194  * This typedef contains configuration information for a device.
 195  */
 196 typedef struct {
 197         u16 DeviceId;           /**< Unique ID of device */
 198         u32 BaseAddr;           /**< Register base address */
 199 } XGpioPs_Config;
 200
 201 /**
 202  * The XGpioPs driver instance data. The user is required to allocate a
 203  * variable of this type for the GPIO device in the system. A pointer
 204  * to a variable of this type is then passed to the driver API functions.
 205  */
 206 typedef struct {
 207         XGpioPs_Config GpioConfig;      /**< Device configuration */
 208         u32 IsReady;                    /**< Device is initialized and ready */
 209         XGpioPs_Handler Handler;        /**< Status handlers for all banks */
 210         void *CallBackRef;              /**< Callback ref for bank handlers */
 211         u32 Platform;                   /**< Platform data */
 212         u32 MaxPinNum;                  /**< Max pins in the GPIO device */
 213         u8 MaxBanks;                    /**< Max banks in a GPIO device */
 214 } XGpioPs;
 215
 216 /***************** Macros (Inline Functions) Definitions *********************/
 217
 218 /************************** Function Prototypes ******************************/
 219
 220 /* Functions in xgpiops.c */
 221 s32 XGpioPs_CfgInitialize(XGpioPs *InstancePtr, XGpioPs_Config *ConfigPtr,
 222                            u32 EffectiveAddr);
 223
 224 /* Bank APIs in xgpiops.c */
 225 u32 XGpioPs_Read(XGpioPs *InstancePtr, u8 Bank);
 226 void XGpioPs_Write(XGpioPs *InstancePtr, u8 Bank, u32 Data);
 227 void XGpioPs_SetDirection(XGpioPs *InstancePtr, u8 Bank, u32 Direction);
 228 u32 XGpioPs_GetDirection(XGpioPs *InstancePtr, u8 Bank);
 229 void XGpioPs_SetOutputEnable(XGpioPs *InstancePtr, u8 Bank, u32 OpEnable);
 230 u32 XGpioPs_GetOutputEnable(XGpioPs *InstancePtr, u8 Bank);
 231 void XGpioPs_GetBankPin(u8 PinNumber,   u8 *BankNumber, u8 *PinNumberInBank);
 232
 233 /* Pin APIs in xgpiops.c */
 234 u32 XGpioPs_ReadPin(XGpioPs *InstancePtr, u32 Pin);
 235 void XGpioPs_WritePin(XGpioPs *InstancePtr, u32 Pin, u32 Data);
 236 void XGpioPs_SetDirectionPin(XGpioPs *InstancePtr, u32 Pin, u32 Direction);
 237 u32 XGpioPs_GetDirectionPin(XGpioPs *InstancePtr, u32 Pin);
 238 void XGpioPs_SetOutputEnablePin(XGpioPs *InstancePtr, u32 Pin, u32 OpEnable);
 239 u32 XGpioPs_GetOutputEnablePin(XGpioPs *InstancePtr, u32 Pin);
 240
 241 /* Diagnostic functions in xgpiops_selftest.c */
 242 s32 XGpioPs_SelfTest(XGpioPs *InstancePtr);
 243
 244 /* Functions in xgpiops_intr.c */
 245 /* Bank APIs in xgpiops_intr.c */
 246 void XGpioPs_IntrEnable(XGpioPs *InstancePtr, u8 Bank, u32 Mask);
 247 void XGpioPs_IntrDisable(XGpioPs *InstancePtr, u8 Bank, u32 Mask);
 248 u32 XGpioPs_IntrGetEnabled(XGpioPs *InstancePtr, u8 Bank);
 249 u32 XGpioPs_IntrGetStatus(XGpioPs *InstancePtr, u8 Bank);
 250 void XGpioPs_IntrClear(XGpioPs *InstancePtr, u8 Bank, u32 Mask);
 251 void XGpioPs_SetIntrType(XGpioPs *InstancePtr, u8 Bank, u32 IntrType,
 252                           u32 IntrPolarity, u32 IntrOnAny);
 253 void XGpioPs_GetIntrType(XGpioPs *InstancePtr, u8 Bank, u32 *IntrType,
 254                           u32 *IntrPolarity, u32 *IntrOnAny);
 255 void XGpioPs_SetCallbackHandler(XGpioPs *InstancePtr, void *CallBackRef,
 256                              XGpioPs_Handler FuncPointer);
 257 void XGpioPs_IntrHandler(XGpioPs *InstancePtr);
 258
 259 /* Pin APIs in xgpiops_intr.c */
 260 void XGpioPs_SetIntrTypePin(XGpioPs *InstancePtr, u32 Pin, u8 IrqType);
 261 u8 XGpioPs_GetIntrTypePin(XGpioPs *InstancePtr, u32 Pin);
 262
 263 void XGpioPs_IntrEnablePin(XGpioPs *InstancePtr, u32 Pin);
 264 void XGpioPs_IntrDisablePin(XGpioPs *InstancePtr, u32 Pin);
 265 u32 XGpioPs_IntrGetEnabledPin(XGpioPs *InstancePtr, u32 Pin);
 266 u32 XGpioPs_IntrGetStatusPin(XGpioPs *InstancePtr, u32 Pin);
 267 void XGpioPs_IntrClearPin(XGpioPs *InstancePtr, u32 Pin);
 268
 269 /* Functions in xgpiops_sinit.c */
 270 XGpioPs_Config *XGpioPs_LookupConfig(u16 DeviceId);
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif /* end of protection macro */
 277 /** @} */