1 //*****************************************************************************
2 //
3 //! @file am_hal_gpio.h
4 //!
5 //! @brief Functions for Interfacing with the GPIO module
6 //!
7 //! @addtogroup gpio3p GPIO - GPIO Functions
8 //! @ingroup apollo3p_hal
9 //! @{
10 //
11 //*****************************************************************************
12
13 //*****************************************************************************
14 //
15 // Copyright (c) 2024, Ambiq Micro, Inc.
16 // All rights reserved.
17 //
18 // Redistribution and use in source and binary forms, with or without
19 // modification, are permitted provided that the following conditions are met:
20 //
21 // 1. Redistributions of source code must retain the above copyright notice,
22 // this list of conditions and the following disclaimer.
23 //
24 // 2. Redistributions in binary form must reproduce the above copyright
25 // notice, this list of conditions and the following disclaimer in the
26 // documentation and/or other materials provided with the distribution.
27 //
28 // 3. Neither the name of the copyright holder nor the names of its
29 // contributors may be used to endorse or promote products derived from this
30 // software without specific prior written permission.
31 //
32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
42 // POSSIBILITY OF SUCH DAMAGE.
43 //
44 // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package.
45 //
46 //*****************************************************************************
47
48 #ifndef AM_HAL_GPIO_H
49 #define AM_HAL_GPIO_H 1
50
51 #ifdef __cplusplus
52 extern "C"
53 {
54 #endif
55
56 //
57 //! Designate this peripheral.
58 //
59 #define AM_APOLLO3_GPIO 1
60
61 //
62 //! Maximum number of GPIOs on this device
63 //
64 #define AM_HAL_GPIO_MAX_PADS (74)
65 #define AM_HAL_GPIO_NUMWORDS ((AM_HAL_GPIO_MAX_PADS + 31) / 32)
66
67 //
68 //! Macros to assist with defining a GPIO mask given a GPIO number.
69 //!
70 //! IMPORTANT: AM_HAL_GPIO_BIT(n) is DEPRECATED and is
71 //! replaced with AM_HAL_GPIO_MASKBIT().
72 //
73 #define AM_HAL_GPIO_BIT(n) DEPRECATED_USE_AM_HAL_GPIO_MASKBIT // Force a compile error if used
74
75 //!
76 //! The following macros ensure forward compatibility with future SDK releases.
77 //! They should be used, in lieu of AM_HAL_GPIO_BIT(), when creating bitmasks
78 //! for GPIO interrupts.
79 //! AM_HAL_GPIO_MASKCREATE()
80 //! AM_HAL_GPIO_MASKBIT()
81 //!
82 #define AM_HAL_GPIO_MASKCREATE(sMaskNm) \
83 am_hal_gpio_mask_t sMaskNm; \
84 am_hal_gpio_mask_t *p##sMaskNm = &sMaskNm; \
85 sMaskNm.U.Msk[0] = sMaskNm.U.Msk[1] = sMaskNm.U.Msk[2] = 0;
86 //! AM_HAL_GPIO_MASKCREATE() should be used before AM_HAL_GPIO_MASKBIT() to
87 //! ensure forward compatibility. In future releases it will allocate and
88 //! initialize a bitmask structure used in the various GPIO interrupt functions.
89 //!
90
91 // #define AM_HAL_GPIO_MASKBIT(psMaskNm, n) inline_function_below
92 //! AM_HAL_GPIO_MASKBIT(psMaskNm, n)
93 //! Implemented as an inline function below.
94 //! Support macros for use with AM_HAL_GPIO_MASKBIT().
95 //! AM_HAL_GPIO_MASKCREATE()
96 //! AM_HAL_GPIO_MASKCLR()
97 //!
98 //! To set a single bit based on a pin number in an existing bitmask structure.
99 //! AM_HAL_GPIO_MASKBIT(pGpioIntMask, n)
100 //! where n is the desired GPIO bit number.
101 //! Note - this usage is analogous to the deprecated AM_HAL_GPIO_BIT(n).
102 //!
103
104 #define AM_HAL_GPIO_MASKCLR(psMaskNm) ( psMaskNm->U.Msk[0] = psMaskNm->U.Msk[1] = psMaskNm->U.Msk[2] = 0 )
105 //! AM_HAL_GPIO_MASKCLR()
106 //! Clear an existing GpioIntMask bitmask structure.
107 //! Note that AM_HAL_GPIO_MASKCREATE() clears the bitmask struct on creation.
108 //! IMPORTANT - The AM_HAL_GPIO_MASKCLR() macro does not operate on any hardware
109 //! or register. It is used for initializing/clearing the memory allocated for
110 //! the bitmask structure.
111 //!
112 //! // Usage example for any Apollo device:
113 //! // Create a GPIO interrupt bitmask structure named GpioIntMask, initialize
114 //! // that structure, and create a ptr to that structure named pGpioIntMask.
115 //! // Then use that structure to pass a bitmask to the interrupt function.
116 //! AM_HAL_GPIO_MASKCREATE(GpioIntMask);
117 //! am_hal_gpio_interrupt_clear(AM_HAL_GPIO_MASKBIT(pGpioIntMask));
118 //!
119
120 //*****************************************************************************
121 //!
122 //! Structure for defining bitmasks used in the interrupt functions.
123 //!
124 //*****************************************************************************
125 typedef struct
126 {
127 union
128 {
129 volatile uint32_t Msk[AM_HAL_GPIO_NUMWORDS];
130
131 struct
132 {
133 volatile uint32_t b0: 1;
134 volatile uint32_t b1: 1;
135 volatile uint32_t b2: 1;
136 volatile uint32_t b3: 1;
137 volatile uint32_t b4: 1;
138 volatile uint32_t b5: 1;
139 volatile uint32_t b6: 1;
140 volatile uint32_t b7: 1;
141 volatile uint32_t b8: 1;
142 volatile uint32_t b9: 1;
143 volatile uint32_t b10: 1;
144 volatile uint32_t b11: 1;
145 volatile uint32_t b12: 1;
146 volatile uint32_t b13: 1;
147 volatile uint32_t b14: 1;
148 volatile uint32_t b15: 1;
149 volatile uint32_t b16: 1;
150 volatile uint32_t b17: 1;
151 volatile uint32_t b18: 1;
152 volatile uint32_t b19: 1;
153 volatile uint32_t b20: 1;
154 volatile uint32_t b21: 1;
155 volatile uint32_t b22: 1;
156 volatile uint32_t b23: 1;
157 volatile uint32_t b24: 1;
158 volatile uint32_t b25: 1;
159 volatile uint32_t b26: 1;
160 volatile uint32_t b27: 1;
161 volatile uint32_t b28: 1;
162 volatile uint32_t b29: 1;
163 volatile uint32_t b30: 1;
164 volatile uint32_t b31: 1;
165 volatile uint32_t b32: 1;
166 volatile uint32_t b33: 1;
167 volatile uint32_t b34: 1;
168 volatile uint32_t b35: 1;
169 volatile uint32_t b36: 1;
170 volatile uint32_t b37: 1;
171 volatile uint32_t b38: 1;
172 volatile uint32_t b39: 1;
173 volatile uint32_t b40: 1;
174 volatile uint32_t b41: 1;
175 volatile uint32_t b42: 1;
176 volatile uint32_t b43: 1;
177 volatile uint32_t b44: 1;
178 volatile uint32_t b45: 1;
179 volatile uint32_t b46: 1;
180 volatile uint32_t b47: 1;
181 volatile uint32_t b48: 1;
182 volatile uint32_t b49: 1;
183 volatile uint32_t b50: 1;
184 volatile uint32_t b51: 1;
185 volatile uint32_t b52: 1;
186 volatile uint32_t b53: 1;
187 volatile uint32_t b54: 1;
188 volatile uint32_t b55: 1;
189 volatile uint32_t b56: 1;
190 volatile uint32_t b57: 1;
191 volatile uint32_t b58: 1;
192 volatile uint32_t b59: 1;
193 volatile uint32_t b60: 1;
194 volatile uint32_t b61: 1;
195 volatile uint32_t b62: 1;
196 volatile uint32_t b63: 1;
197 volatile uint32_t b64: 1;
198 volatile uint32_t b65: 1;
199 volatile uint32_t b66: 1;
200 volatile uint32_t b67: 1;
201 volatile uint32_t b68: 1;
202 volatile uint32_t b69: 1;
203 volatile uint32_t b70: 1;
204 volatile uint32_t b71: 1;
205 volatile uint32_t b72: 1;
206 volatile uint32_t b73: 1;
207 volatile uint32_t brsvd: 22; // Pad out to the next full word
208 } Msk_b;
209 } U;
210 } am_hal_gpio_mask_t;
211
212 //*****************************************************************************
213 //!
214 //! AM_HAL_GPIO_MASKBIT()
215 //!
216 //*****************************************************************************
217 //
218 // AM_HAL_GPIO_MASKBIT(psMaskNm, n)
219 //
220 // Entry:
221 // psMaskNm is a pointer to the structure type, am_hal_gpio_mask_t.
222 // n is the desired bitnumber.
223 //
224 // Returns ptr to the bit structure.
225 //
226 // Since the ptr is required as a return value, a macro does not work.
227 // Therefore an inline function is used.
228 //
229 static inline am_hal_gpio_mask_t*
AM_HAL_GPIO_MASKBIT(am_hal_gpio_mask_t * psMaskNm,uint32_t n)230 AM_HAL_GPIO_MASKBIT(am_hal_gpio_mask_t*psMaskNm, uint32_t n)
231 {
232 psMaskNm->U.Msk[n / 32] = (1 << (n % 32));
233 return psMaskNm;
234 }
235
236 //*****************************************************************************
237 //!
238 //! AM_HAL_GPIO_MASKBITSMULT()
239 //!
240 //*****************************************************************************
241 //
242 // AM_HAL_GPIO_MASKBITSMULT(psMaskNm, n)
243 //
244 // Entry:
245 // psMaskNm is a pointer to the structure type, am_hal_gpio_mask_t.
246 // n is the desired bitnumber.
247 //
248 // Returns ptr to the bit structure.
249 //
250 // Since the ptr is required as a return value, a macro does not work.
251 // Therefore an inline function is used.
252 //
253 static inline am_hal_gpio_mask_t*
AM_HAL_GPIO_MASKBITSMULT(am_hal_gpio_mask_t * psMaskNm,uint32_t n)254 AM_HAL_GPIO_MASKBITSMULT(am_hal_gpio_mask_t*psMaskNm, uint32_t n)
255 {
256 psMaskNm->U.Msk[n / 32] |= (1 << (n % 32));
257 return psMaskNm;
258 }
259
260 //*****************************************************************************
261 //!
262 //! Read types for am_hal_gpio_state_read().
263 //!
264 //! - AM_HAL_GPIO_INPUT_READ\n
265 //! Used for reading the value on the pad whether the pad is configured
266 //! as an input or an output. Assumes that the pin is configured with
267 //! AM_HAL_GPIO_PIN_INPUT_ENABLE and AM_HAL_GPIO_PIN_RDZERO_READPIN, even
268 //! if configured for output (e.g. see g_AM_HAL_GPIO_OUTPUT_WITH_READ).\n
269 //! Perhaps a reasonable alias would be AM_HAL_GPIO_PAD_READ.
270 //!
271 //! - AM_HAL_GPIO_OUTPUT_READ\n
272 //! Used for reading the last value written to the GPIO output, e.g via
273 //! am_hal_gpio_state_write(AM_HAL_GPIO_OUTPUT_SET) or even the macro
274 //! am_hal_gpio_output_set(n).
275 //!
276 //! - AM_HAL_GPIO_ENABLE_READ\n
277 //! Used for reading the state of the tristate enable, e.g. the state
278 //! of the tristate enable after calling
279 //! am_hal_gpio_state_write(AM_HAL_GPIO_OUTPUT_TRISTATE_ENABLE) or
280 //! am_hal_gpio_state_write(AM_HAL_GPIO_OUTPUT_TRISTATE_DISABLE), or even
281 //! the macro am_hal_gpio_output_tristate_disable(n).
282 //!
283 //*****************************************************************************
284 typedef enum
285 {
286 AM_HAL_GPIO_INPUT_READ,
287 AM_HAL_GPIO_OUTPUT_READ,
288 AM_HAL_GPIO_ENABLE_READ
289 } am_hal_gpio_read_type_e;
290
291 //*****************************************************************************
292 //!
293 //! Write types for am_hal_gpio_state_write().
294 //!
295 //*****************************************************************************
296 typedef enum
297 {
298 AM_HAL_GPIO_OUTPUT_CLEAR,
299 AM_HAL_GPIO_OUTPUT_SET,
300 AM_HAL_GPIO_OUTPUT_TOGGLE,
301 AM_HAL_GPIO_OUTPUT_TRISTATE_DISABLE,
302 AM_HAL_GPIO_OUTPUT_TRISTATE_ENABLE,
303 AM_HAL_GPIO_OUTPUT_TRISTATE_TOGGLE
304 } am_hal_gpio_write_type_e;
305
306
307 //*****************************************************************************
308 //!
309 //! Types for ui32GpioCfg bitfields in am_hal_gpio_pinconfig().
310 //!
311 //*****************************************************************************
312 //!
313 //! @par
314 //! Power Switch configuration: am_hal_gpio_pincfg_t.ePowerSw enums
315 //!
316 typedef enum
317 {
318 AM_HAL_GPIO_PIN_POWERSW_NONE,
319 AM_HAL_GPIO_PIN_POWERSW_VDD,
320 AM_HAL_GPIO_PIN_POWERSW_VSS,
321 AM_HAL_GPIO_PIN_POWERSW_INVALID,
322 } am_hal_gpio_powersw_e;
323
324 //!
325 //! Pullup configuration: am_hal_gpio_pincfg_t.ePullup enums
326 //!
327 //! Define pullup enums.\n
328 //! The 1.5K - 24K pullup values are valid for select I2C enabled pads.\n
329 //! For Apollo3 these pins are 0-1,5-6,8-9,25,27,39-40,42-43,48-49.\n
330 //! The "weak" value is used for almost every other pad except pin 20.
331 //!
332 typedef enum
333 {
334 AM_HAL_GPIO_PIN_PULLUP_NONE = 0x00,
335 AM_HAL_GPIO_PIN_PULLUP_WEAK,
336 AM_HAL_GPIO_PIN_PULLUP_1_5K,
337 AM_HAL_GPIO_PIN_PULLUP_6K,
338 AM_HAL_GPIO_PIN_PULLUP_12K,
339 AM_HAL_GPIO_PIN_PULLUP_24K,
340 AM_HAL_GPIO_PIN_PULLDOWN
341 } am_hal_gpio_pullup_e;
342
343 //!
344 //! Pad Drive Strength configuration: am_hal_gpio_pincfg_t.eDriveStrength enums
345 //!
346 //! DRIVESTRENGTH is a 2-bit field.\n
347 //! - bit0 maps to bit2 of a PADREG field.
348 //! - bit1 maps to bit0 of an ALTPADCFG field.
349 //!
350 typedef enum
351 {
352 AM_HAL_GPIO_PIN_DRIVESTRENGTH_2MA = 0x0,
353 AM_HAL_GPIO_PIN_DRIVESTRENGTH_4MA = 0x1,
354 AM_HAL_GPIO_PIN_DRIVESTRENGTH_8MA = 0x2,
355 AM_HAL_GPIO_PIN_DRIVESTRENGTH_12MA = 0x3
356 } am_hal_gpio_drivestrength_e;
357
358 //!
359 //! OUTCFG pad configuration: am_hal_gpio_pincfg_t.eGPOutcfg enums\n
360 //! Applies only to GPIO configured pins.\n
361 //! Ultimately maps to GPIOCFG.OUTCFG, bits [2:1].
362 //!
363 typedef enum
364 {
365 AM_HAL_GPIO_PIN_OUTCFG_DISABLE = 0x0,
366 AM_HAL_GPIO_PIN_OUTCFG_PUSHPULL = 0x1,
367 AM_HAL_GPIO_PIN_OUTCFG_OPENDRAIN = 0x2,
368 AM_HAL_GPIO_PIN_OUTCFG_TRISTATE = 0x3
369 } am_hal_gpio_outcfg_e;
370
371 //!
372 //! GPIO input configuration: am_hal_gpio_pincfg_t.eGPInput enums\n
373 //! Applies only to GPIO configured pins!\n
374 //! Ultimately maps to PADREG.INPEN, bit1.
375 //!
376 typedef enum
377 {
378 AM_HAL_GPIO_PIN_INPUT_AUTO = 0x0,
379 AM_HAL_GPIO_PIN_INPUT_NONE = 0x0,
380 AM_HAL_GPIO_PIN_INPUT_ENABLE = 0x1
381 } am_hal_gpio_input_e;
382
383 //!
384 //! GPIO interrupt direction configuration: am_hal_gpio_pincfg_t.eIntDir enums\n
385 //! @note Setting INTDIR_NONE has the side-effect of disabling being able to
386 //! read a pin - the pin will always read back as 0.
387 //!
388 typedef enum
389 {
390 // Bit1 of these values maps to GPIOCFG.INCFG (b0).
391 // Bit0 of these values maps to GPIOCFG.INTD (b3).
392 AM_HAL_GPIO_PIN_INTDIR_LO2HI = 0x0,
393 AM_HAL_GPIO_PIN_INTDIR_HI2LO = 0x1,
394 AM_HAL_GPIO_PIN_INTDIR_NONE = 0x2,
395 AM_HAL_GPIO_PIN_INTDIR_BOTH = 0x3
396 } am_hal_gpio_intdir_e;
397
398 //!
399 //! am_hal_gpio_pincfg_t.eGPRdZero\n
400 //! For GPIO configurations (funcsel=3), the pin value can be read or 0 can be
401 //! forced as the read value.
402 //!
403 typedef enum
404 {
405 AM_HAL_GPIO_PIN_RDZERO_READPIN = 0x0,
406 AM_HAL_GPIO_PIN_RDZERO_ZERO = 0x1
407 } am_hal_gpio_readen_e;
408
409 //!
410 //! nCE polarity configuration: am_hal_gpio_pincfg_t.eCEpol enums
411 //!
412 typedef enum
413 {
414 AM_HAL_GPIO_PIN_CEPOL_ACTIVELOW = 0x0,
415 AM_HAL_GPIO_PIN_CEPOL_ACTIVEHIGH = 0x1
416 } am_hal_gpio_cepol_e;
417
418
419 //
420 // Apollo3 usage of bits [7:6] of a PADREG field:
421 // PULLUPs are available on pins: 0,1,5,6,8,9,25,27,39,40,42,43,48,49
422 // RESERVED on pins: 2,4,7,10-24,26,28-35,38,44-47
423 // VDD PWR on pins: 3, 36 (b7=0, b6=1)
424 // VSS PWR on pins: 37,41 (b7=1, b6=0)
425 //
426
427 //!
428 //! Define the am_hal_gpio_pinconfig() bitfield structure.
429 //!
430 //! - uFuncSel: - A value of 0-7 corresponding to the FNCSEL field of PADREG.
431 //! - ePowerSw: - Select pins can be set as a power source or sink.
432 //! - ePullup: - Select pins can enable a pullup of varying values.
433 //! - eDriveStrength: - Select pins can be set for varying drive strengths.
434 //! - eGPOutcfg: - GPIO pin only, corresponds to GPIOCFG.OUTCFG field.
435 //! - eGPInput: - GPIO pin only, corresponds to PADREG.INPEN.
436 //! - eGPRdZero: - GPIO read zero. Corresponds to GPIOCFG.INCFG.
437 //! - eIntDir: - Interrupt direction, l2h, h2l, both, none.
438 //! - eGPRdZero: - Read the pin value, or always read the pin as zero.
439 //! - uIOMnum: - nCE pin IOMnumber (0-5, or 6 for MSPI)
440 //! - nNCE: - Selects the SPI channel (CE) number (0-3)
441 //! - eCEpol: - CE polarity.
442 //!
443 typedef struct
444 {
445 uint32_t uFuncSel : 3; //!< [2:0] Function select (FUNCSEL)
446 uint32_t ePowerSw : 2; //!< [4:3] Pin is a power switch source (VCC) or sink (VSS)
447 uint32_t ePullup : 3; //!< [7:5] Pin will enable a pullup resistor
448 uint32_t eDriveStrength : 2; //!< [9:8] Pad strength designator
449 uint32_t eGPOutcfg : 2; //!< [11:10] OUTCFG (GPIO config only)
450 uint32_t eGPInput : 1; //!< [12:12] GPIO Input (GPIO config only)
451 uint32_t eIntDir : 2; //!< [14:13] Interrupt direction
452 uint32_t eGPRdZero : 1; //!< [15:15] GPIO read as zero
453
454 //
455 //! @name chip_enable_features
456 //! The following descriptors designate the chip enable features of the
457 //! pin being configured. If not a CE, these descriptors are ignored.
458 //! uIOMnum is 0-5 for the IOMs, or 0-2 for MSPI.
459 //! @{
460 //
461 uint32_t bIomMSPIn : 1; //!< [16:16] 1 if CE is IOM, 0 if MSPI
462 uint32_t uIOMnum : 3; //!< [19:17] IOM number (0-5) or MSPI (0-2)
463 uint32_t uNCE : 2; //!< [21:20] NCE number (0-3).
464 uint32_t eCEpol : 1; //!< [22:22] NCE polarity.
465 uint32_t uRsvd23 : 9; //!< [31:23]
466
467 //! @} // chip_enable_features
468
469 } am_hal_gpio_pincfg_t;
470
471 //#define IOMNUM_MSPI 6
472 //#define IOMNUM_MAX IOMNUM_MSPI
473
474 //
475 //! Define shift and width values for the above bitfields.
476 // - C bitfields do not provide shift, width, or mask values.
477 // - Shift values are generally compiler specific. However for IAR, Keil, and
478 // GCC, the bitfields are all exactly as defined in the above structure.
479 // - These defines should be used sparingly.
480 //
481 #define UFUNCSEL_S 0
482 #define EPOWERSW_S 3
483 #define EPULLUP_S 5
484 #define EDRVSTR_S 8
485 #define EGPOUTCFG_S 10
486 #define EGPINPUT_S 12
487 #define EINTDIR_S 13
488 #define UIOMNUM_S 16
489 #define UNCE_S 19
490 #define ECEPOL_S 21
491
492 #define UFUNCSEL_W 3
493 #define EPOWERSW_W 2
494 #define EPULLUP_W 3
495 #define EDRVSTR_W 2
496 #define EGPOUTCFG_W 2
497 #define EGPINPUT_W 1
498 #define EINTDIR_W 2
499 #define UIOMNUM_W 3
500 #define UNCE_W 2
501 #define ECEPOL_W 1
502
503 //!
504 //! Define GPIO error codes that are returned by am_hal_gpio_pinconfig().
505 //!
506 enum am_hal_gpio_pincfgerr
507 {
508 AM_HAL_GPIO_ERR_PULLUP = (AM_HAL_STATUS_MODULE_SPECIFIC_START + 0x100),
509 AM_HAL_GPIO_ERR_PULLDOWN,
510 AM_HAL_GPIO_ERR_PWRSW,
511 AM_HAL_GPIO_ERR_INVCE,
512 AM_HAL_GPIO_ERR_INVCEPIN,
513 AM_HAL_GPIO_ERR_PULLUPENUM
514 };
515
516 //*****************************************************************************
517 //
518 //! Globals
519 //
520 //*****************************************************************************
521 //*****************************************************************************
522 //! Define some common GPIO pin configurations.
523 //*****************************************************************************
524 //! Basics
525 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_DEFAULT;
526 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_DISABLE;
527 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_TRISTATE;
528
529 //! Input variations
530 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT;
531 //! Input with various pullups (weak, 1.5K, 6K, 12K, 24K)
532 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT_PULLUP;
533 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT_PULLUP_1_5;
534 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT_PULLUP_6;
535 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT_PULLUP_12;
536 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_INPUT_PULLUP_24;
537
538 //! Output variations
539 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_OUTPUT;
540 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_OUTPUT_4;
541 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_OUTPUT_8;
542 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_OUTPUT_12;
543 extern const am_hal_gpio_pincfg_t g_AM_HAL_GPIO_OUTPUT_WITH_READ;
544
545 //*****************************************************************************
546 //
547 //! Function pointer type for GPIO interrupt handlers.
548 //
549 //*****************************************************************************
550 typedef void (*am_hal_gpio_handler_t)(void);
551 typedef void (*am_hal_gpio_handler_adv_t)(void *);
552
553 //*****************************************************************************
554 //
555 // External functions.
556 //
557 //*****************************************************************************
558
559 //*****************************************************************************
560 //
561 //! @brief Return the current configuration of a pin.
562 //!
563 //! @param ui32GpioNum is the GPIO pin number to configure.
564 //! @param psGpioCfg - Ptr for the return value of the current configuration.
565 //!
566 //! This function returns the current configuration of a GPIO.
567 //!
568 //! @return Standard HAL status code.
569 //
570 //*****************************************************************************
571 extern uint32_t
572 am_hal_gpio_pinconfig_get(uint32_t ui32GpioNum, am_hal_gpio_pincfg_t* psGpioCfg);
573
574 //*****************************************************************************
575 //
576 //! @brief Configure an Apollo3 pin.
577 //!
578 //! @param ui32Pin - pin number to be configured.
579 //! @param bfGpioCfg - Contains multiple descriptor fields.
580 //!
581 //! @details This function configures a pin according to the descriptor parameters as
582 //! passed in sPinCfg. All parameters are validated with regard to each
583 //! other and according to the requested function. Once the parameters and
584 //! settings have been confirmed, the pin is configured accordingly.
585 //!
586 //! @return Status.
587 //
588 //*****************************************************************************
589 extern uint32_t am_hal_gpio_pinconfig(uint32_t ui32Pin,
590 am_hal_gpio_pincfg_t bfGpioCfg);
591
592 //*****************************************************************************
593 //
594 //! @brief Configure specified pins for FAST GPIO operation.
595 //!
596 //! @param psPinMask
597 //! - a mask specifying up to 8 pins to be configured and
598 //! used for FAST GPIO (only bits 0-73 are valid).
599 //!
600 //! @param bfGpioCfg
601 //! - The GPIO configuration (same as am_hal_gpio_pinconfig()).\n
602 //! - All of the pins specified by psPinMask will be set to this
603 //! configuration.
604 //! @param ui32Masks
605 //! @parblock
606 //! - If NULL, not used.\n
607 //! - Otherwise if provided, an array to
608 //! receive two 32-bit values, per pin, of the SET and CLEAR
609 //! masks that can be used for the BBSETCLEAR register.
610 //!
611 //! - The two 32-bit values will be placed at incremental indexes.\n
612 //! For example, say pin numbers 5 and 19 are indicated in the
613 //! mask, and an array pointer is provided in ui32Masks.\n
614 //! This array must be allocated by the caller to be at least 4 wds.
615 //!
616 //! - ui32Masks[0] = the set mask used for pin 5.
617 //! - ui32Masks[1] = the clear mask used for pin 5.
618 //! - ui32Masks[2] = the set mask used for pin 19.
619 //! - ui32Masks[3] = the clear mask used for pin 19.
620 //! @endparblock
621 //! @return Status.
622 //!
623 //! Fast GPIO helper macros:
624 //! am_hal_gpio_fastgpio_set(n) - Sets the value for pin number 'n'.
625 //! am_hal_gpio_fastgpio_clr(n) - Clear the value for pin number 'n'.
626 //!
627 //! am_hal_gpio_fastgpio_enable(n) - Enable Fast GPIO on pin 'n'.
628 //! am_hal_gpio_fastgpio_disable(n) - Disable Fast GPIO on pin 'n'.
629 //!
630 //! @note The enable and disable macros assume the pin has already been
631 //! configured. Once disabled, the state of the pin will revert to the
632 //! state of the normal GPIO configuration for that pin.
633 //! @par
634 //! @note NOTES on pin configuration:
635 //! - To avoid glitches on the pin, it is strongly recommended that before
636 //! calling am_hal_gpio_fast_pinconfig() that am_hal_gpio_fastgpio_disable()
637 //! first be called to make sure that Fast GPIO is disabled before config.
638 //! - If the state of the pin is important, preset the value of the pin to the
639 //! desired value BEFORE calling am_hal_gpio_fast_pinconfig(). The set and
640 //! clear macros shown above can be used for this purpose.
641 //! @par
642 //! @note NOTES on general use of Fast GPIO:
643 //! Fast GPIO input or output will not work if the pin is configured as
644 //! tristate. The overloaded OUTPUT ENABLE control is used for enabling both
645 //! modes, so Apollo3 logic specifically disallows Fast GPIO input or output
646 //! when the pin is configured for tristate mode.
647 //! Fast GPIO input can be used for pushpull, opendrain, or disable modes.
648 //! @par
649 //! Fast GPIO pin groupings:
650 //! The FaST GPIO pins are grouped across a matrix of pins. Each
651 //! row of pins is controlled by a single data bit.
652 //! @par
653 //! Referring to the below chart:
654 //! - If pin 35 were configured for Fast GPIO output, it would be set
655 //! when bit3 of BBSETCLEAR.SET was written with a 1.
656 //! - It would be cleared when bit3 of BBSETCLEAR.CLEAR was written with 1.
657 //! @par
658 //! Note that if all the pins in a row were configured for Fast GPIO output,
659 //! all the pins would respond to set/clear.
660 //!
661 //! Input works in a similar fashion.
662 //!
663 //! BIT PIN controlled
664 //! --- ---------------------------------------
665 //! 0 0 8 16 24 32 40 48 56 64 72
666 //! 1 1 9 17 25 33 41 49 57 65 73
667 //! 2 2 10 18 26 34 42 50 58 66
668 //! 3 3 11 19 27 35 43 51 59 67
669 //! 4 4 12 20 28 36 44 52 60 68
670 //! 5 5 13 21 29 37 45 53 61 69
671 //! 6 6 14 22 30 38 46 54 62 70
672 //! 7 7 15 23 31 39 47 55 63 71
673 //!
674 //
675 //*****************************************************************************
676 extern uint32_t am_hal_gpio_fast_pinconfig(am_hal_gpio_mask_t *psPinMask,
677 am_hal_gpio_pincfg_t bfGpioCfg,
678 uint32_t ui32Masks[]);
679
680 //*****************************************************************************
681 //
682 //! @brief Read GPIO.
683 //!
684 //! This function reads a pin state as given by eReadType.
685 //!
686 //! @param ui32Pin - pin number to be read.
687 //! @param eReadType - State type to read. One of:
688 //! - AM_HAL_GPIO_INPUT_READ
689 //! - AM_HAL_GPIO_OUTPUT_READ
690 //! - AM_HAL_GPIO_ENABLE_READ
691 //! @param pui32ReadState - returns pin state value here
692 //!
693 //! @return Status.
694 //
695 //*****************************************************************************
696 extern uint32_t am_hal_gpio_state_read(
697 uint32_t ui32Pin,
698 am_hal_gpio_read_type_e eReadType,
699 uint32_t *pui32ReadState);
700
701 //*****************************************************************************
702 //
703 //! @brief Write GPIO.
704 //!
705 //! @param ui32Pin - pin number to be read.
706 //! @param eWriteType - State type to write. One of:
707 //! - AM_HAL_GPIO_OUTPUT_SET - Write a one to a GPIO.
708 //! - AM_HAL_GPIO_OUTPUT_CLEAR - Write a zero to a GPIO.
709 //! - AM_HAL_GPIO_OUTPUT_TOGGLE - Toggle the GPIO value.
710 //! - ** The following two apply when output is set for TriState (OUTCFG==3).
711 //! - AM_HAL_GPIO_OUTPUT_TRISTATE_ENABLE - Enable a tri-state GPIO.
712 //! - AM_HAL_GPIO_OUTPUT_TRISTATE_DISABLE - Disable a tri-state GPIO.
713 //!
714 //! This function writes a GPIO value.
715 //!
716 //! @return Status.
717 //! - Fails if the pad is not configured for GPIO (PADFNCSEL != 3).
718 //
719 //*****************************************************************************
720 extern uint32_t am_hal_gpio_state_write(uint32_t ui32Pin,
721 am_hal_gpio_write_type_e eWriteType);
722
723 //*****************************************************************************
724 //
725 //! @brief Enable GPIO interrupts.
726 //!
727 //! @param pGpioIntMask - Mask of GPIO interrupts to enable.\n
728 //! - Only bits 0-73 are valid in the mask.
729 //!
730 //! @return Status.
731 //! - Fails if any bit above bit73 is set in pGpioIntMask.
732 //
733 //*****************************************************************************
734 extern uint32_t am_hal_gpio_interrupt_enable(am_hal_gpio_mask_t *pGpioIntMask);
735
736 //*****************************************************************************
737 //
738 //! @brief Disable GPIO interrupts.
739 //!
740 //! @param pGpioIntMask - Mask of GPIO interrupts to disable.\n
741 //! - Only bits 0-73 are valid in the mask.
742 //!
743 //! @return Status.
744 //! - Fails if any bit above bit73 is set in pGpioIntMask.
745 //
746 //*****************************************************************************
747 extern uint32_t am_hal_gpio_interrupt_disable(am_hal_gpio_mask_t *pGpioIntMask);
748
749 //*****************************************************************************
750 //
751 //! @brief Clear GPIO interrupts.
752 //!
753 //! @param pGpioIntMask - Mask of GPIO interrupts to be cleared.\n
754 //! - Only bits 0-73 are valid in the mask.
755 //!
756 //! @return Status.
757 //! - Fails if any bit above bit73 is set in pGpioIntMask.
758 //
759 //*****************************************************************************
760 extern uint32_t am_hal_gpio_interrupt_clear(am_hal_gpio_mask_t *pGpioIntMask);
761
762 //*****************************************************************************
763 //
764 //! @brief Get GPIO interrupt status.
765 //!
766 //! @param bEnabledOnly - Return status only for currently enabled interrupts.
767 //!
768 //! @param pGpioIntMask - Bitmask array to return a bitmask of the status
769 //! of the interrupts.
770 //!
771 //! @return Status.
772 //! - Fails if pGpioIntMask is NULL.
773 //
774 //*****************************************************************************
775 extern uint32_t am_hal_gpio_interrupt_status_get(bool bEnabledOnly,
776 am_hal_gpio_mask_t *pGpioIntMask);
777
778 //*****************************************************************************
779 //
780 //! @brief GPIO interrupt service routine registration.
781 //!
782 //! @param ui32GPIONumber - GPIO number (0-73) to be registered.
783 //!
784 //! @param pfnHandler - Function pointer to the callback.
785 //!
786 //! @return Status.
787 //! - Fails if pfnHandler is NULL or ui32GPIONumber > 73.
788 //
789 //*****************************************************************************
790 extern uint32_t am_hal_gpio_interrupt_register(uint32_t ui32GPIONumber,
791 am_hal_gpio_handler_t pfnHandler);
792
793 //*****************************************************************************
794 //
795 //! @brief Advanced GPIO interrupt service routine registration.
796 //!
797 //! @param ui32GPIONumber - GPIO number (0-73) to be registered.
798 //!
799 //! @param pfnHandler - Function pointer to the callback.
800 //!
801 //! @param pCtxt - Context for the callback.
802 //!
803 //! @return Status.
804 //! - Fails if pfnHandler is NULL or ui32GPIONumber > 73.
805 //
806 //*****************************************************************************
807 extern uint32_t am_hal_gpio_interrupt_register_adv(uint32_t ui32GPIONumber,
808 am_hal_gpio_handler_adv_t pfnHandler, void *pCtxt);
809
810 //*****************************************************************************
811 //
812 // GPIO interrupt service routine.
813 //! @brief GPIO interrupt service routine registration.
814 //!
815 //! @param pGpioIntMask - Mask of the interrupt(s) to be serviced.\n This mask is
816 //! typically obtained via a call to am_hal_gpio_interrupt_status_get().
817 //!
818 //! The intended use is that the application first registers a handler for a
819 //! particular GPIO via am_hal_gpio_interrupt_register(), and to supply the
820 //! main ISR, am_gpio_isr().
821 //!
822 //! On a GPIO interrupt, am_gpio_isr() calls am_hal_gpio_interrupt_status_get()
823 //! and provides the return value to this function.
824 //!
825 //! In the event that multiple GPIO interrupts are active, the corresponding
826 //! interrupt handlers will be called in numerical order by GPIO number
827 //! starting with the lowest GPIO number.
828 //!
829 //! @return Status.
830 //! - AM_HAL_STATUS_INVALID_OPERATION if no handler had been registered
831 //! for any of the GPIOs that caused the interrupt.
832 //! - AM_HAL_STATUS_OUT_OF_RANGE if any bit above bit73 is set.
833 //! - AM_HAL_STATUS_FAIL if pGpioIntMask is 0.
834 //! - AM_HAL_STATUS_SUCCESS otherwise.
835 //
836 //*****************************************************************************
837 extern uint32_t am_hal_gpio_interrupt_service(am_hal_gpio_mask_t *pGpioIntMask);
838
839 //*****************************************************************************
840 //!
841 //! am_hal_gpio_isinput()
842 //!
843 //! Determine whether a pad is configured with input enable.
844 //! Returns true if input enable is set, false otherwise.
845 //!
846 //*****************************************************************************
847 extern bool am_hal_gpio_isinput(uint32_t ui32Pin);
848
849 //*****************************************************************************
850 //!
851 //! am_hal_gpio_isgpio()
852 //!
853 //! Determine whether the GPIO is configured as input or output.
854 //!
855 //! Return values:
856 //! 0: Pin is not configured as GPIO.
857 //! 1: Pin is configured as GPIO input.
858 //! 2: Pin is configured as GPIO output.
859 //!
860 //*****************************************************************************
861 extern uint32_t am_hal_gpio_isgpio(uint32_t ui32Pin);
862
863 //*****************************************************************************
864 //
865 //! @name Helper macros
866 //! @{
867 //
868 //*****************************************************************************
869 #define AM_HAL_MASK32(n) ((uint32_t)1 << ((n) & 0x1F))
870
871 #define AM_HAL_GPIO_RDn(pin) ((volatile uint32_t *)&GPIO->RDA + (((pin) >> 5) & 0x3))
872 #define AM_HAL_GPIO_WTn(pin) ((volatile uint32_t *)&GPIO->WTA + (((pin) >> 5) & 0x3))
873 #define AM_HAL_GPIO_WTCn(pin) ((volatile uint32_t *)&GPIO->WTCA + (((pin) >> 5) & 0x3))
874 #define AM_HAL_GPIO_WTSn(pin) ((volatile uint32_t *)&GPIO->WTSA + (((pin) >> 5) & 0x3))
875 #define AM_HAL_GPIO_ENn(pin) ((volatile uint32_t *)&GPIO->ENA + (((pin) >> 5) & 0x3))
876 #define AM_HAL_GPIO_ENCn(pin) ((volatile uint32_t *)&GPIO->ENCA + (((pin) >> 5) & 0x3))
877 #define AM_HAL_GPIO_ENSn(pin) ((volatile uint32_t *)&GPIO->ENSA + (((pin) >> 5) & 0x3))
878
879 //! @}
880
881 //*****************************************************************************
882 //
883 //! @brief Macros to read GPIO values in an optimized manner.
884 //!
885 //! @param n - The GPIO number to be read.
886 //!
887 //! In almost all cases, it is reasonable to use am_hal_gpio_state_read() to
888 //! read GPIO values with all of the inherent error checking, critical
889 //! sectioning, and general safety.
890 //!
891 //! However, occasionally there is a need to read a GPIO value in an optimized
892 //! manner. These 3 macros will accomplish that. Each macro will return a
893 //! value of 1 or 0.
894 //!
895 //! Note that the macros are named as lower-case counterparts to the
896 //! enumerations for the am_hal_gpio_state_read() function. That is:
897 //!
898 //! AM_HAL_GPIO_INPUT_READ -> am_hal_gpio_input_read(n)
899 //! AM_HAL_GPIO_OUTPUT_READ -> am_hal_gpio_output_read(n)
900 //! AM_HAL_GPIO_ENABLE_READ -> am_hal_gpio_enable_read(n)
901 //!
902 //! @return Each macro will return a 1 or 0 per the value of the requested GPIO.
903 //!
904 //
905 //*****************************************************************************
906 #define am_hal_gpio_input_read(n) ((*AM_HAL_GPIO_RDn((n)) >> ((n) % 32)) & 1)
907 #define am_hal_gpio_output_read(n) ((*AM_HAL_GPIO_WTn((n)) >> ((n) % 32)) & 1)
908 #define am_hal_gpio_enable_read(n) ((*AM_HAL_GPIO_ENn((n)) >> ((n) % 32)) & 1)
909
910
911 //*****************************************************************************
912 //
913 //! @brief Macros to write GPIO values in an optimized manner.
914 //!
915 //! @param n - The GPIO number to be written.
916 //!
917 //! In almost all cases, it is reasonable to use am_hal_gpio_state_write() to
918 //! write GPIO values with all of the inherent error checking, critical
919 //! sectioning, and general safety.
920 //!
921 //! However, occasionally there is a need to write a GPIO value in an optimized
922 //! manner. These 3 macros will accomplish that.
923 //!
924 //! Note that the macros are named as lower-case counterparts to the
925 //! enumerations for the am_hal_gpio_state_read() function. That is:
926 //!
927 //! AM_HAL_GPIO_OUTPUT_CLEAR -> am_hal_gpio_output_clear(n)
928 //! AM_HAL_GPIO_OUTPUT_SET -> am_hal_gpio_output_set(n)
929 //! AM_HAL_GPIO_OUTPUT_TOGGLE -> am_hal_gpio_output_toggle(n)
930 //! AM_HAL_GPIO_OUTPUT_TRISTATE_DISABLE -> am_hal_gpio_output_tristate_disable(n)
931 //! AM_HAL_GPIO_OUTPUT_TRISTATE_ENABLE -> am_hal_gpio_output_tristate_enable(n)
932 //! AM_HAL_GPIO_OUTPUT_TRISTATE_TOGGLE -> am_hal_gpio_output_tristate_toggle(n)
933 //!
934 //! @return None.
935 //!
936 //*****************************************************************************
937 //
938 // Note - these macros use byte-oriented addressing.
939 //
940 #define am_hal_gpio_output_clear(n) \
941 ((*((volatile uint32_t *) \
942 ((AM_REGADDR(GPIO, WTCA) + (((uint32_t)(n) & 0x60) >> 3))))) = \
943 ((uint32_t) 0x1 << ((uint32_t)(n) % 32)))
944
945 #define am_hal_gpio_output_set(n) \
946 ((*((volatile uint32_t *) \
947 ((AM_REGADDR(GPIO, WTSA) + (((uint32_t)(n) & 0x60) >> 3))))) = \
948 ((uint32_t) 0x1 << ((uint32_t)(n) % 32)))
949
950 #define am_hal_gpio_output_toggle(n) \
951 if ( 1 ) \
952 { \
953 AM_CRITICAL_BEGIN \
954 ((*((volatile uint32_t *) \
955 ((AM_REGADDR(GPIO, WTA) + (((uint32_t)(n) & 0x60) >> 3))))) ^= \
956 ((uint32_t) 0x1 << ((uint32_t)(n) % 32))); \
957 AM_CRITICAL_END \
958 }
959
960 #define am_hal_gpio_output_tristate_disable(n) \
961 ((*((volatile uint32_t *) \
962 ((AM_REGADDR(GPIO, ENCA) + (((uint32_t)(n) & 0x60) >> 3))))) = \
963 ((uint32_t) 0x1 << ((uint32_t)(n) % 32)))
964
965 #define am_hal_gpio_output_tristate_enable(n) \
966 ((*((volatile uint32_t *) \
967 ((AM_REGADDR(GPIO, ENSA) + (((uint32_t)(n) & 0x60) >> 3))))) = \
968 ((uint32_t) 0x1 << ((uint32_t)(n) % 32)))
969
970 #define am_hal_gpio_output_tristate_toggle(n) \
971 if ( 1 ) \
972 { \
973 AM_CRITICAL_BEGIN \
974 ((*((volatile uint32_t *) \
975 ((AM_REGADDR(GPIO, ENA) + (((uint32_t)(n) & 0x60) >> 3))))) ^= \
976 ((uint32_t) 0x1 << ((uint32_t)(n) % 32))); \
977 AM_CRITICAL_END \
978 }
979
980
981 //*****************************************************************************
982 //!
983 //! @brief Fast GPIO helper macros.
984 //!
985 //*****************************************************************************
986 //
987 // Define Fast GPIO enable and disable.
988 //
989 #define am_hal_gpio_fastgpio_enable(n) am_hal_gpio_output_tristate_enable(n)
990 #define am_hal_gpio_fastgpio_disable(n) am_hal_gpio_output_tristate_disable(n)
991
992 //
993 // Macros for accessing Fast GPIO: set, clear, and read.
994 // The 'n' parameter is the pin number.
995 // Note - these macros are most efficient if 'n' is a constant value, and
996 // of course when compiled with -O3.
997 //
998 #define am_hal_gpio_fastgpio_read(n) ((APBDMA->BBINPUT >> (n & 0x7)) & 0x1)
999 #define am_hal_gpio_fastgpio_set(n) (APBDMA->BBSETCLEAR = _VAL2FLD(APBDMA_BBSETCLEAR_SET, (1 << (n & 0x7))))
1000 #define am_hal_gpio_fastgpio_clr(n) (APBDMA->BBSETCLEAR = _VAL2FLD(APBDMA_BBSETCLEAR_CLEAR, (1 << (n & 0x7))))
1001 #define am_hal_gpio_fastgpio_setmsk(m) (APBDMA->BBSETCLEAR = _VAL2FLD(APBDMA_BBSETCLEAR_SET, m))
1002 #define am_hal_gpio_fastgpio_clrmsk(m) (APBDMA->BBSETCLEAR = _VAL2FLD(APBDMA_BBSETCLEAR_CLEAR, m))
1003 #define am_hal_gpio_fastgpio_wrval(val) (APBDMA->BBSETCLEAR = \
1004 (_VAL2FLD(APBDMA_BBSETCLEAR_SET, val) | \
1005 _VAL2FLD(APBDMA_BBSETCLEAR_CLEAR, val ^ 0xFF)))
1006
1007
1008 #ifdef __cplusplus
1009 }
1010 #endif
1011
1012 #endif // AM_HAL_GPIO_H
1013
1014 //*****************************************************************************
1015 //
1016 // End Doxygen group.
1017 //! @}
1018 //
1019 //*****************************************************************************
1020
