le_gpio_interface.h

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