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