Add set clock div (#2572)

* Add spi.set_clock_div

This will allow the SPI clock divider to be changed relatively simply,
to better support multiple devices with varying SPI clock rate support

* Add documentation

app/modules/spi.c

@@ -301,6 +301,22 @@ static int spi_transaction( lua_State *L )
   return 0;
 }
 
+// Lua: old_div = spi.set_clock_div( id, new_div )
+static int spi_set_clock_div( lua_State *L )
+{
+  int id = luaL_checkinteger( L, 1 );
+
+  MOD_CHECK_ID( spi, id );
+
+  u32 clk_div = luaL_checkinteger( L, 2 );
+
+  u32 old_div = spi_set_clkdiv(id, clk_div);
+
+  lua_pushinteger( L, old_div );
+
+  return 1;
+}
+
 
 // Module function map
 static const LUA_REG_TYPE spi_map[] = {
@@ -310,6 +326,7 @@ static const LUA_REG_TYPE spi_map[] = {
   { LSTRKEY( "set_mosi" ),    LFUNCVAL( spi_set_mosi ) },
   { LSTRKEY( "get_miso" ),    LFUNCVAL( spi_get_miso ) },
   { LSTRKEY( "transaction" ), LFUNCVAL( spi_transaction ) },
+  { LSTRKEY( "set_clock_div" ), LFUNCVAL( spi_set_clock_div ) },
   { LSTRKEY( "MASTER" ),      LNUMVAL( PLATFORM_SPI_MASTER ) },
   { LSTRKEY( "SLAVE" ),       LNUMVAL( PLATFORM_SPI_SLAVE) },
   { LSTRKEY( "CPHA_LOW" ),    LNUMVAL( PLATFORM_SPI_CPHA_LOW) },

docs/en/modules/spi.md

@@ -129,6 +129,26 @@ spi.setup(1, spi.MASTER, spi.CPOL_LOW, spi.CPHA_LOW, 8, 8)
 gpio.mode(8, gpio.INPUT, gpio.PULLUP)
 ```
 
+## spi.set_clock_div()
+Set the SPI clock divider.
+
+#### Syntax
+`old_div = spi.set_clock_div(id, clock_div)`
+
+#### Parameters
+- `id` SPI ID number: 0 for SPI, 1 for HSPI
+- `clock_div` SPI clock divider, f(SPI) = 80 MHz / `clock_div`, 1 .. n
+
+#### Returns
+Number: Old clock divider
+
+#### Example
+```lua
+old_div = spi.set_clock_div(1, 84) --drop to slow clock for slow device
+spi.send(1, 0x0B, 0xFF)
+spi.set_clock_div(1, old_div)
+```
+
 ## Low Level Hardware Functions
 The low level functions provide a hardware-centric API for application
 scenarios that need to excercise more complex SPI transactions. The