Definition and comments improvements for pins management

Signed-off-by: Frederic Pillon <frederic.pillon@st.com>

Author: fpistm

cores/arduino/pins_arduino.c

@@ -77,7 +77,7 @@ bool digitalpinIsAnalogInput(uint32_t pin)
 {
   bool ret = false;
 #if NUM_ANALOG_INPUTS > 0
-  if ((pin & PANA) == PANA) {
+  if ((pin & PNUM_ANALOG_BASE) == PNUM_ANALOG_BASE) {
     ret = true;
   } else {
     for (uint32_t i = 0; i < NUM_ANALOG_INPUTS; i++) {
@@ -100,9 +100,9 @@ uint32_t digitalPinToAnalogInput(uint32_t pin)
 {
   uint32_t ret = NUM_ANALOG_INPUTS;
 #if NUM_ANALOG_INPUTS > 0
-  if ((pin & PANA) == PANA) {
+  if ((pin & PNUM_ANALOG_BASE) == PNUM_ANALOG_BASE) {
     /* PYn = Ax */
-    ret = (pin & PANA_IDX) | (pin & ALTX_MASK);
+    ret = (pin & PNUM_ANALOG_INDEX) | (pin & ALTX_MASK);
   } else {
     for (uint32_t i = 0; i < NUM_ANALOG_INPUTS; i++) {
       if (analogInputPin[i] == (pin & PNUM_MASK)) {

cores/arduino/pins_arduino.h

@@ -25,7 +25,10 @@
 #include "pins_arduino_analog.h"
 #include "pins_arduino_digital.h"
 
-/* Pin number */
+/*
+ * Pin number mask
+ * allows to retrieve the pin number without ALTx
+ */
 #define PNUM_MASK 0xFF
 
 /* Avoid PortName issue */
@@ -90,9 +93,9 @@ extern const uint32_t analogInputPin[];
 /* Note: Analog pin is also a digital pin */
 #define digitalPinToPinName(p)      ((((uint32_t)(p) & PNUM_MASK) < NUM_DIGITAL_PINS) ? \
             (PinName)(digitalPin[(uint32_t)(p) & PNUM_MASK] | ((p) & ALTX_MASK)) : \
-            (((uint32_t)(p) & PANA) == PANA) && \
+            (((uint32_t)(p) & PNUM_ANALOG_BASE) == PNUM_ANALOG_BASE) && \
             (((uint32_t)(p) & PNUM_MASK) < NUM_ANALOG_INTERNAL_FIRST) ? \
-            (PinName)(digitalPin[analogInputPin[(p) & PANA_IDX]] | ((p) & ALTX_MASK)) : NC)
+            (PinName)(digitalPin[analogInputPin[(p) & PNUM_ANALOG_INDEX]] | ((p) & ALTX_MASK)) : NC)
 #else
 #define digitalPinToPinName(p)      ((((uint32_t)(p) & PNUM_MASK) < NUM_DIGITAL_PINS) ? \
             (PinName)(digitalPin[(uint32_t)(p) & PNUM_MASK] | ((p) & ALTX_MASK)) : NC)
@@ -106,9 +109,9 @@ uint32_t pinNametoDigitalPin(PinName p);
 /* Non contiguous analog pins definition in digitalPin array */
 #define analogInputToDigitalPin(p)  ((((uint32_t)(p) & PNUM_MASK) < NUM_ANALOG_INPUTS) ? \
             analogInputPin[(uint32_t)(p) & PNUM_MASK] | ((uint32_t)(p) & ALTX_MASK) : \
-            (((uint32_t)(p) & PANA) == PANA) && \
+            (((uint32_t)(p) & PNUM_ANALOG_BASE) == PNUM_ANALOG_BASE) && \
             (((uint32_t)(p) & PNUM_MASK) < NUM_ANALOG_INTERNAL_FIRST) ? \
-            analogInputPin[(p) & PANA_IDX] | ((uint32_t)(p) & ALTX_MASK) : (uint32_t)NC)
+            analogInputPin[(p) & PNUM_ANALOG_INDEX] | ((uint32_t)(p) & ALTX_MASK) : (uint32_t)NC)
 #else/* No analog pin defined */
 #define analogInputToDigitalPin(p)  (NUM_DIGITAL_PINS)
 #endif /* NUM_ANALOG_INPUTS > 0 */

cores/arduino/pins_arduino_analog.h

@@ -15,18 +15,29 @@
 #include "variant.h"
 #include "PinNames.h"
 
-/* Analog */
-#define PANA       0xC0
-/* Analog index */
-#define PANA_IDX   0x3F
+/*
+ * Pin number Analog base
+ * To check if a pin number is an analog pin:
+ * ((p & PNUM_ANALOG_BASE) == PNUM_ANALOG_BASE)
+ * if true then p is an analog pin number
+ * else not
+ */
+#define PNUM_ANALOG_BASE    0xC0
+/*
+ * Pin number Analog index
+ * allows to retrieve the pin number index of an analog pin
+ * in the analogInputPin[] array:
+ * analogInputPin[p & PNUM_ANALOG_INDEX]
+ */
+#define PNUM_ANALOG_INDEX   0x3F
 
 /* Arduino analog pins */
 #ifndef NUM_ANALOG_INPUTS
   #define NUM_ANALOG_INPUTS 0
 #endif
 
 /* Analog internal pin numbers follow the analog pin number */
-#define NUM_ANALOG_INTERNAL_FIRST (PANA + NUM_ANALOG_INPUTS)
+#define NUM_ANALOG_INTERNAL_FIRST (PNUM_ANALOG_BASE + NUM_ANALOG_INPUTS)
 
 /* ADC internal channels (not a pins) */
 /* Only used for analogRead() */
@@ -46,7 +57,7 @@
 /* If NUM_ANALOG_INPUTS is not defined there is no analog pins defined. */
 /* Anyway ADC internal channels are always available. */
 #if NUM_ANALOG_INPUTS > 0
-#define PIN_A0       PANA
+#define PIN_A0       PNUM_ANALOG_BASE
 #if NUM_ANALOG_INPUTS > 1
   #define PIN_A1      (PIN_A0 + 1)
 #endif

cores/arduino/stm32/PinNames.h

@@ -9,26 +9,26 @@ extern "C" {
 #endif
 
 // Alternative possibilities which use other HW peripheral instances
-#define ALT0        0x100
-#define ALT1        0x200
-#define ALT2        0x300
-#define ALT3        0x400
-#define ALT4        0x500
-#define ALT5        0x600
-#define ALT6        0x700
+#define ALT0                        0x100
+#define ALT1                        0x200
+#define ALT2                        0x300
+#define ALT3                        0x400
+#define ALT4                        0x500
+#define ALT5                        0x600
+#define ALT6                        0x700
 // ALTX mask
-#define ALTX_MASK   0x700
+#define ALTX_MASK                   0x700
 // Specific pinmap definition
 // Analog internal
-#define PANAINT     0x1000
+#define PNAME_ANALOG_INTERNAL_BASE  0x1000
 // Dual pad pin
 // Direct channels are connected to analog I/Os
 // (PY_C) to optimize ADC performance.
-#define PDUAL       0x2000
+#define PDUAL                       0x2000
 // Remap pin
-#define PREMAP      0x3000
+#define PREMAP                      0x3000
 // PinName mask
-#define PNAME_MASK  0xFF
+#define PNAME_MASK                  0xFF
 
 typedef enum {
   // Not connected
@@ -249,7 +249,7 @@ typedef enum {
   PZ_15 = (PortZ << 4) + 0x0F,
 #endif
   // Specific pin name
-  PADC_BASE = PANAINT,
+  PADC_BASE = PNAME_ANALOG_INTERNAL_BASE,
 #if defined(ADC_CHANNEL_TEMPSENSOR) || defined(ADC_CHANNEL_TEMPSENSOR_ADC1)
   PADC_TEMP,
 #endif

keywords.txt

@@ -734,8 +734,11 @@ ALT4	LITERAL1
 ALT5	LITERAL1
 ALT6	LITERAL1
 ATLX_MASK	LITERAL1
-PANA	LITERAL1
-PANAINT	LITERAL1
+PNUM_MASK	LITERAL1
+PNUM_ANALOG_BASE	LITERAL1
+PNUM_ANALOG_INDEX	LITERAL1
+PNAME_MASK	LITERAL1
+PNAME_ANALOG_INTERNAL_BASE	LITERAL1
 PDUAL	LITERAL1
 PREMAP	LITERAL1