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