le_gpio_interface.h

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