From 7ee49d03eaf20fb069b2236dde3cdcac8174780d Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Thu, 18 Jul 2019 00:34:00 -0700 Subject: [PATCH] doc: driver-model: Convert spi-howto.txt to reST Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Bin Meng --- doc/driver-model/index.rst | 1 + doc/driver-model/spi-howto.rst | 692 +++++++++++++++++++++++++++++++++++++++++ doc/driver-model/spi-howto.txt | 623 ------------------------------------- 3 files changed, 693 insertions(+), 623 deletions(-) create mode 100644 doc/driver-model/spi-howto.rst delete mode 100644 doc/driver-model/spi-howto.txt diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index 82f4393..64151bd 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -17,3 +17,4 @@ Driver Model pmic-framework remoteproc-framework serial-howto + spi-howto diff --git a/doc/driver-model/spi-howto.rst b/doc/driver-model/spi-howto.rst new file mode 100644 index 0000000..a538fdc --- /dev/null +++ b/doc/driver-model/spi-howto.rst @@ -0,0 +1,692 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port a SPI driver to driver model +======================================== + +Here is a rough step-by-step guide. It is based around converting the +exynos SPI driver to driver model (DM) and the example code is based +around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for +v2015.04. + +It is quite long since it includes actual code examples. + +Before driver model, SPI drivers have their own private structure which +contains 'struct spi_slave'. With driver model, 'struct spi_slave' still +exists, but now it is 'per-child data' for the SPI bus. Each child of the +SPI bus is a SPI slave. The information that was stored in the +driver-specific slave structure can now be port in private data for the +SPI bus. + +For example, struct tegra_spi_slave looks like this: + +.. code-block:: c + + struct tegra_spi_slave { + struct spi_slave slave; + struct tegra_spi_ctrl *ctrl; + }; + +In this case 'slave' will be in per-child data, and 'ctrl' will be in the +SPI's buses private data. + + +How long does this take? +------------------------ + +You should be able to complete this within 2 hours, including testing but +excluding preparing the patches. The API is basically the same as before +with only minor changes: + +- methods to set speed and mode are separated out +- cs_info is used to get information on a chip select + + +Enable driver mode for SPI and SPI flash +---------------------------------------- + +Add these to your board config: + +* CONFIG_DM_SPI +* CONFIG_DM_SPI_FLASH + + +Add the skeleton +---------------- + +Put this code at the bottom of your existing driver file: + +.. code-block:: c + + struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, + unsigned int max_hz, unsigned int mode) + { + return NULL; + } + + struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, + int spi_node) + { + return NULL; + } + + static int exynos_spi_ofdata_to_platdata(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_probe(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_remove(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_claim_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_release_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, + const void *dout, void *din, unsigned long flags) + { + + return -ENODEV; + } + + static int exynos_spi_set_speed(struct udevice *dev, uint speed) + { + return -ENODEV; + } + + static int exynos_spi_set_mode(struct udevice *dev, uint mode) + { + return -ENODEV; + } + + static int exynos_cs_info(struct udevice *bus, uint cs, + struct spi_cs_info *info) + { + return -ENODEV; + } + + static const struct dm_spi_ops exynos_spi_ops = { + .claim_bus = exynos_spi_claim_bus, + .release_bus = exynos_spi_release_bus, + .xfer = exynos_spi_xfer, + .set_speed = exynos_spi_set_speed, + .set_mode = exynos_spi_set_mode, + .cs_info = exynos_cs_info, + }; + + static const struct udevice_id exynos_spi_ids[] = { + { .compatible = "samsung,exynos-spi" }, + { } + }; + + U_BOOT_DRIVER(exynos_spi) = { + .name = "exynos_spi", + .id = UCLASS_SPI, + .of_match = exynos_spi_ids, + .ops = &exynos_spi_ops, + .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, + .probe = exynos_spi_probe, + .remove = exynos_spi_remove, + }; + + +Replace 'exynos' in the above code with your driver name +-------------------------------------------------------- + + +#ifdef out all of the code in your driver except for the above +-------------------------------------------------------------- + +This will allow you to get it building, which means you can work +incrementally. Since all the methods return an error initially, there is +less chance that you will accidentally leave something in. + +Also, even though your conversion is basically a rewrite, it might help +reviewers if you leave functions in the same place in the file, +particularly for large drivers. + + +Add some includes +----------------- + +Add these includes to your driver: + +.. code-block:: c + + #include + #include + + +Build +----- + +At this point you should be able to build U-Boot for your board with the +empty SPI driver. You still have empty methods in your driver, but we will +write these one by one. + +Set up your platform data structure +----------------------------------- + +This will hold the information your driver to operate, like its hardware +address or maximum frequency. + +You may already have a struct like this, or you may need to create one +from some of the #defines or global variables in the driver. + +Note that this information is not the run-time information. It should not +include state that changes. It should be fixed throughout the live of +U-Boot. Run-time information comes later. + +Here is what was in the exynos spi driver: + +.. code-block:: c + + struct spi_bus { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + int inited; /* 1 if this bus is ready for use */ + int node; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + +Of these, inited is handled by DM and node is the device tree node, which +DM tells you. The name is not quite right. So in this case we would use: + +.. code-block:: c + + struct exynos_spi_platdata { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + + +Write ofdata_to_platdata() [for device tree only] +------------------------------------------------- + +This method will convert information in the device tree node into a C +structure in your driver (called platform data). If you are not using +device tree, go to 8b. + +DM will automatically allocate the struct for us when we are using device +tree, but we need to tell it the size: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), + + +Here is a sample function. It gets a pointer to the platform data and +fills in the fields from device tree. + +.. code-block:: c + + static int exynos_spi_ofdata_to_platdata(struct udevice *bus) + { + struct exynos_spi_platdata *plat = bus->platdata; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); + plat->periph_id = pinmux_decode_periph_id(blob, node); + + if (plat->periph_id == PERIPH_ID_NONE) { + debug("%s: Invalid peripheral ID %d\n", __func__, + plat->periph_id); + return -FDT_ERR_NOTFOUND; + } + + /* Use 500KHz as a suitable default */ + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", + 500000); + plat->deactivate_delay_us = fdtdec_get_int(blob, node, + "spi-deactivate-delay", 0); + debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", + __func__, plat->regs, plat->periph_id, plat->frequency, + plat->deactivate_delay_us); + + return 0; + } + + +Add the platform data [non-device-tree only] +-------------------------------------------- + +Specify this data in a U_BOOT_DEVICE() declaration in your board file: + +.. code-block:: c + + struct exynos_spi_platdata platdata_spi0 = { + .periph_id = ... + .frequency = ... + .regs = ... + .deactivate_delay_us = ... + }; + + U_BOOT_DEVICE(board_spi0) = { + .name = "exynos_spi", + .platdata = &platdata_spi0, + }; + +You will unfortunately need to put the struct definition into a header file +in this case so that your board file can use it. + + +Add the device private data +--------------------------- + +Most devices have some private data which they use to keep track of things +while active. This is the run-time information and needs to be stored in +a structure. There is probably a structure in the driver that includes a +'struct spi_slave', so you can use that. + +.. code-block:: c + + struct exynos_spi_slave { + struct spi_slave slave; + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + struct spi_bus *bus; /* Pointer to our SPI bus info */ + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +We should rename this to make its purpose more obvious, and get rid of +the slave structure, so we have: + +.. code-block:: c + + struct exynos_spi_priv { + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +DM can auto-allocate this also: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), + + +Note that this is created before the probe method is called, and destroyed +after the remove method is called. It will be zeroed when the probe +method is called. + + +Add the probe() and remove() methods +------------------------------------ + +Note: It's a good idea to build repeatedly as you are working, to avoid a +huge amount of work getting things compiling at the end. + +The probe method is supposed to set up the hardware. U-Boot used to use +spi_setup_slave() to do this. So take a look at this function and see +what you can copy out to set things up. + +.. code-block:: c + + static int exynos_spi_probe(struct udevice *bus) + { + struct exynos_spi_platdata *plat = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + priv->regs = plat->regs; + if (plat->periph_id == PERIPH_ID_SPI1 || + plat->periph_id == PERIPH_ID_SPI2) + priv->fifo_size = 64; + else + priv->fifo_size = 256; + + priv->skip_preamble = 0; + priv->last_transaction_us = timer_get_us(); + priv->freq = plat->frequency; + priv->periph_id = plat->periph_id; + + return 0; + } + +This implementation doesn't actually touch the hardware, which is somewhat +unusual for a driver. In this case we will do that when the device is +claimed by something that wants to use the SPI bus. + +For remove we could shut down the clocks, but in this case there is +nothing to do. DM frees any memory that it allocated, so we can just +remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. + + +Implement set_speed() +--------------------- + +This should set up clocks so that the SPI bus is running at the right +speed. With the old API spi_claim_bus() would normally do this and several +of the following functions, so let's look at that function: + +.. code-block:: c + + int spi_claim_bus(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + struct exynos_spi *regs = spi_slave->regs; + u32 reg = 0; + int ret; + + ret = set_spi_clk(spi_slave->periph_id, + spi_slave->freq); + if (ret < 0) { + debug("%s: Failed to setup spi clock\n", __func__); + return ret; + } + + exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); + + spi_flush_fifo(slave); + + reg = readl(®s->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (spi_slave->mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (spi_slave->mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, ®s->ch_cfg); + writel(SPI_FB_DELAY_180, ®s->fb_clk); + + return 0; + } + + +It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. +With DM these will happen in separate methods. + + +Here is an example for the speed part: + +.. code-block:: c + + static int exynos_spi_set_speed(struct udevice *bus, uint speed) + { + struct exynos_spi_platdata *plat = bus->platdata; + struct exynos_spi_priv *priv = dev_get_priv(bus); + int ret; + + if (speed > plat->frequency) + speed = plat->frequency; + ret = set_spi_clk(priv->periph_id, speed); + if (ret) + return ret; + priv->freq = speed; + debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); + + return 0; + } + + +Implement set_mode() +-------------------- + +This should adjust the SPI mode (polarity, etc.). Again this code probably +comes from the old spi_claim_bus(). Here is an example: + +.. code-block:: c + + static int exynos_spi_set_mode(struct udevice *bus, uint mode) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + uint32_t reg; + + reg = readl(&priv->regs->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, &priv->regs->ch_cfg); + priv->mode = mode; + debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); + + return 0; + } + + +Implement claim_bus() +--------------------- + +This is where a client wants to make use of the bus, so claims it first. +At this point we need to make sure everything is set up ready for data +transfer. Note that this function is wholly internal to the driver - at +present the SPI uclass never calls it. + +Here again we look at the old claim function and see some code that is +needed. It is anything unrelated to speed and mode: + +.. code-block:: c + + static int exynos_spi_claim_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); + spi_flush_fifo(priv->regs); + + writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); + + return 0; + } + +The spi_flush_fifo() function is in the removed part of the code, so we +need to expose it again (perhaps with an #endif before it and '#if 0' +after it). It only needs access to priv->regs which is why we have +passed that in: + +.. code-block:: c + + /** + * Flush spi tx, rx fifos and reset the SPI controller + * + * @param regs Pointer to SPI registers + */ + static void spi_flush_fifo(struct exynos_spi *regs) + { + clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); + clrbits_le32(®s->ch_cfg, SPI_CH_RST); + setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); + } + + +Implement release_bus() +----------------------- + +This releases the bus - in our example the old code in spi_release_bus() +is a call to spi_flush_fifo, so we add: + +.. code-block:: c + + static int exynos_spi_release_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + spi_flush_fifo(priv->regs); + + return 0; + } + + +Implement xfer() +---------------- + +This is the final method that we need to create, and it is where all the +work happens. The method parameters are the same as the old spi_xfer() with +the addition of a 'struct udevice' so conversion is pretty easy. Start +by copying the contents of spi_xfer() to your new xfer() method and proceed +from there. + +If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an +activate function, something like this: + +.. code-block:: c + + void spi_cs_activate(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + + /* If it's too soon to do another transaction, wait */ + if (spi_slave->bus->deactivate_delay_us && + spi_slave->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - spi_slave->last_transaction_us; + if (delay_us < spi_slave->bus->deactivate_delay_us) + udelay(spi_slave->bus->deactivate_delay_us - delay_us); + } + + clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus %d\n", spi_slave->slave.bus); + spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; + } + +The new version looks like this: + +.. code-block:: c + + static void spi_cs_activate(struct udevice *dev) + { + struct udevice *bus = dev->parent; + struct exynos_spi_platdata *pdata = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + /* If it's too soon to do another transaction, wait */ + if (pdata->deactivate_delay_us && + priv->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - priv->last_transaction_us; + if (delay_us < pdata->deactivate_delay_us) + udelay(pdata->deactivate_delay_us - delay_us); + } + + clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus '%s'\n", bus->name); + priv->skip_preamble = priv->mode & SPI_PREAMBLE; + } + +All we have really done here is change the pointers and print the device name +instead of the bus number. Other local static functions can be treated in +the same way. + + +Set up the per-child data and child pre-probe function +------------------------------------------------------ + +To minimise the pain and complexity of the SPI subsystem while the driver +model change-over is in place, struct spi_slave is used to reference a +SPI bus slave, even though that slave is actually a struct udevice. In fact +struct spi_slave is the device's child data. We need to make sure this space +is available. It is possible to allocate more space that struct spi_slave +needs, but this is the minimum. + +.. code-block:: c + + U_BOOT_DRIVER(exynos_spi) = { + ... + .per_child_auto_alloc_size = sizeof(struct spi_slave), + } + + +Optional: Set up cs_info() if you want it +----------------------------------------- + +Sometimes it is useful to know whether a SPI chip select is valid, but this +is not obvious from outside the driver. In this case you can provide a +method for cs_info() to deal with this. If you don't provide it, then the +device tree will be used to determine what chip selects are valid. + +Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. +If you don't provide the cs_info() method, -ENODEV is assumed for all +chip selects that do not appear in the device tree. + + +Test it +------- + +Now that you have the code written and it compiles, try testing it using +the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your +board. + + +Prepare patches and send them to the mailing lists +-------------------------------------------------- + +You can use 'tools/patman/patman' to prepare, check and send patches for +your work. See the README for details. + +A little note about SPI uclass features +--------------------------------------- + +The SPI uclass keeps some information about each device 'dev' on the bus: + + struct dm_spi_slave_platdata: + This is device_get_parent_platdata(dev). + This is where the chip select number is stored, along with + the default bus speed and mode. It is automatically read + from the device tree in spi_child_post_bind(). It must not + be changed at run-time after being set up because platform + data is supposed to be immutable at run-time. + struct spi_slave: + This is device_get_parentdata(dev). + Already mentioned above. It holds run-time information about + the device. + +There are also some SPI uclass methods that get called behind the scenes: + + spi_post_bind(): + Called when a new bus is bound. + This scans the device tree for devices on the bus, and binds + each one. This in turn causes spi_child_post_bind() to be + called for each, which reads the device tree information + into the parent (per-child) platform data. + spi_child_post_bind(): + Called when a new child is bound. + As mentioned above this reads the device tree information + into the per-child platform data + spi_child_pre_probe(): + Called before a new child is probed. + This sets up the mode and speed in struct spi_slave by + copying it from the parent's platform data for this child. + It also sets the 'dev' pointer, needed to permit passing + 'struct spi_slave' around the place without needing a + separate 'struct udevice' pointer. + +The above housekeeping makes it easier to write your SPI driver. diff --git a/doc/driver-model/spi-howto.txt b/doc/driver-model/spi-howto.txt deleted file mode 100644 index 38c26f6..0000000 --- a/doc/driver-model/spi-howto.txt +++ /dev/null @@ -1,623 +0,0 @@ -How to port a SPI driver to driver model -======================================== - -Here is a rough step-by-step guide. It is based around converting the -exynos SPI driver to driver model (DM) and the example code is based -around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for -v2015.04. - -It is quite long since it includes actual code examples. - -Before driver model, SPI drivers have their own private structure which -contains 'struct spi_slave'. With driver model, 'struct spi_slave' still -exists, but now it is 'per-child data' for the SPI bus. Each child of the -SPI bus is a SPI slave. The information that was stored in the -driver-specific slave structure can now be port in private data for the -SPI bus. - -For example, struct tegra_spi_slave looks like this: - -struct tegra_spi_slave { - struct spi_slave slave; - struct tegra_spi_ctrl *ctrl; -}; - -In this case 'slave' will be in per-child data, and 'ctrl' will be in the -SPI's buses private data. - - -0. How long does this take? - -You should be able to complete this within 2 hours, including testing but -excluding preparing the patches. The API is basically the same as before -with only minor changes: - -- methods to set speed and mode are separated out -- cs_info is used to get information on a chip select - - -1. Enable driver mode for SPI and SPI flash - -Add these to your board config: - -CONFIG_DM_SPI -CONFIG_DM_SPI_FLASH - - -2. Add the skeleton - -Put this code at the bottom of your existing driver file: - -struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, - unsigned int max_hz, unsigned int mode) -{ - return NULL; -} - -struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, - int spi_node) -{ - return NULL; -} - -static int exynos_spi_ofdata_to_platdata(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_probe(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_remove(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_claim_bus(struct udevice *dev) -{ - - return -ENODEV; -} - -static int exynos_spi_release_bus(struct udevice *dev) -{ - - return -ENODEV; -} - -static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, - const void *dout, void *din, unsigned long flags) -{ - - return -ENODEV; -} - -static int exynos_spi_set_speed(struct udevice *dev, uint speed) -{ - return -ENODEV; -} - -static int exynos_spi_set_mode(struct udevice *dev, uint mode) -{ - return -ENODEV; -} - -static int exynos_cs_info(struct udevice *bus, uint cs, - struct spi_cs_info *info) -{ - return -ENODEV; -} - -static const struct dm_spi_ops exynos_spi_ops = { - .claim_bus = exynos_spi_claim_bus, - .release_bus = exynos_spi_release_bus, - .xfer = exynos_spi_xfer, - .set_speed = exynos_spi_set_speed, - .set_mode = exynos_spi_set_mode, - .cs_info = exynos_cs_info, -}; - -static const struct udevice_id exynos_spi_ids[] = { - { .compatible = "samsung,exynos-spi" }, - { } -}; - -U_BOOT_DRIVER(exynos_spi) = { - .name = "exynos_spi", - .id = UCLASS_SPI, - .of_match = exynos_spi_ids, - .ops = &exynos_spi_ops, - .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, - .probe = exynos_spi_probe, - .remove = exynos_spi_remove, -}; - - -3. Replace 'exynos' in the above code with your driver name - - -4. #ifdef out all of the code in your driver except for the above - -This will allow you to get it building, which means you can work -incrementally. Since all the methods return an error initially, there is -less chance that you will accidentally leave something in. - -Also, even though your conversion is basically a rewrite, it might help -reviewers if you leave functions in the same place in the file, -particularly for large drivers. - - -5. Add some includes - -Add these includes to your driver: - -#include -#include - - -6. Build - -At this point you should be able to build U-Boot for your board with the -empty SPI driver. You still have empty methods in your driver, but we will -write these one by one. - -7. Set up your platform data structure - -This will hold the information your driver to operate, like its hardware -address or maximum frequency. - -You may already have a struct like this, or you may need to create one -from some of the #defines or global variables in the driver. - -Note that this information is not the run-time information. It should not -include state that changes. It should be fixed throughout the live of -U-Boot. Run-time information comes later. - -Here is what was in the exynos spi driver: - -struct spi_bus { - enum periph_id periph_id; - s32 frequency; /* Default clock frequency, -1 for none */ - struct exynos_spi *regs; - int inited; /* 1 if this bus is ready for use */ - int node; - uint deactivate_delay_us; /* Delay to wait after deactivate */ -}; - -Of these, inited is handled by DM and node is the device tree node, which -DM tells you. The name is not quite right. So in this case we would use: - -struct exynos_spi_platdata { - enum periph_id periph_id; - s32 frequency; /* Default clock frequency, -1 for none */ - struct exynos_spi *regs; - uint deactivate_delay_us; /* Delay to wait after deactivate */ -}; - - -8a. Write ofdata_to_platdata() [for device tree only] - -This method will convert information in the device tree node into a C -structure in your driver (called platform data). If you are not using -device tree, go to 8b. - -DM will automatically allocate the struct for us when we are using device -tree, but we need to tell it the size: - -U_BOOT_DRIVER(spi_exynos) = { -... - .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), - - -Here is a sample function. It gets a pointer to the platform data and -fills in the fields from device tree. - -static int exynos_spi_ofdata_to_platdata(struct udevice *bus) -{ - struct exynos_spi_platdata *plat = bus->platdata; - const void *blob = gd->fdt_blob; - int node = dev_of_offset(bus); - - plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); - plat->periph_id = pinmux_decode_periph_id(blob, node); - - if (plat->periph_id == PERIPH_ID_NONE) { - debug("%s: Invalid peripheral ID %d\n", __func__, - plat->periph_id); - return -FDT_ERR_NOTFOUND; - } - - /* Use 500KHz as a suitable default */ - plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", - 500000); - plat->deactivate_delay_us = fdtdec_get_int(blob, node, - "spi-deactivate-delay", 0); - debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", - __func__, plat->regs, plat->periph_id, plat->frequency, - plat->deactivate_delay_us); - - return 0; -} - - -8b. Add the platform data [non-device-tree only] - -Specify this data in a U_BOOT_DEVICE() declaration in your board file: - -struct exynos_spi_platdata platdata_spi0 = { - .periph_id = ... - .frequency = ... - .regs = ... - .deactivate_delay_us = ... -}; - -U_BOOT_DEVICE(board_spi0) = { - .name = "exynos_spi", - .platdata = &platdata_spi0, -}; - -You will unfortunately need to put the struct definition into a header file -in this case so that your board file can use it. - - -9. Add the device private data - -Most devices have some private data which they use to keep track of things -while active. This is the run-time information and needs to be stored in -a structure. There is probably a structure in the driver that includes a -'struct spi_slave', so you can use that. - -struct exynos_spi_slave { - struct spi_slave slave; - struct exynos_spi *regs; - unsigned int freq; /* Default frequency */ - unsigned int mode; - enum periph_id periph_id; /* Peripheral ID for this device */ - unsigned int fifo_size; - int skip_preamble; - struct spi_bus *bus; /* Pointer to our SPI bus info */ - ulong last_transaction_us; /* Time of last transaction end */ -}; - - -We should rename this to make its purpose more obvious, and get rid of -the slave structure, so we have: - -struct exynos_spi_priv { - struct exynos_spi *regs; - unsigned int freq; /* Default frequency */ - unsigned int mode; - enum periph_id periph_id; /* Peripheral ID for this device */ - unsigned int fifo_size; - int skip_preamble; - ulong last_transaction_us; /* Time of last transaction end */ -}; - - -DM can auto-allocate this also: - -U_BOOT_DRIVER(spi_exynos) = { -... - .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), - - -Note that this is created before the probe method is called, and destroyed -after the remove method is called. It will be zeroed when the probe -method is called. - - -10. Add the probe() and remove() methods - -Note: It's a good idea to build repeatedly as you are working, to avoid a -huge amount of work getting things compiling at the end. - -The probe method is supposed to set up the hardware. U-Boot used to use -spi_setup_slave() to do this. So take a look at this function and see -what you can copy out to set things up. - - -static int exynos_spi_probe(struct udevice *bus) -{ - struct exynos_spi_platdata *plat = dev_get_platdata(bus); - struct exynos_spi_priv *priv = dev_get_priv(bus); - - priv->regs = plat->regs; - if (plat->periph_id == PERIPH_ID_SPI1 || - plat->periph_id == PERIPH_ID_SPI2) - priv->fifo_size = 64; - else - priv->fifo_size = 256; - - priv->skip_preamble = 0; - priv->last_transaction_us = timer_get_us(); - priv->freq = plat->frequency; - priv->periph_id = plat->periph_id; - - return 0; -} - -This implementation doesn't actually touch the hardware, which is somewhat -unusual for a driver. In this case we will do that when the device is -claimed by something that wants to use the SPI bus. - -For remove we could shut down the clocks, but in this case there is -nothing to do. DM frees any memory that it allocated, so we can just -remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. - - -11. Implement set_speed() - -This should set up clocks so that the SPI bus is running at the right -speed. With the old API spi_claim_bus() would normally do this and several -of the following functions, so let's look at that function: - -int spi_claim_bus(struct spi_slave *slave) -{ - struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); - struct exynos_spi *regs = spi_slave->regs; - u32 reg = 0; - int ret; - - ret = set_spi_clk(spi_slave->periph_id, - spi_slave->freq); - if (ret < 0) { - debug("%s: Failed to setup spi clock\n", __func__); - return ret; - } - - exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); - - spi_flush_fifo(slave); - - reg = readl(®s->ch_cfg); - reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); - - if (spi_slave->mode & SPI_CPHA) - reg |= SPI_CH_CPHA_B; - - if (spi_slave->mode & SPI_CPOL) - reg |= SPI_CH_CPOL_L; - - writel(reg, ®s->ch_cfg); - writel(SPI_FB_DELAY_180, ®s->fb_clk); - - return 0; -} - - -It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. -With DM these will happen in separate methods. - - -Here is an example for the speed part: - -static int exynos_spi_set_speed(struct udevice *bus, uint speed) -{ - struct exynos_spi_platdata *plat = bus->platdata; - struct exynos_spi_priv *priv = dev_get_priv(bus); - int ret; - - if (speed > plat->frequency) - speed = plat->frequency; - ret = set_spi_clk(priv->periph_id, speed); - if (ret) - return ret; - priv->freq = speed; - debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); - - return 0; -} - - -12. Implement set_mode() - -This should adjust the SPI mode (polarity, etc.). Again this code probably -comes from the old spi_claim_bus(). Here is an example: - - -static int exynos_spi_set_mode(struct udevice *bus, uint mode) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - uint32_t reg; - - reg = readl(&priv->regs->ch_cfg); - reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); - - if (mode & SPI_CPHA) - reg |= SPI_CH_CPHA_B; - - if (mode & SPI_CPOL) - reg |= SPI_CH_CPOL_L; - - writel(reg, &priv->regs->ch_cfg); - priv->mode = mode; - debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); - - return 0; -} - - -13. Implement claim_bus() - -This is where a client wants to make use of the bus, so claims it first. -At this point we need to make sure everything is set up ready for data -transfer. Note that this function is wholly internal to the driver - at -present the SPI uclass never calls it. - -Here again we look at the old claim function and see some code that is -needed. It is anything unrelated to speed and mode: - -static int exynos_spi_claim_bus(struct udevice *bus) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - - exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); - spi_flush_fifo(priv->regs); - - writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); - - return 0; -} - -The spi_flush_fifo() function is in the removed part of the code, so we -need to expose it again (perhaps with an #endif before it and '#if 0' -after it). It only needs access to priv->regs which is why we have -passed that in: - -/** - * Flush spi tx, rx fifos and reset the SPI controller - * - * @param regs Pointer to SPI registers - */ -static void spi_flush_fifo(struct exynos_spi *regs) -{ - clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); - clrbits_le32(®s->ch_cfg, SPI_CH_RST); - setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); -} - - -14. Implement release_bus() - -This releases the bus - in our example the old code in spi_release_bus() -is a call to spi_flush_fifo, so we add: - -static int exynos_spi_release_bus(struct udevice *bus) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - - spi_flush_fifo(priv->regs); - - return 0; -} - - -15. Implement xfer() - -This is the final method that we need to create, and it is where all the -work happens. The method parameters are the same as the old spi_xfer() with -the addition of a 'struct udevice' so conversion is pretty easy. Start -by copying the contents of spi_xfer() to your new xfer() method and proceed -from there. - -If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an -activate function, something like this: - -void spi_cs_activate(struct spi_slave *slave) -{ - struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); - - /* If it's too soon to do another transaction, wait */ - if (spi_slave->bus->deactivate_delay_us && - spi_slave->last_transaction_us) { - ulong delay_us; /* The delay completed so far */ - delay_us = timer_get_us() - spi_slave->last_transaction_us; - if (delay_us < spi_slave->bus->deactivate_delay_us) - udelay(spi_slave->bus->deactivate_delay_us - delay_us); - } - - clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); - debug("Activate CS, bus %d\n", spi_slave->slave.bus); - spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; -} - -The new version looks like this: - -static void spi_cs_activate(struct udevice *dev) -{ - struct udevice *bus = dev->parent; - struct exynos_spi_platdata *pdata = dev_get_platdata(bus); - struct exynos_spi_priv *priv = dev_get_priv(bus); - - /* If it's too soon to do another transaction, wait */ - if (pdata->deactivate_delay_us && - priv->last_transaction_us) { - ulong delay_us; /* The delay completed so far */ - delay_us = timer_get_us() - priv->last_transaction_us; - if (delay_us < pdata->deactivate_delay_us) - udelay(pdata->deactivate_delay_us - delay_us); - } - - clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); - debug("Activate CS, bus '%s'\n", bus->name); - priv->skip_preamble = priv->mode & SPI_PREAMBLE; -} - -All we have really done here is change the pointers and print the device name -instead of the bus number. Other local static functions can be treated in -the same way. - - -16. Set up the per-child data and child pre-probe function - -To minimise the pain and complexity of the SPI subsystem while the driver -model change-over is in place, struct spi_slave is used to reference a -SPI bus slave, even though that slave is actually a struct udevice. In fact -struct spi_slave is the device's child data. We need to make sure this space -is available. It is possible to allocate more space that struct spi_slave -needs, but this is the minimum. - -U_BOOT_DRIVER(exynos_spi) = { -... - .per_child_auto_alloc_size = sizeof(struct spi_slave), -} - - -17. Optional: Set up cs_info() if you want it - -Sometimes it is useful to know whether a SPI chip select is valid, but this -is not obvious from outside the driver. In this case you can provide a -method for cs_info() to deal with this. If you don't provide it, then the -device tree will be used to determine what chip selects are valid. - -Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. -If you don't provide the cs_info() method, -ENODEV is assumed for all -chip selects that do not appear in the device tree. - - -18. Test it - -Now that you have the code written and it compiles, try testing it using -the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your -board. - - -19. Prepare patches and send them to the mailing lists - -You can use 'tools/patman/patman' to prepare, check and send patches for -your work. See the README for details. - -20. A little note about SPI uclass features: - -The SPI uclass keeps some information about each device 'dev' on the bus: - - struct dm_spi_slave_platdata - this is device_get_parent_platdata(dev) - This is where the chip select number is stored, along with - the default bus speed and mode. It is automatically read - from the device tree in spi_child_post_bind(). It must not - be changed at run-time after being set up because platform - data is supposed to be immutable at run-time. - struct spi_slave - this is device_get_parentdata(dev) - Already mentioned above. It holds run-time information about - the device. - -There are also some SPI uclass methods that get called behind the scenes: - - spi_post_bind() - called when a new bus is bound - This scans the device tree for devices on the bus, and binds - each one. This in turn causes spi_child_post_bind() to be - called for each, which reads the device tree information - into the parent (per-child) platform data. - spi_child_post_bind() - called when a new child is bound - As mentioned above this reads the device tree information - into the per-child platform data - spi_child_pre_probe() - called before a new child is probed - This sets up the mode and speed in struct spi_slave by - copying it from the parent's platform data for this child. - It also sets the 'dev' pointer, needed to permit passing - 'struct spi_slave' around the place without needing a - separate 'struct udevice' pointer. - -The above housekeeping makes it easier to write your SPI driver. -- 2.7.4