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 //--------------------------------------------------------------------------------------------------
156 /**
157  * Type for handler called when a server disconnects.
158  */
159 //--------------------------------------------------------------------------------------------------
160 typedef void (*le_gpio_DisconnectHandler_t)(void *);
161 
162 //--------------------------------------------------------------------------------------------------
163 /**
164  *
165  * Connect the current client thread to the service providing this API. Block until the service is
166  * 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 //--------------------------------------------------------------------------------------------------
176 (
177  void
178 );
179 
180 //--------------------------------------------------------------------------------------------------
181 /**
182  *
183  * Try to connect the current client thread to the service providing this API. Return with an error
184  * if the service is not available.
185  *
186  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
187  * called before any other functions in this API. Normally, ConnectService is automatically called
188  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
189  *
190  * This function is created automatically.
191  *
192  * @return
193  * - LE_OK if the client connected successfully to the service.
194  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
195  * bound.
196  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
197  * - LE_COMM_ERROR if the Service Directory cannot be reached.
198  */
199 //--------------------------------------------------------------------------------------------------
201 (
202  void
203 );
204 
205 //--------------------------------------------------------------------------------------------------
206 /**
207  * Set handler called when server disconnection is detected.
208  *
209  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
210  * to continue without exiting, it should call longjmp() from inside the handler.
211  */
212 //--------------------------------------------------------------------------------------------------
214 (
215  le_gpio_DisconnectHandler_t disconnectHandler,
216  void *contextPtr
217 );
218 
219 //--------------------------------------------------------------------------------------------------
220 /**
221  *
222  * Disconnect the current client thread from the service providing this API.
223  *
224  * Normally, this function doesn't need to be called. After this function is called, there's no
225  * longer a connection to the service, and the functions in this API can't be used. For details, see
226  * @ref apiFilesC_client.
227  *
228  * This function is created automatically.
229  */
230 //--------------------------------------------------------------------------------------------------
232 (
233  void
234 );
235 
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  * Pin polarities.
240  */
241 //--------------------------------------------------------------------------------------------------
242 
243 
244 //--------------------------------------------------------------------------------------------------
245 /**
246  * State change event handler (callback).
247  */
248 //--------------------------------------------------------------------------------------------------
249 
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Edge transitions.
254  */
255 //--------------------------------------------------------------------------------------------------
256 
257 
258 //--------------------------------------------------------------------------------------------------
259 /**
260  * Reference type used by Add/Remove functions for EVENT 'le_gpio_ChangeEvent'
261  */
262 //--------------------------------------------------------------------------------------------------
263 
264 
265 //--------------------------------------------------------------------------------------------------
266 /**
267  * Pull up or down.
268  */
269 //--------------------------------------------------------------------------------------------------
270 
271 
272 //--------------------------------------------------------------------------------------------------
273 /**
274  * Configure the pin as an input pin.
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  le_gpio_Polarity_t polarity
280  ///< [IN] Active-high or active-low.
281 );
282 
283 //--------------------------------------------------------------------------------------------------
284 /**
285  * Configure the pin as a push-pull output pin.
286  */
287 //--------------------------------------------------------------------------------------------------
289 (
290  le_gpio_Polarity_t polarity,
291  ///< [IN] Active-high or active-low.
292  bool value
293  ///< [IN] Initial value to drive (true = active, false = inactive)
294 );
295 
296 //--------------------------------------------------------------------------------------------------
297 /**
298  * Configure the pin as a tri-state output pin.
299  *
300  * @note The initial state will be high-impedance.
301  */
302 //--------------------------------------------------------------------------------------------------
304 (
305  le_gpio_Polarity_t polarity
306  ///< [IN] Active-high or active-low.
307 );
308 
309 //--------------------------------------------------------------------------------------------------
310 /**
311  * Configure the pin as an open-drain output pin. "High" is a high-impedance state, while "Low"
312  * pulls the pin to ground.
313  */
314 //--------------------------------------------------------------------------------------------------
316 (
317  le_gpio_Polarity_t polarity,
318  ///< [IN] Active-high or active-low.
319  bool value
320  ///< [IN] Initial value to drive (true = active, false = inactive)
321 );
322 
323 //--------------------------------------------------------------------------------------------------
324 /**
325  * Enable the pull-up resistor (disables pull-down if previously enabled).
326  */
327 //--------------------------------------------------------------------------------------------------
329 (
330  void
331 );
332 
333 //--------------------------------------------------------------------------------------------------
334 /**
335  * Enable the pull-down resistor (disables pull-up if previously enabled).
336  */
337 //--------------------------------------------------------------------------------------------------
339 (
340  void
341 );
342 
343 //--------------------------------------------------------------------------------------------------
344 /**
345  * Disable the pull-up and pull-down resistors. Does nothing if both are already disabled.
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
350  void
351 );
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Set output pin to active state.
356  *
357  * @warning Only valid for output pins.
358  */
359 //--------------------------------------------------------------------------------------------------
361 (
362  void
363 );
364 
365 //--------------------------------------------------------------------------------------------------
366 /**
367  * Set output pin to inactive state.
368  *
369  * @warning Only valid for output pins.
370  */
371 //--------------------------------------------------------------------------------------------------
373 (
374  void
375 );
376 
377 //--------------------------------------------------------------------------------------------------
378 /**
379  * Set output pin to high impedance state.
380  *
381  * @warning Only valid for tri-state or open-drain output pins.
382  */
383 //--------------------------------------------------------------------------------------------------
385 (
386  void
387 );
388 
389 //--------------------------------------------------------------------------------------------------
390 /**
391  * Read value of GPIO input pin.
392  *
393  * @return true = active, false = inactive.
394  *
395  * @note It is invalid to read an output pin.
396  */
397 //--------------------------------------------------------------------------------------------------
398 bool le_gpio_Read
399 (
400  void
401 );
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Add handler function for EVENT 'le_gpio_ChangeEvent'
406  *
407  * Register a callback function to be called when an input pin changes state.
408  *
409  * If the pin is not capable of interrupt-driven operation, then it will be sampled every
410  * sampleMs milliseconds. Otherwise, sampleMs will be ignored.
411  *
412  * If this fails, either because the handler cannot be registered, or setting the
413  * edge detection fails, then it will return a NULL reference.
414  */
415 //--------------------------------------------------------------------------------------------------
416 le_gpio_ChangeEventHandlerRef_t le_gpio_AddChangeEventHandler
417 (
418  le_gpio_Edge_t trigger,
419  ///< [IN] Change(s) that should trigger the callback to be called.
420  le_gpio_ChangeCallbackFunc_t handlerPtr,
421  ///< [IN] The callback function.
422  void* contextPtr,
423  ///< [IN]
424  int32_t sampleMs
425  ///< [IN] If not interrupt capable, sample the input this often (ms).
426 );
427 
428 //--------------------------------------------------------------------------------------------------
429 /**
430  * Remove handler function for EVENT 'le_gpio_ChangeEvent'
431  */
432 //--------------------------------------------------------------------------------------------------
434 (
435  le_gpio_ChangeEventHandlerRef_t handlerRef
436  ///< [IN]
437 );
438 
439 //--------------------------------------------------------------------------------------------------
440 /**
441  * Set the edge detection mode. This function can only be used when a handler is registered
442  * in order to prevent interrupts being generated and not handled
443  */
444 //--------------------------------------------------------------------------------------------------
446 (
447  le_gpio_Edge_t trigger
448  ///< [IN] Change(s) that should trigger the callback to be called.
449 );
450 
451 //--------------------------------------------------------------------------------------------------
452 /**
453  * Turn off edge detection
454  */
455 //--------------------------------------------------------------------------------------------------
457 (
458  void
459 );
460 
461 //--------------------------------------------------------------------------------------------------
462 /**
463  * Check if the pin is configured as an output.
464  *
465  * @return true = output, false = input.
466  */
467 //--------------------------------------------------------------------------------------------------
468 bool le_gpio_IsOutput
469 (
470  void
471 );
472 
473 //--------------------------------------------------------------------------------------------------
474 /**
475  * Check if the pin is configured as an input.
476  *
477  * @return true = input, false = output.
478  */
479 //--------------------------------------------------------------------------------------------------
480 bool le_gpio_IsInput
481 (
482  void
483 );
484 
485 //--------------------------------------------------------------------------------------------------
486 /**
487  * Get the current value of edge sensing.
488  *
489  * @return The current configured value
490  *
491  * @note it is invalid to read the edge sense of an output
492  */
493 //--------------------------------------------------------------------------------------------------
494 le_gpio_Edge_t le_gpio_GetEdgeSense
495 (
496  void
497 );
498 
499 //--------------------------------------------------------------------------------------------------
500 /**
501  * Get the current value the pin polarity.
502  *
503  * @return The current configured value
504  */
505 //--------------------------------------------------------------------------------------------------
506 le_gpio_Polarity_t le_gpio_GetPolarity
507 (
508  void
509 );
510 
511 //--------------------------------------------------------------------------------------------------
512 /**
513  * Check if the pin is currently active.
514  *
515  * @return true = active, false = inactive.
516  *
517  * @note this function can only be used on output pins
518  */
519 //--------------------------------------------------------------------------------------------------
520 bool le_gpio_IsActive
521 (
522  void
523 );
524 
525 //--------------------------------------------------------------------------------------------------
526 /**
527  * Get the current value of pull up and down resistors.
528  *
529  * @return The current configured value
530  */
531 //--------------------------------------------------------------------------------------------------
532 le_gpio_PullUpDown_t le_gpio_GetPullUpDown
533 (
534  void
535 );
536 
537 #endif // LE_GPIO_INTERFACE_H_INCLUDE_GUARD
void(* le_gpio_DisconnectHandler_t)(void *)
Definition: le_gpio_interface.h:160
void le_gpio_DisconnectService(void)
bool le_gpio_IsInput(void)
le_result_t
Definition: le_basics.h:45
void le_gpio_ConnectService(void)
le_result_t le_gpio_EnablePullUp(void)
bool le_gpio_IsActive(void)
LE_FULL_API void le_gpio_SetServerDisconnectHandler(le_gpio_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_gpio_Polarity_t le_gpio_GetPolarity(void)
le_result_t le_gpio_DisableEdgeSense(void)
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)
bool le_gpio_Read(void)
le_result_t le_gpio_EnablePullDown(void)
bool le_gpio_IsOutput(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_Deactivate(void)
le_result_t le_gpio_SetEdgeSense(le_gpio_Edge_t trigger)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_gpio_TryConnectService(void)
void le_gpio_RemoveChangeEventHandler(le_gpio_ChangeEventHandlerRef_t handlerRef)
le_result_t le_gpio_SetPushPullOutput(le_gpio_Polarity_t polarity, bool value)
le_result_t le_gpio_DisableResistors(void)
le_result_t le_gpio_Activate(void)
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)