le_gpio_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_gpio GPIO
12  *
13  * @ref le_gpio_interface.h "API Reference" <br>
14  * @ref sampleApps_gpioCf3 "GPIO sample app"
15  *
16  * <HR>
17  *
18  * This API is used by apps to control general-purpose digital input/output pins.
19  *
20  * A GPIO pin typically has one or more of the following features:
21  * - configured as an input pin or an output pin.
22  * - have an internal pull-up resistor or pull-down resistor enabled, or neither.
23  * - if an output, can be push-pull or open-drain.
24  * - if an input, can trigger an @e interrupt (asynchronous notification of state change).
25  *
26  * Output pins can be driven in three modes:
27  * - <b>push-pull</b> one transistor connects to the supply and another transistor connects to
28  * ground (only one is operated at a time).
29  * - <b>tri-state</b> same as push-pull with an added high-impedance (high Z) state to disconnect
30  * pin from both ground and supply.
31  * - <b>open drain</b> transistor connects only to ground. Can only be used to pull low.
32  *
33  * Pins also have a @e polarity mode:
34  * - <b> active-high </b> polarity pin is read/written as a digital 1 (true) when its voltage is
35  * "high" and 0 (false) when its voltage is "low" (grounded).
36  * - <b> active-low </b> pin is read/written as a digital 1 (true) when its voltage is
37  * "low" (grounded) and 0 (false) when its voltage is "high".
38  *
39  * The following functions are used to configure the GPIO pin:
40  * - SetInput() - Configure as an input pin.
41  * - SetPushPullOutput() - Configure as push-pull output pin (can drive high or low).
42  * - SetTriStateOutput() - Configure as tri-state output pin (can drive high or low or neither).
43  * - SetOpenDrainOutput() - Configure as open-drain output pin (only pulls low).
44  * - EnablePullUp() - Enables the internal pull-up resistor (and disables the pull-down).
45  * - EnablePullDown() - Enables the internal pull-down resistor (and disables the pull-up).
46  * - DisableResistors() - Disables the internal pull-up/down resistors.
47  * - SetEdgeSense() - Set the edge sensing on an input pin (only works if you have an EventHandler).
48  *
49  * To set the level of an output pin, call Activate(), Deactivate(), or SetHighZ().
50  *
51  * To poll the value of an input pin, call Read().
52  *
53  * Use the ChangeEvent to register a notification callback function to be called when the
54  * state of an input pin changes. Thje type of edge detection can then be modified by calling
55  * SetEdgeSense() or DisbleEdgeSense()
56  * @note Only one handler can be registered per pin. Subsequent attempts to register a handler
57  * will result in the client being killed.
58  *
59  * The following functions can be used to read the current setting for a GPIO Pin. In a Linux
60  * environment these values are read from the sysfs and reflect the actual value at the time
61  * the function is called.
62  * - IsOutput() - Is the pin currently an output?
63  * - IsInput() - Is the pin currently an input?
64  * - IsActive() - Is an output pin currently being driven? (corresponds to the value file in sysfs)
65  * - GetPolarity() - Retrieve the current polarity (active-low or active-high)
66  * - GetEdgeSense() - What edge sensing has been enabled on an input pin?
67  * - GetPullUpDown() - What pull-up or pull-down has been enabled?
68  *
69  * Each GPIO pin is accessed through a single IPC service. This makes it possible to use bindings
70  * to control which GPIO pins each app is allowed to access. It also simplifies the API by removing
71  * the need to specify which pin is desired and allows the pins to be named differently in the
72  * client and the server, so the client can be more portable. Only one client can connect to each pin.
73  *
74  * @section bindings Using Bindings
75  *
76  * To create a binding from your app to pin 22 of the GPIO service,
77  * add something like this to your @c .adef binding section:
78  *
79  * @verbatim
80 bindings:
81 {
82  ui.frontPanel.powerLed -> gpioService.le_gpio22
83 }
84 @endverbatim
85  *
86  * This connects your component called @c frontPanel to the instance
87  * of this API that can be used to drive GPIO 22. Setting the pin high looks like this:
88  * @code
89  {
90  // Configure the output type
91  powerLed_SetPushPullOutput(LE_GPIOPIN22_ACTIVE_HIGH, false);
92 
93  // Some time later ... set the GPIO high
94  powerLed_Activate();
95  }
96  @endcode
97  *
98  * For details on how the GPIOs exposed by this service map to a CF3 module
99  * (like the WP85), see @ref sampleApps_gpioCf3 "GPIO sample app".
100  *
101  * @section gpioConfig Configuring available GPIOs
102  *
103  * The GPIOs that are available for use are advertised in the sysfs at
104  * @verbatim /sys/class/gpio/gpiochip1/mask @endverbatim
105  * For each entry in this bitmask, a service will be advertised to allow use of the pin.
106  * However, if a pin needs to be disabled form being accessed, e.g. it carries out some system
107  * function that should not be available to apps, then it can be disabled by adding an entry to the
108  * config tree.
109  *
110  * For example, to disable pin 6 from being used, add the entry
111  * @verbatim gpioService:/pins/disabled/n @endverbatim
112  * where n is the GPIO number. The value should be set to true to disable that service. If the value
113  * is either false or absent then the service will run. Entries can be added using the config tool,
114  * for example * @verbatim config set gpioService:/pins/disabled/13 true bool@endverbatim
115  * will disable the service for pin 13. Note that specifying the type as bool is vital as the config
116  * tool defaults to the string type, and hence any value set will default to false.
117  *
118  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
119  */
120 /**
121  * @file le_gpio_interface.h
122  *
123  * Legato @ref c_gpio include file.
124  *
125  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
126  */
127 
128 #ifndef LE_GPIO_INTERFACE_H_INCLUDE_GUARD
129 #define LE_GPIO_INTERFACE_H_INCLUDE_GUARD
130 
131 
132 #include "legato.h"
133 
134 //--------------------------------------------------------------------------------------------------
135 /**
136  *
137  * Connect the current client thread to the service providing this API. Block until the service is
138  * available.
139  *
140  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
141  * called before any other functions in this API. Normally, ConnectService is automatically called
142  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
143  *
144  * This function is created automatically.
145  */
146 //--------------------------------------------------------------------------------------------------
148 (
149  void
150 );
151 
152 //--------------------------------------------------------------------------------------------------
153 /**
154  *
155  * Try to connect the current client thread to the service providing this API. Return with an error
156  * if the service is not available.
157  *
158  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
159  * called before any other functions in this API. Normally, ConnectService is automatically called
160  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
161  *
162  * This function is created automatically.
163  *
164  * @return
165  * - LE_OK if the client connected successfully to the service.
166  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
167  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
168  * - LE_COMM_ERROR if the Service Directory cannot be reached.
169  */
170 //--------------------------------------------------------------------------------------------------
172 (
173  void
174 );
175 
176 //--------------------------------------------------------------------------------------------------
177 /**
178  *
179  * Disconnect the current client thread from the service providing this API.
180  *
181  * Normally, this function doesn't need to be called. After this function is called, there's no
182  * longer a connection to the service, and the functions in this API can't be used. For details, see
183  * @ref apiFilesC_client.
184  *
185  * This function is created automatically.
186  */
187 //--------------------------------------------------------------------------------------------------
189 (
190  void
191 );
192 
193 
194 //--------------------------------------------------------------------------------------------------
195 /**
196  * Pin polarities.
197  */
198 //--------------------------------------------------------------------------------------------------
199 typedef enum
200 {
202  ///< GPIO active-high, output is 1
203 
205  ///< GPIO active-low, output is 0
206 }
208 
209 
210 //--------------------------------------------------------------------------------------------------
211 /**
212  * Edge transitions.
213  */
214 //--------------------------------------------------------------------------------------------------
215 typedef enum
216 {
218  ///< No edge detection
219 
221  ///< Notify when voltage goes from low to high.
222 
224  ///< Notify when voltage goes from high to low.
225 
227  ///< Notify when pin voltage changes state in either direction.
228 }
230 
231 
232 //--------------------------------------------------------------------------------------------------
233 /**
234  * Reference type used by Add/Remove functions for EVENT 'le_gpio_ChangeEvent'
235  */
236 //--------------------------------------------------------------------------------------------------
237 typedef struct le_gpio_ChangeEventHandler* le_gpio_ChangeEventHandlerRef_t;
238 
239 
240 //--------------------------------------------------------------------------------------------------
241 /**
242  * Pull up or down.
243  */
244 //--------------------------------------------------------------------------------------------------
245 typedef enum
246 {
248  ///< Neither resistor is enabled
249 
251  ///< Pulldown resistor is enabled
252 
254  ///< Pullup resistor is enabled
255 }
257 
258 
259 //--------------------------------------------------------------------------------------------------
260 /**
261  * State change event handler (callback).
262  *
263  * @param state
264  * New state of pin (true = active, false = inactive).
265  * @param contextPtr
266  */
267 //--------------------------------------------------------------------------------------------------
268 typedef void (*le_gpio_ChangeCallbackFunc_t)
269 (
270  bool state,
271  void* contextPtr
272 );
273 
274 //--------------------------------------------------------------------------------------------------
275 /**
276  * Configure the pin as an input pin.
277  */
278 //--------------------------------------------------------------------------------------------------
280 (
281  le_gpio_Polarity_t polarity
282  ///< [IN] Active-high or active-low.
283 );
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Configure the pin as a push-pull output pin.
288  */
289 //--------------------------------------------------------------------------------------------------
291 (
292  le_gpio_Polarity_t polarity,
293  ///< [IN] Active-high or active-low.
294 
295  bool value
296  ///< [IN] Initial value to drive (true = active, false = inactive)
297 );
298 
299 //--------------------------------------------------------------------------------------------------
300 /**
301  * Configure the pin as a tri-state output pin.
302  *
303  * @note The initial state will be high-impedance.
304  */
305 //--------------------------------------------------------------------------------------------------
307 (
308  le_gpio_Polarity_t polarity
309  ///< [IN] Active-high or active-low.
310 );
311 
312 //--------------------------------------------------------------------------------------------------
313 /**
314  * Configure the pin as an open-drain output pin. "High" is a high-impedance state, while "Low"
315  * pulls the pin to ground.
316  */
317 //--------------------------------------------------------------------------------------------------
319 (
320  le_gpio_Polarity_t polarity,
321  ///< [IN] Active-high or active-low.
322 
323  bool value
324  ///< [IN] Initial value to drive (true = active, false = inactive)
325 );
326 
327 //--------------------------------------------------------------------------------------------------
328 /**
329  * Enable the pull-up resistor (disables pull-down if previously enabled).
330  */
331 //--------------------------------------------------------------------------------------------------
333 (
334  void
335 );
336 
337 //--------------------------------------------------------------------------------------------------
338 /**
339  * Enable the pull-down resistor (disables pull-up if previously enabled).
340  */
341 //--------------------------------------------------------------------------------------------------
343 (
344  void
345 );
346 
347 //--------------------------------------------------------------------------------------------------
348 /**
349  * Disable the pull-up and pull-down resistors. Does nothing if both are already disabled.
350  */
351 //--------------------------------------------------------------------------------------------------
353 (
354  void
355 );
356 
357 //--------------------------------------------------------------------------------------------------
358 /**
359  * Set output pin to active state.
360  *
361  * @warning Only valid for output pins.
362  */
363 //--------------------------------------------------------------------------------------------------
365 (
366  void
367 );
368 
369 //--------------------------------------------------------------------------------------------------
370 /**
371  * Set output pin to inactive state.
372  *
373  * @warning Only valid for output pins.
374  */
375 //--------------------------------------------------------------------------------------------------
377 (
378  void
379 );
380 
381 //--------------------------------------------------------------------------------------------------
382 /**
383  * Set output pin to high impedance state.
384  *
385  * @warning Only valid for tri-state or open-drain output pins.
386  */
387 //--------------------------------------------------------------------------------------------------
389 (
390  void
391 );
392 
393 //--------------------------------------------------------------------------------------------------
394 /**
395  * Read value of GPIO input pin.
396  *
397  * @return true = active, false = inactive.
398  *
399  * @note It is invalid to read an output pin.
400  */
401 //--------------------------------------------------------------------------------------------------
402 bool le_gpio_Read
403 (
404  void
405 );
406 
407 //--------------------------------------------------------------------------------------------------
408 /**
409  * Add handler function for EVENT 'le_gpio_ChangeEvent'
410  *
411  * Register a callback function to be called when an input pin changes state.
412  *
413  * If the pin is not capable of interrupt-driven operation, then it will be sampled every
414  * sampleMs milliseconds. Otherwise, sampleMs will be ignored.
415  *
416  * If this fails, either because the handler cannot be registered, or setting the
417  * edge detection fails, then it will return a NULL reference.
418  */
419 //--------------------------------------------------------------------------------------------------
421 (
422  le_gpio_Edge_t trigger,
423  ///< [IN] Change(s) that should trigger the callback to be called.
424 
425  le_gpio_ChangeCallbackFunc_t handlerPtr,
426  ///< [IN]
427 
428  void* contextPtr,
429  ///< [IN]
430 
431  int32_t sampleMs
432  ///< [IN] If not interrupt capable, sample the input this often (ms).
433 );
434 
435 //--------------------------------------------------------------------------------------------------
436 /**
437  * Remove handler function for EVENT 'le_gpio_ChangeEvent'
438  */
439 //--------------------------------------------------------------------------------------------------
441 (
442  le_gpio_ChangeEventHandlerRef_t addHandlerRef
443  ///< [IN]
444 );
445 
446 //--------------------------------------------------------------------------------------------------
447 /**
448  * Set the edge detection mode. This function can only be used when a handler is registered
449  * in order to prevent interrupts being generated and not handled
450  */
451 //--------------------------------------------------------------------------------------------------
453 (
454  le_gpio_Edge_t trigger
455  ///< [IN] Change(s) that should trigger the callback to be called.
456 );
457 
458 //--------------------------------------------------------------------------------------------------
459 /**
460  * Turn off edge detection
461  */
462 //--------------------------------------------------------------------------------------------------
464 (
465  void
466 );
467 
468 //--------------------------------------------------------------------------------------------------
469 /**
470  * Check if the pin is configured as an output.
471  *
472  * @return true = output, false = input.
473  */
474 //--------------------------------------------------------------------------------------------------
475 bool le_gpio_IsOutput
476 (
477  void
478 );
479 
480 //--------------------------------------------------------------------------------------------------
481 /**
482  * Check if the pin is configured as an input.
483  *
484  * @return true = input, false = output.
485  */
486 //--------------------------------------------------------------------------------------------------
487 bool le_gpio_IsInput
488 (
489  void
490 );
491 
492 //--------------------------------------------------------------------------------------------------
493 /**
494  * Get the current value of edge sensing.
495  *
496  * @return The current configured value
497  *
498  * @note it is invalid to read the edge sense of an output
499  */
500 //--------------------------------------------------------------------------------------------------
502 (
503  void
504 );
505 
506 //--------------------------------------------------------------------------------------------------
507 /**
508  * Get the current value the pin polarity.
509  *
510  * @return The current configured value
511  */
512 //--------------------------------------------------------------------------------------------------
514 (
515  void
516 );
517 
518 //--------------------------------------------------------------------------------------------------
519 /**
520  * Check if the pin is currently active.
521  *
522  * @return true = active, false = inactive.
523  *
524  * @note this function can only be used on output pins
525  */
526 //--------------------------------------------------------------------------------------------------
527 bool le_gpio_IsActive
528 (
529  void
530 );
531 
532 //--------------------------------------------------------------------------------------------------
533 /**
534  * Get the current value of pull up and down resistors.
535  *
536  * @return The current configured value
537  */
538 //--------------------------------------------------------------------------------------------------
540 (
541  void
542 );
543 
544 
545 #endif // LE_GPIO_INTERFACE_H_INCLUDE_GUARD
546 
void le_gpio_DisconnectService(void)
bool le_gpio_IsInput(void)
GPIO active-high, output is 1.
Definition: le_gpio_interface.h:201
Notify when pin voltage changes state in either direction.
Definition: le_gpio_interface.h:226
le_result_t
Definition: le_basics.h:35
le_gpio_PullUpDown_t
Definition: le_gpio_interface.h:245
void le_gpio_ConnectService(void)
le_result_t le_gpio_EnablePullUp(void)
bool le_gpio_IsActive(void)
le_gpio_Polarity_t le_gpio_GetPolarity(void)
le_result_t le_gpio_DisableEdgeSense(void)
Notify when voltage goes from high to low.
Definition: le_gpio_interface.h:223
GPIO active-low, output is 0.
Definition: le_gpio_interface.h:204
le_result_t le_gpio_SetTriStateOutput(le_gpio_Polarity_t polarity)
le_gpio_Edge_t le_gpio_GetEdgeSense(void)
le_result_t le_gpio_SetHighZ(void)
le_gpio_Polarity_t
Definition: le_gpio_interface.h:199
bool le_gpio_Read(void)
Notify when voltage goes from low to high.
Definition: le_gpio_interface.h:220
le_result_t le_gpio_EnablePullDown(void)
bool le_gpio_IsOutput(void)
Pulldown resistor is enabled.
Definition: le_gpio_interface.h:250
le_gpio_ChangeEventHandlerRef_t le_gpio_AddChangeEventHandler(le_gpio_Edge_t trigger, le_gpio_ChangeCallbackFunc_t handlerPtr, void *contextPtr, int32_t sampleMs)
le_result_t le_gpio_Deactivate(void)
le_result_t le_gpio_SetEdgeSense(le_gpio_Edge_t trigger)
le_result_t le_gpio_TryConnectService(void)
void le_gpio_RemoveChangeEventHandler(le_gpio_ChangeEventHandlerRef_t addHandlerRef)
Neither resistor is enabled.
Definition: le_gpio_interface.h:247
le_result_t le_gpio_SetPushPullOutput(le_gpio_Polarity_t polarity, bool value)
No edge detection.
Definition: le_gpio_interface.h:217
struct le_gpio_ChangeEventHandler * le_gpio_ChangeEventHandlerRef_t
Definition: le_gpio_interface.h:237
le_result_t le_gpio_DisableResistors(void)
le_result_t le_gpio_Activate(void)
Pullup resistor is enabled.
Definition: le_gpio_interface.h:253
void(* le_gpio_ChangeCallbackFunc_t)(bool state, void *contextPtr)
Definition: le_gpio_interface.h:269
le_result_t le_gpio_SetInput(le_gpio_Polarity_t polarity)
le_gpio_PullUpDown_t le_gpio_GetPullUpDown(void)
le_result_t le_gpio_SetOpenDrainOutput(le_gpio_Polarity_t polarity, bool value)
le_gpio_Edge_t
Definition: le_gpio_interface.h:215