Architecture: How to define pins for a new board?

As I work upon the ESP8266 port, the time has come to provide some attention on the GPIO mechanism. When one defines a new board, one creates a Python script with the board name under /boards. It appears that within this script, we can define a variable called devices as well as define a function called get_pins(). What I am hoping I can get is some boot strap information on these. In return, I'll write up a users guide for those who may follow. Let's start with get_pins. What is that supposed to return when called?

Great, if you could write some stuff as a .md file and link it from https://github.com/espruino/Espruino/blob/master/README.md#adding-more-devices it'd be hugely helpful (to be honest you could probably copy/paste what's below). If it's small you could just add it under that heading, or maybe move the contents out into NewDevices.md or something.

get_pins

Best to look here for an example of exactly what needs to get returned.

On ST chips some utility functions auto-generate the code from CSV files that were copied from ST's datasheets.

• name is the pin name - due to random historical reasons (from ST datasheets) it needs prefixing with P
  
• sortingname is the name, but padded so that when it's sorted everything appears in the right order
  
• port is the actual port - on ESP8266 this might not be needed and could just default to D
  
• num is the pin number - this doesn't have to match D - it's what is needed internally to access the hardware. For instance Olimexino has 'logical' pins that actually map all over the place.
  
• function is a map of pin functions to their 'alternate functions' (an STM32 chip thing - STM32F4 chips can have different peripherals on each pin, so the alternate function is a number that you shove in that pin's register in order to connect it to that peripheral). The format, for instance I2C1_SDA is important as it's parsed later and is used to build gen/jspininfo.c. The code to parse them is here
  
• csv isn't needed afaik, but when using data grabbed from csv files from ST's datasheets like this it contains the raw data for debugging)
  
  
  

devices

This is a list of built-in stuff on the board that is made accessible to Espruino. It's parsed and turned into defines in gen/platform_config.h by this code

Stuff you can use is LED1-8, BTN1-4, USB, LCD (for boards with FSMC LCDs built in), SD (SD card), JTAG (when JTAG pins are defined, but we need to make sure we leave them alone when the board resets).

Excellent ... thank you my friend. As I was studying the GPIO subsystem yesterday and making notes I was writing up the following:

https://github.com/esp8266-espruino/esp8266-espurino/wiki/68-Espruino-GPIO

So will merge your words into that. At the end of the Espruino-ESP8266 board making exercise once we have merged into the master, that project will be taken down an destroyed ... however, before that ... we will decide what (if anything) to harvest from the notes I have been taking and maybe bring those into the master project too ... if that is useful to you.