le_gpio_interface.h

    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 //--------------------------------------------------------------------------------------------------
  179 void le_gpio_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  204 le_result_t le_gpio_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  217 LE_FULL_API void le_gpio_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  235 void le_gpio_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  281 le_result_t le_gpio_SetInput
  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 //--------------------------------------------------------------------------------------------------
  292 le_result_t le_gpio_SetPushPullOutput
  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 //--------------------------------------------------------------------------------------------------
  307 le_result_t le_gpio_SetTriStateOutput
  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 //--------------------------------------------------------------------------------------------------
  319 le_result_t le_gpio_SetOpenDrainOutput
  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 //--------------------------------------------------------------------------------------------------
  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     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 //--------------------------------------------------------------------------------------------------
  437 void le_gpio_RemoveChangeEventHandler
  438 (
  439     le_gpio_ChangeEventHandlerRef_t handlerRef
  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 //--------------------------------------------------------------------------------------------------
  449 le_result_t le_gpio_SetEdgeSense
  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 //--------------------------------------------------------------------------------------------------
  460 le_result_t le_gpio_DisableEdgeSense
  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 //--------------------------------------------------------------------------------------------------
  498 le_gpio_Edge_t le_gpio_GetEdgeSense
  499 (
  500     void
  501 );
  502 
  503 //--------------------------------------------------------------------------------------------------
  504 /**
  505  * Get the current value the pin polarity.
  506  *
  507  * @return The current configured value
  508  */
  509 //--------------------------------------------------------------------------------------------------
  510 le_gpio_Polarity_t le_gpio_GetPolarity
  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 //--------------------------------------------------------------------------------------------------
  536 le_gpio_PullUpDown_t le_gpio_GetPullUpDown
  537 (
  538     void
  539 );
  540 
  541 /** @} **/
  542 
  543 #endif // LE_GPIO_INTERFACE_H_INCLUDE_GUARD
le_gpio_SetTriStateOutput
le_result_t le_gpio_SetTriStateOutput(le_gpio_Polarity_t polarity)
le_gpio_IsActive
bool le_gpio_IsActive(void)
le_gpio_GetPullUpDown
le_gpio_PullUpDown_t le_gpio_GetPullUpDown(void)
le_gpio_ChangeCallbackFunc_t
void(* le_gpio_ChangeCallbackFunc_t)(bool state, void *contextPtr)
Definition: le_gpio_common.h:93
le_gpio_GetPolarity
le_gpio_Polarity_t le_gpio_GetPolarity(void)
le_gpio_GetEdgeSense
le_gpio_Edge_t le_gpio_GetEdgeSense(void)
le_gpio_DisconnectHandler_t
void(* le_gpio_DisconnectHandler_t)(void *)
Definition: le_gpio_interface.h:164
le_gpio_DisableEdgeSense
le_result_t le_gpio_DisableEdgeSense(void)
le_result_t
le_result_t
Definition: le_basics.h:46
le_gpio_RemoveChangeEventHandler
void le_gpio_RemoveChangeEventHandler(le_gpio_ChangeEventHandlerRef_t handlerRef)
le_gpio_DisableResistors
le_result_t le_gpio_DisableResistors(void)
le_gpio_ChangeEventHandlerRef_t
struct le_gpio_ChangeEventHandler * le_gpio_ChangeEventHandlerRef_t
Definition: le_gpio_common.h:67
le_gpio_Edge_t
le_gpio_Edge_t
Definition: le_gpio_common.h:48
le_gpio_SetEdgeSense
le_result_t le_gpio_SetEdgeSense(le_gpio_Edge_t trigger)
le_gpio_IsInput
bool le_gpio_IsInput(void)
le_gpio_SetHighZ
le_result_t le_gpio_SetHighZ(void)
le_gpio_EnablePullUp
le_result_t le_gpio_EnablePullUp(void)
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_SetOpenDrainOutput
le_result_t le_gpio_SetOpenDrainOutput(le_gpio_Polarity_t polarity, bool value)
le_gpio_DisconnectService
void le_gpio_DisconnectService(void)
le_gpio_Deactivate
le_result_t le_gpio_Deactivate(void)
le_gpio_TryConnectService
le_result_t le_gpio_TryConnectService(void)
le_gpio_EnablePullDown
le_result_t le_gpio_EnablePullDown(void)
le_gpio_Activate
le_result_t le_gpio_Activate(void)
le_gpio_common.h
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_gpio_SetInput
le_result_t le_gpio_SetInput(le_gpio_Polarity_t polarity)
le_gpio_Polarity_t
le_gpio_Polarity_t
Definition: le_gpio_common.h:33
le_gpio_PullUpDown_t
le_gpio_PullUpDown_t
Definition: le_gpio_common.h:75
le_gpio_SetServerDisconnectHandler
LE_FULL_API void le_gpio_SetServerDisconnectHandler(le_gpio_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_gpio_IsOutput
bool le_gpio_IsOutput(void)
le_gpio_Read
bool le_gpio_Read(void)
le_gpio_ConnectService
void le_gpio_ConnectService(void)
le_gpio_SetPushPullOutput
le_result_t le_gpio_SetPushPullOutput(le_gpio_Polarity_t polarity, bool value)