begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/VIO.txt

   1 /**
   2 \defgroup vio_interface_gr VIO
   3 \brief API for Virtual I/O (VIO) (%cmsis_vio.h)
   4 \details
   5
   6 The VIO software component is a virtual I/O abstraction for peripherals that are typically used in example projects. It
   7 enables developers to move from an evaluation kit to custom hardware and helps to scale project examples at large to many
   8 development boards:
   9
  10 \image html vioRationale.png "Virtual I/O provides a generic API for examples and testing"
  11
  12 <b>VIO API</b>
  13
  14 The following header file defines the Application Programming Interface (API) for VIO:
  15   - \b %cmsis_vio.h : API for VIO
  16
  17 <b>VIO User Code Templates</b>
  18
  19 The VIO software component contains two user code templates with different purposes:
  20   - VIO:Custom: This file is an empty stub with all functions that are defined in the header file that can be used to
  21     implement the VIO layer for the hardware that is used in the application.
  22   - VIO:Virtual: This file uses a fixed memory location to emulate the VIO functionality and can be used off-the-shelf.
  23
  24 <b>VIO Memory Location Structure</b>
  25
  26 For testing purposes, it is required to have fixed memory locations that are used to read/store values. In the VIO:Virtual
  27 template file (\b %vio.c), an exemplary implementation is shown:
  28
  29 \code
  30 // Input, output variables
  31 __USED uint32_t vioSignalIn;                // Memory for incoming signal
  32 __USED uint32_t vioSignalOut;               // Memory for outgoing signal
  33 __USED int32_t  vioValue[VIO_VALUE_NUM];    // Memory for value used in vioGetValue/vioSetValue
  34 \endcode
  35
  36 Use these memory locations to monitor or set the variables as required in the application.
  37
  38 Two defines are available that help to disconnect the actual peripherals and enable virtual I/Os: \c CMSIS_VIN and
  39 \c CMSIS_VOUT. They help to write code that can be used in testing environments without real hardware access. The following
  40 implementation example shows such code:
  41
  42 <b>Code Example (VIO Implementation)</b>
  43 \code
  44 // Initialize test input, output.
  45 void vioInit (void) {
  46 #if !defined CMSIS_VIN
  47 // Add user variables here:
  48
  49 #endif
  50 #if !defined CMSIS_VOUT
  51 // Add user variables here:
  52
  53 #endif
  54
  55   vioSignalIn  = 0U;
  56   vioSignalOut = 0U;
  57
  58   memset(vioValue, 0, sizeof(vioValue));
  59
  60 #if !defined CMSIS_VOUT
  61 // Add user code here:
  62 // <code vioInit output>
  63
  64   BSP_LED_Init(LED_BLUE);
  65   BSP_LED_Init(LED_RED);
  66   BSP_LED_Init(LED_GREEN);
  67 // </code>
  68 #endif
  69
  70 #if !defined CMSIS_VIN
  71 // Add user code here:
  72 // <code vioInit input>
  73
  74   BSP_PB_Init(BUTTON_USER, BUTTON_MODE_GPIO);
  75 // </code>
  76 #endif
  77
  78   return;
  79 }
  80 \endcode
  81
  82 <b>Memory display in IDEs</b>
  83
  84 Arm Keil MDK uses the provided SCVD file to display the VIO signals in Component Viewer:
  85
  86 \image html vioComponentViewer.png
  87
  88 @{
  89 */
  90
  91 /**
  92 \defgroup vioSignals_gr  Signals
  93 \ingroup vio_interface_gr
  94 \brief Signal related defines.
  95 \details
  96 @{
  97 \def vioLED0
  98 \def vioLED1
  99 \def vioLED2
 100 \def vioLED3
 101 \def vioLED4
 102 \def vioLED5
 103 \def vioLED6
 104 \def vioLED7
 105 \def vioLEDon
 106 \def vioLEDoff
 107 \def vioBUTTON0
 108 \def vioBUTTON1
 109 \def vioBUTTON2
 110 \def vioBUTTON3
 111 \def vioJOYup
 112 \def vioJOYdown
 113 \def vioJOYleft
 114 \def vioJOYright
 115 \def vioJOYselect
 116 \def vioJOYall
 117 @}
 118 */
 119
 120 /**
 121 \defgroup vioValueIDs_gr  Value IDs
 122 \ingroup vio_interface_gr
 123 \brief Value Identifier related defines.
 124 \details
 125 @{
 126 \def vioAIN0
 127 \def vioAIN1
 128 \def vioAIN2
 129 \def vioAIN3
 130 \def vioAOUT0
 131 @}
 132 */
 133
 134
 135 void vioInit (void) {};
 136 /**
 137 \fn void vioInit (void)
 138 \details
 139 The function \b vioInit initializes the VIO interface. Use it to initialize any connected hardware that is used to
 140 map VIO signals.
 141
 142 \b Code \b Example:
 143 \code
 144 #include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
 145
 146 int main (void) {
 147
 148   // System Initialization
 149   SystemCoreClockUpdate();
 150   vioInit();
 151   // ...
 152
 153 }
 154 \endcode
 155 ***************************************************************************************************************************/
 156
 157 void vioSetSignal (uint32_t mask, uint32_t signal) {};
 158 /**
 159 \fn void vioSetSignal (uint32_t mask, uint32_t signal)
 160 \details
 161 The function \b vioSetSignal set a \a signal to an output specified by \a mask. Use this function to map VIOs to actual
 162 hardware for displaying signals on a target board.
 163
 164 Refer to \ref vioSignals_gr for information about the possible \a mask and \a signal values.
 165
 166 \b Code \b Example:
 167 \code
 168 #include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
 169
 170 int main (void) {
 171
 172   vioInit();
 173   vioSetSignal(vioLED0, vioLEDon);
 174   // ...
 175   vioSetSignal(vioLED0, vioLEDoff);
 176 }
 177 \endcode
 178 ***************************************************************************************************************************/
 179
 180 uint32_t vioGetSignal (uint32_t mask) {
 181   return (0);
 182 };
 183 /**
 184 \fn uint32_t vioGetSignal (uint32_t mask)
 185 \details
 186 The function \b vioGetSignal retrieves a signal from an input identified by \a mask. Use this function to read data from any
 187 input that is provided.
 188
 189 Refer to \ref vioSignals_gr for information about the possible \a mask values.
 190
 191 \b Code \b Example:
 192 \code
 193 #include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
 194
 195 int main (void) {
 196   uint32_t state;
 197   uint32_t last = 0U;
 198
 199   vioInit();
 200   for (;;) {
 201     state = (vioGetSignal (vioBUTTON0)); // Get pressed button state
 202     if (state != last){
 203       if (state == vioBUTTON0){
 204         // do something
 205       }
 206     }
 207     last = state;
 208   }
 209 }
 210 \endcode
 211 ***************************************************************************************************************************/
 212
 213 void vioSetValue (uint32_t id, int32_t value) {};
 214 /**
 215 \fn void vioSetValue (uint32_t id, int32_t value)
 216 \details
 217 The function \b vioSetValue set the \a value to the output identified by \a id. Use this function to set states of I/Os for
 218 example.
 219
 220 Refer to \ref vioValueIDs_gr for information about \a id.
 221
 222 \b Code \b Example:
 223 \code
 224 #include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
 225
 226 int main (void) {
 227
 228   vioInit();
 229   vioSetValue(vioAOUT0, 1024);
 230 }
 231 \endcode
 232 ***************************************************************************************************************************/
 233
 234 int32_t vioGetValue (uint32_t id) {
 235   return (0);
 236 };
 237 /**
 238 \fn int32_t vioGetValue (uint32_t id)
 239 \details
 240 The function \b vioGetValue retrieves a value from the input identified by \a id. Use this function to read data from inputs.
 241
 242 Refer to \ref vioValueIDs_gr for information about \a id.
 243
 244 \b Code \b Example:
 245 \code
 246 #include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
 247
 248 int main (void) {
 249   uint32_t button;
 250
 251   vioInit();
 252   button = vioGetValue(vioBUTTON0);
 253 }
 254 \endcode
 255 ***************************************************************************************************************************/
 256
 257 /**
 258 @}
 259 */
 260 // End VIO Interface