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 // Internal includes for this interface
154 #include "le_gpio_common.h"
155 /** @addtogroup le_gpio le_gpio API Reference
156  * @{
157  * @file le_gpio_common.h
158  * @file le_gpio_interface.h **/
159 //--------------------------------------------------------------------------------------------------
160 /**
161  * Type for handler called when a server disconnects.
162  */
163 //--------------------------------------------------------------------------------------------------
164 typedef void (*le_gpio_DisconnectHandler_t)(void *);
165 
166 //--------------------------------------------------------------------------------------------------
167 /**
168  *
169  * Connect the current client thread to the service providing this API. Block until the service is
170  * available.
171  *
172  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
173  * called before any other functions in this API. Normally, ConnectService is automatically called
174  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
175  *
176  * This function is created automatically.
177  */
178 //--------------------------------------------------------------------------------------------------
180 (
181  void
182 );
183 
184 //--------------------------------------------------------------------------------------------------
185 /**
186  *
187  * Try to connect the current client thread to the service providing this API. Return with an error
188  * if the service is not available.
189  *
190  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
191  * called before any other functions in this API. Normally, ConnectService is automatically called
192  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
193  *
194  * This function is created automatically.
195  *
196  * @return
197  * - LE_OK if the client connected successfully to the service.
198  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
199  * bound.
200  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
201  * - LE_COMM_ERROR if the Service Directory cannot be reached.
202  */
203 //--------------------------------------------------------------------------------------------------
205 (
206  void
207 );
208 
209 //--------------------------------------------------------------------------------------------------
210 /**
211  * Set handler called when server disconnection is detected.
212  *
213  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
214  * to continue without exiting, it should call longjmp() from inside the handler.
215  */
216 //--------------------------------------------------------------------------------------------------
218 (
219  le_gpio_DisconnectHandler_t disconnectHandler,
220  void *contextPtr
221 );
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  *
226  * Disconnect the current client thread from the service providing this API.
227  *
228  * Normally, this function doesn't need to be called. After this function is called, there's no
229  * longer a connection to the service, and the functions in this API can't be used. For details, see
230  * @ref apiFilesC_client.
231  *
232  * This function is created automatically.
233  */
234 //--------------------------------------------------------------------------------------------------
236 (
237  void
238 );
239 
240 
241 //--------------------------------------------------------------------------------------------------
242 /**
243  * Pin polarities.
244  */
245 //--------------------------------------------------------------------------------------------------
246 
247 
248 //--------------------------------------------------------------------------------------------------
249 /**
250  * State change event handler (callback).
251  */
252 //--------------------------------------------------------------------------------------------------
253 
254 
255 //--------------------------------------------------------------------------------------------------
256 /**
257  * Edge transitions.
258  */
259 //--------------------------------------------------------------------------------------------------
260 
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Reference type used by Add/Remove functions for EVENT 'le_gpio_ChangeEvent'
265  */
266 //--------------------------------------------------------------------------------------------------
267 
268 
269 //--------------------------------------------------------------------------------------------------
270 /**
271  * Pull up or down.
272  */
273 //--------------------------------------------------------------------------------------------------
274 
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Configure the pin as an input pin.
279  */
280 //--------------------------------------------------------------------------------------------------
282 (
283  le_gpio_Polarity_t polarity
284  ///< [IN] Active-high or active-low.
285 );
286 
287 //--------------------------------------------------------------------------------------------------
288 /**
289  * Configure the pin as a push-pull output pin.
290  */
291 //--------------------------------------------------------------------------------------------------
293 (
294  le_gpio_Polarity_t polarity,
295  ///< [IN] Active-high or active-low.
296  bool value
297  ///< [IN] Initial value to drive (true = active, false = inactive)
298 );
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Configure the pin as a tri-state output pin.
303  *
304  * @note The initial state will be high-impedance.
305  */
306 //--------------------------------------------------------------------------------------------------
308 (
309  le_gpio_Polarity_t polarity
310  ///< [IN] Active-high or active-low.
311 );
312 
313 //--------------------------------------------------------------------------------------------------
314 /**
315  * Configure the pin as an open-drain output pin. "High" is a high-impedance state, while "Low"
316  * pulls the pin to ground.
317  */
318 //--------------------------------------------------------------------------------------------------
320 (
321  le_gpio_Polarity_t polarity,
322  ///< [IN] Active-high or active-low.
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  le_gpio_ChangeCallbackFunc_t handlerPtr,
425  ///< [IN] The callback function.
426  void* contextPtr,
427  ///< [IN]
428  int32_t sampleMs
429  ///< [IN] If not interrupt capable, sample the input this often (ms).
430 );
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Remove handler function for EVENT 'le_gpio_ChangeEvent'
435  */
436 //--------------------------------------------------------------------------------------------------
438 (
440  ///< [IN]
441 );
442 
443 //--------------------------------------------------------------------------------------------------
444 /**
445  * Set the edge detection mode. This function can only be used when a handler is registered
446  * in order to prevent interrupts being generated and not handled
447  */
448 //--------------------------------------------------------------------------------------------------
450 (
451  le_gpio_Edge_t trigger
452  ///< [IN] Change(s) that should trigger the callback to be called.
453 );
454 
455 //--------------------------------------------------------------------------------------------------
456 /**
457  * Turn off edge detection
458  */
459 //--------------------------------------------------------------------------------------------------
461 (
462  void
463 );
464 
465 //--------------------------------------------------------------------------------------------------
466 /**
467  * Check if the pin is configured as an output.
468  *
469  * @return true = output, false = input.
470  */
471 //--------------------------------------------------------------------------------------------------
472 bool le_gpio_IsOutput
473 (
474  void
475 );
476 
477 //--------------------------------------------------------------------------------------------------
478 /**
479  * Check if the pin is configured as an input.
480  *
481  * @return true = input, false = output.
482  */
483 //--------------------------------------------------------------------------------------------------
484 bool le_gpio_IsInput
485 (
486  void
487 );
488 
489 //--------------------------------------------------------------------------------------------------
490 /**
491  * Get the current value of edge sensing.
492  *
493  * @return The current configured value
494  *
495  * @note it is invalid to read the edge sense of an output
496  */
497 //--------------------------------------------------------------------------------------------------
499 (
500  void
501 );
502 
503 //--------------------------------------------------------------------------------------------------
504 /**
505  * Get the current value the pin polarity.
506  *
507  * @return The current configured value
508  */
509 //--------------------------------------------------------------------------------------------------
511 (
512  void
513 );
514 
515 //--------------------------------------------------------------------------------------------------
516 /**
517  * Check if the pin is currently active.
518  *
519  * @return true = active, false = inactive.
520  *
521  * @note this function can only be used on output pins
522  */
523 //--------------------------------------------------------------------------------------------------
524 bool le_gpio_IsActive
525 (
526  void
527 );
528 
529 //--------------------------------------------------------------------------------------------------
530 /**
531  * Get the current value of pull up and down resistors.
532  *
533  * @return The current configured value
534  */
535 //--------------------------------------------------------------------------------------------------
537 (
538  void
539 );
540 
541 /** @} **/
542 
543 #endif // LE_GPIO_INTERFACE_H_INCLUDE_GUARD
le_result_t le_gpio_SetTriStateOutput(le_gpio_Polarity_t polarity)
bool le_gpio_IsActive(void)
le_gpio_PullUpDown_t le_gpio_GetPullUpDown(void)
void(* le_gpio_ChangeCallbackFunc_t)(bool state, void *contextPtr)
Definition: le_gpio_common.h:93
le_gpio_Polarity_t le_gpio_GetPolarity(void)
le_gpio_Edge_t le_gpio_GetEdgeSense(void)
void(* le_gpio_DisconnectHandler_t)(void *)
Definition: le_gpio_interface.h:164
le_result_t le_gpio_DisableEdgeSense(void)
le_result_t
Definition: le_basics.h:46
void le_gpio_RemoveChangeEventHandler(le_gpio_ChangeEventHandlerRef_t handlerRef)
le_result_t le_gpio_DisableResistors(void)
struct le_gpio_ChangeEventHandler * le_gpio_ChangeEventHandlerRef_t
Definition: le_gpio_common.h:67
le_gpio_Edge_t
Definition: le_gpio_common.h:48
le_result_t le_gpio_SetEdgeSense(le_gpio_Edge_t trigger)
bool le_gpio_IsInput(void)
le_result_t le_gpio_SetHighZ(void)
le_result_t le_gpio_EnablePullUp(void)
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_SetOpenDrainOutput(le_gpio_Polarity_t polarity, bool value)
void le_gpio_DisconnectService(void)
le_result_t le_gpio_Deactivate(void)
le_result_t le_gpio_TryConnectService(void)
le_result_t le_gpio_EnablePullDown(void)
le_result_t le_gpio_Activate(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_gpio_SetInput(le_gpio_Polarity_t polarity)
le_gpio_Polarity_t
Definition: le_gpio_common.h:33
le_gpio_PullUpDown_t
Definition: le_gpio_common.h:75
LE_FULL_API void le_gpio_SetServerDisconnectHandler(le_gpio_DisconnectHandler_t disconnectHandler, void *contextPtr)
bool le_gpio_IsOutput(void)
bool le_gpio_Read(void)
void le_gpio_ConnectService(void)
le_result_t le_gpio_SetPushPullOutput(le_gpio_Polarity_t polarity, bool value)