/** \addtogroup hal */
/** @{*/
/* mbed Microcontroller Library
 * Copyright (c) 2006-2013 ARM Limited
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef MBED_PINMAP_H
#define MBED_PINMAP_H

#include "PinNames.h"
#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
    PinName pin;
    int peripheral;
    int function;
} PinMap;

typedef struct {
    uint32_t count;
    const PinName *pins;
} PinList;

typedef struct {
    uint32_t count;
    const int *peripheral;
} PeripheralList;

void pin_function(PinName pin, int function);
void pin_mode(PinName pin, PinMode mode);

uint32_t pinmap_peripheral(PinName pin, const PinMap *map);
uint32_t pinmap_function(PinName pin, const PinMap *map);
uint32_t pinmap_merge(uint32_t a, uint32_t b);
void     pinmap_pinout(PinName pin, const PinMap *map);
uint32_t pinmap_find_peripheral(PinName pin, const PinMap *map);
uint32_t pinmap_find_function(PinName pin, const PinMap *map);

/**
 * Find a combination of pins suitable for use given the constraints
 *
 * This function finds pins which meet these specific properties:
 * - The pin is part of the form factor
 * - The pin is not in the restricted list
 * - The pin is contained within the respective pinmap
 * - The pin belongs to the given peripheral
 * - Each pin found is distinct; in the example below
 *      mosi and miso will never be assigned the same pin
 *
 * Example:
 * @code
 * #include "mbed.h"
 * #include "pinmap.h"
 *
 * int main()
 * {
 *     int per = spi_master_cs_pinmap()->peripheral;
 *     const PinList *pins_ff = pinmap_ff_default_pins();
 *     const PinList *pins_avoid = pinmap_restricted_pins();
 *     PinName mosi = NC;
 *     PinName miso = NC;
 *     PinName sclk = NC;
 *     PinName ssel = NC;
 *     const PinMap *maps[] = {
 *         spi_master_mosi_pinmap(),
 *         spi_master_miso_pinmap(),
 *         spi_master_clk_pinmap(),
 *         spi_master_cs_pinmap()
 *     };
 *     PinName *pins[] = {
 *         &mosi,
 *         &miso,
 *         &sclk,
 *         &ssel
 *     };
 *     if (pinmap_find_peripheral_pins(pins_ff, pins_avoid, per, maps, pins, sizeof(maps) / sizeof(maps[0]))) {
 *         printf("Found SPI pins to test instance %i with:\n"
 *                "  mosi=%s\n"
 *                "  miso=%s\n"
 *                "  sclk=%s\n"
 *                "  ssel=%s\n", per,
 *                pinmap_ff_default_pin_to_string(mosi),
 *                pinmap_ff_default_pin_to_string(miso),
 *                pinmap_ff_default_pin_to_string(sclk),
 *                pinmap_ff_default_pin_to_string(ssel));
 *     } else {
 *         printf("Could not find SPI combination to test %i\n", per);
 *     }
 *     return 0;
 * }
 * @endcode
 *
 * @param whitelist List of pins to choose from
 * @param blacklist List of pins which cannot be used
 * @param per Peripheral to which the pins belong
 * @param maps An array of pin maps to select from
 * @param pins An array of pins to find. Pins already set to a value will be
 *             left unchanged. Only pins initialized to NC will be updated by this function
 * @param count The size of maps and pins
 * @return true if a suitable combination of pins was found and
 *         written to the pins array, otherwise false
 */
bool pinmap_find_peripheral_pins(const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count);

/**
 * Check if the pin is in the list
 *
 * @param list pin list to check
 * @param pin pin to check for in the list
 * @return true if the pin is in the list, false otherwise
 */
bool pinmap_list_has_pin(const PinList *list, PinName pin);

/**
 * Check if the peripheral is in the list
 *
 * @param list peripheral list to check
 * @param peripheral peripheral to check for in the list
 * @return true if the peripheral is in the list, false otherwise
 */
