MFC r274670, r274671, r276168:

Moves all the duplicate code to a single function.

Verify for invalid modes and unwanted flags before pass the new flags to
driver.

Make gpio_default_map_gpios() static. No functional changes.

Improves the GPIO API description a little bit.

gpio_pin_max must return the maximum supported pin number and not the total
number of pins on the system.