begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_GPIO.c

   1 /**
   2 \defgroup gpio_interface_gr GPIO Interface
   3 \brief Driver API for GPIO Interface (%Driver_GPIO.h)
   4 \details
   5 The <b>General-purpose Input/Output Interface</b> (GPIO) features Input/Output operations on pin level (does not support simultaneous operations on multiple pins belonging to the same port).
   6
   7 Features:
   8  - basic pin configuration (direction, output mode, pull-resistor, event trigger) excluding advanced settings (drive strength or speed, input filter, ...),
   9  - events on edge detection,
  10  - setting outputs,
  11  - reading inputs.
  12
  13 Each function operates on a pin level and uses a pin identification as the first parameter. Pin identification is a virtual number which is mapped to an actual pin.
  14
  15 <b>GPIO API</b>
  16
  17 The following header files define the Application Programming Interface (API) for the GPIO interface:
  18   - \b %Driver_GPIO.h : Driver API for GPIO Interface
  19
  20 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
  21 peripherals of the microcontroller family.
  22
  23
  24 <b>Driver Functions</b>
  25
  26 The driver functions are published in the access struct as explained in \ref DriverFunctions
  27   - \ref ARM_DRIVER_GPIO : access struct for GPIO driver functions
  28
  29
  30 <b>Example Code</b>
  31
  32 The following example code shows the usage of the GPIO interface.
  33
  34 \include GPIO_Demo.c
  35
  36 @{
  37 */
  38
  39
  40 /**
  41 \struct     ARM_DRIVER_GPIO
  42 \details
  43 The functions of the GPIO driver are accessed by function pointers exposed by this structure.
  44 Refer to \ref DriverFunctions for overview information.
  45
  46 Each instance of a GPIO interface provides such an access structure.
  47 The instance is identified by a postfix number in the symbol name of the access structure, for example:
  48  - \b Driver_GPIO0 is the name of the access struct of the first instance (no. 0).
  49  - \b Driver_GPIO1 is the name of the access struct of the second instance (no. 1).
  50
  51 A middleware configuration setting allows connecting the middleware to a specific driver instance \b %Driver_GPIO<i>n</i>.
  52 The default is \token{0}, which connects a middleware to the first instance of a driver.
  53 **************************************************************************************************************************/
  54
  55 /**
  56 \typedef    ARM_GPIO_DIRECTION
  57 \details
  58 Specifies values for setting the direction.
  59
  60 <b>Parameter for:</b>
  61   - \ref ARM_GPIO_SetDirection
  62 *****************************************************************************************************************/
  63
  64 /**
  65 \typedef    ARM_GPIO_OUTPUT_MODE
  66 \details
  67 Specifies values for setting the output mode.
  68
  69 <b>Parameter for:</b>
  70   - \ref ARM_GPIO_SetOutputMode
  71 *****************************************************************************************************************/
  72
  73 /**
  74 \typedef    ARM_GPIO_PULL_RESISTOR
  75 \details
  76 Specifies values for setting the pull resistor.
  77
  78 <b>Parameter for:</b>
  79   - \ref ARM_GPIO_SetPullResistor
  80 *****************************************************************************************************************/
  81
  82 /**
  83 \typedef    ARM_GPIO_EVENT_TRIGGER
  84 \details
  85 Specifies values for setting the event trigger.
  86
  87 <b>Parameter for:</b>
  88   - \ref ARM_GPIO_SetEventTrigger
  89 *****************************************************************************************************************/
  90
  91 /**
  92 \typedef    ARM_GPIO_SignalEvent_t
  93 \details
  94 Provides the typedef for the callback function \ref ARM_GPIO_SignalEvent.
  95
  96 <b>Parameter for:</b>
  97   - \ref ARM_GPIO_Setup
  98 *******************************************************************************************************************/
  99
 100 /**
 101 \defgroup gpio_execution_status GPIO Status Error Codes
 102 \ingroup gpio_interface_gr
 103 \brief Negative values indicate errors (GPIO has specific codes in addition to common \ref execution_status).
 104 \details
 105 The GPIO driver has additional status error codes that are listed below.
 106 Note that the GPIO driver also returns the common \ref execution_status.
 107
 108 @{
 109 \def ARM_GPIO_ERROR_PIN
 110 The \b pin specified is not available.
 111 @}
 112 */
 113
 114 /**
 115 \defgroup GPIO_events GPIO Events
 116 \ingroup gpio_interface_gr
 117 \brief The GPIO driver generates call back events that are notified via the function \ref ARM_GPIO_SignalEvent.
 118 \details
 119 This section provides the event values for the \ref ARM_GPIO_SignalEvent callback function.
 120
 121 The following call back notification events are generated:
 122 @{
 123 \def  ARM_GPIO_EVENT_RISING_EDGE
 124 \def  ARM_GPIO_EVENT_FALLING_EDGE
 125 \def  ARM_GPIO_EVENT_EITHER_EDGE
 126 @}
 127 */
 128
 129 //
 130 //  Functions
 131 //
 132
 133 int32_t ARM_GPIO_Setup (ARM_GPIO_Pin_t pin, ARM_GPIO_SignalEvent_t cb_event) {
 134   return ARM_DRIVER_OK;
 135 }
 136 /**
 137 \fn int32_t ARM_GPIO_Setup (ARM_GPIO_Pin_t pin, ARM_GPIO_SignalEvent_t cb_event)
 138 \details
 139 The function \b ARM_GPIO_Setup sets-up the specified \em pin as GPIO with default configuration.
 140 Pin is configured as input without pull-resistor and without event trigger.
 141
 142 The parameter \em cb_event specifies a pointer to the \ref ARM_GPIO_SignalEvent callback function.
 143 Use a NULL pointer when no callback events are required.
 144 **************************************************************************************************************************/
 145
 146 int32_t ARM_GPIO_SetDirection (ARM_GPIO_Pin_t pin, ARM_GPIO_DIRECTION direction) {
 147   return ARM_DRIVER_OK;
 148 }
 149 /**
 150 \fn int32_t ARM_GPIO_SetDirection (ARM_GPIO_Pin_t pin, ARM_GPIO_DIRECTION direction)
 151 \details
 152 The function \b ARM_GPIO_SetDirection configures the direction of the specified \em pin.
 153
 154 Direction is specified with parameter \em direction:
 155  - \ref ARM_GPIO_INPUT : Input (default),
 156  - \ref ARM_GPIO_OUTPUT : Output.
 157 **************************************************************************************************************************/
 158
 159 int32_t ARM_GPIO_SetOutputMode (ARM_GPIO_Pin_t pin, ARM_GPIO_OUTPUT_MODE mode) {
 160   return ARM_DRIVER_OK;
 161 }
 162 /**
 163 \fn int32_t ARM_GPIO_SetOutputMode (ARM_GPIO_Pin_t pin, ARM_GPIO_OUTPUT_MODE mode)
 164 \details
 165 The function \b ARM_GPIO_SetOutputMode configures the output mode of the specified \em pin.
 166
 167 Output mode is specified with parameter \em mode:
 168  - \ref ARM_GPIO_PUSH_PULL : Push-pull (default),
 169  - \ref ARM_GPIO_OPEN_DRAIN : Open-drain.
 170
 171 \note Output mode is relevant only when the pin is configured as output.
 172 **************************************************************************************************************************/
 173
 174 int32_t ARM_GPIO_SetPullResistor (ARM_GPIO_Pin_t pin, ARM_GPIO_PULL_RESISTOR resistor) {
 175   return ARM_DRIVER_OK;
 176 }
 177 /**
 178 \fn int32_t ARM_GPIO_SetPullResistor (ARM_GPIO_Pin_t pin, ARM_GPIO_PULL_RESISTOR resistor)
 179 \details
 180 The function \b ARM_GPIO_SetPullResistor configures the pull resistor of the specified \em pin.
 181
 182 Pull resistor is specified with parameter \em resistor:
 183  - \ref ARM_GPIO_PULL_NONE : None (default),
 184  - \ref ARM_GPIO_PULL_UP : Pull-up,
 185  - \ref ARM_GPIO_PULL_DOWN : Pull-down.
 186
 187 \note Pull resistor applies to the pin regardless of pin direction.
 188 **************************************************************************************************************************/
 189
 190 int32_t ARM_GPIO_SetEventTrigger (ARM_GPIO_Pin_t pin, ARM_GPIO_EVENT_TRIGGER trigger) {
 191   return ARM_DRIVER_OK;
 192 }
 193 /**
 194 \fn int32_t ARM_GPIO_SetEventTrigger (ARM_GPIO_Pin_t pin, ARM_GPIO_EVENT_TRIGGER trigger)
 195 \details
 196 The function \b ARM_GPIO_SetEventTrigger configures the event trigger of the specified \em pin.
 197
 198 Event trigger is specified with parameter \em trigger:
 199  - \ref ARM_GPIO_TRIGGER_NONE : None (default),
 200  - \ref ARM_GPIO_TRIGGER_RISING_EDGE : Rising-edge,
 201  - \ref ARM_GPIO_TRIGGER_FALLING_EDGE : Falling-edge,
 202  - \ref ARM_GPIO_TRIGGER_EITHER_EDGE : Either edge (rising and falling).
 203 **************************************************************************************************************************/
 204
 205 void ARM_GPIO_SetOutput (ARM_GPIO_Pin_t pin, uint32_t val) {
 206 }
 207 /**
 208 \fn void ARM_GPIO_SetOutput (ARM_GPIO_Pin_t pin, uint32_t val)
 209 \details
 210 The function \b ARM_GPIO_SetOutput sets the level of the specified \em pin defined as output to the value specified by \em val.
 211
 212 \note
 213 When a pin is configured as input, the level is latched and will be driven once the pin is configured as output.
 214 **************************************************************************************************************************/
 215
 216 uint32_t ARM_GPIO_GetInput (ARM_GPIO_Pin_t pin) {
 217   return 0U;
 218 }
 219 /**
 220 \fn uint32_t ARM_GPIO_GetInput (ARM_GPIO_Pin_t pin)
 221 \details
 222 The function \b ARM_GPIO_GetInput reads the level of the specified \em pin.
 223 **************************************************************************************************************************/
 224
 225 void ARM_GPIO_SignalEvent (ARM_GPIO_Pin_t pin, uint32_t event) {
 226 }
 227 /**
 228 \fn void ARM_GPIO_SignalEvent (ARM_GPIO_Pin_t pin, uint32_t event)
 229 \details
 230 The function \b ARM_GPIO_SignalEvent is a callback functions registered by the function \ref ARM_GPIO_Setup.
 231 It is called by the GPIO driver to notify the application about \ref GPIO_events occurred during operation.
 232
 233 The parameter \em pin indicates on which pin the event occurred and parameter \em event indicates one or more events that occurred.
 234
 235 The following events can be generated:
 236
 237 <table class="cmtable" summary="">
 238 <tr>
 239   <th> Parameter \em event              </th><th> Bit </th><th> Description </th>
 240 </tr>
 241 <tr>
 242   <td> \ref ARM_GPIO_EVENT_RISING_EDGE  </td><td>  0  </td><td> Occurs when rising-edge is detected on the indicated pin. </td>
 243 </tr>
 244 <tr>
 245   <td> \ref ARM_GPIO_EVENT_FALLING_EDGE </td><td>  1  </td><td> Occurs when falling-edge is detected on the indicated pin. </td>
 246 </tr>
 247 <tr>
 248   <td> \ref ARM_GPIO_EVENT_EITHER_EDGE  </td><td>  2  </td><td> Occurs when either edge is detected on the indicated pin
 249                                                                 when trigger is configured as \ref ARM_GPIO_TRIGGER_EITHER_EDGE
 250                                                                 and hardware is not able to distinguish between rising and falling edge. </td>
 251 </tr>
 252 </table>
 253 **************************************************************************************************************************/
 254
 255 /**
 256 @}
 257 */
 258 // End GPIO Interface