1 /* 2 * Copyright (c) 2006-2024 RT-Thread Development Team 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Change Logs: 7 * Date Author Notes 8 * 2015-01-20 Bernard the first version 9 * 2017-10-20 ZYH add mode open drain and input pull down 10 */ 11 12 #ifndef DEV_PIN_H__ 13 #define DEV_PIN_H__ 14 15 #include <rtthread.h> 16 17 /** 18 * @defgroup group_drivers_pin Pin 19 * @brief Pin driver api 20 * @ingroup group_device_driver 21 * 22 * <b>Example</b> 23 * @code {.c} 24 * #include <rtthread.h> 25 * #include <rtdevice.h> 26 * 27 * 28 * #ifndef BEEP_PIN_NUM 29 * #define BEEP_PIN_NUM 35 // PB0 30 * #endif 31 * #ifndef KEY0_PIN_NUM 32 * #define KEY0_PIN_NUM 55 // PD8 33 * #endif 34 * #ifndef KEY1_PIN_NUM 35 * #define KEY1_PIN_NUM 56 // PD9 36 * #endif 37 * 38 * void beep_on(void *args) 39 * { 40 * rt_kprintf("turn on beep!\n"); 41 * 42 * rt_pin_write(BEEP_PIN_NUM, PIN_HIGH); 43 * } 44 * 45 * void beep_off(void *args) 46 * { 47 * rt_kprintf("turn off beep!\n"); 48 * 49 * rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 50 * } 51 * 52 * static void pin_beep_sample(void) 53 * { 54 * rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT); 55 * rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 56 * 57 * rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP); 58 * rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL); 59 * rt_pin_irq_enable(KEY0_PIN_NUM, PIN_IRQ_ENABLE); 60 * 61 * 62 * rt_pin_mode(KEY1_PIN_NUM, PIN_MODE_INPUT_PULLUP); 63 * rt_pin_attach_irq(KEY1_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_off, RT_NULL); 64 * rt_pin_irq_enable(KEY1_PIN_NUM, PIN_IRQ_ENABLE); 65 * } 66 * 67 * MSH_CMD_EXPORT(pin_beep_sample, pin beep sample); 68 * @endcode 69 */ 70 71 /*! 72 * @addtogroup group_drivers_pin 73 * @{ 74 */ 75 #ifdef __cplusplus 76 extern "C" { 77 #endif 78 79 #ifdef RT_USING_DM 80 #include <drivers/pic.h> 81 82 struct rt_pin_irqchip 83 { 84 struct rt_pic parent; 85 86 int irq; 87 rt_base_t pin_range[2]; 88 }; 89 90 struct rt_pin_irq_hdr; 91 #endif /* RT_USING_DM */ 92 93 /** 94 * @brief pin device structure 95 */ 96 struct rt_device_pin 97 { 98 struct rt_device parent; 99 #ifdef RT_USING_DM 100 /* MUST keep the order member after parent */ 101 struct rt_pin_irqchip irqchip; 102 /* Fill by DM */ 103 rt_base_t pin_start; 104 rt_size_t pin_nr; 105 rt_list_t list; 106 struct rt_pin_irq_hdr *legacy_isr; 107 #endif /* RT_USING_DM */ 108 const struct rt_pin_ops *ops; 109 }; 110 111 #define PIN_NONE (-RT_EEMPTY) 112 113 #define PIN_LOW 0x00 /*!< low level */ 114 #define PIN_HIGH 0x01 /*!< high level */ 115 116 #define PIN_MODE_OUTPUT 0x00 /*!< output mode */ 117 #define PIN_MODE_INPUT 0x01 /*!< input mode */ 118 #define PIN_MODE_INPUT_PULLUP 0x02 /*!< input mode with pull-up */ 119 #define PIN_MODE_INPUT_PULLDOWN 0x03 /*!< input mode with pull-down */ 120 #define PIN_MODE_OUTPUT_OD 0x04 /*!< output mode with open-drain */ 121 122 #ifdef RT_USING_PINCTRL 123 enum 124 { 125 PIN_CONFIG_BIAS_BUS_HOLD, 126 PIN_CONFIG_BIAS_DISABLE, 127 PIN_CONFIG_BIAS_HIGH_IMPEDANCE, 128 PIN_CONFIG_BIAS_PULL_DOWN, 129 PIN_CONFIG_BIAS_PULL_PIN_DEFAULT, 130 PIN_CONFIG_BIAS_PULL_UP, 131 PIN_CONFIG_DRIVE_OPEN_DRAIN, 132 PIN_CONFIG_DRIVE_OPEN_SOURCE, 133 PIN_CONFIG_DRIVE_PUSH_PULL, 134 PIN_CONFIG_DRIVE_STRENGTH, 135 PIN_CONFIG_DRIVE_STRENGTH_UA, 136 PIN_CONFIG_INPUT_DEBOUNCE, 137 PIN_CONFIG_INPUT_ENABLE, 138 PIN_CONFIG_INPUT_SCHMITT, 139 PIN_CONFIG_INPUT_SCHMITT_ENABLE, 140 PIN_CONFIG_MODE_LOW_POWER, 141 PIN_CONFIG_MODE_PWM, 142 PIN_CONFIG_OUTPUT, 143 PIN_CONFIG_OUTPUT_ENABLE, 144 PIN_CONFIG_OUTPUT_IMPEDANCE_OHMS, 145 PIN_CONFIG_PERSIST_STATE, 146 PIN_CONFIG_POWER_SOURCE, 147 PIN_CONFIG_SKEW_DELAY, 148 PIN_CONFIG_SLEEP_HARDWARE_STATE, 149 PIN_CONFIG_SLEW_RATE, 150 PIN_CONFIG_END = 0x7f, 151 PIN_CONFIG_MAX = 0xff, 152 }; 153 #endif /* RT_USING_PINCTRL */ 154 155 #define PIN_IRQ_MODE_RISING 0x00 /*!< rising edge trigger */ 156 #define PIN_IRQ_MODE_FALLING 0x01 /*!< falling edge trigger */ 157 #define PIN_IRQ_MODE_RISING_FALLING 0x02 /*!< rising and falling edge trigger */ 158 #define PIN_IRQ_MODE_HIGH_LEVEL 0x03 /*!< high level trigger */ 159 #define PIN_IRQ_MODE_LOW_LEVEL 0x04 /*!< low level trigger */ 160 161 #define PIN_IRQ_DISABLE 0x00 /*!< disable irq */ 162 #define PIN_IRQ_ENABLE 0x01 /*!< enable irq */ 163 164 #define PIN_IRQ_PIN_NONE PIN_NONE /*!< no pin irq */ 165 166 /** 167 * @brief pin mode structure 168 */ 169 struct rt_device_pin_mode 170 { 171 rt_base_t pin; 172 rt_uint8_t mode; /* e.g. PIN_MODE_OUTPUT */ 173 }; 174 175 /** 176 * @brief pin value structure 177 */ 178 struct rt_device_pin_value 179 { 180 rt_base_t pin; 181 rt_uint8_t value; /* PIN_LOW or PIN_HIGH */ 182 }; 183 184 /** 185 * @brief pin irq structure 186 */ 187 struct rt_pin_irq_hdr 188 { 189 rt_base_t pin; 190 rt_uint8_t mode; /* e.g. PIN_IRQ_MODE_RISING */ 191 void (*hdr)(void *args); 192 void *args; 193 }; 194 195 #ifdef RT_USING_PINCTRL 196 /** 197 * @brief pin control configure structure 198 */ 199 struct rt_pin_ctrl_conf_params 200 { 201 const char *propname; 202 rt_uint32_t param; 203 rt_uint32_t default_value; 204 }; 205 #endif /* RT_USING_PINCTRL */ 206 207 /** 208 * @brief pin device operations 209 */ 210 struct rt_pin_ops 211 { 212 void (*pin_mode)(struct rt_device *device, rt_base_t pin, rt_uint8_t mode); 213 void (*pin_write)(struct rt_device *device, rt_base_t pin, rt_uint8_t value); 214 rt_ssize_t (*pin_read)(struct rt_device *device, rt_base_t pin); 215 rt_err_t (*pin_attach_irq)(struct rt_device *device, rt_base_t pin, 216 rt_uint8_t mode, void (*hdr)(void *args), void *args); 217 rt_err_t (*pin_detach_irq)(struct rt_device *device, rt_base_t pin); 218 rt_err_t (*pin_irq_enable)(struct rt_device *device, rt_base_t pin, rt_uint8_t enabled); 219 rt_base_t (*pin_get)(const char *name); 220 rt_err_t (*pin_debounce)(struct rt_device *device, rt_base_t pin, rt_uint32_t debounce); 221 #ifdef RT_USING_DM 222 rt_err_t (*pin_irq_mode)(struct rt_device *device, rt_base_t pin, rt_uint8_t mode); 223 rt_ssize_t (*pin_parse)(struct rt_device *device, struct rt_ofw_cell_args *args, rt_uint32_t *flags); 224 #endif 225 #ifdef RT_USING_PINCTRL 226 rt_err_t (*pin_ctrl_confs_apply)(struct rt_device *device, void *fw_conf_np); 227 #endif /* RT_USING_PINCTRL */ 228 }; 229 230 /** 231 * @brief register a pin device 232 * @param name the name of pin device 233 * @param ops the operations of pin device 234 * @param user_data the user data of pin device 235 * @return int error code 236 */ 237 int rt_device_pin_register(const char *name, const struct rt_pin_ops *ops, void *user_data); 238 239 /** 240 * @brief set pin mode 241 * @param pin the pin number 242 * @param mode the pin mode 243 */ 244 void rt_pin_mode(rt_base_t pin, rt_uint8_t mode); 245 246 /** 247 * @brief write pin value 248 * @param pin the pin number 249 * @param value the pin value 250 */ 251 void rt_pin_write(rt_base_t pin, rt_ssize_t value); 252 253 /** 254 * @brief read pin value 255 * @param pin the pin number 256 * @return rt_ssize_t the pin value 257 */ 258 rt_ssize_t rt_pin_read(rt_base_t pin); 259 260 /** 261 * @brief get pin number by name 262 * @param name the pin name 263 * @return rt_base_t the pin number 264 */ 265 rt_base_t rt_pin_get(const char *name); 266 267 /** 268 * @brief bind the pin interrupt callback function 269 * @param pin the pin number 270 * @param mode the irq mode 271 * @param hdr the irq callback function 272 * @param args the argument of the callback function 273 * @return rt_err_t error code 274 */ 275 rt_err_t rt_pin_attach_irq(rt_base_t pin, rt_uint8_t mode, 276 void (*hdr)(void *args), void *args); 277 278 /** 279 * @brief detach the pin interrupt callback function 280 * @param pin the pin number 281 * @return rt_err_t error code 282 */ 283 rt_err_t rt_pin_detach_irq(rt_base_t pin); 284 285 /** 286 * @brief enable or disable the pin interrupt 287 * @param pin the pin number 288 * @param enabled PIN_IRQ_ENABLE or PIN_IRQ_DISABLE 289 * @return rt_err_t error code 290 */ 291 rt_err_t rt_pin_irq_enable(rt_base_t pin, rt_uint8_t enabled); 292 293 /** 294 * @brief set the pin's debounce time 295 * @param pin the pin number 296 * @param debounce time 297 * @return rt_err_t error code 298 */ 299 rt_err_t rt_pin_debounce(rt_base_t pin, rt_uint32_t debounce); 300 301 #ifdef RT_USING_DM 302 rt_ssize_t rt_pin_get_named_pin(struct rt_device *dev, const char *propname, int index, 303 rt_uint8_t *out_mode, rt_uint8_t *out_value); 304 rt_ssize_t rt_pin_get_named_pin_count(struct rt_device *dev, const char *propname); 305 306 #ifdef RT_USING_OFW 307 rt_ssize_t rt_ofw_get_named_pin(struct rt_ofw_node *np, const char *propname, int index, 308 rt_uint8_t *out_mode, rt_uint8_t *out_value); 309 rt_ssize_t rt_ofw_get_named_pin_count(struct rt_ofw_node *np, const char *propname); 310 #endif 311 #endif /* RT_USING_DM */ 312 313 #ifdef RT_USING_PINCTRL 314 rt_ssize_t rt_pin_ctrl_confs_lookup(struct rt_device *device, const char *name); 315 rt_err_t rt_pin_ctrl_confs_apply(struct rt_device *device, int index); 316 rt_err_t rt_pin_ctrl_confs_apply_by_name(struct rt_device *device, const char *name); 317 #endif /* RT_USING_PINCTRL */ 318 319 #ifdef __cplusplus 320 } 321 #endif 322 323 /*! @}*/ 324 325 #endif 326