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 //--------------------------------------------------------------------------------------------------
  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 //--------------------------------------------------------------------------------------------------
  175 void le_gpio_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  200 le_result_t le_gpio_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  213 LE_FULL_API void le_gpio_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  231 void le_gpio_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  277 le_result_t le_gpio_SetInput
  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 //--------------------------------------------------------------------------------------------------
  288 le_result_t le_gpio_SetPushPullOutput
  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 //--------------------------------------------------------------------------------------------------
  303 le_result_t le_gpio_SetTriStateOutput
  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 //--------------------------------------------------------------------------------------------------
  315 le_result_t le_gpio_SetOpenDrainOutput
  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 //--------------------------------------------------------------------------------------------------
  328 le_result_t le_gpio_EnablePullUp
  329 (
  330     void
  331 );
  332 
  333 //--------------------------------------------------------------------------------------------------
  334 /**
  335  * Enable the pull-down resistor (disables pull-up if previously enabled).
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 le_result_t le_gpio_EnablePullDown
  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 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_gpio_DisableResistors
  349 (
  350     void
  351 );
  352 
  353 //--------------------------------------------------------------------------------------------------
  354 /**
  355  * Set output pin to active state.
  356  *
  357  * @warning Only valid for output pins.
  358  */
  359 //--------------------------------------------------------------------------------------------------
  360 le_result_t le_gpio_Activate
  361 (
  362     void
  363 );
  364 
  365 //--------------------------------------------------------------------------------------------------
  366 /**
  367  * Set output pin to inactive state.
  368  *
  369  * @warning Only valid for output pins.
  370  */
  371 //--------------------------------------------------------------------------------------------------
  372 le_result_t le_gpio_Deactivate
  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 //--------------------------------------------------------------------------------------------------
  384 le_result_t le_gpio_SetHighZ
  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 //--------------------------------------------------------------------------------------------------
  433 void le_gpio_RemoveChangeEventHandler
  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 //--------------------------------------------------------------------------------------------------
  445 le_result_t le_gpio_SetEdgeSense
  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 //--------------------------------------------------------------------------------------------------
  456 le_result_t le_gpio_DisableEdgeSense
  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
le_gpio_DisconnectHandler_t
void(* le_gpio_DisconnectHandler_t)(void *)
Definition: le_gpio_interface.h:160
le_gpio_DisconnectService
void le_gpio_DisconnectService(void)
le_gpio_IsInput
bool le_gpio_IsInput(void)
le_result_t
le_result_t
Definition: le_basics.h:35
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_SetServerDisconnectHandler
LE_FULL_API void le_gpio_SetServerDisconnectHandler(le_gpio_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_gpio_GetPolarity
le_gpio_Polarity_t le_gpio_GetPolarity(void)
le_gpio_DisableEdgeSense
le_result_t le_gpio_DisableEdgeSense(void)
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_Read
bool le_gpio_Read(void)
le_gpio_EnablePullDown
le_result_t le_gpio_EnablePullDown(void)
le_gpio_IsOutput
bool le_gpio_IsOutput(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_Deactivate
le_result_t le_gpio_Deactivate(void)
le_gpio_SetEdgeSense
le_result_t le_gpio_SetEdgeSense(le_gpio_Edge_t trigger)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_gpio_TryConnectService
le_result_t le_gpio_TryConnectService(void)
le_gpio_RemoveChangeEventHandler
void le_gpio_RemoveChangeEventHandler(le_gpio_ChangeEventHandlerRef_t handlerRef)
le_gpio_SetPushPullOutput
le_result_t le_gpio_SetPushPullOutput(le_gpio_Polarity_t polarity, bool value)
le_gpio_DisableResistors
le_result_t le_gpio_DisableResistors(void)
le_gpio_Activate
le_result_t le_gpio_Activate(void)
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)