nrf_gpio.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 #ifndef NRF_GPIO_H__
00034 #define NRF_GPIO_H__
00035 
00036 #include "nrf51.h"
00037 #include "nrf51_bitfields.h"
00038 
00039 /**
00040  * @defgroup nrf_gpio GPIO abstraction
00041  * @{
00042  * @ingroup nrf_drivers
00043  * @brief GPIO pin abstraction and port abstraction for reading and writing byte-wise to GPIO ports.
00044  *
00045  * Here, the GPIO ports are defined as follows:
00046  * - Port 0 -> pin 0-7
00047  * - Port 1 -> pin 8-15
00048  * - Port 2 -> pin 16-23
00049  * - Port 3 -> pin 24-31
00050  */
00051 
00052 /**
00053  * @enum nrf_gpio_port_dir_t
00054  * @brief Enumerator used for setting the direction of a GPIO port.
00055  */
00056 typedef enum
00057 {
00058     NRF_GPIO_PORT_DIR_OUTPUT,       ///<  Output
00059     NRF_GPIO_PORT_DIR_INPUT         ///<  Input
00060 } nrf_gpio_port_dir_t;
00061 
00062 /**
00063  * @enum nrf_gpio_pin_dir_t
00064  * Pin direction definitions.
00065  */
00066 typedef enum
00067 {
00068     NRF_GPIO_PIN_DIR_INPUT,   ///< Input
00069     NRF_GPIO_PIN_DIR_OUTPUT   ///< Output
00070 } nrf_gpio_pin_dir_t;
00071 
00072 /**
00073  * @enum nrf_gpio_port_select_t
00074  * @brief Enumerator used for selecting between port 0 - 3.
00075  */
00076 typedef enum
00077 {
00078     NRF_GPIO_PORT_SELECT_PORT0 = 0,           ///<  Port 0 (GPIO pin 0-7)
00079     NRF_GPIO_PORT_SELECT_PORT1,               ///<  Port 1 (GPIO pin 8-15)
00080     NRF_GPIO_PORT_SELECT_PORT2,               ///<  Port 2 (GPIO pin 16-23)
00081     NRF_GPIO_PORT_SELECT_PORT3,               ///<  Port 3 (GPIO pin 24-31)
00082 } nrf_gpio_port_select_t;
00083 
00084 /**
00085  * @enum nrf_gpio_pin_pull_t
00086  * @brief Enumerator used for selecting the pin to be pulled down or up at the time of pin configuration
00087  */
00088 typedef enum
00089 {
00090     NRF_GPIO_PIN_NOPULL   = GPIO_PIN_CNF_PULL_Disabled,                 ///<  Pin pullup resistor disabled
00091     NRF_GPIO_PIN_PULLDOWN = GPIO_PIN_CNF_PULL_Pulldown,                 ///<  Pin pulldown resistor enabled
00092     NRF_GPIO_PIN_PULLUP   = GPIO_PIN_CNF_PULL_Pullup,                   ///<  Pin pullup resistor enabled
00093 } nrf_gpio_pin_pull_t;
00094 
00095 /**
00096  * @enum nrf_gpio_pin_sense_t
00097  * @brief Enumerator used for selecting the pin to sense high or low level on the pin input.
00098  */
00099 typedef enum
00100 {
00101     NRF_GPIO_PIN_NOSENSE    = GPIO_PIN_CNF_SENSE_Disabled,              ///<  Pin sense level disabled.
00102     NRF_GPIO_PIN_SENSE_LOW  = GPIO_PIN_CNF_SENSE_Low,                   ///<  Pin sense low level.
00103     NRF_GPIO_PIN_SENSE_HIGH = GPIO_PIN_CNF_SENSE_High,                  ///<  Pin sense high level.
00104 } nrf_gpio_pin_sense_t;
00105 
00106 /**
00107  * @brief Function for configuring the GPIO pin range as outputs with normal drive strength.
00108  *        This function can be used to configure pin range as simple output with gate driving GPIO_PIN_CNF_DRIVE_S0S1 (normal cases).
00109  *
00110  * @param pin_range_start specifies the start number (inclusive) in the range of pin numbers to be configured (allowed values 0-30)
00111  *
00112  * @param pin_range_end specifies the end number (inclusive) in the range of pin numbers to be configured (allowed values 0-30)
00113  *
00114  * @note For configuring only one pin as output use @ref nrf_gpio_cfg_output
00115  *       Sense capability on the pin is disabled, and input is disconnected from the buffer as the pins are configured as output.
00116  */
00117 static __INLINE void nrf_gpio_range_cfg_output(uint32_t pin_range_start, uint32_t pin_range_end)
00118 {
00119     /*lint -e{845} // A zero has been given as right argument to operator '|'" */
00120     for (; pin_range_start <= pin_range_end; pin_range_start++)
00121     {
00122         NRF_GPIO->PIN_CNF[pin_range_start] = (GPIO_PIN_CNF_SENSE_Disabled << GPIO_PIN_CNF_SENSE_Pos)
00123                                         | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00124                                         | (GPIO_PIN_CNF_PULL_Disabled << GPIO_PIN_CNF_PULL_Pos)
00125                                         | (GPIO_PIN_CNF_INPUT_Disconnect << GPIO_PIN_CNF_INPUT_Pos)
00126                                         | (GPIO_PIN_CNF_DIR_Output << GPIO_PIN_CNF_DIR_Pos);
00127     }
00128 }
00129 
00130 /**
00131  * @brief Function for configuring the GPIO pin range as inputs with given initial value set, hiding inner details.
00132  *        This function can be used to configure pin range as simple input.
00133  *
00134  * @param pin_range_start specifies the start number (inclusive) in the range of pin numbers to be configured (allowed values 0-30)
00135  *
00136  * @param pin_range_end specifies the end number (inclusive) in the range of pin numbers to be configured (allowed values 0-30)
00137  *
00138  * @param pull_config State of the pin range pull resistor (no pull, pulled down or pulled high)
00139  *
00140  * @note  For configuring only one pin as input use @ref nrf_gpio_cfg_input
00141  *        Sense capability on the pin is disabled, and input is connected to buffer so that the GPIO->IN register is readable
00142  */
00143 static __INLINE void nrf_gpio_range_cfg_input(uint32_t pin_range_start, uint32_t pin_range_end, nrf_gpio_pin_pull_t pull_config)
00144 {
00145     /*lint -e{845} // A zero has been given as right argument to operator '|'" */
00146     for (; pin_range_start <= pin_range_end; pin_range_start++)
00147     {
00148         NRF_GPIO->PIN_CNF[pin_range_start] = (GPIO_PIN_CNF_SENSE_Disabled << GPIO_PIN_CNF_SENSE_Pos)
00149                                         | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00150                                         | (pull_config << GPIO_PIN_CNF_PULL_Pos)
00151                                         | (GPIO_PIN_CNF_INPUT_Connect << GPIO_PIN_CNF_INPUT_Pos)
00152                                         | (GPIO_PIN_CNF_DIR_Input << GPIO_PIN_CNF_DIR_Pos);
00153     }
00154 }
00155 
00156 /**
00157  * @brief Function for configuring the given GPIO pin number as output with given initial value set, hiding inner details.
00158  *        This function can be used to configure pin range as simple input with gate driving GPIO_PIN_CNF_DRIVE_S0S1 (normal cases).
00159  *
00160  * @param pin_number specifies the pin number of gpio pin numbers to be configured (allowed values 0-30)
00161  *
00162  * @note  Sense capability on the pin is disabled, and input is disconnected from the buffer as the pins are configured as output.
00163  */
00164 static __INLINE void nrf_gpio_cfg_output(uint32_t pin_number)
00165 {
00166     /*lint -e{845} // A zero has been given as right argument to operator '|'" */
00167     NRF_GPIO->PIN_CNF[pin_number] = (GPIO_PIN_CNF_SENSE_Disabled << GPIO_PIN_CNF_SENSE_Pos)
00168                                             | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00169                                             | (GPIO_PIN_CNF_PULL_Disabled << GPIO_PIN_CNF_PULL_Pos)
00170                                             | (GPIO_PIN_CNF_INPUT_Disconnect << GPIO_PIN_CNF_INPUT_Pos)
00171                                             | (GPIO_PIN_CNF_DIR_Output << GPIO_PIN_CNF_DIR_Pos);
00172 }
00173 
00174 /**
00175  * @brief Function for configuring the given GPIO pin number as input with given initial value set, hiding inner details.
00176  *        This function can be used to configure pin range as simple input with gate driving GPIO_PIN_CNF_DRIVE_S0S1 (normal cases).
00177  *
00178  * @param pin_number specifies the pin number of gpio pin numbers to be configured (allowed values 0-30)
00179  *
00180  * @param pull_config State of the pin range pull resistor (no pull, pulled down or pulled high)
00181  *
00182  * @note  Sense capability on the pin is disabled, and input is connected to buffer so that the GPIO->IN register is readable
00183  */
00184 static __INLINE void nrf_gpio_cfg_input(uint32_t pin_number, nrf_gpio_pin_pull_t pull_config)
00185 {
00186     /*lint -e{845} // A zero has been given as right argument to operator '|'" */
00187     NRF_GPIO->PIN_CNF[pin_number] = (GPIO_PIN_CNF_SENSE_Disabled << GPIO_PIN_CNF_SENSE_Pos)
00188                                         | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00189                                         | (pull_config << GPIO_PIN_CNF_PULL_Pos)
00190                                         | (GPIO_PIN_CNF_INPUT_Connect << GPIO_PIN_CNF_INPUT_Pos)
00191                                         | (GPIO_PIN_CNF_DIR_Input << GPIO_PIN_CNF_DIR_Pos);
00192 }
00193 
00194 /**
00195  * @brief Function for configuring the given GPIO pin number as input with given initial value set, hiding inner details.
00196  *        This function can be used to configure pin range as simple input with gate driving GPIO_PIN_CNF_DRIVE_S0S1 (normal cases).
00197  *        Sense capability on the pin is configurable, and input is connected to buffer so that the GPIO->IN register is readable.
00198  *
00199  * @param pin_number specifies the pin number of gpio pin numbers to be configured (allowed values 0-30).
00200  *
00201  * @param pull_config state of the pin pull resistor (no pull, pulled down or pulled high).
00202  *
00203  * @param sense_config sense level of the pin (no sense, sense low or sense high).
00204  */
00205 static __INLINE void nrf_gpio_cfg_sense_input(uint32_t pin_number, nrf_gpio_pin_pull_t pull_config, nrf_gpio_pin_sense_t sense_config)
00206 {
00207     /*lint -e{845} // A zero has been given as right argument to operator '|'" */
00208     NRF_GPIO->PIN_CNF[pin_number] = (sense_config << GPIO_PIN_CNF_SENSE_Pos)
00209                                         | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00210                                         | (pull_config << GPIO_PIN_CNF_PULL_Pos)
00211                                         | (GPIO_PIN_CNF_INPUT_Connect << GPIO_PIN_CNF_INPUT_Pos)
00212                                         | (GPIO_PIN_CNF_DIR_Input << GPIO_PIN_CNF_DIR_Pos);
00213 }
00214 
00215 /**
00216  * @brief Function for setting the direction for a GPIO pin.
00217  *
00218  * @param pin_number specifies the pin number [0:31] for which to
00219  * set the direction.
00220  *
00221  * @param direction specifies the direction
00222  */
00223 static __INLINE void nrf_gpio_pin_dir_set(uint32_t pin_number, nrf_gpio_pin_dir_t direction)
00224 {
00225     if(direction == NRF_GPIO_PIN_DIR_INPUT)
00226     {
00227         NRF_GPIO->PIN_CNF[pin_number] =
00228           (GPIO_PIN_CNF_SENSE_Disabled << GPIO_PIN_CNF_SENSE_Pos)
00229         | (GPIO_PIN_CNF_DRIVE_S0S1 << GPIO_PIN_CNF_DRIVE_Pos)
00230         | (GPIO_PIN_CNF_PULL_Disabled << GPIO_PIN_CNF_PULL_Pos)
00231         | (GPIO_PIN_CNF_INPUT_Connect << GPIO_PIN_CNF_INPUT_Pos)
00232         | (GPIO_PIN_CNF_DIR_Input << GPIO_PIN_CNF_DIR_Pos);
00233     }
00234     else
00235     {
00236         NRF_GPIO->DIRSET = (1UL << pin_number);
00237     }
00238 }
00239 
00240 /**
00241  * @brief Function for setting a GPIO pin.
00242  *
00243  * Note that the pin must be configured as an output for this
00244  * function to have any effect.
00245  *
00246  * @param pin_number specifies the pin number [0:31] to
00247  * set.
00248  */
00249 static __INLINE void nrf_gpio_pin_set(uint32_t pin_number)
00250 {
00251     NRF_GPIO->OUTSET = (1UL << pin_number);
00252 }
00253 
00254 /**
00255  * @brief Function for clearing a GPIO pin.
00256  *
00257  * Note that the pin must be configured as an output for this
00258  * function to have any effect.
00259  *
00260  * @param pin_number specifies the pin number [0:31] to
00261  * clear.
00262  */
00263 static __INLINE void nrf_gpio_pin_clear(uint32_t pin_number)
00264 {
00265     NRF_GPIO->OUTCLR = (1UL << pin_number);
00266 }
00267 
00268 /**
00269  * @brief Function for toggling a GPIO pin.
00270  *
00271  * Note that the pin must be configured as an output for this
00272  * function to have any effect.
00273  *
00274  * @param pin_number specifies the pin number [0:31] to
00275  * toggle.
00276  */
00277 static __INLINE void nrf_gpio_pin_toggle(uint32_t pin_number)
00278 {
00279     const uint32_t pin_bit   = 1UL << pin_number;
00280     const uint32_t pin_state = ((NRF_GPIO->OUT >> pin_number) & 1UL);
00281     
00282     if (pin_state == 0)
00283     {
00284         // Current state low, set high.
00285         NRF_GPIO->OUTSET = pin_bit;        
00286     }
00287     else
00288     {
00289         // Current state high, set low.    
00290         NRF_GPIO->OUTCLR = pin_bit;       
00291     }
00292 }
00293 
00294 /**
00295  * @brief Function for writing a value to a GPIO pin.
00296  *
00297  * Note that the pin must be configured as an output for this
00298  * function to have any effect.
00299  *
00300  * @param pin_number specifies the pin number [0:31] to
00301  * write.
00302  *
00303  * @param value specifies the value to be written to the pin.
00304  * @arg 0 clears the pin
00305  * @arg >=1 sets the pin.
00306  */
00307 static __INLINE void nrf_gpio_pin_write(uint32_t pin_number, uint32_t value)
00308 {
00309     if (value == 0)
00310     {
00311         nrf_gpio_pin_clear(pin_number);
00312     }
00313     else
00314     {
00315         nrf_gpio_pin_set(pin_number);
00316     }
00317 }
00318 
00319 /**
00320  * @brief Function for reading the input level of a GPIO pin.
00321  *
00322  * Note that the pin must have input connected for the value
00323  * returned from this function to be valid.
00324  *
00325  * @param pin_number specifies the pin number [0:31] to
00326  * read.
00327  *
00328  * @return
00329  * @retval 0 if the pin input level is low.
00330  * @retval 1 if the pin input level is high.
00331  * @retval > 1 should never occur.
00332  */
00333 static __INLINE uint32_t nrf_gpio_pin_read(uint32_t pin_number)
00334 {
00335     return  ((NRF_GPIO->IN >> pin_number) & 1UL);
00336 }
00337 
00338 /**
00339  * @brief Generic function for writing a single byte of a 32 bit word at a given
00340  * address.
00341  *
00342  * This function should not be called from outside the nrf_gpio
00343  * abstraction layer.
00344  *
00345  * @param word_address is the address of the word to be written.
00346  *
00347  * @param byte_no is the the word byte number (0-3) to be written.
00348  *
00349  * @param value is the value to be written to byte "byte_no" of word
00350  * at address "word_address"
00351  */
00352 static __INLINE void nrf_gpio_word_byte_write(volatile uint32_t * word_address, uint8_t byte_no, uint8_t value)
00353 {
00354     *((volatile uint8_t*)(word_address) + byte_no) = value;
00355 }
00356 
00357 /**
00358  * @brief Generic function for reading a single byte of a 32 bit word at a given
00359  * address.
00360  *
00361  * This function should not be called from outside the nrf_gpio
00362  * abstraction layer.
00363  *
00364  * @param word_address is the address of the word to be read.
00365  *
00366  * @param byte_no is the the byte number (0-3) of the word to be read.
00367  *
00368  * @return byte "byte_no" of word at address "word_address".
00369  */
00370 static __INLINE uint8_t nrf_gpio_word_byte_read(const volatile uint32_t* word_address, uint8_t byte_no)
00371 {
00372     return (*((const volatile uint8_t*)(word_address) + byte_no));
00373 }
00374 
00375 /**
00376  * @brief Function for setting the direction of a port.
00377  *
00378  * @param port is the port for which to set the direction.
00379  *
00380  * @param dir direction to be set for this port.
00381  */
00382 static __INLINE void nrf_gpio_port_dir_set(nrf_gpio_port_select_t port, nrf_gpio_port_dir_t dir)
00383 {
00384     if (dir == NRF_GPIO_PORT_DIR_OUTPUT)
00385     {
00386         nrf_gpio_word_byte_write(&NRF_GPIO->DIRSET, port, 0xFF);
00387     }
00388     else
00389     {
00390         nrf_gpio_range_cfg_input(port*8, (port+1)*8-1, NRF_GPIO_PIN_NOPULL);
00391     }
00392 }
00393 
00394 /**
00395  * @brief Function for reading a GPIO port.
00396  *
00397  * @param port is the port to read.
00398  *
00399  * @return the input value on this port.
00400  */
00401 static __INLINE uint8_t nrf_gpio_port_read(nrf_gpio_port_select_t port)
00402 {
00403     return nrf_gpio_word_byte_read(&NRF_GPIO->IN, port);
00404 }
00405 
00406 /**
00407  * @brief Function for writing to a GPIO port.
00408  *
00409  * @param port is the port to write.
00410  *
00411  * @param value is the value to write to this port.
00412  *
00413  * @sa nrf_gpio_port_dir_set()
00414  */
00415 static __INLINE void nrf_gpio_port_write(nrf_gpio_port_select_t port, uint8_t value)
00416 {
00417     nrf_gpio_word_byte_write(&NRF_GPIO->OUT, port, value);
00418 }
00419 
00420 /**
00421  * @brief Function for setting individual pins on GPIO port.
00422  *
00423  * @param port is the port for which to set the pins.
00424  *
00425  * @param set_mask is a mask specifying which pins to set. A bit
00426  * set to 1 indicates that the corresponding port pin shall be
00427  * set.
00428  *
00429  * @sa nrf_gpio_port_dir_set()
00430  */
00431 static __INLINE void nrf_gpio_port_set(nrf_gpio_port_select_t port, uint8_t set_mask)
00432 {
00433     nrf_gpio_word_byte_write(&NRF_GPIO->OUTSET, port, set_mask);
00434 }
00435 
00436 /**
00437  * @brief Function for clearing individual pins on GPIO port.
00438  *
00439  * @param port is the port for which to clear the pins.
00440  *
00441  * @param clr_mask is a mask specifying which pins to clear. A bit
00442  * set to 1 indicates that the corresponding port pin shall be
00443  * cleared.
00444  *
00445  * @sa nrf_gpio_port_dir_set()
00446  */
00447 static __INLINE void nrf_gpio_port_clear(nrf_gpio_port_select_t port, uint8_t clr_mask)
00448 {
00449     nrf_gpio_word_byte_write(&NRF_GPIO->OUTCLR, port, clr_mask);
00450 }
00451 
00452 /** @} */
00453 
00454 #endif