1/**
2\defgroup vio_interface_gr VIO
3\brief API for Virtual I/O (VIO) (%cmsis_vio.h)
4\details
5
6The VIO software component is a virtual I/O abstraction for peripherals that are typically used in example projects. It
7enables developers to move from an evaluation kit to custom hardware and helps to scale project examples at large to many
8development 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
14The 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
19The 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
26For testing purposes, it is required to have fixed memory locations that are used to read/store values. In the VIO:Virtual
27template 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
36Use these memory locations to monitor or set the variables as required in the application.
37
38Two 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
40implementation example shows such code:
41
42<b>Code Example (VIO Implementation)</b>
43\code
44// Initialize test input, output.
45void 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
84Arm 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
135void vioInit (void) {};
136/**
137\fn void vioInit (void)
138\details
139The function \b vioInit initializes the VIO interface. Use it to initialize any connected hardware that is used to
140map VIO signals.
141
142\b Code \b Example:
143\code
144#include "cmsis_vio.h"                  // ::CMSIS Driver:VIO
145
146int main (void) {
147
148  // System Initialization
149  SystemCoreClockUpdate();
150  vioInit();
151  // ...
152
153}
154\endcode
155***************************************************************************************************************************/
156
157void vioSetSignal (uint32_t mask, uint32_t signal) {};
158/**
159\fn void vioSetSignal (uint32_t mask, uint32_t signal)
160\details
161The function \b vioSetSignal set a \a signal to an output specified by \a mask. Use this function to map VIOs to actual
162hardware for displaying signals on a target board.
163
164Refer 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
170int main (void) {
171
172  vioInit();
173  vioSetSignal(vioLED0, vioLEDon);
174  // ...
175  vioSetSignal(vioLED0, vioLEDoff);
176}
177\endcode
178***************************************************************************************************************************/
179
180uint32_t vioGetSignal (uint32_t mask) {
181  return (0);
182};
183/**
184\fn uint32_t vioGetSignal (uint32_t mask)
185\details
186The function \b vioGetSignal retrieves a signal from an input identified by \a mask. Use this function to read data from any
187input that is provided.
188
189Refer 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
195int 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
213void vioSetValue (uint32_t id, int32_t value) {};
214/**
215\fn void vioSetValue (uint32_t id, int32_t value)
216\details
217The function \b vioSetValue set the \a value to the output identified by \a id. Use this function to set states of I/Os for
218example.
219
220Refer 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
226int main (void) {
227
228  vioInit();
229  vioSetValue(vioAOUT0, 1024);
230}
231\endcode
232***************************************************************************************************************************/
233
234int32_t vioGetValue (uint32_t id) {
235  return (0);
236};
237/**
238\fn int32_t vioGetValue (uint32_t id)
239\details
240The function \b vioGetValue retrieves a value from the input identified by \a id. Use this function to read data from inputs.
241
242Refer 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
248int 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
261