bool pinmap_list_has_peripheral(const PeripheralList *list, int peripheral);

/**
 * Get the pin list of pins to avoid during testing
 *
 * The restricted pin list is used to indicate to testing
 * that a pin should be skipped due to some caveat about it.
 * For example, using USBRX and USBTX during tests will interfere
 * with the test runner and should be avoided.
 *
 * Targets should override the weak implementation of this
 * function if they have additional pins which should be
 * skipped during testing.
 *
 * @return Pointer to a pin list of pins to avoid
 */
const PinList *pinmap_restricted_pins(void);

/**
 * Get the pin list of peripherals per interface to avoid during testing
 *
 * The restricted peripheral list is used to indicate to testing
 * that a peripheral should be skipped due to some caveat about it.
 * For example, using the USB serial port during tests will interfere
 * with the test runner and should be avoided.
 *
 * Targets should override the weak implementation of this
 * function if they have peripherals which should be
 * skipped during testing.
 *
 * @note Restricting peripheral is at the moment available for UART
 *       interface only as only STDIO UART must be skipped because it is
 *       used by Mbed.
 *       Restricting peripherals for other interfaces should be added
 *       in the future if required.
 *
 * @return Pointer to a peripheral list of peripheral to avoid
 */
#if DEVICE_SERIAL
const PeripheralList *pinmap_uart_restricted_peripherals(void);
#endif

/**
 * Get the pin list of pins to avoid during GPIO/GPIO_IRQ testing
 *
 * The GPIO restricted pin list is used to indicate to testing
 * that a pin should be skipped due to some caveat about it.
 *
 * Targets should override the weak implementation of this
 * function if they have peripherals which should be
 * skipped during testing.
 *
 * @note This is special case only for GPIO/GPIO_IRQ tests because
 *       targets do not provide pin-maps for GPIO.
 *
 * @return Pointer to a peripheral list of peripheral to avoid
 */
const PinList *pinmap_gpio_restricted_pins(void);

#ifdef TARGET_FF_ARDUINO

/**
 * Get the pin list of the Arduino form factor
 *
 * @return Pointer to the Arduino pin list
 */
const PinList *pinmap_ff_arduino_pins(void);

/**
 * Get the string representation of a form factor pin
 *
 * @param pin Pin to get a string for
 * @return String representing the form factor pin
 */
const char *pinmap_ff_arduino_pin_to_string(PinName pin);

/* Default to arduino form factor if unspecified */
#ifndef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
#define MBED_CONF_TARGET_DEFAULT_FORM_FACTOR arduino
#endif

#endif

#ifdef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR

#define PINMAP_DEFAULT_PINS_(name)              pinmap_ff_ ## name ## _pins
#define PINMAP_DEFAULT_PIN_TO_STRING_(name)     pinmap_ff_ ## name ## _pin_to_string
#define PINMAP_DEFAULT_PINS(name)               PINMAP_DEFAULT_PINS_(name)
#define PINMAP_DEFAULT_PIN_TO_STRING(name)      PINMAP_DEFAULT_PIN_TO_STRING_(name)
#define pinmap_ff_default_pins                  PINMAP_DEFAULT_PINS(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
#define pinmap_ff_default_pin_to_string         PINMAP_DEFAULT_PIN_TO_STRING(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)

/**
 * Get the pin list of the default form factor
 *
 * This is an alias to whichever form factor is set
 * to be the default.
 *
 * @return Pointer to the default pin list
 */
const PinList *pinmap_ff_default_pins(void);

/**
 * Get the string representation of a form factor pin
 *
 * This is an alias to whichever form factor is set
 * to be the default.
 *
 * @param pin Pin to get a string for
 * @return String representing the form factor pin
 */
const char *pinmap_ff_default_pin_to_string(PinName pin);

#endif

#ifdef __cplusplus
}
#endif

#endif

/** @}*/