--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Binding/unbinding a driver
+==========================
+
+This document aims to describe the bind and unbind commands.
+
+For debugging purpose, it should be useful to bind or unbind a driver from
+the U-boot command line.
+
+The unbind command calls the remove device driver callback and unbind the
+device from its driver.
+
+The bind command binds a device to its driver.
+
+In some cases it can be useful to be able to bind a device to a driver from
+the command line.
+The obvious example is for versatile devices such as USB gadget.
+Another use case is when the devices are not yet ready at startup and
+require some setup before the drivers are bound (ex: FPGA which bitsream is
+fetched from a mass storage or ethernet)
+
+usage:
+
+bind <node path> <driver>
+bind <class> <index> <driver>
+
+unbind <node path>
+unbind <class> <index>
+unbind <class> <index> <driver>
+
+Where:
+ - <node path> is the node's device tree path
+ - <class> is one of the class available in the list given by the "dm uclass"
+ command or first column of "dm tree" command.
+ - <index> is the index of the parent's node (second column of "dm tree" output).
+ - <driver> is the driver name to bind given by the "dm drivers" command or the by
+ the fourth column of "dm tree" output.
+
+example:
+
+bind usb_dev_generic 0 usb_ether
+unbind usb_dev_generic 0 usb_ether
+or
+unbind eth 1
+
+bind /ocp/omap_dwc3@48380000/usb@48390000 usb_ether
+unbind /ocp/omap_dwc3@48380000/usb@48390000
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Debugging driver model
+======================
+
+This document aims to provide help when you cannot work out why driver model is
+not doing what you expect.
+
+
+Useful techniques in general
+----------------------------
+
+Here are some useful debugging features generally.
+
+ - If you are writing a new feature, consider doing it in sandbox instead of
+ on your board. Sandbox has no limits, allows easy debugging (e.g. gdb) and
+ you can write emulators for most common devices.
+ - Put '#define DEBUG' at the top of a file, to activate all the debug() and
+ log_debug() statements in that file.
+ - Where logging is used, change the logging level, e.g. in SPL with
+ CONFIG_SPL_LOG_MAX_LEVEL=7 (which is LOGL_DEBUG) and
+ CONFIG_LOG_DEFAULT_LEVEL=7
+ - Where logging of return values is implemented with log_msg_ret(), set
+ CONFIG_LOG_ERROR_RETURN=y to see exactly where the error is happening
+ - Make sure you have a debug UART enabled - see CONFIG_DEBUG_UART. With this
+ you can get serial output (printf(), etc.) before the serial driver is
+ running.
+ - Use a JTAG emulator to set breakpoints and single-step through code
+
+Not that most of these increase code/data size somewhat when enabled.
+
+
+Failure to locate a device
+--------------------------
+
+Let's say you have uclass_first_device_err() and it is not finding anything.
+
+If it is returning an error, then that gives you a clue. Look up linux/errno.h
+to see errors. Common ones are:
+
+ - -ENOMEM which indicates that memory is short. If it happens in SPL or
+ before relocation in U-Boot, check CONFIG_SPL_SYS_MALLOC_F_LEN and
+ CONFIG_SYS_MALLOC_F_LEN as they may need to be larger. Add '#define DEBUG'
+ at the very top of malloc_simple.c to get an idea of where your memory is
+ going.
+ - -EINVAL which typically indicates that something was missing or wrong in
+ the device tree node. Check that everything is correct and look at the
+ of_to_plat() method in the driver.
+
+If there is no error, you should check if the device is actually bound. Call
+dm_dump_all() just before you locate the device to make sure it exists.
+
+If it does not exist, check your device tree compatible strings match up with
+what the driver expects (in the struct udevice_id array).
+
+If you are using of-platdata (e.g. CONFIG_SPL_OF_PLATDATA), check that the
+driver name is the same as the first compatible string in the device tree (with
+invalid-variable characters converted to underscore).
+
+If you are really stuck, putting '#define LOG_DEBUG' at the top of
+drivers/core/lists.c should show you what is going on.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Design Details
+==============
+
+This README contains high-level information about driver model, a unified
+way of declaring and accessing drivers in U-Boot. The original work was done
+by:
+
+
+This has been both simplified and extended into the current implementation
+by:
+
+
+
+Terminology
+-----------
+
+Uclass
+ a group of devices which operate in the same way. A uclass provides
+ a way of accessing individual devices within the group, but always
+ using the same interface. For example a GPIO uclass provides
+ operations for get/set value. An I2C uclass may have 10 I2C ports,
+ 4 with one driver, and 6 with another.
+
+Driver
+ some code which talks to a peripheral and presents a higher-level
+ interface to it.
+
+Device
+ an instance of a driver, tied to a particular port or peripheral.
+
+
+How to try it
+-------------
+
+Build U-Boot sandbox and run it::
+
+ make sandbox_defconfig
+ make
+ ./u-boot -d u-boot.dtb
+
+ (type 'reset' to exit U-Boot)
+
+
+There is a uclass called 'demo'. This uclass handles
+saying hello, and reporting its status. There are two drivers in this
+uclass:
+
+ - simple: Just prints a message for hello, doesn't implement status
+ - shape: Prints shapes and reports number of characters printed as status
+
+The demo class is pretty simple, but not trivial. The intention is that it
+can be used for testing, so it will implement all driver model features and
+provide good code coverage of them. It does have multiple drivers, it
+handles parameter data and plat (data which tells the driver how
+to operate on a particular platform) and it uses private driver data.
+
+To try it, see the example session below::
+
+ =>demo hello 1
+ Hello '@' from 07981110: red 4
+ =>demo status 2
+ Status: 0
+ =>demo hello 2
+ g
+ r@
+ e@@
+ e@@@
+ n@@@@
+ g@@@@@
+ =>demo status 2
+ Status: 21
+ =>demo hello 4 ^
+ y^^^
+ e^^^^^
+ l^^^^^^^
+ l^^^^^^^
+ o^^^^^
+ w^^^
+ =>demo status 4
+ Status: 36
+ =>
+
+
+Running the tests
+-----------------
+
+The intent with driver model is that the core portion has 100% test coverage
+in sandbox, and every uclass has its own test. As a move towards this, tests
+are provided in test/dm. To run them, try::
+
+ ./test/py/test.py --bd sandbox --build -k ut_dm -v
+
+You should see something like this::
+
+ (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v
+ +make O=/root/u-boot/build-sandbox -s sandbox_defconfig
+ +make O=/root/u-boot/build-sandbox -s -j8
+ ============================= test session starts ==============================
+ platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python
+ cachedir: .cache
+ rootdir: /root/u-boot, inifile:
+ collected 199 items
+
+ test/py/tests/test_ut.py::test_ut_dm_init PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED
+ test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED
+
+ ======================= 84 tests deselected by '-kut_dm' =======================
+ ================== 115 passed, 84 deselected in 3.77 seconds ===================
+
+What is going on?
+-----------------
+
+Let's start at the top. The demo command is in cmd/demo.c. It does
+the usual command processing and then:
+
+.. code-block:: c
+
+ struct udevice *demo_dev;
+
+ ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev);
+
+UCLASS_DEMO means the class of devices which implement 'demo'. Other
+classes might be MMC, or GPIO, hashing or serial. The idea is that the
+devices in the class all share a particular way of working. The class
+presents a unified view of all these devices to U-Boot.
+
+This function looks up a device for the demo uclass. Given a device
+number we can find the device because all devices have registered with
+the UCLASS_DEMO uclass.
+
+The device is automatically activated ready for use by uclass_get_device().
+
+Now that we have the device we can do things like:
+
+.. code-block:: c
+
+ return demo_hello(demo_dev, ch);
+
+This function is in the demo uclass. It takes care of calling the 'hello'
+method of the relevant driver. Bearing in mind that there are two drivers,
+this particular device may use one or other of them.
+
+The code for demo_hello() is in drivers/demo/demo-uclass.c:
+
+.. code-block:: c
+
+ int demo_hello(struct udevice *dev, int ch)
+ {
+ const struct demo_ops *ops = device_get_ops(dev);
+
+ if (!ops->hello)
+ return -ENOSYS;
+
+ return ops->hello(dev, ch);
+ }
+
+As you can see it just calls the relevant driver method. One of these is
+in drivers/demo/demo-simple.c:
+
+.. code-block:: c
+
+ static int simple_hello(struct udevice *dev, int ch)
+ {
+ const struct dm_demo_pdata *pdata = dev_get_plat(dev);
+
+ printf("Hello from %08x: %s %d\n", map_to_sysmem(dev),
+ pdata->colour, pdata->sides);
+
+ return 0;
+ }
+
+
+So that is a trip from top (command execution) to bottom (driver action)
+but it leaves a lot of topics to address.
+
+
+Declaring Drivers
+-----------------
+
+A driver declaration looks something like this (see
+drivers/demo/demo-shape.c):
+
+.. code-block:: c
+
+ static const struct demo_ops shape_ops = {
+ .hello = shape_hello,
+ .status = shape_status,
+ };
+
+ U_BOOT_DRIVER(demo_shape_drv) = {
+ .name = "demo_shape_drv",
+ .id = UCLASS_DEMO,
+ .ops = &shape_ops,
+ .priv_data_size = sizeof(struct shape_data),
+ };
+
+
+This driver has two methods (hello and status) and requires a bit of
+private data (accessible through dev_get_priv(dev) once the driver has
+been probed). It is a member of UCLASS_DEMO so will register itself
+there.
+
+In U_BOOT_DRIVER it is also possible to specify special methods for bind
+and unbind, and these are called at appropriate times. For many drivers
+it is hoped that only 'probe' and 'remove' will be needed.
+
+The U_BOOT_DRIVER macro creates a data structure accessible from C,
+so driver model can find the drivers that are available.
+
+The methods a device can provide are documented in the device.h header.
+Briefly, they are:
+
+ * bind - make the driver model aware of a device (bind it to its driver)
+ * unbind - make the driver model forget the device
+ * of_to_plat - convert device tree data to plat - see later
+ * probe - make a device ready for use
+ * remove - remove a device so it cannot be used until probed again
+
+The sequence to get a device to work is bind, of_to_plat (if using
+device tree) and probe.
+
+
+Platform Data
+-------------
+
+Note: platform data is the old way of doing things. It is
+basically a C structure which is passed to drivers to tell them about
+platform-specific settings like the address of its registers, bus
+speed, etc. Device tree is now the preferred way of handling this.
+Unless you have a good reason not to use device tree (the main one
+being you need serial support in SPL and don't have enough SRAM for
+the cut-down device tree and libfdt libraries) you should stay away
+from platform data.
+
+Platform data is like Linux platform data, if you are familiar with that.
+It provides the board-specific information to start up a device.
+
+Why is this information not just stored in the device driver itself? The
+idea is that the device driver is generic, and can in principle operate on
+any board that has that type of device. For example, with modern
+highly-complex SoCs it is common for the IP to come from an IP vendor, and
+therefore (for example) the MMC controller may be the same on chips from
+different vendors. It makes no sense to write independent drivers for the
+MMC controller on each vendor's SoC, when they are all almost the same.
+Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
+but lie at different addresses in the address space.
+
+Using the UART example, we have a single driver and it is instantiated 6
+times by supplying 6 lots of platform data. Each lot of platform data
+gives the driver name and a pointer to a structure containing information
+about this instance - e.g. the address of the register space. It may be that
+one of the UARTS supports RS-485 operation - this can be added as a flag in
+the platform data, which is set for this one port and clear for the rest.
+
+Think of your driver as a generic piece of code which knows how to talk to
+a device, but needs to know where it is, any variant/option information and
+so on. Platform data provides this link between the generic piece of code
+and the specific way it is bound on a particular board.
+
+Examples of platform data include:
+
+ - The base address of the IP block's register space
+ - Configuration options, like:
+ - the SPI polarity and maximum speed for a SPI controller
+ - the I2C speed to use for an I2C device
+ - the number of GPIOs available in a GPIO device
+
+Where does the platform data come from? It is either held in a structure
+which is compiled into U-Boot, or it can be parsed from the Device Tree
+(see 'Device Tree' below).
+
+For an example of how it can be compiled in, see demo-pdata.c which
+sets up a table of driver names and their associated platform data.
+The data can be interpreted by the drivers however they like - it is
+basically a communication scheme between the board-specific code and
+the generic drivers, which are intended to work on any board.
+
+Drivers can access their data via dev->info->plat. Here is
+the declaration for the platform data, which would normally appear
+in the board file.
+
+.. code-block:: c
+
+ static const struct dm_demo_pdata red_square = {
+ .colour = "red",
+ .sides = 4.
+ };
+
+ static const struct driver_info info[] = {
+ {
+ .name = "demo_shape_drv",
+ .plat = &red_square,
+ },
+ };
+
+ demo1 = driver_bind(root, &info[0]);
+
+
+Device Tree
+-----------
+
+While plat is useful, a more flexible way of providing device data is
+by using device tree. In U-Boot you should use this where possible. Avoid
+sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly
+necessary.
+
+With device tree we replace the above code with the following device tree
+fragment:
+
+.. code-block:: c
+
+ red-square {
+ compatible = "demo-shape";
+ colour = "red";
+ sides = <4>;
+ };
+
+This means that instead of having lots of U_BOOT_DRVINFO() declarations in
+the board file, we put these in the device tree. This approach allows a lot
+more generality, since the same board file can support many types of boards
+(e,g. with the same SoC) just by using different device trees. An added
+benefit is that the Linux device tree can be used, thus further simplifying
+the task of board-bring up either for U-Boot or Linux devs (whoever gets to
+the board first!).
+
+The easiest way to make this work it to add a few members to the driver:
+
+.. code-block:: c
+
+ .plat_auto = sizeof(struct dm_test_pdata),
+ .of_to_plat = testfdt_of_to_plat,
+
+The 'auto' feature allowed space for the plat to be allocated
+and zeroed before the driver's of_to_plat() method is called. The
+of_to_plat() method, which the driver write supplies, should parse
+the device tree node for this device and place it in dev->plat. Thus
+when the probe method is called later (to set up the device ready for use)
+the platform data will be present.
+
+Note that both methods are optional. If you provide an of_to_plat
+method then it will be called first (during activation). If you provide a
+probe method it will be called next. See Driver Lifecycle below for more
+details.
+
+If you don't want to have the plat automatically allocated then you
+can leave out plat_auto. In this case you can use malloc
+in your of_to_plat (or probe) method to allocate the required memory,
+and you should free it in the remove method.
+
+The driver model tree is intended to mirror that of the device tree. The
+root driver is at device tree offset 0 (the root node, '/'), and its
+children are the children of the root node.
+
+In order for a device tree to be valid, the content must be correct with
+respect to either device tree specification
+(https://www.devicetree.org/specifications/) or the device tree bindings that
+are found in the doc/device-tree-bindings directory. When not U-Boot specific
+the bindings in this directory tend to come from the Linux Kernel. As such
+certain design decisions may have been made already for us in terms of how
+specific devices are described and bound. In most circumstances we wish to
+retain compatibility without additional changes being made to the device tree
+source files.
+
+Declaring Uclasses
+------------------
+
+The demo uclass is declared like this:
+
+.. code-block:: c
+
+ UCLASS_DRIVER(demo) = {
+ .id = UCLASS_DEMO,
+ };
+
+It is also possible to specify special methods for probe, etc. The uclass
+numbering comes from include/dm/uclass-id.h. To add a new uclass, add to the
+end of the enum there, then declare your uclass as above.
+
+
+Device Sequence Numbers
+-----------------------
+
+U-Boot numbers devices from 0 in many situations, such as in the command
+line for I2C and SPI buses, and the device names for serial ports (serial0,
+serial1, ...). Driver model supports this numbering and permits devices
+to be locating by their 'sequence'. This numbering uniquely identifies a
+device in its uclass, so no two devices within a particular uclass can have
+the same sequence number.
+
+Sequence numbers start from 0 but gaps are permitted. For example, a board
+may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are
+numbered is up to a particular board, and may be set by the SoC in some
+cases. While it might be tempting to automatically renumber the devices
+where there are gaps in the sequence, this can lead to confusion and is
+not the way that U-Boot works.
+
+Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS
+Kconfig option, which can have a different value in U-Boot proper and SPL.
+If this option is not set, aliases are ignored.
+
+Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the
+DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases.
+
+With those options set, devices with an alias (e.g. "serial2") will get that
+sequence number (e.g. 2). Other devices get the next available number after all
+aliases and all existing numbers. This means that if there is just a single
+alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and
+1 being unused.
+
+If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get
+sequence numbers in a simple ordering starting from 0. To find the next number
+to allocate, driver model scans through to find the maximum existing number,
+then uses the next one. It does not attempt to fill in gaps.
+
+.. code-block:: none
+
+ aliases {
+ serial2 = "/serial@22230000";
+ };
+
+This indicates that in the uclass called "serial", the named node
+("/serial@22230000") will be given sequence number 2. Any command or driver
+which requests serial device 2 will obtain this device.
+
+More commonly you can use node references, which expand to the full path:
+
+.. code-block:: none
+
+ aliases {
+ serial2 = &serial_2;
+ };
+ ...
+ serial_2: serial@22230000 {
+ ...
+ };
+
+The alias resolves to the same string in this case, but this version is
+easier to read.
+
+Device sequence numbers are resolved when a device is bound and the number does
+not change for the life of the device.
+
+There are some situations where the uclass must allocate sequence numbers,
+since a strictly increase sequence (with devicetree nodes bound first) is not
+suitable. An example of this is the PCI bus. In this case, you can set the
+uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an
+alias will be assigned a number by driver model. The rest is left to the uclass
+to sort out, e.g. when enumerating the bus.
+
+Note that changing the sequence number for a device (e.g. in a driver) is not
+permitted. If it is felt to be necessary, ask on the mailing list.
+
+Bus Drivers
+-----------
+
+A common use of driver model is to implement a bus, a device which provides
+access to other devices. Example of buses include SPI and I2C. Typically
+the bus provides some sort of transport or translation that makes it
+possible to talk to the devices on the bus.
+
+Driver model provides some useful features to help with implementing buses.
+Firstly, a bus can request that its children store some 'parent data' which
+can be used to keep track of child state. Secondly, the bus can define
+methods which are called when a child is probed or removed. This is similar
+to the methods the uclass driver provides. Thirdly, per-child platform data
+can be provided to specify things like the child's address on the bus. This
+persists across child probe()/remove() cycles.
+
+For consistency and ease of implementation, the bus uclass can specify the
+per-child platform data, so that it can be the same for all children of buses
+in that uclass. There are also uclass methods which can be called when
+children are bound and probed.
+
+Here an explanation of how a bus fits with a uclass may be useful. Consider
+a USB bus with several devices attached to it, each from a different (made
+up) uclass::
+
+ xhci_usb (UCLASS_USB)
+ eth (UCLASS_ETH)
+ camera (UCLASS_CAMERA)
+ flash (UCLASS_FLASH_STORAGE)
+
+Each of the devices is connected to a different address on the USB bus.
+The bus device wants to store this address and some other information such
+as the bus speed for each device.
+
+To achieve this, the bus device can use dev->parent_plat in each of its
+three children. This can be auto-allocated if the bus driver (or bus uclass)
+has a non-zero value for per_child_plat_auto. If not, then
+the bus device or uclass can allocate the space itself before the child
+device is probed.
+
+Also the bus driver can define the child_pre_probe() and child_post_remove()
+methods to allow it to do some processing before the child is activated or
+after it is deactivated.
+
+Similarly the bus uclass can define the child_post_bind() method to obtain
+the per-child platform data from the device tree and set it up for the child.
+The bus uclass can also provide a child_pre_probe() method. Very often it is
+the bus uclass that controls these features, since it avoids each driver
+having to do the same processing. Of course the driver can still tweak and
+override these activities.
+
+Note that the information that controls this behaviour is in the bus's
+driver, not the child's. In fact it is possible that child has no knowledge
+that it is connected to a bus. The same child device may even be used on two
+different bus types. As an example. the 'flash' device shown above may also
+be connected on a SATA bus or standalone with no bus::
+
+ xhci_usb (UCLASS_USB)
+ flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus
+
+ sata (UCLASS_AHCI)
+ flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus
+
+ flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus)
+
+Above you can see that the driver for xhci_usb/sata controls the child's
+bus methods. In the third example the device is not on a bus, and therefore
+will not have these methods at all. Consider the case where the flash
+device defines child methods. These would be used for *its* children, and
+would be quite separate from the methods defined by the driver for the bus
+that the flash device is connetced to. The act of attaching a device to a
+parent device which is a bus, causes the device to start behaving like a
+bus device, regardless of its own views on the matter.
+
+The uclass for the device can also contain data private to that uclass.
+But note that each device on the bus may be a member of a different
+uclass, and this data has nothing to do with the child data for each child
+on the bus. It is the bus' uclass that controls the child with respect to
+the bus.
+
+
+Driver Lifecycle
+----------------
+
+Here are the stages that a device goes through in driver model. Note that all
+methods mentioned here are optional - e.g. if there is no probe() method for
+a device then it will not be called. A simple device may have very few
+methods actually defined.
+
+Bind stage
+^^^^^^^^^^
+
+U-Boot discovers devices using one of these two methods:
+
+- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified
+ by each, to find the appropriate U_BOOT_DRIVER() definition. In this case,
+ there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO()
+ may provide plat.
+
+- Scan through the device tree definitions. U-Boot looks at top-level
+ nodes in the the device tree. It looks at the compatible string in each node
+ and uses the of_match table of the U_BOOT_DRIVER() structure to find the
+ right driver for each node. In this case, the of_match table may provide a
+ driver_data value, but plat cannot be provided until later.
+
+For each device that is discovered, U-Boot then calls device_bind() to create a
+new device, initializes various core fields of the device object such as name,
+uclass & driver, initializes any optional fields of the device object that are
+applicable such as of_offset, driver_data & plat, and finally calls the
+driver's bind() method if one is defined.
+
+At this point all the devices are known, and bound to their drivers. There
+is a 'struct udevice' allocated for all devices. However, nothing has been
+activated (except for the root device). Each bound device that was created
+from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified
+in that declaration. For a bound device created from the device tree,
+plat will be NULL, but of_offset will be the offset of the device tree
+node that caused the device to be created. The uclass is set correctly for
+the device.
+
+The device's sequence number is assigned, either the requested one or the next
+available one (after all aliases are processed) if nothing particular is
+requested.
+
+The device's bind() method is permitted to perform simple actions, but
+should not scan the device tree node, not initialise hardware, nor set up
+structures or allocate memory. All of these tasks should be left for
+the probe() method.
+
+Note that compared to Linux, U-Boot's driver model has a separate step of
+probe/remove which is independent of bind/unbind. This is partly because in
+U-Boot it may be expensive to probe devices and we don't want to do it until
+they are needed, or perhaps until after relocation.
+
+Reading ofdata
+^^^^^^^^^^^^^^
+
+Most devices have data in the device tree which they can read to find out the
+base address of hardware registers and parameters relating to driver
+operation. This is called 'ofdata' (Open-Firmware data).
+
+The device's of_to_plat() implemnents allocation and reading of
+plat. A parent's ofdata is always read before a child.
+
+The steps are:
+
+ 1. If priv_auto is non-zero, then the device-private space
+ is allocated for the device and zeroed. It will be accessible as
+ dev->priv. The driver can put anything it likes in there, but should use
+ it for run-time information, not platform data (which should be static
+ and known before the device is probed).
+
+ 2. If plat_auto is non-zero, then the platform data space
+ is allocated. This is only useful for device tree operation, since
+ otherwise you would have to specify the platform data in the
+ U_BOOT_DRVINFO() declaration. The space is allocated for the device and
+ zeroed. It will be accessible as dev->plat.
+
+ 3. If the device's uclass specifies a non-zero per_device_auto,
+ then this space is allocated and zeroed also. It is allocated for and
+ stored in the device, but it is uclass data. owned by the uclass driver.
+ It is possible for the device to access it.
+
+ 4. If the device's immediate parent specifies a per_child_auto
+ then this space is allocated. This is intended for use by the parent
+ device to keep track of things related to the child. For example a USB
+ flash stick attached to a USB host controller would likely use this
+ space. The controller can hold information about the USB state of each
+ of its children.
+
+ 5. If the driver provides an of_to_plat() method, then this is
+ called to convert the device tree data into platform data. This should
+ do various calls like dev_read_u32(dev, ...) to access the node and store
+ the resulting information into dev->plat. After this point, the device
+ works the same way whether it was bound using a device tree node or
+ U_BOOT_DRVINFO() structure. In either case, the platform data is now stored
+ in the plat structure. Typically you will use the
+ plat_auto feature to specify the size of the platform data
+ structure, and U-Boot will automatically allocate and zero it for you before
+ entry to of_to_plat(). But if not, you can allocate it yourself in
+ of_to_plat(). Note that it is preferable to do all the device tree
+ decoding in of_to_plat() rather than in probe(). (Apart from the
+ ugliness of mixing configuration and run-time data, one day it is possible
+ that U-Boot will cache platform data for devices which are regularly
+ de/activated).
+
+ 6. The device is marked 'plat valid'.
+
+Note that ofdata reading is always done (for a child and all its parents)
+before probing starts. Thus devices go through two distinct states when
+probing: reading platform data and actually touching the hardware to bring
+the device up.
+
+Having probing separate from ofdata-reading helps deal with of-platdata, where
+the probe() method is common to both DT/of-platdata operation, but the
+of_to_plat() method is implemented differently.
+
+Another case has come up where this separate is useful. Generation of ACPI
+tables uses the of-platdata but does not want to probe the device. Probing
+would cause U-Boot to violate one of its design principles, viz that it
+should only probe devices that are used. For ACPI we want to generate a
+table for each device, even if U-Boot does not use it. In fact it may not
+even be possible to probe the device - e.g. an SD card which is not
+present will cause an error on probe, yet we still must tell Linux about
+the SD card connector in case it is used while Linux is running.
+
+It is important that the of_to_plat() method does not actually probe
+the device itself. However there are cases where other devices must be probed
+in the of_to_plat() method. An example is where a device requires a
+GPIO for it to operate. To select a GPIO obviously requires that the GPIO
+device is probed. This is OK when used by common, core devices such as GPIO,
+clock, interrupts, reset and the like.
+
+If your device relies on its parent setting up a suitable address space, so
+that dev_read_addr() works correctly, then make sure that the parent device
+has its setup code in of_to_plat(). If it has it in the probe method,
+then you cannot call dev_read_addr() from the child device's
+of_to_plat() method. Move it to probe() instead. Buses like PCI can
+fall afoul of this rule.
+
+Activation/probe
+^^^^^^^^^^^^^^^^
+
+When a device needs to be used, U-Boot activates it, by first reading ofdata
+as above and then following these steps (see device_probe()):
+
+ 1. All parent devices are probed. It is not possible to activate a device
+ unless its predecessors (all the way up to the root device) are activated.
+ This means (for example) that an I2C driver will require that its bus
+ be activated.
+
+ 2. The device's probe() method is called. This should do anything that
+ is required by the device to get it going. This could include checking
+ that the hardware is actually present, setting up clocks for the
+ hardware and setting up hardware registers to initial values. The code
+ in probe() can access:
+
+ - platform data in dev->plat (for configuration)
+ - private data in dev->priv (for run-time state)
+ - uclass data in dev->uclass_priv (for things the uclass stores
+ about this device)
+
+ Note: If you don't use priv_auto then you will need to
+ allocate the priv space here yourself. The same applies also to
+ plat_auto. Remember to free them in the remove() method.
+
+ 3. The device is marked 'activated'
+
+ 4. The uclass's post_probe() method is called, if one exists. This may
+ cause the uclass to do some housekeeping to record the device as
+ activated and 'known' by the uclass.
+
+Running stage
+^^^^^^^^^^^^^
+
+The device is now activated and can be used. From now until it is removed
+all of the above structures are accessible. The device appears in the
+uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
+as a device in the GPIO uclass). This is the 'running' state of the device.
+
+Removal stage
+^^^^^^^^^^^^^
+
+When the device is no-longer required, you can call device_remove() to
+remove it. This performs the probe steps in reverse:
+
+ 1. The uclass's pre_remove() method is called, if one exists. This may
+ cause the uclass to do some housekeeping to record the device as
+ deactivated and no-longer 'known' by the uclass.
+
+ 2. All the device's children are removed. It is not permitted to have
+ an active child device with a non-active parent. This means that
+ device_remove() is called for all the children recursively at this point.
+
+ 3. The device's remove() method is called. At this stage nothing has been
+ deallocated so platform data, private data and the uclass data will all
+ still be present. This is where the hardware can be shut down. It is
+ intended that the device be completely inactive at this point, For U-Boot
+ to be sure that no hardware is running, it should be enough to remove
+ all devices.
+
+ 4. The device memory is freed (platform data, private data, uclass data,
+ parent data).
+
+ Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a
+ static pointer, it is not de-allocated during the remove() method. For
+ a device instantiated using the device tree data, the platform data will
+ be dynamically allocated, and thus needs to be deallocated during the
+ remove() method, either:
+
+ - if the plat_auto is non-zero, the deallocation happens automatically
+ within the driver model core in the unbind stage; or
+
+ - when plat_auto is 0, both the allocation (in probe()
+ or preferably of_to_plat()) and the deallocation in remove()
+ are the responsibility of the driver author.
+
+ 5. The device is marked inactive. Note that it is still bound, so the
+ device structure itself is not freed at this point. Should the device be
+ activated again, then the cycle starts again at step 2 above.
+
+Unbind stage
+^^^^^^^^^^^^
+
+The device is unbound. This is the step that actually destroys the device.
+If a parent has children these will be destroyed first. After this point
+the device does not exist and its memory has be deallocated.
+
+
+Special cases for removal
+-------------------------
+
+Some devices need to do clean-up before the OS is called. For example, a USB
+driver may want to stop the bus. This can be done in the remove() method.
+Some special flags are used to determine whether to remove the device:
+
+ DM_FLAG_OS_PREPARE - indicates that the device needs to get ready for OS
+ boot. The device will be removed just before the OS is booted
+ DM_REMOVE_ACTIVE_DMA - indicates that the device uses DMA. This is
+ effectively the same as DM_FLAG_OS_PREPARE, so the device is removed
+ before the OS is booted
+ DM_FLAG_VITAL - indicates that the device is 'vital' to the operation of
+ other devices. It is possible to remove this device after all regular
+ devices are removed. This is useful e.g. for a clock, which need to
+ be active during the device-removal phase.
+
+The dm_remove_devices_flags() function can be used to remove devices based on
+their driver flags.
+
+Data Structures
+---------------
+
+Driver model uses a doubly-linked list as the basic data structure. Some
+nodes have several lists running through them. Creating a more efficient
+data structure might be worthwhile in some rare cases, once we understand
+what the bottlenecks are.
+
+
+Changes since v1
+----------------
+
+For the record, this implementation uses a very similar approach to the
+original patches, but makes at least the following changes:
+
+- Tried to aggressively remove boilerplate, so that for most drivers there
+ is little or no 'driver model' code to write.
+- Moved some data from code into data structure - e.g. store a pointer to
+ the driver operations structure in the driver, rather than passing it
+ to the driver bind function.
+- Rename some structures to make them more similar to Linux (struct udevice
+ instead of struct instance, struct plat, etc.)
+- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
+ this concept relates to a class of drivers (or a subsystem). We shouldn't
+ use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
+ better than 'core'.
+- Remove 'struct driver_instance' and just use a single 'struct udevice'.
+ This removes a level of indirection that doesn't seem necessary.
+- Built in device tree support, to avoid the need for plat
+- Removed the concept of driver relocation, and just make it possible for
+ the new driver (created after relocation) to access the old driver data.
+ I feel that relocation is a very special case and will only apply to a few
+ drivers, many of which can/will just re-init anyway. So the overhead of
+ dealing with this might not be worth it.
+- Implemented a GPIO system, trying to keep it simple
+
+
+Pre-Relocation Support
+----------------------
+
+For pre-relocation we simply call the driver model init function. Only
+drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
+property are initialised prior to relocation. This helps to reduce the driver
+model overhead. This flag applies to SPL and TPL as well, if device tree is
+enabled (CONFIG_OF_CONTROL) there.
+
+Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
+property can provide better control granularity on which device is bound
+before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all
+devices with the same driver are bound, which requires allocation a large
+amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the
+only way for statically declared devices via U_BOOT_DRVINFO() to be bound
+prior to relocation.
+
+It is possible to limit this to specific relocation steps, by using
+the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
+in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
+which means that it will be processed (and a driver bound) in U-Boot proper
+prior to relocation, but will not be available in SPL or TPL.
+
+To reduce the size of SPL and TPL, only the nodes with pre-relocation properties
+('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their
+device trees (see README.SPL for details); the remaining nodes are always bound.
+
+Then post relocation we throw that away and re-init driver model again.
+For drivers which require some sort of continuity between pre- and
+post-relocation devices, we can provide access to the pre-relocation
+device pointers, but this is not currently implemented (the root device
+pointer is saved but not made available through the driver model API).
+
+
+SPL Support
+-----------
+
+Driver model can operate in SPL. Its efficient implementation and small code
+size provide for a small overhead which is acceptable for all but the most
+constrained systems.
+
+To enable driver model in SPL, define CONFIG_SPL_DM. You might want to
+consider the following option also. See the main README for more details.
+
+ - CONFIG_SYS_MALLOC_SIMPLE
+ - CONFIG_DM_WARN
+ - CONFIG_DM_DEVICE_REMOVE
+ - CONFIG_DM_STDIO
+
+
+Enabling Driver Model
+---------------------
+
+Driver model is being brought into U-Boot gradually. As each subsystems gets
+support, a uclass is created and a CONFIG to enable use of driver model for
+that subsystem.
+
+For example CONFIG_DM_SERIAL enables driver model for serial. With that
+defined, the old serial support is not enabled, and your serial driver must
+conform to driver model. With that undefined, the old serial support is
+enabled and driver model is not available for serial. This means that when
+you convert a driver, you must either convert all its boards, or provide for
+the driver to be compiled both with and without driver model (generally this
+is not very hard).
+
+See the main README for full details of the available driver model CONFIG
+options.
+
+
+Things to punt for later
+------------------------
+
+Uclasses are statically numbered at compile time. It would be possible to
+change this to dynamic numbering, but then we would require some sort of
+lookup service, perhaps searching by name. This is slightly less efficient
+so has been left out for now. One small advantage of dynamic numbering might
+be fewer merge conflicts in uclass-id.h.
--- /dev/null
+Ethernet Driver Guide
+=======================
+
+The networking stack in Das U-Boot is designed for multiple network devices
+to be easily added and controlled at runtime. This guide is meant for people
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver. Here we will describe a new pseudo 'APE' driver.
+
+Most existing drivers do already - and new network driver MUST - use the
+U-Boot core driver model. Generic information about this can be found in
+doc/driver-model/design.rst, this document will thus focus on the network
+specific code parts.
+Some drivers are still using the old Ethernet interface, differences between
+the two and hints about porting will be handled at the end.
+
+Driver framework
+------------------
+
+A network driver following the driver model must declare itself using
+the UCLASS_ETH .id field in the U-Boot driver struct:
+
+.. code-block:: c
+
+ U_BOOT_DRIVER(eth_ape) = {
+ .name = "eth_ape",
+ .id = UCLASS_ETH,
+ .of_match = eth_ape_ids,
+ .of_to_plat = eth_ape_of_to_plat,
+ .probe = eth_ape_probe,
+ .ops = ð_ape_ops,
+ .priv_auto = sizeof(struct eth_ape_priv),
+ .plat_auto = sizeof(struct eth_ape_pdata),
+ .flags = DM_FLAG_ALLOC_PRIV_DMA,
+ };
+
+struct eth_ape_priv contains runtime per-instance data, like buffers, pointers
+to current descriptors, current speed settings, pointers to PHY related data
+(like struct mii_dev) and so on. Declaring its size in .priv_auto
+will let the driver framework allocate it at the right time.
+It can be retrieved using a dev_get_priv(dev) call.
+
+struct eth_ape_pdata contains static platform data, like the MMIO base address,
+a hardware variant, the MAC address. ``struct eth_pdata eth_pdata``
+as the first member of this struct helps to avoid duplicated code.
+If you don't need any more platform data beside the standard member,
+just use sizeof(struct eth_pdata) for the plat_auto.
+
+PCI devices add a line pointing to supported vendor/device ID pairs:
+
+.. code-block:: c
+
+ static struct pci_device_id supported[] = {
+ { PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) },
+ {}
+ };
+
+ U_BOOT_PCI_DEVICE(eth_ape, supported);
+
+It is also possible to declare support for a whole class of PCI devices::
+
+ { PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) },
+
+Device probing and instantiation will be handled by the driver model framework,
+so follow the guidelines there. The probe() function would initialise the
+platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO
+bus. Also it would take care of any special PHY setup (power rails, enable
+bits for internal PHYs, etc.).
+
+Driver methods
+----------------
+
+The real work will be done in the driver method functions the driver provides
+by defining the members of struct eth_ops:
+
+.. code-block:: c
+
+ struct eth_ops {
+ int (*start)(struct udevice *dev);
+ int (*send)(struct udevice *dev, void *packet, int length);
+ int (*recv)(struct udevice *dev, int flags, uchar **packetp);
+ int (*free_pkt)(struct udevice *dev, uchar *packet, int length);
+ void (*stop)(struct udevice *dev);
+ int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join);
+ int (*write_hwaddr)(struct udevice *dev);
+ int (*read_rom_hwaddr)(struct udevice *dev);
+ };
+
+An up-to-date version of this struct together with more information can be
+found in include/net.h.
+
+Only start, stop, send and recv are required, the rest are optional and are
+handled by generic code or ignored if not provided.
+
+The **start** function initialises the hardware and gets it ready for send/recv
+operations. You often do things here such as resetting the MAC
+and/or PHY, and waiting for the link to autonegotiate. You should also take
+the opportunity to program the device's MAC address with the enetaddr member
+of the generic struct eth_pdata (which would be the first member of your
+own plat struct). This allows the rest of U-Boot to dynamically change
+the MAC address and have the new settings be respected.
+
+The **send** function does what you think -- transmit the specified packet
+whose size is specified by length (in bytes). The packet buffer can (and
+will!) be reused for subsequent calls to send(), so it must be no longer
+used when the send() function returns. The easiest way to achieve this is
+to wait until the transmission is complete. Alternatively, if supported by
+the hardware, just waiting for the buffer to be consumed (by some DMA engine)
+might be an option as well.
+Another way of consuming the buffer could be to copy the data to be send,
+then just queue the copied packet (for instance handing it over to a DMA
+engine), and return immediately afterwards.
+In any case you should leave the state such that the send function can be
+called multiple times in a row.
+
+The **recv** function polls for availability of a new packet. If none is
+available, it must return with -EAGAIN.
+If a packet has been received, make sure it is accessible to the CPU
+(invalidate caches if needed), then write its address to the packetp pointer,
+and return the length. If there is an error (receive error, too short or too
+long packet), return 0 if you require the packet to be cleaned up normally,
+or a negative error code otherwise (cleanup not necessary or already done).
+The U-Boot network stack will then process the packet.
+
+If **free_pkt** is defined, U-Boot will call it after a received packet has
+been processed, so the packet buffer can be freed or recycled. Typically you
+would hand it back to the hardware to acquire another packet. free_pkt() will
+be called after recv(), for the same packet, so you don't necessarily need
+to infer the buffer to free from the ``packet`` pointer, but can rely on that
+being the last packet that recv() handled.
+The common code sets up packet buffers for you already in the .bss
+(net_rx_packets), so there should be no need to allocate your own. This doesn't
+mean you must use the net_rx_packets array however; you're free to use any
+buffer you wish.
+
+The **stop** function should turn off / disable the hardware and place it back
+in its reset state. It can be called at any time (before any call to the
+related start() function), so make sure it can handle this sort of thing.
+
+The (optional) **write_hwaddr** function should program the MAC address stored
+in pdata->enetaddr into the Ethernet controller.
+
+So the call graph at this stage would look something like:
+
+.. code-block:: c
+
+ (some net operation (ping / tftp / whatever...))
+ eth_init()
+ ops->start()
+ eth_send()
+ ops->send()
+ eth_rx()
+ ops->recv()
+ (process packet)
+ if (ops->free_pkt)
+ ops->free_pkt()
+ eth_halt()
+ ops->stop()
+
+
+CONFIG_PHYLIB / CONFIG_CMD_MII
+--------------------------------
+
+If your device supports banging arbitrary values on the MII bus (pretty much
+every device does), you should add support for the mii command. Doing so is
+fairly trivial and makes debugging mii issues a lot easier at runtime.
+
+In your driver's ``probe()`` function, add a call to mdio_alloc() and
+mdio_register() like so:
+
+.. code-block:: c
+
+ bus = mdio_alloc();
+ if (!bus) {
+ ...
+ return -ENOMEM;
+ }
+
+ bus->read = ape_mii_read;
+ bus->write = ape_mii_write;
+ mdio_register(bus);
+
+And then define the mii_read and mii_write functions if you haven't already.
+Their syntax is straightforward::
+
+ int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
+ int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
+ u16 val);
+
+The read function should read the register 'reg' from the phy at address 'addr'
+and return the result to its caller. The implementation for the write function
+should logically follow.
+
+................................................................
+
+Legacy network drivers
+------------------------
+
+!!! WARNING !!!
+
+This section below describes the old way of doing things. No new Ethernet
+drivers should be implemented this way. All new drivers should be written
+against the U-Boot core driver model, as described above.
+
+The actual callback functions are fairly similar, the differences are:
+
+- ``start()`` is called ``init()``
+- ``stop()`` is called ``halt()``
+- The ``recv()`` function must loop until all packets have been received, for
+ each packet it must call the net_process_received_packet() function,
+ handing it over the pointer and the length. Afterwards it should free
+ the packet, before checking for new data.
+
+For porting an old driver to the new driver model, split the existing recv()
+function into the actual new recv() function, just fetching **one** packet,
+remove the call to net_process_received_packet(), then move the packet
+cleanup into the ``free_pkt()`` function.
+
+Registering the driver and probing a device is handled very differently,
+follow the recommendations in the driver model design documentation for
+instructions on how to port this over. For the records, the old way of
+initialising a network driver is as follows:
+
+Old network driver registration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When U-Boot initializes, it will call the common function eth_initialize().
+This will in turn call the board-specific board_eth_init() (or if that fails,
+the cpu-specific cpu_eth_init()). These board-specific functions can do random
+system handling, but ultimately they will call the driver-specific register
+function which in turn takes care of initializing that particular instance.
+
+Keep in mind that you should code the driver to avoid storing state in global
+data as someone might want to hook up two of the same devices to one board.
+Any such information that is specific to an interface should be stored in a
+private, driver-defined data structure and pointed to by eth->priv (see below).
+
+So the call graph at this stage would look something like:
+
+.. code-block:: c
+
+ board_init()
+ eth_initialize()
+ board_eth_init() / cpu_eth_init()
+ driver_register()
+ initialize eth_device
+ eth_register()
+
+At this point in time, the only thing you need to worry about is the driver's
+register function. The pseudo code would look something like:
+
+.. code-block:: c
+
+ int ape_register(struct bd_info *bis, int iobase)
+ {
+ struct ape_priv *priv;
+ struct eth_device *dev;
+ struct mii_dev *bus;
+
+ priv = malloc(sizeof(*priv));
+ if (priv == NULL)
+ return -ENOMEM;
+
+ dev = malloc(sizeof(*dev));
+ if (dev == NULL) {
+ free(priv);
+ return -ENOMEM;
+ }
+
+ /* setup whatever private state you need */
+
+ memset(dev, 0, sizeof(*dev));
+ sprintf(dev->name, "APE");
+
+ /*
+ * if your device has dedicated hardware storage for the
+ * MAC, read it and initialize dev->enetaddr with it
+ */
+ ape_mac_read(dev->enetaddr);
+
+ dev->iobase = iobase;
+ dev->priv = priv;
+ dev->init = ape_init;
+ dev->halt = ape_halt;
+ dev->send = ape_send;
+ dev->recv = ape_recv;
+ dev->write_hwaddr = ape_write_hwaddr;
+
+ eth_register(dev);
+
+ #ifdef CONFIG_PHYLIB
+ bus = mdio_alloc();
+ if (!bus) {
+ free(priv);
+ free(dev);
+ return -ENOMEM;
+ }
+
+ bus->read = ape_mii_read;
+ bus->write = ape_mii_write;
+ mdio_register(bus);
+ #endif
+
+ return 1;
+ }
+
+The exact arguments needed to initialize your device are up to you. If you
+need to pass more/less arguments, that's fine. You should also add the
+prototype for your new register function to include/netdev.h.
+
+The return value for this function should be as follows:
+< 0 - failure (hardware failure, not probe failure)
+>=0 - number of interfaces detected
+
+You might notice that many drivers seem to use xxx_initialize() rather than
+xxx_register(). This is the old naming convention and should be avoided as it
+causes confusion with the driver-specific init function.
+
+Other than locating the MAC address in dedicated hardware storage, you should
+not touch the hardware in anyway. That step is handled in the driver-specific
+init function. Remember that we are only registering the device here, we are
+not checking its state or doing random probing.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Pre-relocation device tree manipulation
+=======================================
+
+Purpose
+-------
+
+In certain markets, it is beneficial for manufacturers of embedded devices to
+offer certain ranges of products, where the functionality of the devices within
+one series either don't differ greatly from another, or can be thought of as
+"extensions" of each other, where one device only differs from another in the
+addition of a small number of features (e.g. an additional output connector).
+
+To realize this in hardware, one method is to have a motherboard, and several
+possible daughter boards that can be attached to this mother board. Different
+daughter boards then either offer the slightly different functionality, or the
+addition of the daughter board to the device realizes the "extension" of
+functionality to the device described previously.
+
+For the software, we obviously want to reuse components for all these
+variations of the device. This means that the software somehow needs to cope
+with the situation that certain ICs may or may not be present on any given
+system, depending on which daughter boards are connected to the motherboard.
+
+In the Linux kernel, one possible solution to this problem is to employ the
+device tree overlay mechanism: There exists one "base" device tree, which
+features only the components guaranteed to exist in all varieties of the
+device. At the start of the kernel, the presence and type of the daughter
+boards is then detected, and the corresponding device tree overlays are applied
+to support the components on the daughter boards.
+
+Note that the components present on every variety of the board must, of course,
+provide a way to find out if and which daughter boards are installed for this
+mechanism to work.
+
+In the U-Boot boot loader, support for device tree overlays has recently been
+integrated, and is used on some boards to alter the device tree that is later
+passed to Linux. But since U-Boot's driver model, which is device tree-based as
+well, is being used in more and more drivers, the same problem of altering the
+device tree starts cropping up in U-Boot itself as well.
+
+An additional problem with the device tree in U-Boot is that it is read-only,
+and the current mechanisms don't allow easy manipulation of the device tree
+after the driver model has been initialized. While migrating to a live device
+tree (at least after the relocation) would greatly simplify the solution of
+this problem, it is a non-negligible task to implement it, an a interim
+solution is needed to address the problem at least in the medium-term.
+
+Hence, we propose a solution to this problem by offering a board-specific
+call-back function, which is passed a writeable pointer to the device tree.
+This function is called before the device tree is relocated, and specifically
+before the main U-Boot's driver model is instantiated, hence the main U-Boot
+"sees" all modifications to the device tree made in this function. Furthermore,
+we have the pre-relocation driver model at our disposal at this stage, which
+means that we can query the hardware for the existence and variety of the
+components easily.
+
+Implementation
+--------------
+
+To take advantage of the pre-relocation device tree manipulation mechanism,
+boards have to implement the function board_fix_fdt, which has the following
+signature:
+
+.. code-block:: c
+
+ int board_fix_fdt (void *rw_fdt_blob)
+
+The passed-in void pointer is a writeable pointer to the device tree, which can
+be used to manipulate the device tree using e.g. functions from
+include/fdt_support.h. The return value should either be 0 in case of
+successful execution of the device tree manipulation or something else for a
+failure. Note that returning a non-null value from the function will
+unrecoverably halt the boot process, as with any function from init_sequence_f
+(in common/board_f.c).
+
+Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function
+to be called::
+
+ Device Tree Control
+ -> [*] Board-specific manipulation of Device Tree
+
++----------------------------------------------------------+
+| WARNING: The actual manipulation of the device tree has |
+| to be the _last_ set of operations in board_fix_fdt! |
+| Since the pre-relocation driver model does not adapt to |
+| changes made to the device tree either, its references |
+| into the device tree will be invalid after manipulating |
+| it, and unpredictable behavior might occur when |
+| functions that rely on them are executed! |
++----------------------------------------------------------+
+
+Hence, the recommended layout of the board_fixup_fdt call-back function is the
+following:
+
+.. code-block:: c
+
+ int board_fix_fdt(void *rw_fdt_blob)
+ {
+ /*
+ * Collect information about device's hardware and store
+ * them in e.g. local variables
+ */
+
+ /* Do device tree manipulation using the values previously collected */
+
+ /* Return 0 on successful manipulation and non-zero otherwise */
+ }
+
+If this convention is kept, both an "additive" approach, meaning that nodes for
+detected components are added to the device tree, as well as a "subtractive"
+approach, meaning that nodes for absent components are removed from the tree,
+as well as a combination of both approaches should work.
+
+Example
+-------
+
+The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a
+board_fix_fdt function, in which six GPIO expanders (which might be present or
+not, since they are on daughter boards) on a I2C bus are queried for, and
+subsequently deactivated in the device tree if they are not present.
+
+Note that the dm_i2c_simple_probe function does not use the device tree, hence
+it is safe to call it after the tree has already been manipulated.
+
+Work to be done
+---------------
+
+* The application of device tree overlay should be possible in board_fixup_fdt,
+ but has not been tested at this stage.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2018-2019 Intel Corporation <www.intel.com>
+
+File System Firmware Loader
+===========================
+
+This is file system firmware loader for U-Boot framework, which has very close
+to some Linux Firmware API. For the details of Linux Firmware API, you can refer
+to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
+
+File system firmware loader can be used to load whatever(firmware, image,
+and binary) from the storage device in file system format into target location
+such as memory, then consumer driver such as FPGA driver can program FPGA image
+from the target location into FPGA.
+
+To enable firmware loader, CONFIG_FS_LOADER need to be set at
+<board_name>_defconfig such as "CONFIG_FS_LOADER=y".
+
+Firmware Loader API core features
+---------------------------------
+
+Firmware storage device described in device tree source
+-------------------------------------------------------
+For passing data like storage device phandle and partition where the
+firmware loading from to the firmware loader driver, those data could be
+defined in fs-loader node as shown in below:
+
+Example for block device::
+
+ fs_loader0: fs-loader {
+ u-boot,dm-pre-reloc;
+ compatible = "u-boot,fs-loader";
+ phandlepart = <&mmc 1>;
+ };
+
+<&mmc 1> means block storage device pointer and its partition.
+
+Above example is a description for block storage, but for UBI storage
+device, it can be described in FDT as shown in below:
+
+Example for ubi::
+
+ fs_loader1: fs-loader {
+ u-boot,dm-pre-reloc;
+ compatible = "u-boot,fs-loader";
+ mtdpart = "UBI",
+ ubivol = "ubi0";
+ };
+
+Then, firmware-loader property can be added with any device node, which
+driver would use the firmware loader for loading.
+
+The value of the firmware-loader property should be set with phandle
+of the fs-loader node. For example::
+
+ firmware-loader = <&fs_loader0>;
+
+If there are majority of devices using the same fs-loader node, then
+firmware-loader property can be added under /chosen node instead of
+adding to each of device node.
+
+For example::
+
+ /{
+ chosen {
+ firmware-loader = <&fs_loader0>;
+ };
+ };
+
+In each respective driver of devices using firmware loader, the firmware
+loaded instance should be created by DT phandle.
+
+For example of getting DT phandle from /chosen and creating instance:
+
+.. code-block:: c
+
+ chosen_node = ofnode_path("/chosen");
+ if (!ofnode_valid(chosen_node)) {
+ debug("/chosen node was not found.\n");
+ return -ENOENT;
+ }
+
+ phandle_p = ofnode_get_property(chosen_node, "firmware-loader", &size);
+ if (!phandle_p) {
+ debug("firmware-loader property was not found.\n");
+ return -ENOENT;
+ }
+
+ phandle = fdt32_to_cpu(*phandle_p);
+ ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
+ phandle, &dev);
+ if (ret)
+ return ret;
+
+Firmware loader driver is also designed to support U-boot environment
+variables, so all these data from FDT can be overwritten
+through the U-boot environment variable during run time.
+
+For examples:
+
+storage_interface:
+ Storage interface, it can be "mmc", "usb", "sata" or "ubi".
+fw_dev_part:
+ Block device number and its partition, it can be "0:1".
+fw_ubi_mtdpart:
+ UBI device mtd partition, it can be "UBI".
+fw_ubi_volume:
+ UBI volume, it can be "ubi0".
+
+When above environment variables are set, environment values would be
+used instead of data from FDT.
+The benefit of this design allows user to change storage attribute data
+at run time through U-boot console and saving the setting as default
+environment values in the storage for the next power cycle, so no
+compilation is required for both driver and FDT.
+
+File system firmware Loader API
+-------------------------------
+
+.. code-block:: c
+
+ int request_firmware_into_buf(struct udevice *dev,
+ const char *name,
+ void *buf, size_t size, u32 offset)
+
+Load firmware into a previously allocated buffer
+
+Parameters:
+
+* struct udevice \*dev: An instance of a driver
+* const char \*name: name of firmware file
+* void \*buf: address of buffer to load firmware into
+* size_t size: size of buffer
+* u32 offset: offset of a file for start reading into buffer
+
+Returns:
+ size of total read
+ -ve when error
+
+Description:
+ The firmware is loaded directly into the buffer pointed to by buf
+
+Example of calling request_firmware_into_buf API after creating firmware loader
+instance:
+
+.. code-block:: c
+
+ ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
+ phandle, &dev);
+ if (ret)
+ return ret;
+
+ request_firmware_into_buf(dev, filename, buffer_location, buffer_size,
+ offset_ofreading);
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+How to port an I2C driver to driver model
+=========================================
+
+Over half of the I2C drivers have been converted as at November 2016. These
+ones remain:
+
+ * adi_i2c
+ * davinci_i2c
+ * fti2c010
+ * ihs_i2c
+ * kona_i2c
+ * lpc32xx_i2c
+ * pca9564_i2c
+ * ppc4xx_i2c
+ * rcar_i2c
+ * sh_i2c
+ * soft_i2c
+ * zynq_i2c
+
+The deadline for this work is the end of June 2017. If no one steps
+forward to convert these, at some point there may come a patch to remove them!
+
+Here is a suggested approach for converting your I2C driver over to driver
+model. Please feel free to update this file with your ideas and suggestions.
+
+- #ifdef out all your own I2C driver code (#if !CONFIG_IS_ENABLED(DM_I2C))
+- Define CONFIG_DM_I2C for your board, vendor or architecture
+- If the board does not already use driver model, you need CONFIG_DM also
+- Your board should then build, but will not work fully since there will be
+ no I2C driver
+- Add the U_BOOT_DRIVER piece at the end (e.g. copy tegra_i2c.c for example)
+- Add a private struct for the driver data - avoid using static variables
+- Implement each of the driver methods, perhaps by calling your old methods
+- You may need to adjust the function parameters so that the old and new
+ implementations can share most of the existing code
+- If you convert all existing users of the driver, remove the pre-driver-model
+ code
+
+In terms of patches a conversion series typically has these patches:
+- clean up / prepare the driver for conversion
+- add driver model code
+- convert at least one existing board to use driver model serial
+- (if no boards remain that don't use driver model) remove the old code
+
+This may be a good time to move your board to use device tree also. Mostly
+this involves these steps:
+
+- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE
+- add your device tree files to arch/<arch>/dts
+- update the Makefile there
+- Add stdout-path to your /chosen device tree node if it is not already there
+- build and get u-boot-dtb.bin so you can test it
+- Your drivers can now use device tree
+- For device tree in SPL, define CONFIG_SPL_OF_CONTROL
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Driver Model
+============
+
+The following holds information on the U-Boot device driver framework:
+driver-model, including the design details of itself and several driver
+subsystems
+
+.. toctree::
+ :maxdepth: 2
+
+ bind
+ debugging
+ design
+ ethernet
+ fdt-fixup
+ fs_firmware_loader
+ i2c-howto
+ livetree
+ migration
+ of-plat
+ pci-info
+ pmic-framework
+ remoteproc-framework
+ serial-howto
+ soc-framework
+ spi-howto
+ usb-info
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Live Device Tree
+================
+
+
+Introduction
+------------
+
+Traditionally U-Boot has used a 'flat' device tree. This means that it
+reads directly from the device tree binary structure. It is called a flat
+device tree because nodes are listed one after the other, with the
+hierarchy detected by tags in the format.
+
+This document describes U-Boot's support for a 'live' device tree, meaning
+that the tree is loaded into a hierarchical data structure within U-Boot.
+
+
+Motivation
+----------
+
+The flat device tree has several advantages:
+
+- it is the format produced by the device tree compiler, so no translation
+ is needed
+
+- it is fairly compact (e.g. there is no need for pointers)
+
+- it is accessed by the libfdt library, which is well tested and stable
+
+
+However the flat device tree does have some limitations. Adding new
+properties can involve copying large amounts of data around to make room.
+The overall tree has a fixed maximum size so sometimes the tree must be
+rebuilt in a new location to create more space. Even if not adding new
+properties or nodes, scanning the tree can be slow. For example, finding
+the parent of a node is a slow process. Reading from nodes involves a
+small amount parsing which takes a little time.
+
+Driver model scans the entire device tree sequentially on start-up which
+avoids the worst of the flat tree's limitations. But if the tree is to be
+modified at run-time, a live tree is much faster. Even if no modification
+is necessary, parsing the tree once and using a live tree from then on
+seems to save a little time.
+
+
+Implementation
+--------------
+
+In U-Boot a live device tree ('livetree') is currently supported only
+after relocation. Therefore we need a mechanism to specify a device
+tree node regardless of whether it is in the flat tree or livetree.
+
+The 'ofnode' type provides this. An ofnode can point to either a flat tree
+node (when the live tree node is not yet set up) or a livetree node. The
+caller of an ofnode function does not need to worry about these details.
+
+The main users of the information in a device tree are drivers. These have
+a 'struct udevice \*' which is attached to a device tree node. Therefore it
+makes sense to be able to read device tree properties using the
+'struct udevice \*', rather than having to obtain the ofnode first.
+
+The 'dev_read\_...()' interface provides this. It allows properties to be
+easily read from the device tree using only a device pointer. Under the
+hood it uses ofnode so it works with both flat and live device trees.
+
+
+Enabling livetree
+-----------------
+
+CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat
+tree will be used in SPL and before relocation in U-Boot proper. Just
+before relocation a livetree is built, and this is used for U-Boot proper
+after relocation.
+
+Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that
+for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does
+not exist, since SPL does not support livetree.
+
+
+Porting drivers
+---------------
+
+Many existing drivers use the fdtdec interface to read device tree
+properties. This only works with a flat device tree. The drivers should be
+converted to use the dev_read_() interface.
+
+For example, the old code may be like this:
+
+.. code-block:: c
+
+ struct udevice *bus;
+ const void *blob = gd->fdt_blob;
+ int node = dev_of_offset(bus);
+
+ i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);
+ plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
+
+The new code is:
+
+.. code-block:: c
+
+ struct udevice *bus;
+
+ i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
+ plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
+
+The dev_read\_...() interface is more convenient and works with both the
+flat and live device trees. See include/dm/read.h for a list of functions.
+
+Where properties must be read from sub-nodes or other nodes, you must fall
+back to using ofnode. For example, for old code like this:
+
+.. code-block:: c
+
+ const void *blob = gd->fdt_blob;
+ int subnode;
+
+ fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) {
+ freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
+ ...
+ }
+
+you should use:
+
+.. code-block:: c
+
+ ofnode subnode;
+
+ ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
+ freq = ofnode_read_u32(node, "spi-max-frequency", 500000);
+ ...
+ }
+
+
+Useful ofnode functions
+-----------------------
+
+The internal data structures of the livetree are defined in include/dm/of.h :
+
+ :struct device_node: holds information about a device tree node
+ :struct property: holds information about a property within a node
+
+Nodes have pointers to their first property, their parent, their first child
+and their sibling. This allows nodes to be linked together in a hierarchical
+tree.
+
+Properties have pointers to the next property. This allows all properties of
+a node to be linked together in a chain.
+
+It should not be necessary to use these data structures in normal code. In
+particular, you should refrain from using functions which access the livetree
+directly, such as of_read_u32(). Use ofnode functions instead, to allow your
+code to work with a flat tree also.
+
+Some conversion functions are used internally. Generally these are not needed
+for driver code. Note that they will not work if called in the wrong context.
+For example it is invalid to call ofnode_to_no() when a flat tree is being
+used. Similarly it is not possible to call ofnode_to_offset() on a livetree
+node.
+
+ofnode_to_np():
+ converts ofnode to struct device_node *
+ofnode_to_offset():
+ converts ofnode to offset
+
+no_to_ofnode():
+ converts node pointer to ofnode
+offset_to_ofnode():
+ converts offset to ofnode
+
+
+Other useful functions:
+
+of_live_active():
+ returns true if livetree is in use, false if flat tree
+ofnode_valid():
+ return true if a given node is valid
+ofnode_is_np():
+ returns true if a given node is a livetree node
+ofnode_equal():
+ compares two ofnodes
+ofnode_null():
+ returns a null ofnode (for which ofnode_valid() returns false)
+
+
+Phandles
+--------
+
+There is full phandle support for live tree. All functions make use of
+struct ofnode_phandle_args, which has an ofnode within it. This supports both
+livetree and flat tree transparently. See for example
+ofnode_parse_phandle_with_args().
+
+
+Reading addresses
+-----------------
+
+You should use dev_read_addr() and friends to read addresses from device-tree
+nodes.
+
+
+fdtdec
+------
+
+The existing fdtdec interface will eventually be retired. Please try to avoid
+using it in new code.
+
+
+Modifying the livetree
+----------------------
+
+This is not currently supported. Once implemented it should provide a much
+more efficient implementation for modification of the device tree than using
+the flat tree.
+
+
+Internal implementation
+-----------------------
+
+The dev_read\_...() functions have two implementations. When
+CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
+functions directly. This is useful when livetree is not enabled. The ofnode
+functions call ofnode_is_np(node) which will always return false if livetree
+is disabled, just falling back to flat tree code.
+
+This optimisation means that without livetree enabled, the dev_read\_...() and
+ofnode interfaces do not noticeably add to code size.
+
+The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
+disabled.
+
+Most livetree code comes directly from Linux and is modified as little as
+possible. This is deliberate since this code is fairly stable and does what
+we want. Some features (such as get/put) are not supported. Internal macros
+take care of removing these features silently.
+
+Within the of_access.c file there are pointers to the alias node, the chosen
+node and the stdout-path alias.
+
+
+Errors
+------
+
+With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
+For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
+the ofnode and dev_read\_...() functions return either one or other type of
+error. This is clearly not desirable. Once tests are added for all the
+functions this can be tidied up.
+
+
+Adding new access functions
+---------------------------
+
+Adding a new function for device-tree access involves the following steps:
+
+ - Add two dev_read() functions:
+ - inline version in the read.h header file, which calls an ofnode function
+ - standard version in the read.c file (or perhaps another file), which
+ also calls an ofnode function
+
+ The implementations of these functions can be the same. The purpose
+ of the inline version is purely to reduce code size impact.
+
+ - Add an ofnode function. This should call ofnode_is_np() to work out
+ whether a livetree or flat tree is used. For the livetree it should
+ call an of\_...() function. For the flat tree it should call an
+ fdt\_...() function. The livetree version will be optimised out at
+ compile time if livetree is not enabled.
+
+ - Add an of\_...() function for the livetree implementation. If a similar
+ function is available in Linux, the implementation should be taken
+ from there and modified as little as possible (generally not at all).
+
+
+Future work
+-----------
+
+Live tree support was introduced in U-Boot 2017.07. There is still quite a bit
+of work to do to flesh this out:
+
+- tests for all access functions
+- support for livetree modification
+- addition of more access functions as needed
+- support for livetree in SPL and before relocation (if desired)
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Migration Schedule
+==================
+
+U-Boot has been migrating to a new driver model since its introduction in
+2014. This file describes the schedule for deprecation of pre-driver-model
+features.
+
+CONFIG_DM
+---------
+
+* Status: In progress
+* Deadline: 2020.01
+
+Starting with the 2010.01 release CONFIG_DM will be enabled for all boards.
+This does not concern CONFIG_DM_SPL and CONFIG_DM_TPL. The conversion date for
+these configuration items still needs to be defined.
+
+CONFIG_DM_MMC
+-------------
+
+* Status: In progress
+* Deadline: 2019.04
+
+The subsystem itself has been converted and maintainers should submit patches
+switching over to using CONFIG_DM_MMC and other base driver model options in
+time for inclusion in the 2019.04 rerelease.
+
+CONFIG_DM_USB
+-------------
+
+* Status: In progress
+* Deadline: 2019.07
+
+The subsystem itself has been converted along with many of the host controller
+and maintainers should submit patches switching over to using CONFIG_DM_USB and
+other base driver model options in time for inclusion in the 2019.07 rerelease.
+
+CONFIG_SATA
+-----------
+
+* Status: In progress
+* Deadline: 2019.07
+
+The subsystem itself has been converted along with many of the host controller
+and maintainers should submit patches switching over to using CONFIG_AHCI and
+other base driver model options in time for inclusion in the 2019.07 rerelease.
+
+CONFIG_BLK
+----------
+
+* Status: In progress
+* Deadline: 2019.07
+
+In concert with maintainers migrating their block device usage to the
+appropriate DM driver, CONFIG_BLK needs to be set as well. The final deadline
+here coincides with the final deadline for migration of the various block
+subsystems. At this point we will be able to audit and correct the logic in
+Kconfig around using CONFIG_PARTITIONS and CONFIG_HAVE_BLOCK_DEVICE and make
+use of CONFIG_BLK / CONFIG_SPL_BLK as needed.
+
+CONFIG_DM_SPI / CONFIG_DM_SPI_FLASH
+-----------------------------------
+
+Board Maintainers should submit the patches for enabling DM_SPI and DM_SPI_FLASH
+to move the migration with in the deadline.
+
+Partially converted::
+
+ drivers/spi/fsl_espi.c
+ drivers/spi/mxc_spi.c
+ drivers/spi/sh_qspi.c
+
+* Status: In progress
+* Deadline: 2019.07
+
+CONFIG_DM_PCI
+-------------
+Deadline: 2019.07
+
+The PCI subsystem has supported driver model since mid 2015. Maintainers should
+submit patches switching over to using CONFIG_DM_PCI and other base driver
+model options in time for inclusion in the 2019.07 release.
+
+
+CONFIG_DM_VIDEO
+---------------
+Deadline: 2019.07
+
+The video subsystem has supported driver model since early 2016. Maintainers
+should submit patches switching over to using CONFIG_DM_VIDEO and other base
+driver model options in time for inclusion in the 2019.07 release.
+
+CONFIG_DM_ETH
+-------------
+Deadline: 2020.07
+
+The network subsystem has supported the driver model since early 2015.
+Maintainers should submit patches switching over to using CONFIG_DM_ETH and
+other base driver model options in time for inclusion in the 2020.07 release.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Compiled-in Device Tree / Platform Data
+=======================================
+
+
+Introduction
+------------
+
+Device tree is the standard configuration method in U-Boot. It is used to
+define what devices are in the system and provide configuration information
+to these devices.
+
+The overhead of adding devicetree access to U-Boot is fairly modest,
+approximately 3KB on Thumb 2 (plus the size of the DT itself). This means
+that in most cases it is best to use devicetree for configuration.
+
+However there are some very constrained environments where U-Boot needs to
+work. These include SPL with severe memory limitations. For example, some
+SoCs require a 16KB SPL image which must include a full MMC stack. In this
+case the overhead of devicetree access may be too great.
+
+It is possible to create platform data manually by defining C structures
+for it, and reference that data in a `U_BOOT_DRVINFO()` declaration. This
+bypasses the use of devicetree completely, effectively creating a parallel
+configuration mechanism. But it is an available option for SPL.
+
+As an alternative, the 'of-platdata' feature is provided. This converts the
+devicetree contents into C code which can be compiled into the SPL binary.
+This saves the 3KB of code overhead and perhaps a few hundred more bytes due
+to more efficient storage of the data.
+
+
+How it works
+------------
+
+The feature is enabled by CONFIG OF_PLATDATA. This is only available in
+SPL/TPL and should be tested with:
+
+.. code-block:: c
+
+ #if CONFIG_IS_ENABLED(OF_PLATDATA)
+
+A tool called 'dtoc' converts a devicetree file either into a set of
+struct declarations, one for each compatible node, and a set of
+`U_BOOT_DRVINFO()` declarations along with the actual platform data for each
+device. As an example, consider this MMC node:
+
+.. code-block:: none
+
+ sdmmc: dwmmc@ff0c0000 {
+ compatible = "rockchip,rk3288-dw-mshc";
+ clock-freq-min-max = <400000 150000000>;
+ clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
+ <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
+ clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
+ fifo-depth = <0x100>;
+ interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
+ reg = <0xff0c0000 0x4000>;
+ bus-width = <4>;
+ cap-mmc-highspeed;
+ cap-sd-highspeed;
+ card-detect-delay = <200>;
+ disable-wp;
+ num-slots = <1>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
+ vmmc-supply = <&vcc_sd>;
+ status = "okay";
+ u-boot,dm-pre-reloc;
+ };
+
+
+Some of these properties are dropped by U-Boot under control of the
+CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
+the following C struct declaration:
+
+.. code-block:: c
+
+ struct dtd_rockchip_rk3288_dw_mshc {
+ fdt32_t bus_width;
+ bool cap_mmc_highspeed;
+ bool cap_sd_highspeed;
+ fdt32_t card_detect_delay;
+ fdt32_t clock_freq_min_max[2];
+ struct phandle_1_arg clocks[4];
+ bool disable_wp;
+ fdt32_t fifo_depth;
+ fdt32_t interrupts[3];
+ fdt32_t num_slots;
+ fdt32_t reg[2];
+ fdt32_t vmmc_supply;
+ };
+
+and the following device declarations:
+
+.. code-block:: c
+
+ /* Node /clock-controller@ff760000 index 0 */
+ ...
+
+ /* Node /dwmmc@ff0c0000 index 2 */
+ static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
+ .fifo_depth = 0x100,
+ .cap_sd_highspeed = true,
+ .interrupts = {0x0, 0x20, 0x4},
+ .clock_freq_min_max = {0x61a80, 0x8f0d180},
+ .vmmc_supply = 0xb,
+ .num_slots = 0x1,
+ .clocks = {{0, 456},
+ {0, 68},
+ {0, 114},
+ {0, 118}},
+ .cap_mmc_highspeed = true,
+ .disable_wp = true,
+ .bus_width = 0x4,
+ .u_boot_dm_pre_reloc = true,
+ .reg = {0xff0c0000, 0x4000},
+ .card_detect_delay = 0xc8,
+ };
+
+ U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = {
+ .name = "rockchip_rk3288_dw_mshc",
+ .plat = &dtv_dwmmc_at_ff0c0000,
+ .plat_size = sizeof(dtv_dwmmc_at_ff0c0000),
+ .parent_idx = -1,
+ };
+
+The device is then instantiated at run-time and the platform data can be
+accessed using:
+
+.. code-block:: c
+
+ struct udevice *dev;
+ struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev);
+
+This avoids the code overhead of converting the devicetree data to
+platform data in the driver. The `of_to_plat()` method should
+therefore do nothing in such a driver.
+
+Note that for the platform data to be matched with a driver, the 'name'
+property of the `U_BOOT_DRVINFO()` declaration has to match a driver declared
+via `U_BOOT_DRIVER()`. This effectively means that a `U_BOOT_DRIVER()` with a
+'name' corresponding to the devicetree 'compatible' string (after converting
+it to a valid name for C) is needed, so a dedicated driver is required for
+each 'compatible' string.
+
+In order to make this a bit more flexible, the `DM_DRIVER_ALIAS()` macro can be
+used to declare an alias for a driver name, typically a 'compatible' string.
+This macro produces no code, but is used by dtoc tool. It must be located in the
+same file as its associated driver, ideally just after it.
+
+The parent_idx is the index of the parent `driver_info` structure within its
+linker list (instantiated by the `U_BOOT_DRVINFO()` macro). This is used to
+support `dev_get_parent()`.
+
+During the build process dtoc parses both `U_BOOT_DRIVER()` and
+`DM_DRIVER_ALIAS()` to build a list of valid driver names and driver aliases.
+If the 'compatible' string used for a device does not not match a valid driver
+name, it will be checked against the list of driver aliases in order to get the
+right driver name to use. If in this step there is no match found a warning is
+issued to avoid run-time failures.
+
+Where a node has multiple compatible strings, dtoc generates a `#define` to
+make them equivalent, e.g.:
+
+.. code-block:: c
+
+ #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
+
+
+Converting of-platdata to a useful form
+---------------------------------------
+
+Of course it would be possible to use the of-platdata directly in your driver
+whenever configuration information is required. However this means that the
+driver will not be able to support devicetree, since the of-platdata
+structure is not available when devicetree is used. It would make no sense
+to use this structure if devicetree were available, since the structure has
+all the limitations metioned in caveats below.
+
+Therefore it is recommended that the of-platdata structure should be used
+only in the `probe()` method of your driver. It cannot be used in the
+`of_to_plat()` method since this is not called when platform data is
+already present.
+
+
+How to structure your driver
+----------------------------
+
+Drivers should always support devicetree as an option. The of-platdata
+feature is intended as a add-on to existing drivers.
+
+Your driver should convert the plat struct in its `probe()` method. The
+existing devicetree decoding logic should be kept in the
+`of_to_plat()` method and wrapped with `#if`.
+
+For example:
+
+.. code-block:: c
+
+ #include <dt-structs.h>
+
+ struct mmc_plat {
+ #if CONFIG_IS_ENABLED(OF_PLATDATA)
+ /* Put this first since driver model will copy the data here */
+ struct dtd_mmc dtplat;
+ #endif
+ /*
+ * Other fields can go here, to be filled in by decoding from
+ * the devicetree (or the C structures when of-platdata is used).
+ */
+ int fifo_depth;
+ };
+
+ static int mmc_of_to_plat(struct udevice *dev)
+ {
+ #if !CONFIG_IS_ENABLED(OF_PLATDATA)
+ /* Decode the devicetree data */
+ struct mmc_plat *plat = dev_get_plat(dev);
+ const void *blob = gd->fdt_blob;
+ int node = dev_of_offset(dev);
+
+ plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
+ #endif
+
+ return 0;
+ }
+
+ static int mmc_probe(struct udevice *dev)
+ {
+ struct mmc_plat *plat = dev_get_plat(dev);
+
+ #if CONFIG_IS_ENABLED(OF_PLATDATA)
+ /* Decode the of-platdata from the C structures */
+ struct dtd_mmc *dtplat = &plat->dtplat;
+
+ plat->fifo_depth = dtplat->fifo_depth;
+ #endif
+ /* Set up the device from the plat data */
+ writel(plat->fifo_depth, ...)
+ }
+
+ static const struct udevice_id mmc_ids[] = {
+ { .compatible = "vendor,mmc" },
+ { }
+ };
+
+ U_BOOT_DRIVER(mmc_drv) = {
+ .name = "mmc_drv",
+ .id = UCLASS_MMC,
+ .of_match = mmc_ids,
+ .of_to_plat = mmc_of_to_plat,
+ .probe = mmc_probe,
+ .priv_auto = sizeof(struct mmc_priv),
+ .plat_auto = sizeof(struct mmc_plat),
+ };
+
+ DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */
+
+Note that `struct mmc_plat` is defined in the C file, not in a header. This
+is to avoid needing to include dt-structs.h in a header file. The idea is to
+keep the use of each of-platdata struct to the smallest possible code area.
+There is just one driver C file for each struct, that can convert from the
+of-platdata struct to the standard one used by the driver.
+
+In the case where SPL_OF_PLATDATA is enabled, `plat_auto` is
+still used to allocate space for the platform data. This is different from
+the normal behaviour and is triggered by the use of of-platdata (strictly
+speaking it is a non-zero `plat_size` which triggers this).
+
+The of-platdata struct contents is copied from the C structure data to the
+start of the newly allocated area. In the case where devicetree is used,
+the platform data is allocated, and starts zeroed. In this case the
+`of_to_plat()` method should still set up the platform data (and the
+of-platdata struct will not be present).
+
+SPL must use either of-platdata or devicetree. Drivers cannot use both at
+the same time, but they must support devicetree. Supporting of-platdata is
+optional.
+
+The devicetree becomes inaccessible when CONFIG_SPL_OF_PLATDATA is enabled,
+since the devicetree access code is not compiled in. A corollary is that
+a board can only move to using of-platdata if all the drivers it uses support
+it. There would be little point in having some drivers require the device
+tree data, since then libfdt would still be needed for those drivers and
+there would be no code-size benefit.
+
+
+Build-time instantiation
+------------------------
+
+Even with of-platdata there is a fair amount of code required in driver model.
+It is possible to have U-Boot handle the instantiation of devices at build-time,
+so avoiding the need for the `device_bind()` code and some parts of
+`device_probe()`.
+
+The feature is enabled by CONFIG_OF_PLATDATA_INST.
+
+Here is an example device, as generated by dtoc::
+
+ /*
+ * Node /serial index 6
+ * driver sandbox_serial parent root_driver
+ */
+
+ #include <asm/serial.h>
+ struct sandbox_serial_plat __attribute__ ((section (".priv_data")))
+ _sandbox_serial_plat_serial = {
+ .dtplat = {
+ .sandbox_text_colour = "cyan",
+ },
+ };
+ #include <asm/serial.h>
+ u8 _sandbox_serial_priv_serial[sizeof(struct sandbox_serial_priv)]
+ __attribute__ ((section (".priv_data")));
+ #include <serial.h>
+ u8 _sandbox_serial_uc_priv_serial[sizeof(struct serial_dev_priv)]
+ __attribute__ ((section (".priv_data")));
+
+ DM_DEVICE_INST(serial) = {
+ .driver = DM_DRIVER_REF(sandbox_serial),
+ .name = "sandbox_serial",
+ .plat_ = &_sandbox_serial_plat_serial,
+ .priv_ = _sandbox_serial_priv_serial,
+ .uclass = DM_UCLASS_REF(serial),
+ .uclass_priv_ = _sandbox_serial_uc_priv_serial,
+ .uclass_node = {
+ .prev = &DM_UCLASS_REF(serial)->dev_head,
+ .next = &DM_UCLASS_REF(serial)->dev_head,
+ },
+ .child_head = {
+ .prev = &DM_DEVICE_REF(serial)->child_head,
+ .next = &DM_DEVICE_REF(serial)->child_head,
+ },
+ .sibling_node = {
+ .prev = &DM_DEVICE_REF(i2c_at_0)->sibling_node,
+ .next = &DM_DEVICE_REF(spl_test)->sibling_node,
+ },
+ .seq_ = 0,
+ };
+
+Here is part of the driver, for reference::
+
+ static const struct udevice_id sandbox_serial_ids[] = {
+ { .compatible = "sandbox,serial" },
+ { }
+ };
+
+ U_BOOT_DRIVER(sandbox_serial) = {
+ .name = "sandbox_serial",
+ .id = UCLASS_SERIAL,
+ .of_match = sandbox_serial_ids,
+ .of_to_plat = sandbox_serial_of_to_plat,
+ .plat_auto = sizeof(struct sandbox_serial_plat),
+ .priv_auto = sizeof(struct sandbox_serial_priv),
+ .probe = sandbox_serial_probe,
+ .remove = sandbox_serial_remove,
+ .ops = &sandbox_serial_ops,
+ .flags = DM_FLAG_PRE_RELOC,
+ };
+
+
+The `DM_DEVICE_INST()` macro declares a struct udevice so you can see that the
+members are from that struct. The private data is declared immediately above,
+as `_sandbox_serial_priv_serial`, so there is no need for run-time memory
+allocation. The #include lines are generated as well, since dtoc searches the
+U-Boot source code for the definition of `struct sandbox_serial_priv` and adds
+the relevant header so that the code will compile without errors.
+
+The `plat_` member is set to the dtv data which is declared immediately above
+the device. This is similar to how it would look without of-platdata-inst, but
+node that the `dtplat` member inside is part of the wider
+`_sandbox_serial_plat_serial` struct. This is because the driver declares its
+own platform data, and the part generated by dtoc can only be a portion of it.
+The `dtplat` part is always first in the struct. If the device has no
+`.plat_auto` field, then a simple dtv struct can be used as with this example::
+
+ static struct dtd_sandbox_clk dtv_clk_sbox = {
+ .assigned_clock_rates = 0x141,
+ .assigned_clocks = {0x7, 0x3},
+ };
+
+ #include <asm/clk.h>
+ u8 _sandbox_clk_priv_clk_sbox[sizeof(struct sandbox_clk_priv)]
+ __attribute__ ((section (".priv_data")));
+
+ DM_DEVICE_INST(clk_sbox) = {
+ .driver = DM_DRIVER_REF(sandbox_clk),
+ .name = "sandbox_clk",
+ .plat_ = &dtv_clk_sbox,
+
+Here is part of the driver, for reference::
+
+ static const struct udevice_id sandbox_clk_ids[] = {
+ { .compatible = "sandbox,clk" },
+ { }
+ };
+
+ U_BOOT_DRIVER(sandbox_clk) = {
+ .name = "sandbox_clk",
+ .id = UCLASS_CLK,
+ .of_match = sandbox_clk_ids,
+ .ops = &sandbox_clk_ops,
+ .probe = sandbox_clk_probe,
+ .priv_auto = sizeof(struct sandbox_clk_priv),
+ };
+
+
+You can see that `dtv_clk_sbox` just has the devicetree contents and there is
+no need for the `dtplat` separation, since the driver has no platform data of
+its own, besides that provided by the devicetree (i.e. no `.plat_auto` field).
+
+The doubly linked lists are handled by explicitly declaring the value of each
+node, as you can see with the `.prev` and `.next` values in the example above.
+Since dtoc knows the order of devices it can link them into the appropriate
+lists correctly.
+
+One of the features of driver model is the ability for a uclass to have a
+small amount of private data for each device in that uclass. This is used to
+provide a generic data structure that the uclass can use for all devices, thus
+allowing generic features to be implemented in common code. An example is I2C,
+which stores the bus speed there.
+
+Similarly, parent devices can have data associated with each of their children.
+This is used to provide information common to all children of a particular bus.
+For an I2C bus, this is used to store the I2C address of each child on the bus.
+
+This is all handled automatically by dtoc::
+
+ #include <asm/i2c.h>
+ u8 _sandbox_i2c_priv_i2c_at_0[sizeof(struct sandbox_i2c_priv)]
+ __attribute__ ((section (".priv_data")));
+ #include <i2c.h>
+ u8 _sandbox_i2c_uc_priv_i2c_at_0[sizeof(struct dm_i2c_bus)]
+ __attribute__ ((section (".priv_data")));
+
+ DM_DEVICE_INST(i2c_at_0) = {
+ .driver = DM_DRIVER_REF(sandbox_i2c),
+ .name = "sandbox_i2c",
+ .plat_ = &dtv_i2c_at_0,
+ .priv_ = _sandbox_i2c_priv_i2c_at_0,
+ .uclass = DM_UCLASS_REF(i2c),
+ .uclass_priv_ = _sandbox_i2c_uc_priv_i2c_at_0,
+ ...
+
+Part of driver, for reference::
+
+ static const struct udevice_id sandbox_i2c_ids[] = {
+ { .compatible = "sandbox,i2c" },
+ { }
+ };
+
+ U_BOOT_DRIVER(sandbox_i2c) = {
+ .name = "sandbox_i2c",
+ .id = UCLASS_I2C,
+ .of_match = sandbox_i2c_ids,
+ .ops = &sandbox_i2c_ops,
+ .priv_auto = sizeof(struct sandbox_i2c_priv),
+ };
+
+Part of I2C uclass, for reference::
+
+ UCLASS_DRIVER(i2c) = {
+ .id = UCLASS_I2C,
+ .name = "i2c",
+ .flags = DM_UC_FLAG_SEQ_ALIAS,
+ .post_bind = i2c_post_bind,
+ .pre_probe = i2c_pre_probe,
+ .post_probe = i2c_post_probe,
+ .per_device_auto = sizeof(struct dm_i2c_bus),
+ .per_child_plat_auto = sizeof(struct dm_i2c_chip),
+ .child_post_bind = i2c_child_post_bind,
+ };
+
+Here, `_sandbox_i2c_uc_priv_i2c_at_0` is required by the uclass but is declared
+in the device, as required by driver model. The required header file is included
+so that the code will compile without errors. A similar mechanism is used for
+child devices, but is not shown by this example.
+
+It would not be that useful to avoid binding devices but still need to allocate
+uclasses at runtime. So dtoc generates uclass instances as well::
+
+ struct list_head uclass_head = {
+ .prev = &DM_UCLASS_REF(serial)->sibling_node,
+ .next = &DM_UCLASS_REF(clk)->sibling_node,
+ };
+
+ DM_UCLASS_INST(clk) = {
+ .uc_drv = DM_UCLASS_DRIVER_REF(clk),
+ .sibling_node = {
+ .prev = &uclass_head,
+ .next = &DM_UCLASS_REF(i2c)->sibling_node,
+ },
+ .dev_head = {
+ .prev = &DM_DEVICE_REF(clk_sbox)->uclass_node,
+ .next = &DM_DEVICE_REF(clk_fixed)->uclass_node,
+ },
+ };
+
+At the top is the list head. Driver model uses this on start-up, instead of
+creating its own.
+
+Below that are a set of `DM_UCLASS_INST()` macros, each declaring a
+`struct uclass`. The doubly linked lists work as for devices.
+
+All private data is placed into a `.priv_data` section so that it is contiguous
+in the resulting output binary.
+
+
+Indexes
+-------
+
+U-Boot stores drivers, devices and many other things in linker_list structures.
+These are sorted by name, so dtoc knows the order that they will appear when
+the linker runs. Each driver_info / udevice is referenced by its index in the
+linker_list array, called 'idx' in the code.
+
+When CONFIG_OF_PLATDATA_INST is enabled, idx is the udevice index, otherwise it
+is the driver_info index. In either case, indexes are used to reference devices
+using device_get_by_ofplat_idx(). This allows phandles to work as expected.
+
+
+Phases
+------
+
+U-Boot operates in several phases, typically TPL, SPL and U-Boot proper.
+The latter does not use dtoc.
+
+In some rare cases different drivers are used for two phases. For example,
+in TPL it may not be necessary to use the full PCI subsystem, so a simple
+driver can be used instead.
+
+This works in the build system simply by compiling in one driver or the
+other (e.g. PCI driver + uclass for SPL; simple_bus for TPL). But dtoc has
+no way of knowing which code is compiled in for which phase, since it does
+not inspect Makefiles or dependency graphs.
+
+So to make this work for dtoc, we need to be able to explicitly mark
+drivers with their phase. This is done by adding a macro to the driver::
+
+ /* code in tpl.c only compiled into TPL */
+ U_BOOT_DRIVER(pci_x86) = {
+ .name = "pci_x86",
+ .id = UCLASS_SIMPLE_BUS,
+ .of_match = of_match_ptr(tpl_fake_pci_ids),
+ DM_PHASE(tpl)
+ };
+
+
+ /* code in pci_x86.c compiled into SPL and U-Boot proper */
+ U_BOOT_DRIVER(pci_x86) = {
+ .name = "pci_x86",
+ .id = UCLASS_PCI,
+ .of_match = pci_x86_ids,
+ .ops = &pci_x86_ops,
+ };
+
+
+Notice that the second driver has the same name but no DM_PHASE(), so it will be
+used for SPL and U-Boot.
+
+Note also that this only affects the code generated by dtoc. You still need to
+make sure that only the required driver is build into each phase.
+
+
+Header files
+------------
+
+With OF_PLATDATA_INST, dtoc must include the correct header file in the
+generated code for any structs that are used, so that the code will compile.
+For example, if `struct ns16550_plat` is used, the code must include the
+`ns16550.h` header file.
+
+Typically dtoc can detect the header file needed for a driver by looking
+for the structs that it uses. For example, if a driver as a `.priv_auto`
+that uses `struct ns16550_plat`, then dtoc can search header files for the
+definition of that struct and use the file.
+
+In some cases, enums are used in drivers, typically with the `.data` field
+of `struct udevice_id`. Since dtoc does not support searching for these,
+you must use the `DM_HDR()` macro to tell dtoc which header to use. This works
+as a macro included in the driver definition::
+
+ static const struct udevice_id apl_syscon_ids[] = {
+ { .compatible = "intel,apl-punit", .data = X86_SYSCON_PUNIT },
+ { }
+ };
+
+ U_BOOT_DRIVER(intel_apl_punit) = {
+ .name = "intel_apl_punit",
+ .id = UCLASS_SYSCON,
+ .of_match = apl_syscon_ids,
+ .probe = apl_punit_probe,
+ DM_HEADER(<asm/cpu.h>) /* for X86_SYSCON_PUNIT */
+ };
+
+
+
+Caveats
+-------
+
+There are various complications with this feature which mean it should only
+be used when strictly necessary, i.e. in SPL with limited memory. Notable
+caveats include:
+
+ - Device tree does not describe data types. But the C code must define a
+ type for each property. These are guessed using heuristics which
+ are wrong in several fairly common cases. For example an 8-byte value
+ is considered to be a 2-item integer array, and is byte-swapped. A
+ boolean value that is not present means 'false', but cannot be
+ included in the structures since there is generally no mention of it
+ in the devicetree file.
+
+ - Naming of nodes and properties is automatic. This means that they follow
+ the naming in the devicetree, which may result in C identifiers that
+ look a bit strange.
+
+ - It is not possible to find a value given a property name. Code must use
+ the associated C member variable directly in the code. This makes
+ the code less robust in the face of devicetree changes. To avoid having
+ a second struct with similar members and names you need to explicitly
+ declare it as an alias with `DM_DRIVER_ALIAS()`.
+
+ - The platform data is provided to drivers as a C structure. The driver
+ must use the same structure to access the data. Since a driver
+ normally also supports devicetree it must use `#ifdef` to separate
+ out this code, since the structures are only available in SPL. This could
+ be fixed fairly easily by making the structs available outside SPL, so
+ that `IS_ENABLED()` could be used.
+
+ - With CONFIG_OF_PLATDATA_INST all binding happens at build-time, meaning
+ that (by default) it is not possible to call `device_bind()` from C code.
+ This means that all devices must have an associated devicetree node and
+ compatible string. For example if a GPIO device currently creates child
+ devices in its `bind()` method, it will not work with
+ CONFIG_OF_PLATDATA_INST. Arguably this is bad practice anyway and the
+ devicetree binding should be updated to declare compatible strings for
+ the child devices. It is possible to disable OF_PLATDATA_NO_BIND but this
+ is not recommended since it increases code size.
+
+
+Internals
+---------
+
+Generated files
+```````````````
+
+When enabled, dtoc generates the following five files:
+
+include/generated/dt-decl.h (OF_PLATDATA_INST only)
+ Contains declarations for all drivers, devices and uclasses. This allows
+ any `struct udevice`, `struct driver` or `struct uclass` to be located by its
+ name
+
+include/generated/dt-structs-gen.h
+ Contains the struct definitions for the devicetree nodes that are used. This
+ is the same as without OF_PLATDATA_INST
+
+spl/dts/dt-plat.c (only with !OF_PLATDATA_INST)
+ Contains the `U_BOOT_DRVINFO()` declarations that U-Boot uses to bind devices
+ at start-up. See above for an example
+
+spl/dts/dt-device.c (only with OF_PLATDATA_INST)
+ Contains `DM_DEVICE_INST()` declarations for each device that can be used at
+ run-time. These are declared in the file along with any private/platform data
+ that they use. Every device has an idx, as above. Since each device must be
+ part of a double-linked list, the nodes are declared in the code as well.
+
+spl/dts/dt-uclass.c (only with OF_PLATDATA_INST)
+ Contains `DM_UCLASS_INST()` declarations for each uclass that can be used at
+ run-time. These are declared in the file along with any private data
+ associated with the uclass itself (the `.priv_auto` member). Since each
+ uclass must be part of a double-linked list, the nodes are declared in the
+ code as well.
+
+The dt-structs.h file includes the generated file
+`(include/generated/dt-structs.h`) if CONFIG_SPL_OF_PLATDATA is enabled.
+Otherwise (such as in U-Boot proper) these structs are not available. This
+prevents them being used inadvertently. All usage must be bracketed with
+`#if CONFIG_IS_ENABLED(OF_PLATDATA)`.
+
+The dt-plat.c file contains the device declarations and is is built in
+spl/dt-plat.c.
+
+
+CONFIG options
+``````````````
+
+Several CONFIG options are used to control the behaviour of of-platdata, all
+available for both SPL and TPL:
+
+OF_PLATDATA
+ This is the main option which enables the of-platdata feature
+
+OF_PLATDATA_PARENT
+ This allows `device_get_parent()` to work. Without this, all devices exist as
+ direct children of the root node. This option is highly desirable (if not
+ always absolutely essential) for buses such as I2C.
+
+OF_PLATDATA_INST
+ This controls the instantiation of devices at build time. With it disabled,
+ only `U_BOOT_DRVINFO()` records are created, with U-Boot handling the binding
+ in `device_bind()` on start-up. With it enabled, only `DM_DEVICE_INST()` and
+ `DM_UCLASS_INST()` records are created, and `device_bind()` is not needed at
+ runtime.
+
+OF_PLATDATA_NO_BIND
+ This controls whether `device_bind()` is supported. It is enabled by default
+ with OF_PLATDATA_INST since code-size reduction is really the main point of
+ the feature. It can be disabled if needed but is not likely to be supported
+ in the long term.
+
+OF_PLATDATA_DRIVER_RT
+ This controls whether the `struct driver_rt` records are used by U-Boot.
+ Normally when a device is bound, U-Boot stores the device pointer in one of
+ these records. There is one for every `struct driver_info` in the system,
+ i.e. one for every device that is bound from those records. It provides a
+ way to locate a device in the code and is used by
+ `device_get_by_ofplat_idx()`. This option is always enabled with of-platdata,
+ provided OF_PLATDATA_INST is not. In that case the records are useless since
+ we don't have any `struct driver_info` records.
+
+OF_PLATDATA_RT
+ This controls whether the `struct udevice_rt` records are used by U-Boot.
+ It moves the updatable fields from `struct udevice` (currently only `flags`)
+ into a separate structure, allowing the records to be kept in read-only
+ memory. It is generally enabled if OF_PLATDATA_INST is enabled. This option
+ also controls whether the private data is used in situ, or first copied into
+ an allocated region. Again this is to allow the private data declared by
+ dtoc-generated code to be in read-only memory. Note that access to private
+ data must be done via accessor functions, such as `dev_get_priv()`, so that
+ the relocation is handled.
+
+READ_ONLY
+ This indicates that the data generated by dtoc should not be modified. Only
+ a few fields actually do get changed in U-Boot, such as device flags. This
+ option causes those to move into an allocated space (see OF_PLATDATA_RT).
+ Also, since updating doubly linked lists is generally impossible when some of
+ the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled.
+
+Data structures
+```````````````
+
+A few extra data structures are used with of-platdata:
+
+`struct udevice_rt`
+ Run-time information for devices. When OF_PLATDATA_RT is enabled, this holds
+ the flags for each device, so that `struct udevice` can remain unchanged by
+ U-Boot, and potentially reside in read-only memory. Access to flags is then
+ via functions like `dev_get_flags()` and `dev_or_flags()`. This data
+ structure is allocated on start-up, where the private data is also copied.
+ All flags values start at 0 and any changes are handled by `dev_or_flags()`
+ and `dev_bic_flags()`. It would be more correct for the flags to be set to
+ `DM_FLAG_BOUND`, or perhaps `DM_FLAG_BOUND | DM_FLAG_ALLOC_PDATA`, but since
+ there is no code to bind/unbind devices and no code to allocate/free
+ private data / platform data, it doesn't matter.
+
+`struct driver_rt`
+ Run-time information for `struct driver_info` records. When
+ OF_PLATDATA_DRIVER_RT is enabled, this holds a pointer to the device
+ created by each record. This is needed so that is it possible to locate a
+ device from C code. Specifically, the code can use `DM_DRVINFO_GET(name)` to
+ get a reference to a particular `struct driver_info`, with `name` being the
+ name of the devicetree node. This is very convenient. It is also fast, since
+ no searching or string comparison is needed. This data structure is
+ allocated on start-up, filled out by `device_bind()` and used by
+ `device_get_by_ofplat_idx()`.
+
+Other changes
+`````````````
+
+Some other changes are made with of-platdata:
+
+Accessor functions
+ Accessing private / platform data via functions such as `dev_get_priv()` has
+ always been encouraged. With OF_PLATDATA_RT this is essential, since the
+ `priv_` and `plat_` (etc.) values point to the data generated by dtoc, not
+ the read-write copy that is sometimes made on start-up. Changing the
+ private / platform data pointers has always been discouraged (the API is
+ marked internal) but with OF_PLATDATA_RT this is not currently supported in
+ general, since it assumes that all such pointers point to the relocated data.
+ Note also that the renaming of struct members to have a trailing underscore
+ was partly done to make people aware that they should not be accessed
+ directly.
+
+`gd->uclass_root_s`
+ Normally U-Boot sets up the head of the uclass list here and makes
+ `gd->uclass_root` point to it. With OF_PLATDATA_INST, dtoc generates a
+ declaration of `uclass_head` in `dt-uclass.c` since it needs to link the
+ head node into the list. In that case, `gd->uclass_root_s` is not used and
+ U-Boot just makes `gd->uclass_root` point to `uclass_head`.
+
+`gd->dm_driver_rt`
+ This holds a pointer to a list of `struct driver_rt` records, one for each
+ `struct driver_info`. The list is in alphabetical order by the name used
+ in `U_BOOT_DRVINFO(name)` and indexed by idx, with the first record having
+ an index of 0. It is only used if OF_PLATDATA_INST is not enabled. This is
+ accessed via macros so that it can be used inside IS_ENABLED(), rather than
+ requiring #ifdefs in the C code when it is not present.
+
+`gd->dm_udevice_rt`
+ This holds a pointer to a list of `struct udevice_rt` records, one for each
+ `struct udevice`. The list is in alphabetical order by the name used
+ in `DM_DEVICE_INST(name)` (a C version of the devicetree node) and indexed by
+ idx, with the first record having an index of 0. It is only used if
+ OF_PLATDATA_INST is enabled. This is accessed via macros so that it can be
+ used inside `IS_ENABLED()`, rather than requiring #ifdefs in the C code when
+ it is not present.
+
+`gd->dm_priv_base`
+ When OF_PLATDATA_RT is enabled, the private/platform data for each device is
+ copied into an allocated region by U-Boot on start-up. This points to that
+ region. All calls to accessor functions (e.g. `dev_get_priv()`) then
+ translate from the pointer provided by the caller (assumed to lie between
+ `__priv_data_start` and `__priv_data_end`) to the new allocated region. This
+ member is accessed via macros so that it can be used inside IS_ENABLED(),
+ rather than required #ifdefs in the C code when it is not present.
+
+`struct udevice->flags_`
+ When OF_PLATDATA_RT is enabled, device flags are no-longer part of
+ `struct udevice`, but are instead kept in `struct udevice_rt`, as described
+ above. Flags are accessed via functions, such as `dev_get_flags()` and
+ `dev_or_flags()`.
+
+`struct udevice->node_`
+ When OF_PLATDATA is enabled, there is no devicetree at runtime, so no need
+ for this field. It is removed, just to save space.
+
+`DM_PHASE`
+ This macro is used to indicate which phase of U-Boot a driver is intended
+ for. See above for details.
+
+`DM_HDR`
+ This macro is used to indicate which header file dtoc should use to allow
+ a driver declaration to compile correctly. See above for details.
+
+`device_get_by_ofplat_idx()`
+ There used to be a function called `device_get_by_driver_info()` which
+ looked up a `struct driver_info` pointer and returned the `struct udevice`
+ that was created from it. It was only available for use with of-platdata.
+ This has been removed in favour of `device_get_by_ofplat_idx()` which uses
+ `idx`, the index of the `struct driver_info` or `struct udevice` in the
+ linker_list. Similarly, the `struct phandle_0_arg` (etc.) structs have been
+ updated to use this index instead of a pointer to `struct driver_info`.
+
+`DM_DRVINFO_GET`
+ This has been removed since we now use indexes to obtain a driver from
+ `struct phandle_0_arg` and the like.
+
+Two-pass binding
+ The original of-platdata tried to order `U_BOOT_DRVINFO()` in the generated
+ files so as to have parents declared ahead of children. This was convenient
+ as it avoided any special code in U-Boot. With OF_PLATDATA_INST this does
+ not work as the idx value relies on using alphabetical order for everything,
+ so that dtoc and U-Boot's linker_lists agree on the idx value. Devices are
+ then bound in order of idx, having no regard to parent/child relationships.
+ For this reason, device binding now hapens in multiple passes, with parents
+ being bound before their children. This is important so that children can
+ find their parents in the bind() method if needed.
+
+Root device
+ The root device is generally bound by U-Boot but with OF_PLATDATA_INST it
+ cannot be, since binding needs to be done at build time. So in this case
+ dtoc sets up a root device using `DM_DEVICE_INST()` in `dt-device.c` and
+ U-Boot makes use of that. When OF_PLATDATA_INST is not enabled, U-Boot
+ generally ignores the root node and does not create a `U_BOOT_DRVINFO()`
+ record for it. This means that the idx numbers used by `struct driver_info`
+ (when OF_PLATDATA_INST is disabled) and the idx numbers used by
+ `struct udevice` (when OF_PLATDATA_INST is enabled) differ, since one has a
+ root node and the other does not. This does not actually matter, since only
+ one of them is actually used for any particular build, but it is worth
+ keeping in mind if comparing index values and switching OF_PLATDATA_INST on
+ and off.
+
+`__priv_data_start` and `__priv_data_end`
+ The private/platform data declared by dtoc is all collected together in
+ a linker section and these symbols mark the start and end of it. This allows
+ U-Boot to relocate the area to a new location if needed (with
+ OF_PLATDATA_RT)
+
+`dm_priv_to_rw()`
+ This function converts a private- or platform-data pointer value generated by
+ dtoc into one that can be used by U-Boot. It is a NOP unless OF_PLATDATA_RT
+ is enabled, in which case it translates the address to the relocated
+ region. See above for more information.
+
+The dm_populate_phandle_data() function that was previous needed has now been
+removed, since dtoc can address the drivers directly from dt-plat.c and does
+not need to fix up things at runtime.
+
+The pylibfdt Python module is used to access the devicetree.
+
+
+Credits
+-------
+
+
+
+Future work
+-----------
+- Consider programmatically reading binding files instead of devicetree
+ contents
+- Allow IS_ENABLED() to be used in the C code instead of #if
+
+
+.. Google, Inc
+.. 6/6/16
+.. Updated Independence Day 2016
+.. Updated 1st October 2020
+.. Updated 5th February 2021
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+PCI with Driver Model
+=====================
+
+How busses are scanned
+----------------------
+
+Any config read will end up at pci_read_config(). This uses
+uclass_get_device_by_seq() to get the PCI bus for a particular bus number.
+Bus number 0 will need to be requested first, and the alias in the device
+tree file will point to the correct device::
+
+ aliases {
+ pci0 = &pcic;
+ };
+
+ pcic: pci@0 {
+ compatible = "sandbox,pci";
+ ...
+ };
+
+
+If there is no alias the devices will be numbered sequentially in the device
+tree.
+
+The call to uclass_get_device() will cause the PCI bus to be probed.
+This does a scan of the bus to locate available devices. These devices are
+bound to their appropriate driver if available. If there is no driver, then
+they are bound to a generic PCI driver which does nothing.
+
+After probing a bus, the available devices will appear in the device tree
+under that bus.
+
+Note that this is all done on a lazy basis, as needed, so until something is
+touched on PCI (eg: a call to pci_find_devices()) it will not be probed.
+
+PCI devices can appear in the flattened device tree. If they do, their node
+often contains extra information which cannot be derived from the PCI IDs or
+PCI class of the device. Each PCI device node must have a <reg> property, as
+defined by the IEEE Std 1275-1994 PCI bus binding document v2.1. Compatible
+string list is optional and generally not needed, since PCI is discoverable
+bus, albeit there are justified exceptions. If the compatible string is
+present, matching on it takes precedence over PCI IDs and PCI classes.
+
+Note we must describe PCI devices with the same bus hierarchy as the
+hardware, otherwise driver model cannot detect the correct parent/children
+relationship during PCI bus enumeration thus PCI devices won't be bound to
+their drivers accordingly. A working example like below::
+
+ pci {
+ #address-cells = <3>;
+ #size-cells = <2>;
+ compatible = "pci-x86";
+ u-boot,dm-pre-reloc;
+ ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000
+ 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000
+ 0x01000000 0x0 0x2000 0x2000 0 0xe000>;
+
+ pcie@17,0 {
+ #address-cells = <3>;
+ #size-cells = <2>;
+ compatible = "pci-bridge";
+ u-boot,dm-pre-reloc;
+ reg = <0x0000b800 0x0 0x0 0x0 0x0>;
+
+ topcliff@0,0 {
+ #address-cells = <3>;
+ #size-cells = <2>;
+ compatible = "pci-bridge";
+ u-boot,dm-pre-reloc;
+ reg = <0x00010000 0x0 0x0 0x0 0x0>;
+
+ pciuart0: uart@a,1 {
+ compatible = "pci8086,8811.00",
+ "pci8086,8811",
+ "pciclass,070002",
+ "pciclass,0700",
+ "x86-uart";
+ u-boot,dm-pre-reloc;
+ reg = <0x00025100 0x0 0x0 0x0 0x0
+ 0x01025110 0x0 0x0 0x0 0x0>;
+ ......
+ };
+
+ ......
+ };
+ };
+
+ ......
+ };
+
+In this example, the root PCI bus node is the "/pci" which matches "pci-x86"
+driver. It has a subnode "pcie@17,0" with driver "pci-bridge". "pcie@17,0"
+also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge,
+a PCI UART device "uart@a,1" is described. This exactly reflects the hardware
+bus hierarchy: on the root PCI bus, there is a PCIe root port which connects
+to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a
+PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART
+device are on the PCI bus. Like other devices in the device tree, if we want
+to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared
+in each of these nodes.
+
+If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
+to specify the driver to use for the device. The device tree takes precedence
+over U_BOOT_PCI_DEVICE. Please note with U_BOOT_PCI_DEVICE, only drivers with
+DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor
+U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or
+pci_generic_drv) will be used.
+
+
+Sandbox
+-------
+
+With sandbox we need a device emulator for each device on the bus since there
+is no real PCI bus. This works by looking in the device tree node for an
+emulator driver. For example::
+
+ pci@1f,0 {
+ compatible = "pci-generic";
+ reg = <0xf800 0 0 0 0>;
+ sandbox,emul = <&emul_1f>;
+ };
+ pci-emul {
+ compatible = "sandbox,pci-emul-parent";
+ emul_1f: emul@1f,0 {
+ compatible = "sandbox,swap-case";
+ #emul-cells = <0>;
+ };
+ };
+
+This means that there is a 'sandbox,swap-case' driver at that bus position.
+Note that the first cell in the 'reg' value is the bus/device/function. See
+PCI_BDF() for the encoding (it is also specified in the IEEE Std 1275-1994
+PCI bus binding document, v2.1)
+
+The pci-emul node should go outside the pci bus node, since otherwise it will
+be scanned as a PCI device, causing confusion.
+
+When this bus is scanned we will end up with something like this::
+
+ `- * pci@0 @ 05c660c8, 0
+ `- pci@1f,0 @ 05c661c8, 63488
+ `- emul@1f,0 @ 05c662c8
+
+When accesses go to the pci@1f,0 device they are forwarded to its emulator.
+
+The sandbox PCI drivers also support dynamic driver binding, allowing device
+driver to declare the driver binding information via U_BOOT_PCI_DEVICE(),
+eliminating the need to provide any device tree node under the host controller
+node. It is required a "sandbox,dev-info" property must be provided in the
+host controller node for this functionality to work.
+
+.. code-block:: none
+
+ pci1: pci@1 {
+ compatible = "sandbox,pci";
+ ...
+ sandbox,dev-info = <0x08 0x00 0x1234 0x5678
+ 0x0c 0x00 0x1234 0x5678>;
+ };
+
+The "sandbox,dev-info" property specifies all dynamic PCI devices on this bus.
+Each dynamic PCI device is encoded as 4 cells a group. The first and second
+cells are PCI device number and function number respectively. The third and
+fourth cells are PCI vendor ID and device ID respectively.
+
+When this bus is scanned we will end up with something like this::
+
+ pci [ + ] pci_sandbo |-- pci1
+ pci_emul [ ] sandbox_sw | |-- sandbox_swap_case_emul
+ pci_emul [ ] sandbox_sw | `-- sandbox_swap_case_emul
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2014-2015 Samsung Electronics
+
+PMIC framework based on Driver Model
+====================================
+
+Introduction
+------------
+This is an introduction to driver-model multi uclass PMIC IC's support.
+At present it's based on two uclass types:
+
+UCLASS_PMIC:
+ basic uclass type for PMIC I/O, which provides common
+ read/write interface.
+UCLASS_REGULATOR:
+ additional uclass type for specific PMIC features, which are
+ Voltage/Current regulators.
+
+New files:
+
+UCLASS_PMIC:
+ - drivers/power/pmic/pmic-uclass.c
+ - include/power/pmic.h
+UCLASS_REGULATOR:
+ - drivers/power/regulator/regulator-uclass.c
+ - include/power/regulator.h
+
+Commands:
+- common/cmd_pmic.c
+- common/cmd_regulator.c
+
+How doees it work
+-----------------
+The Power Management Integrated Circuits (PMIC) are used in embedded systems
+to provide stable, precise and specific voltage power source with over-voltage
+and thermal protection circuits.
+
+The single PMIC can provide various functions by single or multiple interfaces,
+like in the example below::
+
+ -- SoC
+ |
+ | ______________________________________
+ | BUS 0 | Multi interface PMIC IC |--> LDO out 1
+ | e.g.I2C0 | |--> LDO out N
+ |-----------|---- PMIC device 0 (READ/WRITE ops) |
+ | or SPI0 | |_ REGULATOR device (ldo/... ops) |--> BUCK out 1
+ | | |_ CHARGER device (charger ops) |--> BUCK out M
+ | | |_ MUIC device (microUSB con ops) |
+ | BUS 1 | |_ ... |---> BATTERY
+ | e.g.I2C1 | |
+ |-----------|---- PMIC device 1 (READ/WRITE ops) |---> USB in 1
+ . or SPI1 | |_ RTC device (rtc ops) |---> USB in 2
+ . |______________________________________|---> USB out
+ .
+
+Since U-Boot provides driver model features for I2C and SPI bus drivers,
+the PMIC devices should also support this. By the pmic and regulator API's,
+PMIC drivers can simply provide a common functions, for multi-interface and
+and multi-instance device support.
+
+Basic design assumptions:
+
+- Common I/O API:
+ UCLASS_PMIC. For the multi-function PMIC devices, this can be used as
+ parent I/O device for each IC's interface. Then, each children uses the
+ same dev for read/write.
+
+- Common regulator API:
+ UCLASS_REGULATOR. For driving the regulator attributes, auto setting
+ function or command line interface, based on kernel-style regulator device
+ tree constraints.
+
+For simple implementations, regulator drivers are not required, so the code can
+use pmic read/write directly.
+
+Pmic uclass
+-----------
+The basic information:
+
+* Uclass: 'UCLASS_PMIC'
+* Header: 'include/power/pmic.h'
+* Core: 'drivers/power/pmic/pmic-uclass.c' (config 'CONFIG_DM_PMIC')
+* Command: 'common/cmd_pmic.c' (config 'CONFIG_CMD_PMIC')
+* Example: 'drivers/power/pmic/max77686.c'
+
+For detailed API description, please refer to the header file.
+
+As an example of the pmic driver, please refer to the MAX77686 driver.
+
+Please pay attention for the driver's bind() method. Exactly the function call:
+'pmic_bind_children()', which is used to bind the regulators by using the array
+of regulator's node, compatible prefixes.
+
+The 'pmic; command also supports the new API. So the pmic command can be enabled
+by adding CONFIG_CMD_PMIC.
+The new pmic command allows to:
+- list pmic devices
+- choose the current device (like the mmc command)
+- read or write the pmic register
+- dump all pmic registers
+
+This command can use only UCLASS_PMIC devices, since this uclass is designed
+for pmic I/O operations only.
+
+For more information, please refer to the core file.
+
+Regulator uclass
+----------------
+The basic information:
+
+* Uclass: 'UCLASS_REGULATOR'
+
+* Header: 'include/power/regulator.h'
+
+* Core: 'drivers/power/regulator/regulator-uclass.c'
+ (config 'CONFIG_DM_REGULATOR')
+
+* Binding: 'doc/device-tree-bindings/regulator/regulator.txt'
+
+* Command: 'common/cmd_regulator.c' (config 'CONFIG_CMD_REGULATOR')
+
+* Example: 'drivers/power/regulator/max77686.c'
+ 'drivers/power/pmic/max77686.c' (required I/O driver for the above)
+
+* Example: 'drivers/power/regulator/fixed.c'
+ (config 'CONFIG_DM_REGULATOR_FIXED')
+
+For detailed API description, please refer to the header file.
+
+For the example regulator driver, please refer to the MAX77686 regulator driver,
+but this driver can't operate without pmic's example driver, which provides an
+I/O interface for MAX77686 regulator.
+
+The second example is a fixed Voltage/Current regulator for a common use.
+
+The 'regulator' command also supports the new API. The command allow:
+- list regulator devices
+- choose the current device (like the mmc command)
+- do all regulator-specific operations
+
+For more information, please refer to the command file.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2015
+.. Texas Instruments Incorporated - http://www.ti.com/
+
+Remote Processor Framework
+==========================
+
+Introduction
+------------
+
+This is an introduction to driver-model for Remote Processors found
+on various System on Chip(SoCs). The term remote processor is used to
+indicate that this is not the processor on which U-Boot is operating
+on, instead is yet another processing entity that may be controlled by
+the processor on which we are functional.
+
+The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
+
+UCLASS_REMOTEPROC:
+ - drivers/remoteproc/rproc-uclass.c
+ - include/remoteproc.h
+
+Commands:
+ - common/cmd_remoteproc.c
+
+Configuration:
+ - CONFIG_REMOTEPROC is selected by drivers as needed
+ - CONFIG_CMD_REMOTEPROC for the commands if required.
+
+How does it work - The driver
+-----------------------------
+
+Overall, the driver statemachine transitions are typically as follows::
+
+ (entry)
+ +-------+
+ +---+ init |
+ | | | <---------------------+
+ | +-------+ |
+ | |
+ | |
+ | +--------+ |
+ Load| | reset | |
+ | | | <----------+ |
+ | +--------+ | |
+ | |Load | |
+ | | | |
+ | +----v----+ reset | |
+ +-> | | (opt) | |
+ | Loaded +-----------+ |
+ | | |
+ +----+----+ |
+ | Start |
+ +---v-----+ (opt) |
+ +->| Running | Stop |
+ Ping +- | +--------------------+
+ (opt) +---------+
+
+(is_running does not change state)
+opt: Optional state transition implemented by driver.
+
+NOTE: It depends on the remote processor as to the exact behavior
+of the statemachine, remoteproc core does not intent to implement
+statemachine logic. Certain processors may allow start/stop without
+reloading the image in the middle, certain other processors may only
+allow us to start the processor(image from a EEPROM/OTP) etc.
+
+It is hence the responsibility of the driver to handle the requisite
+state transitions of the device as necessary.
+
+Basic design assumptions:
+
+Remote processor can operate on a certain firmware that maybe loaded
+and released from reset.
+
+The driver follows a standard UCLASS DM.
+
+in the bare minimum form:
+
+.. code-block:: c
+
+ static const struct dm_rproc_ops sandbox_testproc_ops = {
+ .load = sandbox_testproc_load,
+ .start = sandbox_testproc_start,
+ };
+
+ static const struct udevice_id sandbox_ids[] = {
+ {.compatible = "sandbox,test-processor"},
+ {}
+ };
+
+ U_BOOT_DRIVER(sandbox_testproc) = {
+ .name = "sandbox_test_proc",
+ .of_match = sandbox_ids,
+ .id = UCLASS_REMOTEPROC,
+ .ops = &sandbox_testproc_ops,
+ .probe = sandbox_testproc_probe,
+ };
+
+This allows for the device to be probed as part of the "init" command
+or invocation of 'rproc_init()' function as the system dependencies define.
+
+The driver is expected to maintain it's own statemachine which is
+appropriate for the device it maintains. It must, at the very least
+provide a load and start function. We assume here that the device
+needs to be loaded and started, else, there is no real purpose of
+using the remoteproc framework.
+
+Describing the device using platform data
+-----------------------------------------
+
+*IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
+SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION
+*WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED
+TO DM/FDT.
+
+Considering that many platforms are yet to move to device-tree model,
+a simplified definition of a device is as follows:
+
+.. code-block:: c
+
+ struct dm_rproc_uclass_pdata proc_3_test = {
+ .name = "proc_3_legacy",
+ .mem_type = RPROC_INTERNAL_MEMORY_MAPPED,
+ .driver_plat_data = &mydriver_data;
+ };
+
+ U_BOOT_DRVINFO(proc_3_demo) = {
+ .name = "sandbox_test_proc",
+ .plat = &proc_3_test,
+ };
+
+There can be additional data that may be desired depending on the
+remoteproc driver specific needs (for example: SoC integration
+details such as clock handle or something similar). See appropriate
+documentation for specific remoteproc driver for further details.
+These are passed via driver_plat_data.
+
+Describing the device using device tree
+---------------------------------------
+
+.. code-block: none
+
+ / {
+ ...
+ aliases {
+ ...
+ remoteproc0 = &rproc_1;
+ remoteproc1 = &rproc_2;
+
+ };
+ ...
+
+ rproc_1: rproc@1 {
+ compatible = "sandbox,test-processor";
+ remoteproc-name = "remoteproc-test-dev1";
+ };
+
+ rproc_2: rproc@2 {
+ compatible = "sandbox,test-processor";
+ internal-memory-mapped;
+ remoteproc-name = "remoteproc-test-dev2";
+ };
+ ...
+ };
+
+aliases usage is optional, but it is usually recommended to ensure the
+users have a consistent usage model for a platform.
+the compatible string used here is specific to the remoteproc driver involved.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+How to port a serial driver to driver model
+===========================================
+
+Almost all of the serial drivers have been converted as at January 2016. These
+ones remain:
+
+ * serial_bfin.c
+ * serial_pxa.c
+
+The deadline for this work was the end of January 2016. If no one steps
+forward to convert these, at some point there may come a patch to remove them!
+
+Here is a suggested approach for converting your serial driver over to driver
+model. Please feel free to update this file with your ideas and suggestions.
+
+- #ifdef out all your own serial driver code (#ifndef CONFIG_DM_SERIAL)
+- Define CONFIG_DM_SERIAL for your board, vendor or architecture
+- If the board does not already use driver model, you need CONFIG_DM also
+- Your board should then build, but will not boot since there will be no serial
+ driver
+- Add the U_BOOT_DRIVER piece at the end (e.g. copy serial_s5p.c for example)
+- Add a private struct for the driver data - avoid using static variables
+- Implement each of the driver methods, perhaps by calling your old methods
+- You may need to adjust the function parameters so that the old and new
+ implementations can share most of the existing code
+- If you convert all existing users of the driver, remove the pre-driver-model
+ code
+
+In terms of patches a conversion series typically has these patches:
+- clean up / prepare the driver for conversion
+- add driver model code
+- convert at least one existing board to use driver model serial
+- (if no boards remain that don't use driver model) remove the old code
+
+This may be a good time to move your board to use device tree also. Mostly
+this involves these steps:
+
+- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE
+- add your device tree files to arch/<arch>/dts
+- update the Makefile there
+- Add stdout-path to your /chosen device tree node if it is not already there
+- build and get u-boot-dtb.bin so you can test it
+- Your drivers can now use device tree
+- For device tree in SPL, define CONFIG_SPL_OF_CONTROL
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2020
+.. Texas Instruments Incorporated - http://www.ti.com/
+
+SOC ID Framework
+================
+
+Introduction
+------------
+
+The driver-model SOC ID framework is able to provide identification
+information about a specific SoC in use at runtime, and also provide matching
+from a set of identification information from an array. This can be useful for
+enabling small quirks in drivers that exist between SoC variants that are
+impractical to implement using device tree flags. It is based on UCLASS_SOC.
+
+UCLASS_SOC:
+ - drivers/soc/soc-uclass.c
+ - include/soc.h
+
+Configuration:
+ - CONFIG_SOC_DEVICE is selected by drivers as needed.
+
+Implementing a UCLASS_SOC provider
+----------------------------------
+
+The purpose of this framework is to allow UCLASS_SOC provider drivers to supply
+identification information about the SoC in use at runtime. The framework
+allows drivers to define soc_ops that return identification strings. All
+soc_ops need not be defined and can be left as NULL, in which case the
+framework will return -ENOSYS and not consider the value when doing an
+soc_device_match.
+
+It is left to the driver implementor to decide how the information returned is
+determined, but in general the same SOC should always return the same set of
+identifying information. Information returned must be in the form of a NULL
+terminated string.
+
+See include/soc.h for documentation of the available soc_ops and the intended
+meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for
+an example UCLASS_SOC provider driver.
+
+Using a UCLASS_SOC driver
+-------------------------
+
+The framework provides the ability to retrieve and use the identification
+strings directly. It also has the ability to return a match from a list of
+different sets of SoC data using soc_device_match.
+
+An array of 'struct soc_attr' can be defined, each containing ID information
+for a specific SoC, and when passed to soc_device_match, the identifier values
+for each entry in the list will be compared against the values provided by the
+UCLASS_SOC driver that is in use. The first entry in the list that matches all
+non-null values will be returned by soc_device_match.
+
+An example of various uses of the framework can be found at test/dm/soc.c.
+
+Describing the device using device tree
+---------------------------------------
+
+.. code-block:: none
+
+ chipid: chipid {
+ compatible = "sandbox,soc";
+ };
+
+All that is required in a DT node is a compatible for a corresponding
+UCLASS_SOC driver.
--- /dev/null
+.. 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_of_to_plat(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 -EINVAL;
+ }
+
+ 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,
+ .of_to_plat = exynos_spi_of_to_plat,
+ .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 <dm.h>
+ #include <errno.h>
+
+
+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_plat {
+ 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 of_to_plat() [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) = {
+ ...
+ .plat_auto = sizeof(struct exynos_spi_plat),
+
+
+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_of_to_plat(struct udevice *bus)
+ {
+ struct exynos_spi_plat *plat = bus->plat;
+ 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_DRVINFO() declaration in your board file:
+
+.. code-block:: c
+
+ struct exynos_spi_plat platdata_spi0 = {
+ .periph_id = ...
+ .frequency = ...
+ .regs = ...
+ .deactivate_delay_us = ...
+ };
+
+ U_BOOT_DRVINFO(board_spi0) = {
+ .name = "exynos_spi",
+ .plat = &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 = 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_plat *plat = dev_get_plat(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_plat *plat = bus->plat;
+ 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_plat *pdata = dev_get_plat(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 = 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 -EINVAL if the supplied chip select is invalid, or 0 if it is valid.
+If you don't provide the cs_info() method, 0 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 tools/patman/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_plat:
+ This is device_get_parent_plat(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.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+How USB works with driver model
+===============================
+
+Introduction
+------------
+
+Driver model USB support makes use of existing features but changes how
+drivers are found. This document provides some information intended to help
+understand how things work with USB in U-Boot when driver model is enabled.
+
+
+Enabling driver model for USB
+-----------------------------
+
+A new CONFIG_DM_USB option is provided to enable driver model for USB. This
+causes the USB uclass to be included, and drops the equivalent code in
+usb.c. In particular the usb_init() function is then implemented by the
+uclass.
+
+
+Support for EHCI and XHCI
+-------------------------
+
+So far OHCI is not supported. Both EHCI and XHCI drivers should be declared
+as drivers in the USB uclass. For example:
+
+.. code-block:: c
+
+ static const struct udevice_id ehci_usb_ids[] = {
+ { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 },
+ { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 },
+ { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 },
+ { }
+ };
+
+ U_BOOT_DRIVER(usb_ehci) = {
+ .name = "ehci_tegra",
+ .id = UCLASS_USB,
+ .of_match = ehci_usb_ids,
+ .of_to_plat = ehci_usb_of_to_plat,
+ .probe = tegra_ehci_usb_probe,
+ .remove = tegra_ehci_usb_remove,
+ .ops = &ehci_usb_ops,
+ .plat_auto = sizeof(struct usb_plat),
+ .priv_auto = sizeof(struct fdt_usb),
+ .flags = DM_FLAG_ALLOC_PRIV_DMA,
+ };
+
+Here ehci_usb_ids is used to list the controllers that the driver supports.
+Each has its own data value. Controllers must be in the UCLASS_USB uclass.
+
+The of_to_plat() method allows the controller driver to grab any
+necessary settings from the device tree.
+
+The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in
+most cases, since they are all EHCI-compatible. For EHCI there are also some
+special operations that can be overridden when calling ehci_register().
+
+The driver can use priv_auto to set the size of its private data.
+This can hold run-time information needed by the driver for operation. It
+exists when the device is probed (not when it is bound) and is removed when
+the driver is removed.
+
+Note that usb_plat is currently only used to deal with setting up a bus
+in USB device mode (OTG operation). It can be omitted if that is not
+supported.
+
+The driver's probe() method should do the basic controller init and then
+call ehci_register() to register itself as an EHCI device. It should call
+ehci_deregister() in the remove() method. Registering a new EHCI device
+does not by itself cause the bus to be scanned.
+
+The old ehci_hcd_init() function is no-longer used. Nor is it necessary to
+set up the USB controllers from board init code. When 'usb start' is used,
+each controller will be probed and its bus scanned.
+
+XHCI works in a similar way.
+
+
+Data structures
+---------------
+
+The following primary data structures are in use:
+
+- struct usb_device:
+ This holds information about a device on the bus. All devices have
+ this structure, even the root hub. The controller itself does not
+ have this structure. You can access it for a device 'dev' with
+ dev_get_parent_priv(dev). It matches the old structure except that the
+ parent and child information is not present (since driver model
+ handles that). Once the device is set up, you can find the device
+ descriptor and current configuration descriptor in this structure.
+
+- struct usb_plat:
+ This holds platform data for a controller. So far this is only used
+ as a work-around for controllers which can act as USB devices in OTG
+ mode, since the gadget framework does not use driver model.
+
+- struct usb_dev_plat:
+ This holds platform data for a device. You can access it for a
+ device 'dev' with dev_get_parent_plat(dev). It holds the device
+ address and speed - anything that can be determined before the device
+ driver is actually set up. When probing the bus this structure is
+ used to provide essential information to the device driver.
+
+- struct usb_bus_priv:
+ This is private information for each controller, maintained by the
+ controller uclass. It is mostly used to keep track of the next
+ device address to use.
+
+Of these, only struct usb_device was used prior to driver model.
+
+
+USB buses
+---------
+
+Given a controller, you know the bus - it is the one attached to the
+controller. Each controller handles exactly one bus. Every controller has a
+root hub attached to it. This hub, which is itself a USB device, can provide
+one or more 'ports' to which additional devices can be attached. It is
+possible to power up a hub and find out which of its ports have devices
+attached.
+
+Devices are given addresses starting at 1. The root hub is always address 1,
+and from there the devices are numbered in sequence. The USB uclass takes
+care of this numbering automatically during enumeration.
+
+USB devices are enumerated by finding a device on a particular hub, and
+setting its address to the next available address. The USB bus stretches out
+in a tree structure, potentially with multiple hubs each with several ports
+and perhaps other hubs. Some hubs will have their own power since otherwise
+the 5V 500mA power supplied by the controller will not be sufficient to run
+very many devices.
+
+Enumeration in U-Boot takes a long time since devices are probed one at a
+time, and each is given sufficient time to wake up and announce itself. The
+timeouts are set for the slowest device.
+
+Up to 127 devices can be on each bus. USB has four bus speeds: low
+(1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2
+and newer (EHCI), and super (5Gbps) which is only available with USB3 and
+newer (XHCI). If you connect a super-speed device to a high-speed hub, you
+will only get high-speed.
+
+
+USB operations
+--------------
+
+As before driver model, messages can be sent using submit_bulk_msg() and the
+like. These are now implemented by the USB uclass and route through the
+controller drivers. Note that messages are not sent to the driver of the
+device itself - i.e. they don't pass down the stack to the controller.
+U-Boot simply finds the controller to which the device is attached, and sends
+the message there with an appropriate 'pipe' value so it can be addressed
+properly. Having said that, the USB device which should receive the message
+is passed in to the driver methods, for use by sandbox. This design decision
+is open for review and the code impact of changing it is small since the
+methods are typically implemented by the EHCI and XHCI stacks.
+
+Controller drivers (in UCLASS_USB) themselves provide methods for sending
+each message type. For XHCI an additional alloc_device() method is provided
+since XHCI needs to allocate a device context before it can even read the
+device's descriptor.
+
+These methods use a 'pipe' which is a collection of bit fields used to
+describe the type of message, direction of transfer and the intended
+recipient (device number).
+
+
+USB Devices
+-----------
+
+USB devices are found using a simple algorithm which works through the
+available hubs in a depth-first search. Devices can be in any uclass, but
+are attached to a parent hub (or controller in the case of the root hub) and
+so have parent data attached to them (this is struct usb_device).
+
+By the time the device's probe() method is called, it is enumerated and is
+ready to talk to the host.
+
+The enumeration process needs to work out which driver to attach to each USB
+device. It does this by examining the device class, interface class, vendor
+ID, product ID, etc. See struct usb_driver_entry for how drivers are matched
+with USB devices - you can use the USB_DEVICE() macro to declare a USB
+driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage
+devices, and it will be used for all USB devices which match.
+
+
+
+Technical details on enumeration flow
+-------------------------------------
+
+It is useful to understand precisely how a USB bus is enumerating to avoid
+confusion when dealing with USB devices.
+
+Device initialisation happens roughly like this:
+
+- At some point the 'usb start' command is run
+- This calls usb_init() which works through each controller in turn
+- The controller is probed(). This does no enumeration.
+- Then usb_scan_bus() is called. This calls usb_scan_device() to scan the
+ (only) device that is attached to the controller - a root hub
+- usb_scan_device() sets up a fake struct usb_device and calls
+ usb_setup_device(), passing the port number to be scanned, in this case
+ port 0
+- usb_setup_device() first calls usb_prepare_device() to set the device
+ address, then usb_select_config() to select the first configuration
+- at this point the device is enumerated but we do not have a real struct
+ udevice for it. But we do have the descriptor in struct usb_device so we can
+ use this to figure out what driver to use
+- back in usb_scan_device(), we call usb_find_child() to try to find an
+ existing device which matches the one we just found on the bus. This can
+ happen if the device is mentioned in the device tree, or if we previously
+ scanned the bus and so the device was created before
+- if usb_find_child() does not find an existing device, we call
+ usb_find_and_bind_driver() which tries to bind one
+- usb_find_and_bind_driver() searches all available USB drivers (declared
+ with USB_DEVICE()). If it finds a match it binds that driver to create a
+ new device.
+- If it does not, it binds a generic driver. A generic driver is good enough
+ to allow access to the device (sending it packets, etc.) but all
+ functionality will need to be implemented outside the driver model.
+- in any case, when usb_find_child() and/or usb_find_and_bind_driver() are
+ done, we have a device with the correct uclass. At this point we want to
+ probe the device
+- first we store basic information about the new device (address, port,
+ speed) in its parent platform data. We cannot store it its private data
+ since that will not exist until the device is probed.
+- then we call device_probe() which probes the device
+- the first probe step is actually the USB controller's (or USB hubs's)
+ child_pre_probe() method. This gets called before anything else and is
+ intended to set up a child device ready to be used with its parent bus. For
+ USB this calls usb_child_pre_probe() which grabs the information that was
+ stored in the parent platform data and stores it in the parent private data
+ (which is struct usb_device, a real one this time). It then calls
+ usb_select_config() again to make sure that everything about the device is
+ set up
+- note that we have called usb_select_config() twice. This is inefficient
+ but the alternative is to store additional information in the platform data.
+ The time taken is minimal and this way is simpler
+- at this point the device is set up and ready for use so far as the USB
+ subsystem is concerned
+- the device's probe() method is then called. It can send messages and do
+ whatever else it wants to make the device work.
+
+Note that the first device is always a root hub, and this must be scanned to
+find any devices. The above steps will have created a hub (UCLASS_USB_HUB),
+given it address 1 and set the configuration.
+
+For hubs, the hub uclass has a post_probe() method. This means that after
+any hub is probed, the uclass gets to do some processing. In this case
+usb_hub_post_probe() is called, and the following steps take place:
+
+- usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn
+ calls usb_hub_configure()
+- hub power is enabled
+- we loop through each port on the hub, performing the same steps for each
+- first, check if there is a device present. This happens in
+ usb_hub_port_connect_change(). If so, then usb_scan_device() is called to
+ scan the device, passing the appropriate port number.
+- you will recognise usb_scan_device() from the steps above. It sets up the
+ device ready for use. If it is a hub, it will scan that hub before it
+ continues here (recursively, depth-first)
+- once all hub ports are scanned in this way, the hub is ready for use and
+ all of its downstream devices also
+- additional controllers are scanned in the same way
+
+The above method has some nice properties:
+
+- the bus enumeration happens by virtue of driver model's natural device flow
+- most logic is in the USB controller and hub uclasses; the actual device
+ drivers do not need to know they are on a USB bus, at least so far as
+ enumeration goes
+- hub scanning happens automatically after a hub is probed
+
+
+Hubs
+----
+
+USB hubs are scanned as in the section above. While hubs have their own
+uclass, they share some common elements with controllers:
+
+- they both attach private data to their children (struct usb_device,
+ accessible for a child with dev_get_parent_priv(child))
+- they both use usb_child_pre_probe() to set up their children as proper USB
+ devices
+
+
+Example - Mass Storage
+----------------------
+
+As an example of a USB device driver, see usb_storage.c. It uses its own
+uclass and declares itself as follows:
+
+.. code-block:: c
+
+ U_BOOT_DRIVER(usb_mass_storage) = {
+ .name = "usb_mass_storage",
+ .id = UCLASS_MASS_STORAGE,
+ .of_match = usb_mass_storage_ids,
+ .probe = usb_mass_storage_probe,
+ };
+
+ static const struct usb_device_id mass_storage_id_table[] = {
+ { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS,
+ .bInterfaceClass = USB_CLASS_MASS_STORAGE},
+ { } /* Terminating entry */
+ };
+
+ USB_DEVICE(usb_mass_storage, mass_storage_id_table);
+
+The USB_DEVICE() macro attaches the given table of matching information to
+the given driver. Note that the driver is declared in U_BOOT_DRIVER() as
+'usb_mass_storage' and this must match the first parameter of USB_DEVICE.
+
+When usb_find_and_bind_driver() is called on a USB device with the
+bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find
+this driver and use it.
+
+
+Counter-example: USB Ethernet
+-----------------------------
+
+As an example of the old way of doing things, see usb_ether.c. When the bus
+is scanned, all Ethernet devices will be created as generic USB devices (in
+uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed,
+usb_host_eth_scan() will be called. This looks through all the devices on
+each bus and manually figures out which are Ethernet devices in the ways of
+yore.
+
+In fact, usb_ether should be moved to driver model. Each USB Ethernet driver
+(e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so
+that it will be found as part of normal USB enumeration. Then, instead of a
+generic USB driver, a real (driver-model-aware) driver will be used. Since
+Ethernet now supports driver model, this should be fairly easy to achieve,
+and then usb_ether.c and the usb_host_eth_scan() will melt away.
+
+
+Sandbox
+-------
+
+All driver model uclasses must have tests and USB is no exception. To
+achieve this, a sandbox USB controller is provided. This can make use of
+emulation drivers which pretend to be USB devices. Emulations are provided
+for a hub and a flash stick. These are enough to create a pretend USB bus
+(defined by the sandbox device tree sandbox.dts) which can be scanned and
+used.
+
+Tests in test/dm/usb.c make use of this feature. It allows much of the USB
+stack to be tested without real hardware being needed.
+
+Here is an example device tree fragment:
+
+.. code-block:: none
+
+ usb@1 {
+ compatible = "sandbox,usb";
+ hub {
+ compatible = "usb-hub";
+ usb,device-class = <USB_CLASS_HUB>;
+ hub-emul {
+ compatible = "sandbox,usb-hub";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ flash-stick {
+ reg = <0>;
+ compatible = "sandbox,usb-flash";
+ sandbox,filepath = "flash.bin";
+ };
+ };
+ };
+ };
+
+This defines a single controller, containing a root hub (which is required).
+The hub is emulated by a hub emulator, and the emulated hub has a single
+flash stick to emulate on one of its ports.
+
+When 'usb start' is used, the following 'dm tree' output will be available::
+
+ usb [ + ] `-- usb@1
+ usb_hub [ + ] `-- hub
+ usb_emul [ + ] |-- hub-emul
+ usb_emul [ + ] | `-- flash-stick
+ usb_mass_st [ + ] `-- usb_mass_storage
+
+
+This may look confusing. Most of it mirrors the device tree, but the
+'usb_mass_storage' device is not in the device tree. This is created by
+usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While
+'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot
+USB device driver that talks to it.
+
+
+Future work
+-----------
+
+It is pretty uncommon to have a large USB bus with lots of hubs on an
+embedded system. In fact anything other than a root hub is uncommon. Still
+it would be possible to speed up enumeration in two ways:
+
+- breadth-first search would allow devices to be reset and probed in
+ parallel to some extent
+- enumeration could be lazy, in the sense that we could enumerate just the
+ root hub at first, then only progress to the next 'level' when a device is
+ used that we cannot find. This could be made easier if the devices were
+ statically declared in the device tree (which is acceptable for production
+ boards where the same, known, things are on each bus).
+
+But in common cases the current algorithm is sufficient.
+
+Other things that need doing:
+- Convert usb_ether to use driver model as described above
+- Test that keyboards work (and convert to driver model)
+- Move the USB gadget framework to driver model
+- Implement OHCI in driver model
+- Implement USB PHYs in driver model
+- Work out a clever way to provide lazy init for USB devices
+
+
+.. 23-Mar-15
:maxdepth: 1
commands
+ driver-model/index
global_data
logging
menus
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Binding/unbinding a driver
-==========================
-
-This document aims to describe the bind and unbind commands.
-
-For debugging purpose, it should be useful to bind or unbind a driver from
-the U-boot command line.
-
-The unbind command calls the remove device driver callback and unbind the
-device from its driver.
-
-The bind command binds a device to its driver.
-
-In some cases it can be useful to be able to bind a device to a driver from
-the command line.
-The obvious example is for versatile devices such as USB gadget.
-Another use case is when the devices are not yet ready at startup and
-require some setup before the drivers are bound (ex: FPGA which bitsream is
-fetched from a mass storage or ethernet)
-
-usage:
-
-bind <node path> <driver>
-bind <class> <index> <driver>
-
-unbind <node path>
-unbind <class> <index>
-unbind <class> <index> <driver>
-
-Where:
- - <node path> is the node's device tree path
- - <class> is one of the class available in the list given by the "dm uclass"
- command or first column of "dm tree" command.
- - <index> is the index of the parent's node (second column of "dm tree" output).
- - <driver> is the driver name to bind given by the "dm drivers" command or the by
- the fourth column of "dm tree" output.
-
-example:
-
-bind usb_dev_generic 0 usb_ether
-unbind usb_dev_generic 0 usb_ether
-or
-unbind eth 1
-
-bind /ocp/omap_dwc3@48380000/usb@48390000 usb_ether
-unbind /ocp/omap_dwc3@48380000/usb@48390000
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Debugging driver model
-======================
-
-This document aims to provide help when you cannot work out why driver model is
-not doing what you expect.
-
-
-Useful techniques in general
-----------------------------
-
-Here are some useful debugging features generally.
-
- - If you are writing a new feature, consider doing it in sandbox instead of
- on your board. Sandbox has no limits, allows easy debugging (e.g. gdb) and
- you can write emulators for most common devices.
- - Put '#define DEBUG' at the top of a file, to activate all the debug() and
- log_debug() statements in that file.
- - Where logging is used, change the logging level, e.g. in SPL with
- CONFIG_SPL_LOG_MAX_LEVEL=7 (which is LOGL_DEBUG) and
- CONFIG_LOG_DEFAULT_LEVEL=7
- - Where logging of return values is implemented with log_msg_ret(), set
- CONFIG_LOG_ERROR_RETURN=y to see exactly where the error is happening
- - Make sure you have a debug UART enabled - see CONFIG_DEBUG_UART. With this
- you can get serial output (printf(), etc.) before the serial driver is
- running.
- - Use a JTAG emulator to set breakpoints and single-step through code
-
-Not that most of these increase code/data size somewhat when enabled.
-
-
-Failure to locate a device
---------------------------
-
-Let's say you have uclass_first_device_err() and it is not finding anything.
-
-If it is returning an error, then that gives you a clue. Look up linux/errno.h
-to see errors. Common ones are:
-
- - -ENOMEM which indicates that memory is short. If it happens in SPL or
- before relocation in U-Boot, check CONFIG_SPL_SYS_MALLOC_F_LEN and
- CONFIG_SYS_MALLOC_F_LEN as they may need to be larger. Add '#define DEBUG'
- at the very top of malloc_simple.c to get an idea of where your memory is
- going.
- - -EINVAL which typically indicates that something was missing or wrong in
- the device tree node. Check that everything is correct and look at the
- of_to_plat() method in the driver.
-
-If there is no error, you should check if the device is actually bound. Call
-dm_dump_all() just before you locate the device to make sure it exists.
-
-If it does not exist, check your device tree compatible strings match up with
-what the driver expects (in the struct udevice_id array).
-
-If you are using of-platdata (e.g. CONFIG_SPL_OF_PLATDATA), check that the
-driver name is the same as the first compatible string in the device tree (with
-invalid-variable characters converted to underscore).
-
-If you are really stuck, putting '#define LOG_DEBUG' at the top of
-drivers/core/lists.c should show you what is going on.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Design Details
-==============
-
-This README contains high-level information about driver model, a unified
-way of declaring and accessing drivers in U-Boot. The original work was done
-by:
-
-
-This has been both simplified and extended into the current implementation
-by:
-
-
-
-Terminology
------------
-
-Uclass
- a group of devices which operate in the same way. A uclass provides
- a way of accessing individual devices within the group, but always
- using the same interface. For example a GPIO uclass provides
- operations for get/set value. An I2C uclass may have 10 I2C ports,
- 4 with one driver, and 6 with another.
-
-Driver
- some code which talks to a peripheral and presents a higher-level
- interface to it.
-
-Device
- an instance of a driver, tied to a particular port or peripheral.
-
-
-How to try it
--------------
-
-Build U-Boot sandbox and run it::
-
- make sandbox_defconfig
- make
- ./u-boot -d u-boot.dtb
-
- (type 'reset' to exit U-Boot)
-
-
-There is a uclass called 'demo'. This uclass handles
-saying hello, and reporting its status. There are two drivers in this
-uclass:
-
- - simple: Just prints a message for hello, doesn't implement status
- - shape: Prints shapes and reports number of characters printed as status
-
-The demo class is pretty simple, but not trivial. The intention is that it
-can be used for testing, so it will implement all driver model features and
-provide good code coverage of them. It does have multiple drivers, it
-handles parameter data and plat (data which tells the driver how
-to operate on a particular platform) and it uses private driver data.
-
-To try it, see the example session below::
-
- =>demo hello 1
- Hello '@' from 07981110: red 4
- =>demo status 2
- Status: 0
- =>demo hello 2
- g
- r@
- e@@
- e@@@
- n@@@@
- g@@@@@
- =>demo status 2
- Status: 21
- =>demo hello 4 ^
- y^^^
- e^^^^^
- l^^^^^^^
- l^^^^^^^
- o^^^^^
- w^^^
- =>demo status 4
- Status: 36
- =>
-
-
-Running the tests
------------------
-
-The intent with driver model is that the core portion has 100% test coverage
-in sandbox, and every uclass has its own test. As a move towards this, tests
-are provided in test/dm. To run them, try::
-
- ./test/py/test.py --bd sandbox --build -k ut_dm -v
-
-You should see something like this::
-
- (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v
- +make O=/root/u-boot/build-sandbox -s sandbox_defconfig
- +make O=/root/u-boot/build-sandbox -s -j8
- ============================= test session starts ==============================
- platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python
- cachedir: .cache
- rootdir: /root/u-boot, inifile:
- collected 199 items
-
- test/py/tests/test_ut.py::test_ut_dm_init PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED
- test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED
-
- ======================= 84 tests deselected by '-kut_dm' =======================
- ================== 115 passed, 84 deselected in 3.77 seconds ===================
-
-What is going on?
------------------
-
-Let's start at the top. The demo command is in cmd/demo.c. It does
-the usual command processing and then:
-
-.. code-block:: c
-
- struct udevice *demo_dev;
-
- ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev);
-
-UCLASS_DEMO means the class of devices which implement 'demo'. Other
-classes might be MMC, or GPIO, hashing or serial. The idea is that the
-devices in the class all share a particular way of working. The class
-presents a unified view of all these devices to U-Boot.
-
-This function looks up a device for the demo uclass. Given a device
-number we can find the device because all devices have registered with
-the UCLASS_DEMO uclass.
-
-The device is automatically activated ready for use by uclass_get_device().
-
-Now that we have the device we can do things like:
-
-.. code-block:: c
-
- return demo_hello(demo_dev, ch);
-
-This function is in the demo uclass. It takes care of calling the 'hello'
-method of the relevant driver. Bearing in mind that there are two drivers,
-this particular device may use one or other of them.
-
-The code for demo_hello() is in drivers/demo/demo-uclass.c:
-
-.. code-block:: c
-
- int demo_hello(struct udevice *dev, int ch)
- {
- const struct demo_ops *ops = device_get_ops(dev);
-
- if (!ops->hello)
- return -ENOSYS;
-
- return ops->hello(dev, ch);
- }
-
-As you can see it just calls the relevant driver method. One of these is
-in drivers/demo/demo-simple.c:
-
-.. code-block:: c
-
- static int simple_hello(struct udevice *dev, int ch)
- {
- const struct dm_demo_pdata *pdata = dev_get_plat(dev);
-
- printf("Hello from %08x: %s %d\n", map_to_sysmem(dev),
- pdata->colour, pdata->sides);
-
- return 0;
- }
-
-
-So that is a trip from top (command execution) to bottom (driver action)
-but it leaves a lot of topics to address.
-
-
-Declaring Drivers
------------------
-
-A driver declaration looks something like this (see
-drivers/demo/demo-shape.c):
-
-.. code-block:: c
-
- static const struct demo_ops shape_ops = {
- .hello = shape_hello,
- .status = shape_status,
- };
-
- U_BOOT_DRIVER(demo_shape_drv) = {
- .name = "demo_shape_drv",
- .id = UCLASS_DEMO,
- .ops = &shape_ops,
- .priv_data_size = sizeof(struct shape_data),
- };
-
-
-This driver has two methods (hello and status) and requires a bit of
-private data (accessible through dev_get_priv(dev) once the driver has
-been probed). It is a member of UCLASS_DEMO so will register itself
-there.
-
-In U_BOOT_DRIVER it is also possible to specify special methods for bind
-and unbind, and these are called at appropriate times. For many drivers
-it is hoped that only 'probe' and 'remove' will be needed.
-
-The U_BOOT_DRIVER macro creates a data structure accessible from C,
-so driver model can find the drivers that are available.
-
-The methods a device can provide are documented in the device.h header.
-Briefly, they are:
-
- * bind - make the driver model aware of a device (bind it to its driver)
- * unbind - make the driver model forget the device
- * of_to_plat - convert device tree data to plat - see later
- * probe - make a device ready for use
- * remove - remove a device so it cannot be used until probed again
-
-The sequence to get a device to work is bind, of_to_plat (if using
-device tree) and probe.
-
-
-Platform Data
--------------
-
-Note: platform data is the old way of doing things. It is
-basically a C structure which is passed to drivers to tell them about
-platform-specific settings like the address of its registers, bus
-speed, etc. Device tree is now the preferred way of handling this.
-Unless you have a good reason not to use device tree (the main one
-being you need serial support in SPL and don't have enough SRAM for
-the cut-down device tree and libfdt libraries) you should stay away
-from platform data.
-
-Platform data is like Linux platform data, if you are familiar with that.
-It provides the board-specific information to start up a device.
-
-Why is this information not just stored in the device driver itself? The
-idea is that the device driver is generic, and can in principle operate on
-any board that has that type of device. For example, with modern
-highly-complex SoCs it is common for the IP to come from an IP vendor, and
-therefore (for example) the MMC controller may be the same on chips from
-different vendors. It makes no sense to write independent drivers for the
-MMC controller on each vendor's SoC, when they are all almost the same.
-Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
-but lie at different addresses in the address space.
-
-Using the UART example, we have a single driver and it is instantiated 6
-times by supplying 6 lots of platform data. Each lot of platform data
-gives the driver name and a pointer to a structure containing information
-about this instance - e.g. the address of the register space. It may be that
-one of the UARTS supports RS-485 operation - this can be added as a flag in
-the platform data, which is set for this one port and clear for the rest.
-
-Think of your driver as a generic piece of code which knows how to talk to
-a device, but needs to know where it is, any variant/option information and
-so on. Platform data provides this link between the generic piece of code
-and the specific way it is bound on a particular board.
-
-Examples of platform data include:
-
- - The base address of the IP block's register space
- - Configuration options, like:
- - the SPI polarity and maximum speed for a SPI controller
- - the I2C speed to use for an I2C device
- - the number of GPIOs available in a GPIO device
-
-Where does the platform data come from? It is either held in a structure
-which is compiled into U-Boot, or it can be parsed from the Device Tree
-(see 'Device Tree' below).
-
-For an example of how it can be compiled in, see demo-pdata.c which
-sets up a table of driver names and their associated platform data.
-The data can be interpreted by the drivers however they like - it is
-basically a communication scheme between the board-specific code and
-the generic drivers, which are intended to work on any board.
-
-Drivers can access their data via dev->info->plat. Here is
-the declaration for the platform data, which would normally appear
-in the board file.
-
-.. code-block:: c
-
- static const struct dm_demo_pdata red_square = {
- .colour = "red",
- .sides = 4.
- };
-
- static const struct driver_info info[] = {
- {
- .name = "demo_shape_drv",
- .plat = &red_square,
- },
- };
-
- demo1 = driver_bind(root, &info[0]);
-
-
-Device Tree
------------
-
-While plat is useful, a more flexible way of providing device data is
-by using device tree. In U-Boot you should use this where possible. Avoid
-sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly
-necessary.
-
-With device tree we replace the above code with the following device tree
-fragment:
-
-.. code-block:: c
-
- red-square {
- compatible = "demo-shape";
- colour = "red";
- sides = <4>;
- };
-
-This means that instead of having lots of U_BOOT_DRVINFO() declarations in
-the board file, we put these in the device tree. This approach allows a lot
-more generality, since the same board file can support many types of boards
-(e,g. with the same SoC) just by using different device trees. An added
-benefit is that the Linux device tree can be used, thus further simplifying
-the task of board-bring up either for U-Boot or Linux devs (whoever gets to
-the board first!).
-
-The easiest way to make this work it to add a few members to the driver:
-
-.. code-block:: c
-
- .plat_auto = sizeof(struct dm_test_pdata),
- .of_to_plat = testfdt_of_to_plat,
-
-The 'auto' feature allowed space for the plat to be allocated
-and zeroed before the driver's of_to_plat() method is called. The
-of_to_plat() method, which the driver write supplies, should parse
-the device tree node for this device and place it in dev->plat. Thus
-when the probe method is called later (to set up the device ready for use)
-the platform data will be present.
-
-Note that both methods are optional. If you provide an of_to_plat
-method then it will be called first (during activation). If you provide a
-probe method it will be called next. See Driver Lifecycle below for more
-details.
-
-If you don't want to have the plat automatically allocated then you
-can leave out plat_auto. In this case you can use malloc
-in your of_to_plat (or probe) method to allocate the required memory,
-and you should free it in the remove method.
-
-The driver model tree is intended to mirror that of the device tree. The
-root driver is at device tree offset 0 (the root node, '/'), and its
-children are the children of the root node.
-
-In order for a device tree to be valid, the content must be correct with
-respect to either device tree specification
-(https://www.devicetree.org/specifications/) or the device tree bindings that
-are found in the doc/device-tree-bindings directory. When not U-Boot specific
-the bindings in this directory tend to come from the Linux Kernel. As such
-certain design decisions may have been made already for us in terms of how
-specific devices are described and bound. In most circumstances we wish to
-retain compatibility without additional changes being made to the device tree
-source files.
-
-Declaring Uclasses
-------------------
-
-The demo uclass is declared like this:
-
-.. code-block:: c
-
- UCLASS_DRIVER(demo) = {
- .id = UCLASS_DEMO,
- };
-
-It is also possible to specify special methods for probe, etc. The uclass
-numbering comes from include/dm/uclass-id.h. To add a new uclass, add to the
-end of the enum there, then declare your uclass as above.
-
-
-Device Sequence Numbers
------------------------
-
-U-Boot numbers devices from 0 in many situations, such as in the command
-line for I2C and SPI buses, and the device names for serial ports (serial0,
-serial1, ...). Driver model supports this numbering and permits devices
-to be locating by their 'sequence'. This numbering uniquely identifies a
-device in its uclass, so no two devices within a particular uclass can have
-the same sequence number.
-
-Sequence numbers start from 0 but gaps are permitted. For example, a board
-may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are
-numbered is up to a particular board, and may be set by the SoC in some
-cases. While it might be tempting to automatically renumber the devices
-where there are gaps in the sequence, this can lead to confusion and is
-not the way that U-Boot works.
-
-Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS
-Kconfig option, which can have a different value in U-Boot proper and SPL.
-If this option is not set, aliases are ignored.
-
-Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the
-DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases.
-
-With those options set, devices with an alias (e.g. "serial2") will get that
-sequence number (e.g. 2). Other devices get the next available number after all
-aliases and all existing numbers. This means that if there is just a single
-alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and
-1 being unused.
-
-If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get
-sequence numbers in a simple ordering starting from 0. To find the next number
-to allocate, driver model scans through to find the maximum existing number,
-then uses the next one. It does not attempt to fill in gaps.
-
-.. code-block:: none
-
- aliases {
- serial2 = "/serial@22230000";
- };
-
-This indicates that in the uclass called "serial", the named node
-("/serial@22230000") will be given sequence number 2. Any command or driver
-which requests serial device 2 will obtain this device.
-
-More commonly you can use node references, which expand to the full path:
-
-.. code-block:: none
-
- aliases {
- serial2 = &serial_2;
- };
- ...
- serial_2: serial@22230000 {
- ...
- };
-
-The alias resolves to the same string in this case, but this version is
-easier to read.
-
-Device sequence numbers are resolved when a device is bound and the number does
-not change for the life of the device.
-
-There are some situations where the uclass must allocate sequence numbers,
-since a strictly increase sequence (with devicetree nodes bound first) is not
-suitable. An example of this is the PCI bus. In this case, you can set the
-uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an
-alias will be assigned a number by driver model. The rest is left to the uclass
-to sort out, e.g. when enumerating the bus.
-
-Note that changing the sequence number for a device (e.g. in a driver) is not
-permitted. If it is felt to be necessary, ask on the mailing list.
-
-Bus Drivers
------------
-
-A common use of driver model is to implement a bus, a device which provides
-access to other devices. Example of buses include SPI and I2C. Typically
-the bus provides some sort of transport or translation that makes it
-possible to talk to the devices on the bus.
-
-Driver model provides some useful features to help with implementing buses.
-Firstly, a bus can request that its children store some 'parent data' which
-can be used to keep track of child state. Secondly, the bus can define
-methods which are called when a child is probed or removed. This is similar
-to the methods the uclass driver provides. Thirdly, per-child platform data
-can be provided to specify things like the child's address on the bus. This
-persists across child probe()/remove() cycles.
-
-For consistency and ease of implementation, the bus uclass can specify the
-per-child platform data, so that it can be the same for all children of buses
-in that uclass. There are also uclass methods which can be called when
-children are bound and probed.
-
-Here an explanation of how a bus fits with a uclass may be useful. Consider
-a USB bus with several devices attached to it, each from a different (made
-up) uclass::
-
- xhci_usb (UCLASS_USB)
- eth (UCLASS_ETH)
- camera (UCLASS_CAMERA)
- flash (UCLASS_FLASH_STORAGE)
-
-Each of the devices is connected to a different address on the USB bus.
-The bus device wants to store this address and some other information such
-as the bus speed for each device.
-
-To achieve this, the bus device can use dev->parent_plat in each of its
-three children. This can be auto-allocated if the bus driver (or bus uclass)
-has a non-zero value for per_child_plat_auto. If not, then
-the bus device or uclass can allocate the space itself before the child
-device is probed.
-
-Also the bus driver can define the child_pre_probe() and child_post_remove()
-methods to allow it to do some processing before the child is activated or
-after it is deactivated.
-
-Similarly the bus uclass can define the child_post_bind() method to obtain
-the per-child platform data from the device tree and set it up for the child.
-The bus uclass can also provide a child_pre_probe() method. Very often it is
-the bus uclass that controls these features, since it avoids each driver
-having to do the same processing. Of course the driver can still tweak and
-override these activities.
-
-Note that the information that controls this behaviour is in the bus's
-driver, not the child's. In fact it is possible that child has no knowledge
-that it is connected to a bus. The same child device may even be used on two
-different bus types. As an example. the 'flash' device shown above may also
-be connected on a SATA bus or standalone with no bus::
-
- xhci_usb (UCLASS_USB)
- flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus
-
- sata (UCLASS_AHCI)
- flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus
-
- flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus)
-
-Above you can see that the driver for xhci_usb/sata controls the child's
-bus methods. In the third example the device is not on a bus, and therefore
-will not have these methods at all. Consider the case where the flash
-device defines child methods. These would be used for *its* children, and
-would be quite separate from the methods defined by the driver for the bus
-that the flash device is connetced to. The act of attaching a device to a
-parent device which is a bus, causes the device to start behaving like a
-bus device, regardless of its own views on the matter.
-
-The uclass for the device can also contain data private to that uclass.
-But note that each device on the bus may be a member of a different
-uclass, and this data has nothing to do with the child data for each child
-on the bus. It is the bus' uclass that controls the child with respect to
-the bus.
-
-
-Driver Lifecycle
-----------------
-
-Here are the stages that a device goes through in driver model. Note that all
-methods mentioned here are optional - e.g. if there is no probe() method for
-a device then it will not be called. A simple device may have very few
-methods actually defined.
-
-Bind stage
-^^^^^^^^^^
-
-U-Boot discovers devices using one of these two methods:
-
-- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified
- by each, to find the appropriate U_BOOT_DRIVER() definition. In this case,
- there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO()
- may provide plat.
-
-- Scan through the device tree definitions. U-Boot looks at top-level
- nodes in the the device tree. It looks at the compatible string in each node
- and uses the of_match table of the U_BOOT_DRIVER() structure to find the
- right driver for each node. In this case, the of_match table may provide a
- driver_data value, but plat cannot be provided until later.
-
-For each device that is discovered, U-Boot then calls device_bind() to create a
-new device, initializes various core fields of the device object such as name,
-uclass & driver, initializes any optional fields of the device object that are
-applicable such as of_offset, driver_data & plat, and finally calls the
-driver's bind() method if one is defined.
-
-At this point all the devices are known, and bound to their drivers. There
-is a 'struct udevice' allocated for all devices. However, nothing has been
-activated (except for the root device). Each bound device that was created
-from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified
-in that declaration. For a bound device created from the device tree,
-plat will be NULL, but of_offset will be the offset of the device tree
-node that caused the device to be created. The uclass is set correctly for
-the device.
-
-The device's sequence number is assigned, either the requested one or the next
-available one (after all aliases are processed) if nothing particular is
-requested.
-
-The device's bind() method is permitted to perform simple actions, but
-should not scan the device tree node, not initialise hardware, nor set up
-structures or allocate memory. All of these tasks should be left for
-the probe() method.
-
-Note that compared to Linux, U-Boot's driver model has a separate step of
-probe/remove which is independent of bind/unbind. This is partly because in
-U-Boot it may be expensive to probe devices and we don't want to do it until
-they are needed, or perhaps until after relocation.
-
-Reading ofdata
-^^^^^^^^^^^^^^
-
-Most devices have data in the device tree which they can read to find out the
-base address of hardware registers and parameters relating to driver
-operation. This is called 'ofdata' (Open-Firmware data).
-
-The device's of_to_plat() implemnents allocation and reading of
-plat. A parent's ofdata is always read before a child.
-
-The steps are:
-
- 1. If priv_auto is non-zero, then the device-private space
- is allocated for the device and zeroed. It will be accessible as
- dev->priv. The driver can put anything it likes in there, but should use
- it for run-time information, not platform data (which should be static
- and known before the device is probed).
-
- 2. If plat_auto is non-zero, then the platform data space
- is allocated. This is only useful for device tree operation, since
- otherwise you would have to specify the platform data in the
- U_BOOT_DRVINFO() declaration. The space is allocated for the device and
- zeroed. It will be accessible as dev->plat.
-
- 3. If the device's uclass specifies a non-zero per_device_auto,
- then this space is allocated and zeroed also. It is allocated for and
- stored in the device, but it is uclass data. owned by the uclass driver.
- It is possible for the device to access it.
-
- 4. If the device's immediate parent specifies a per_child_auto
- then this space is allocated. This is intended for use by the parent
- device to keep track of things related to the child. For example a USB
- flash stick attached to a USB host controller would likely use this
- space. The controller can hold information about the USB state of each
- of its children.
-
- 5. If the driver provides an of_to_plat() method, then this is
- called to convert the device tree data into platform data. This should
- do various calls like dev_read_u32(dev, ...) to access the node and store
- the resulting information into dev->plat. After this point, the device
- works the same way whether it was bound using a device tree node or
- U_BOOT_DRVINFO() structure. In either case, the platform data is now stored
- in the plat structure. Typically you will use the
- plat_auto feature to specify the size of the platform data
- structure, and U-Boot will automatically allocate and zero it for you before
- entry to of_to_plat(). But if not, you can allocate it yourself in
- of_to_plat(). Note that it is preferable to do all the device tree
- decoding in of_to_plat() rather than in probe(). (Apart from the
- ugliness of mixing configuration and run-time data, one day it is possible
- that U-Boot will cache platform data for devices which are regularly
- de/activated).
-
- 6. The device is marked 'plat valid'.
-
-Note that ofdata reading is always done (for a child and all its parents)
-before probing starts. Thus devices go through two distinct states when
-probing: reading platform data and actually touching the hardware to bring
-the device up.
-
-Having probing separate from ofdata-reading helps deal with of-platdata, where
-the probe() method is common to both DT/of-platdata operation, but the
-of_to_plat() method is implemented differently.
-
-Another case has come up where this separate is useful. Generation of ACPI
-tables uses the of-platdata but does not want to probe the device. Probing
-would cause U-Boot to violate one of its design principles, viz that it
-should only probe devices that are used. For ACPI we want to generate a
-table for each device, even if U-Boot does not use it. In fact it may not
-even be possible to probe the device - e.g. an SD card which is not
-present will cause an error on probe, yet we still must tell Linux about
-the SD card connector in case it is used while Linux is running.
-
-It is important that the of_to_plat() method does not actually probe
-the device itself. However there are cases where other devices must be probed
-in the of_to_plat() method. An example is where a device requires a
-GPIO for it to operate. To select a GPIO obviously requires that the GPIO
-device is probed. This is OK when used by common, core devices such as GPIO,
-clock, interrupts, reset and the like.
-
-If your device relies on its parent setting up a suitable address space, so
-that dev_read_addr() works correctly, then make sure that the parent device
-has its setup code in of_to_plat(). If it has it in the probe method,
-then you cannot call dev_read_addr() from the child device's
-of_to_plat() method. Move it to probe() instead. Buses like PCI can
-fall afoul of this rule.
-
-Activation/probe
-^^^^^^^^^^^^^^^^
-
-When a device needs to be used, U-Boot activates it, by first reading ofdata
-as above and then following these steps (see device_probe()):
-
- 1. All parent devices are probed. It is not possible to activate a device
- unless its predecessors (all the way up to the root device) are activated.
- This means (for example) that an I2C driver will require that its bus
- be activated.
-
- 2. The device's probe() method is called. This should do anything that
- is required by the device to get it going. This could include checking
- that the hardware is actually present, setting up clocks for the
- hardware and setting up hardware registers to initial values. The code
- in probe() can access:
-
- - platform data in dev->plat (for configuration)
- - private data in dev->priv (for run-time state)
- - uclass data in dev->uclass_priv (for things the uclass stores
- about this device)
-
- Note: If you don't use priv_auto then you will need to
- allocate the priv space here yourself. The same applies also to
- plat_auto. Remember to free them in the remove() method.
-
- 3. The device is marked 'activated'
-
- 4. The uclass's post_probe() method is called, if one exists. This may
- cause the uclass to do some housekeeping to record the device as
- activated and 'known' by the uclass.
-
-Running stage
-^^^^^^^^^^^^^
-
-The device is now activated and can be used. From now until it is removed
-all of the above structures are accessible. The device appears in the
-uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
-as a device in the GPIO uclass). This is the 'running' state of the device.
-
-Removal stage
-^^^^^^^^^^^^^
-
-When the device is no-longer required, you can call device_remove() to
-remove it. This performs the probe steps in reverse:
-
- 1. The uclass's pre_remove() method is called, if one exists. This may
- cause the uclass to do some housekeeping to record the device as
- deactivated and no-longer 'known' by the uclass.
-
- 2. All the device's children are removed. It is not permitted to have
- an active child device with a non-active parent. This means that
- device_remove() is called for all the children recursively at this point.
-
- 3. The device's remove() method is called. At this stage nothing has been
- deallocated so platform data, private data and the uclass data will all
- still be present. This is where the hardware can be shut down. It is
- intended that the device be completely inactive at this point, For U-Boot
- to be sure that no hardware is running, it should be enough to remove
- all devices.
-
- 4. The device memory is freed (platform data, private data, uclass data,
- parent data).
-
- Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a
- static pointer, it is not de-allocated during the remove() method. For
- a device instantiated using the device tree data, the platform data will
- be dynamically allocated, and thus needs to be deallocated during the
- remove() method, either:
-
- - if the plat_auto is non-zero, the deallocation happens automatically
- within the driver model core in the unbind stage; or
-
- - when plat_auto is 0, both the allocation (in probe()
- or preferably of_to_plat()) and the deallocation in remove()
- are the responsibility of the driver author.
-
- 5. The device is marked inactive. Note that it is still bound, so the
- device structure itself is not freed at this point. Should the device be
- activated again, then the cycle starts again at step 2 above.
-
-Unbind stage
-^^^^^^^^^^^^
-
-The device is unbound. This is the step that actually destroys the device.
-If a parent has children these will be destroyed first. After this point
-the device does not exist and its memory has be deallocated.
-
-
-Special cases for removal
--------------------------
-
-Some devices need to do clean-up before the OS is called. For example, a USB
-driver may want to stop the bus. This can be done in the remove() method.
-Some special flags are used to determine whether to remove the device:
-
- DM_FLAG_OS_PREPARE - indicates that the device needs to get ready for OS
- boot. The device will be removed just before the OS is booted
- DM_REMOVE_ACTIVE_DMA - indicates that the device uses DMA. This is
- effectively the same as DM_FLAG_OS_PREPARE, so the device is removed
- before the OS is booted
- DM_FLAG_VITAL - indicates that the device is 'vital' to the operation of
- other devices. It is possible to remove this device after all regular
- devices are removed. This is useful e.g. for a clock, which need to
- be active during the device-removal phase.
-
-The dm_remove_devices_flags() function can be used to remove devices based on
-their driver flags.
-
-Data Structures
----------------
-
-Driver model uses a doubly-linked list as the basic data structure. Some
-nodes have several lists running through them. Creating a more efficient
-data structure might be worthwhile in some rare cases, once we understand
-what the bottlenecks are.
-
-
-Changes since v1
-----------------
-
-For the record, this implementation uses a very similar approach to the
-original patches, but makes at least the following changes:
-
-- Tried to aggressively remove boilerplate, so that for most drivers there
- is little or no 'driver model' code to write.
-- Moved some data from code into data structure - e.g. store a pointer to
- the driver operations structure in the driver, rather than passing it
- to the driver bind function.
-- Rename some structures to make them more similar to Linux (struct udevice
- instead of struct instance, struct plat, etc.)
-- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
- this concept relates to a class of drivers (or a subsystem). We shouldn't
- use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
- better than 'core'.
-- Remove 'struct driver_instance' and just use a single 'struct udevice'.
- This removes a level of indirection that doesn't seem necessary.
-- Built in device tree support, to avoid the need for plat
-- Removed the concept of driver relocation, and just make it possible for
- the new driver (created after relocation) to access the old driver data.
- I feel that relocation is a very special case and will only apply to a few
- drivers, many of which can/will just re-init anyway. So the overhead of
- dealing with this might not be worth it.
-- Implemented a GPIO system, trying to keep it simple
-
-
-Pre-Relocation Support
-----------------------
-
-For pre-relocation we simply call the driver model init function. Only
-drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
-property are initialised prior to relocation. This helps to reduce the driver
-model overhead. This flag applies to SPL and TPL as well, if device tree is
-enabled (CONFIG_OF_CONTROL) there.
-
-Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
-property can provide better control granularity on which device is bound
-before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all
-devices with the same driver are bound, which requires allocation a large
-amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the
-only way for statically declared devices via U_BOOT_DRVINFO() to be bound
-prior to relocation.
-
-It is possible to limit this to specific relocation steps, by using
-the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
-in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
-which means that it will be processed (and a driver bound) in U-Boot proper
-prior to relocation, but will not be available in SPL or TPL.
-
-To reduce the size of SPL and TPL, only the nodes with pre-relocation properties
-('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their
-device trees (see README.SPL for details); the remaining nodes are always bound.
-
-Then post relocation we throw that away and re-init driver model again.
-For drivers which require some sort of continuity between pre- and
-post-relocation devices, we can provide access to the pre-relocation
-device pointers, but this is not currently implemented (the root device
-pointer is saved but not made available through the driver model API).
-
-
-SPL Support
------------
-
-Driver model can operate in SPL. Its efficient implementation and small code
-size provide for a small overhead which is acceptable for all but the most
-constrained systems.
-
-To enable driver model in SPL, define CONFIG_SPL_DM. You might want to
-consider the following option also. See the main README for more details.
-
- - CONFIG_SYS_MALLOC_SIMPLE
- - CONFIG_DM_WARN
- - CONFIG_DM_DEVICE_REMOVE
- - CONFIG_DM_STDIO
-
-
-Enabling Driver Model
----------------------
-
-Driver model is being brought into U-Boot gradually. As each subsystems gets
-support, a uclass is created and a CONFIG to enable use of driver model for
-that subsystem.
-
-For example CONFIG_DM_SERIAL enables driver model for serial. With that
-defined, the old serial support is not enabled, and your serial driver must
-conform to driver model. With that undefined, the old serial support is
-enabled and driver model is not available for serial. This means that when
-you convert a driver, you must either convert all its boards, or provide for
-the driver to be compiled both with and without driver model (generally this
-is not very hard).
-
-See the main README for full details of the available driver model CONFIG
-options.
-
-
-Things to punt for later
-------------------------
-
-Uclasses are statically numbered at compile time. It would be possible to
-change this to dynamic numbering, but then we would require some sort of
-lookup service, perhaps searching by name. This is slightly less efficient
-so has been left out for now. One small advantage of dynamic numbering might
-be fewer merge conflicts in uclass-id.h.
+++ /dev/null
-Ethernet Driver Guide
-=======================
-
-The networking stack in Das U-Boot is designed for multiple network devices
-to be easily added and controlled at runtime. This guide is meant for people
-who wish to review the net driver stack with an eye towards implementing your
-own ethernet device driver. Here we will describe a new pseudo 'APE' driver.
-
-Most existing drivers do already - and new network driver MUST - use the
-U-Boot core driver model. Generic information about this can be found in
-doc/driver-model/design.rst, this document will thus focus on the network
-specific code parts.
-Some drivers are still using the old Ethernet interface, differences between
-the two and hints about porting will be handled at the end.
-
-Driver framework
-------------------
-
-A network driver following the driver model must declare itself using
-the UCLASS_ETH .id field in the U-Boot driver struct:
-
-.. code-block:: c
-
- U_BOOT_DRIVER(eth_ape) = {
- .name = "eth_ape",
- .id = UCLASS_ETH,
- .of_match = eth_ape_ids,
- .of_to_plat = eth_ape_of_to_plat,
- .probe = eth_ape_probe,
- .ops = ð_ape_ops,
- .priv_auto = sizeof(struct eth_ape_priv),
- .plat_auto = sizeof(struct eth_ape_pdata),
- .flags = DM_FLAG_ALLOC_PRIV_DMA,
- };
-
-struct eth_ape_priv contains runtime per-instance data, like buffers, pointers
-to current descriptors, current speed settings, pointers to PHY related data
-(like struct mii_dev) and so on. Declaring its size in .priv_auto
-will let the driver framework allocate it at the right time.
-It can be retrieved using a dev_get_priv(dev) call.
-
-struct eth_ape_pdata contains static platform data, like the MMIO base address,
-a hardware variant, the MAC address. ``struct eth_pdata eth_pdata``
-as the first member of this struct helps to avoid duplicated code.
-If you don't need any more platform data beside the standard member,
-just use sizeof(struct eth_pdata) for the plat_auto.
-
-PCI devices add a line pointing to supported vendor/device ID pairs:
-
-.. code-block:: c
-
- static struct pci_device_id supported[] = {
- { PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) },
- {}
- };
-
- U_BOOT_PCI_DEVICE(eth_ape, supported);
-
-It is also possible to declare support for a whole class of PCI devices::
-
- { PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) },
-
-Device probing and instantiation will be handled by the driver model framework,
-so follow the guidelines there. The probe() function would initialise the
-platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO
-bus. Also it would take care of any special PHY setup (power rails, enable
-bits for internal PHYs, etc.).
-
-Driver methods
-----------------
-
-The real work will be done in the driver method functions the driver provides
-by defining the members of struct eth_ops:
-
-.. code-block:: c
-
- struct eth_ops {
- int (*start)(struct udevice *dev);
- int (*send)(struct udevice *dev, void *packet, int length);
- int (*recv)(struct udevice *dev, int flags, uchar **packetp);
- int (*free_pkt)(struct udevice *dev, uchar *packet, int length);
- void (*stop)(struct udevice *dev);
- int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join);
- int (*write_hwaddr)(struct udevice *dev);
- int (*read_rom_hwaddr)(struct udevice *dev);
- };
-
-An up-to-date version of this struct together with more information can be
-found in include/net.h.
-
-Only start, stop, send and recv are required, the rest are optional and are
-handled by generic code or ignored if not provided.
-
-The **start** function initialises the hardware and gets it ready for send/recv
-operations. You often do things here such as resetting the MAC
-and/or PHY, and waiting for the link to autonegotiate. You should also take
-the opportunity to program the device's MAC address with the enetaddr member
-of the generic struct eth_pdata (which would be the first member of your
-own plat struct). This allows the rest of U-Boot to dynamically change
-the MAC address and have the new settings be respected.
-
-The **send** function does what you think -- transmit the specified packet
-whose size is specified by length (in bytes). The packet buffer can (and
-will!) be reused for subsequent calls to send(), so it must be no longer
-used when the send() function returns. The easiest way to achieve this is
-to wait until the transmission is complete. Alternatively, if supported by
-the hardware, just waiting for the buffer to be consumed (by some DMA engine)
-might be an option as well.
-Another way of consuming the buffer could be to copy the data to be send,
-then just queue the copied packet (for instance handing it over to a DMA
-engine), and return immediately afterwards.
-In any case you should leave the state such that the send function can be
-called multiple times in a row.
-
-The **recv** function polls for availability of a new packet. If none is
-available, it must return with -EAGAIN.
-If a packet has been received, make sure it is accessible to the CPU
-(invalidate caches if needed), then write its address to the packetp pointer,
-and return the length. If there is an error (receive error, too short or too
-long packet), return 0 if you require the packet to be cleaned up normally,
-or a negative error code otherwise (cleanup not necessary or already done).
-The U-Boot network stack will then process the packet.
-
-If **free_pkt** is defined, U-Boot will call it after a received packet has
-been processed, so the packet buffer can be freed or recycled. Typically you
-would hand it back to the hardware to acquire another packet. free_pkt() will
-be called after recv(), for the same packet, so you don't necessarily need
-to infer the buffer to free from the ``packet`` pointer, but can rely on that
-being the last packet that recv() handled.
-The common code sets up packet buffers for you already in the .bss
-(net_rx_packets), so there should be no need to allocate your own. This doesn't
-mean you must use the net_rx_packets array however; you're free to use any
-buffer you wish.
-
-The **stop** function should turn off / disable the hardware and place it back
-in its reset state. It can be called at any time (before any call to the
-related start() function), so make sure it can handle this sort of thing.
-
-The (optional) **write_hwaddr** function should program the MAC address stored
-in pdata->enetaddr into the Ethernet controller.
-
-So the call graph at this stage would look something like:
-
-.. code-block:: c
-
- (some net operation (ping / tftp / whatever...))
- eth_init()
- ops->start()
- eth_send()
- ops->send()
- eth_rx()
- ops->recv()
- (process packet)
- if (ops->free_pkt)
- ops->free_pkt()
- eth_halt()
- ops->stop()
-
-
-CONFIG_PHYLIB / CONFIG_CMD_MII
---------------------------------
-
-If your device supports banging arbitrary values on the MII bus (pretty much
-every device does), you should add support for the mii command. Doing so is
-fairly trivial and makes debugging mii issues a lot easier at runtime.
-
-In your driver's ``probe()`` function, add a call to mdio_alloc() and
-mdio_register() like so:
-
-.. code-block:: c
-
- bus = mdio_alloc();
- if (!bus) {
- ...
- return -ENOMEM;
- }
-
- bus->read = ape_mii_read;
- bus->write = ape_mii_write;
- mdio_register(bus);
-
-And then define the mii_read and mii_write functions if you haven't already.
-Their syntax is straightforward::
-
- int mii_read(struct mii_dev *bus, int addr, int devad, int reg);
- int mii_write(struct mii_dev *bus, int addr, int devad, int reg,
- u16 val);
-
-The read function should read the register 'reg' from the phy at address 'addr'
-and return the result to its caller. The implementation for the write function
-should logically follow.
-
-................................................................
-
-Legacy network drivers
-------------------------
-
-!!! WARNING !!!
-
-This section below describes the old way of doing things. No new Ethernet
-drivers should be implemented this way. All new drivers should be written
-against the U-Boot core driver model, as described above.
-
-The actual callback functions are fairly similar, the differences are:
-
-- ``start()`` is called ``init()``
-- ``stop()`` is called ``halt()``
-- The ``recv()`` function must loop until all packets have been received, for
- each packet it must call the net_process_received_packet() function,
- handing it over the pointer and the length. Afterwards it should free
- the packet, before checking for new data.
-
-For porting an old driver to the new driver model, split the existing recv()
-function into the actual new recv() function, just fetching **one** packet,
-remove the call to net_process_received_packet(), then move the packet
-cleanup into the ``free_pkt()`` function.
-
-Registering the driver and probing a device is handled very differently,
-follow the recommendations in the driver model design documentation for
-instructions on how to port this over. For the records, the old way of
-initialising a network driver is as follows:
-
-Old network driver registration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When U-Boot initializes, it will call the common function eth_initialize().
-This will in turn call the board-specific board_eth_init() (or if that fails,
-the cpu-specific cpu_eth_init()). These board-specific functions can do random
-system handling, but ultimately they will call the driver-specific register
-function which in turn takes care of initializing that particular instance.
-
-Keep in mind that you should code the driver to avoid storing state in global
-data as someone might want to hook up two of the same devices to one board.
-Any such information that is specific to an interface should be stored in a
-private, driver-defined data structure and pointed to by eth->priv (see below).
-
-So the call graph at this stage would look something like:
-
-.. code-block:: c
-
- board_init()
- eth_initialize()
- board_eth_init() / cpu_eth_init()
- driver_register()
- initialize eth_device
- eth_register()
-
-At this point in time, the only thing you need to worry about is the driver's
-register function. The pseudo code would look something like:
-
-.. code-block:: c
-
- int ape_register(struct bd_info *bis, int iobase)
- {
- struct ape_priv *priv;
- struct eth_device *dev;
- struct mii_dev *bus;
-
- priv = malloc(sizeof(*priv));
- if (priv == NULL)
- return -ENOMEM;
-
- dev = malloc(sizeof(*dev));
- if (dev == NULL) {
- free(priv);
- return -ENOMEM;
- }
-
- /* setup whatever private state you need */
-
- memset(dev, 0, sizeof(*dev));
- sprintf(dev->name, "APE");
-
- /*
- * if your device has dedicated hardware storage for the
- * MAC, read it and initialize dev->enetaddr with it
- */
- ape_mac_read(dev->enetaddr);
-
- dev->iobase = iobase;
- dev->priv = priv;
- dev->init = ape_init;
- dev->halt = ape_halt;
- dev->send = ape_send;
- dev->recv = ape_recv;
- dev->write_hwaddr = ape_write_hwaddr;
-
- eth_register(dev);
-
- #ifdef CONFIG_PHYLIB
- bus = mdio_alloc();
- if (!bus) {
- free(priv);
- free(dev);
- return -ENOMEM;
- }
-
- bus->read = ape_mii_read;
- bus->write = ape_mii_write;
- mdio_register(bus);
- #endif
-
- return 1;
- }
-
-The exact arguments needed to initialize your device are up to you. If you
-need to pass more/less arguments, that's fine. You should also add the
-prototype for your new register function to include/netdev.h.
-
-The return value for this function should be as follows:
-< 0 - failure (hardware failure, not probe failure)
->=0 - number of interfaces detected
-
-You might notice that many drivers seem to use xxx_initialize() rather than
-xxx_register(). This is the old naming convention and should be avoided as it
-causes confusion with the driver-specific init function.
-
-Other than locating the MAC address in dedicated hardware storage, you should
-not touch the hardware in anyway. That step is handled in the driver-specific
-init function. Remember that we are only registering the device here, we are
-not checking its state or doing random probing.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Pre-relocation device tree manipulation
-=======================================
-
-Purpose
--------
-
-In certain markets, it is beneficial for manufacturers of embedded devices to
-offer certain ranges of products, where the functionality of the devices within
-one series either don't differ greatly from another, or can be thought of as
-"extensions" of each other, where one device only differs from another in the
-addition of a small number of features (e.g. an additional output connector).
-
-To realize this in hardware, one method is to have a motherboard, and several
-possible daughter boards that can be attached to this mother board. Different
-daughter boards then either offer the slightly different functionality, or the
-addition of the daughter board to the device realizes the "extension" of
-functionality to the device described previously.
-
-For the software, we obviously want to reuse components for all these
-variations of the device. This means that the software somehow needs to cope
-with the situation that certain ICs may or may not be present on any given
-system, depending on which daughter boards are connected to the motherboard.
-
-In the Linux kernel, one possible solution to this problem is to employ the
-device tree overlay mechanism: There exists one "base" device tree, which
-features only the components guaranteed to exist in all varieties of the
-device. At the start of the kernel, the presence and type of the daughter
-boards is then detected, and the corresponding device tree overlays are applied
-to support the components on the daughter boards.
-
-Note that the components present on every variety of the board must, of course,
-provide a way to find out if and which daughter boards are installed for this
-mechanism to work.
-
-In the U-Boot boot loader, support for device tree overlays has recently been
-integrated, and is used on some boards to alter the device tree that is later
-passed to Linux. But since U-Boot's driver model, which is device tree-based as
-well, is being used in more and more drivers, the same problem of altering the
-device tree starts cropping up in U-Boot itself as well.
-
-An additional problem with the device tree in U-Boot is that it is read-only,
-and the current mechanisms don't allow easy manipulation of the device tree
-after the driver model has been initialized. While migrating to a live device
-tree (at least after the relocation) would greatly simplify the solution of
-this problem, it is a non-negligible task to implement it, an a interim
-solution is needed to address the problem at least in the medium-term.
-
-Hence, we propose a solution to this problem by offering a board-specific
-call-back function, which is passed a writeable pointer to the device tree.
-This function is called before the device tree is relocated, and specifically
-before the main U-Boot's driver model is instantiated, hence the main U-Boot
-"sees" all modifications to the device tree made in this function. Furthermore,
-we have the pre-relocation driver model at our disposal at this stage, which
-means that we can query the hardware for the existence and variety of the
-components easily.
-
-Implementation
---------------
-
-To take advantage of the pre-relocation device tree manipulation mechanism,
-boards have to implement the function board_fix_fdt, which has the following
-signature:
-
-.. code-block:: c
-
- int board_fix_fdt (void *rw_fdt_blob)
-
-The passed-in void pointer is a writeable pointer to the device tree, which can
-be used to manipulate the device tree using e.g. functions from
-include/fdt_support.h. The return value should either be 0 in case of
-successful execution of the device tree manipulation or something else for a
-failure. Note that returning a non-null value from the function will
-unrecoverably halt the boot process, as with any function from init_sequence_f
-(in common/board_f.c).
-
-Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function
-to be called::
-
- Device Tree Control
- -> [*] Board-specific manipulation of Device Tree
-
-+----------------------------------------------------------+
-| WARNING: The actual manipulation of the device tree has |
-| to be the _last_ set of operations in board_fix_fdt! |
-| Since the pre-relocation driver model does not adapt to |
-| changes made to the device tree either, its references |
-| into the device tree will be invalid after manipulating |
-| it, and unpredictable behavior might occur when |
-| functions that rely on them are executed! |
-+----------------------------------------------------------+
-
-Hence, the recommended layout of the board_fixup_fdt call-back function is the
-following:
-
-.. code-block:: c
-
- int board_fix_fdt(void *rw_fdt_blob)
- {
- /*
- * Collect information about device's hardware and store
- * them in e.g. local variables
- */
-
- /* Do device tree manipulation using the values previously collected */
-
- /* Return 0 on successful manipulation and non-zero otherwise */
- }
-
-If this convention is kept, both an "additive" approach, meaning that nodes for
-detected components are added to the device tree, as well as a "subtractive"
-approach, meaning that nodes for absent components are removed from the tree,
-as well as a combination of both approaches should work.
-
-Example
--------
-
-The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a
-board_fix_fdt function, in which six GPIO expanders (which might be present or
-not, since they are on daughter boards) on a I2C bus are queried for, and
-subsequently deactivated in the device tree if they are not present.
-
-Note that the dm_i2c_simple_probe function does not use the device tree, hence
-it is safe to call it after the tree has already been manipulated.
-
-Work to be done
----------------
-
-* The application of device tree overlay should be possible in board_fixup_fdt,
- but has not been tested at this stage.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-.. Copyright (C) 2018-2019 Intel Corporation <www.intel.com>
-
-File System Firmware Loader
-===========================
-
-This is file system firmware loader for U-Boot framework, which has very close
-to some Linux Firmware API. For the details of Linux Firmware API, you can refer
-to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
-
-File system firmware loader can be used to load whatever(firmware, image,
-and binary) from the storage device in file system format into target location
-such as memory, then consumer driver such as FPGA driver can program FPGA image
-from the target location into FPGA.
-
-To enable firmware loader, CONFIG_FS_LOADER need to be set at
-<board_name>_defconfig such as "CONFIG_FS_LOADER=y".
-
-Firmware Loader API core features
----------------------------------
-
-Firmware storage device described in device tree source
--------------------------------------------------------
-For passing data like storage device phandle and partition where the
-firmware loading from to the firmware loader driver, those data could be
-defined in fs-loader node as shown in below:
-
-Example for block device::
-
- fs_loader0: fs-loader {
- u-boot,dm-pre-reloc;
- compatible = "u-boot,fs-loader";
- phandlepart = <&mmc 1>;
- };
-
-<&mmc 1> means block storage device pointer and its partition.
-
-Above example is a description for block storage, but for UBI storage
-device, it can be described in FDT as shown in below:
-
-Example for ubi::
-
- fs_loader1: fs-loader {
- u-boot,dm-pre-reloc;
- compatible = "u-boot,fs-loader";
- mtdpart = "UBI",
- ubivol = "ubi0";
- };
-
-Then, firmware-loader property can be added with any device node, which
-driver would use the firmware loader for loading.
-
-The value of the firmware-loader property should be set with phandle
-of the fs-loader node. For example::
-
- firmware-loader = <&fs_loader0>;
-
-If there are majority of devices using the same fs-loader node, then
-firmware-loader property can be added under /chosen node instead of
-adding to each of device node.
-
-For example::
-
- /{
- chosen {
- firmware-loader = <&fs_loader0>;
- };
- };
-
-In each respective driver of devices using firmware loader, the firmware
-loaded instance should be created by DT phandle.
-
-For example of getting DT phandle from /chosen and creating instance:
-
-.. code-block:: c
-
- chosen_node = ofnode_path("/chosen");
- if (!ofnode_valid(chosen_node)) {
- debug("/chosen node was not found.\n");
- return -ENOENT;
- }
-
- phandle_p = ofnode_get_property(chosen_node, "firmware-loader", &size);
- if (!phandle_p) {
- debug("firmware-loader property was not found.\n");
- return -ENOENT;
- }
-
- phandle = fdt32_to_cpu(*phandle_p);
- ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
- phandle, &dev);
- if (ret)
- return ret;
-
-Firmware loader driver is also designed to support U-boot environment
-variables, so all these data from FDT can be overwritten
-through the U-boot environment variable during run time.
-
-For examples:
-
-storage_interface:
- Storage interface, it can be "mmc", "usb", "sata" or "ubi".
-fw_dev_part:
- Block device number and its partition, it can be "0:1".
-fw_ubi_mtdpart:
- UBI device mtd partition, it can be "UBI".
-fw_ubi_volume:
- UBI volume, it can be "ubi0".
-
-When above environment variables are set, environment values would be
-used instead of data from FDT.
-The benefit of this design allows user to change storage attribute data
-at run time through U-boot console and saving the setting as default
-environment values in the storage for the next power cycle, so no
-compilation is required for both driver and FDT.
-
-File system firmware Loader API
--------------------------------
-
-.. code-block:: c
-
- int request_firmware_into_buf(struct udevice *dev,
- const char *name,
- void *buf, size_t size, u32 offset)
-
-Load firmware into a previously allocated buffer
-
-Parameters:
-
-* struct udevice \*dev: An instance of a driver
-* const char \*name: name of firmware file
-* void \*buf: address of buffer to load firmware into
-* size_t size: size of buffer
-* u32 offset: offset of a file for start reading into buffer
-
-Returns:
- size of total read
- -ve when error
-
-Description:
- The firmware is loaded directly into the buffer pointed to by buf
-
-Example of calling request_firmware_into_buf API after creating firmware loader
-instance:
-
-.. code-block:: c
-
- ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
- phandle, &dev);
- if (ret)
- return ret;
-
- request_firmware_into_buf(dev, filename, buffer_location, buffer_size,
- offset_ofreading);
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-How to port an I2C driver to driver model
-=========================================
-
-Over half of the I2C drivers have been converted as at November 2016. These
-ones remain:
-
- * adi_i2c
- * davinci_i2c
- * fti2c010
- * ihs_i2c
- * kona_i2c
- * lpc32xx_i2c
- * pca9564_i2c
- * ppc4xx_i2c
- * rcar_i2c
- * sh_i2c
- * soft_i2c
- * zynq_i2c
-
-The deadline for this work is the end of June 2017. If no one steps
-forward to convert these, at some point there may come a patch to remove them!
-
-Here is a suggested approach for converting your I2C driver over to driver
-model. Please feel free to update this file with your ideas and suggestions.
-
-- #ifdef out all your own I2C driver code (#if !CONFIG_IS_ENABLED(DM_I2C))
-- Define CONFIG_DM_I2C for your board, vendor or architecture
-- If the board does not already use driver model, you need CONFIG_DM also
-- Your board should then build, but will not work fully since there will be
- no I2C driver
-- Add the U_BOOT_DRIVER piece at the end (e.g. copy tegra_i2c.c for example)
-- Add a private struct for the driver data - avoid using static variables
-- Implement each of the driver methods, perhaps by calling your old methods
-- You may need to adjust the function parameters so that the old and new
- implementations can share most of the existing code
-- If you convert all existing users of the driver, remove the pre-driver-model
- code
-
-In terms of patches a conversion series typically has these patches:
-- clean up / prepare the driver for conversion
-- add driver model code
-- convert at least one existing board to use driver model serial
-- (if no boards remain that don't use driver model) remove the old code
-
-This may be a good time to move your board to use device tree also. Mostly
-this involves these steps:
-
-- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE
-- add your device tree files to arch/<arch>/dts
-- update the Makefile there
-- Add stdout-path to your /chosen device tree node if it is not already there
-- build and get u-boot-dtb.bin so you can test it
-- Your drivers can now use device tree
-- For device tree in SPL, define CONFIG_SPL_OF_CONTROL
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Driver Model
-============
-
-.. toctree::
- :maxdepth: 2
-
- bind
- debugging
- design
- ethernet
- fdt-fixup
- fs_firmware_loader
- i2c-howto
- livetree
- migration
- of-plat
- pci-info
- pmic-framework
- remoteproc-framework
- serial-howto
- soc-framework
- spi-howto
- usb-info
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Live Device Tree
-================
-
-
-Introduction
-------------
-
-Traditionally U-Boot has used a 'flat' device tree. This means that it
-reads directly from the device tree binary structure. It is called a flat
-device tree because nodes are listed one after the other, with the
-hierarchy detected by tags in the format.
-
-This document describes U-Boot's support for a 'live' device tree, meaning
-that the tree is loaded into a hierarchical data structure within U-Boot.
-
-
-Motivation
-----------
-
-The flat device tree has several advantages:
-
-- it is the format produced by the device tree compiler, so no translation
- is needed
-
-- it is fairly compact (e.g. there is no need for pointers)
-
-- it is accessed by the libfdt library, which is well tested and stable
-
-
-However the flat device tree does have some limitations. Adding new
-properties can involve copying large amounts of data around to make room.
-The overall tree has a fixed maximum size so sometimes the tree must be
-rebuilt in a new location to create more space. Even if not adding new
-properties or nodes, scanning the tree can be slow. For example, finding
-the parent of a node is a slow process. Reading from nodes involves a
-small amount parsing which takes a little time.
-
-Driver model scans the entire device tree sequentially on start-up which
-avoids the worst of the flat tree's limitations. But if the tree is to be
-modified at run-time, a live tree is much faster. Even if no modification
-is necessary, parsing the tree once and using a live tree from then on
-seems to save a little time.
-
-
-Implementation
---------------
-
-In U-Boot a live device tree ('livetree') is currently supported only
-after relocation. Therefore we need a mechanism to specify a device
-tree node regardless of whether it is in the flat tree or livetree.
-
-The 'ofnode' type provides this. An ofnode can point to either a flat tree
-node (when the live tree node is not yet set up) or a livetree node. The
-caller of an ofnode function does not need to worry about these details.
-
-The main users of the information in a device tree are drivers. These have
-a 'struct udevice \*' which is attached to a device tree node. Therefore it
-makes sense to be able to read device tree properties using the
-'struct udevice \*', rather than having to obtain the ofnode first.
-
-The 'dev_read\_...()' interface provides this. It allows properties to be
-easily read from the device tree using only a device pointer. Under the
-hood it uses ofnode so it works with both flat and live device trees.
-
-
-Enabling livetree
------------------
-
-CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat
-tree will be used in SPL and before relocation in U-Boot proper. Just
-before relocation a livetree is built, and this is used for U-Boot proper
-after relocation.
-
-Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that
-for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does
-not exist, since SPL does not support livetree.
-
-
-Porting drivers
----------------
-
-Many existing drivers use the fdtdec interface to read device tree
-properties. This only works with a flat device tree. The drivers should be
-converted to use the dev_read_() interface.
-
-For example, the old code may be like this:
-
-.. code-block:: c
-
- struct udevice *bus;
- const void *blob = gd->fdt_blob;
- int node = dev_of_offset(bus);
-
- i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);
- plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
-
-The new code is:
-
-.. code-block:: c
-
- struct udevice *bus;
-
- i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
- plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
-
-The dev_read\_...() interface is more convenient and works with both the
-flat and live device trees. See include/dm/read.h for a list of functions.
-
-Where properties must be read from sub-nodes or other nodes, you must fall
-back to using ofnode. For example, for old code like this:
-
-.. code-block:: c
-
- const void *blob = gd->fdt_blob;
- int subnode;
-
- fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) {
- freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
- ...
- }
-
-you should use:
-
-.. code-block:: c
-
- ofnode subnode;
-
- ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
- freq = ofnode_read_u32(node, "spi-max-frequency", 500000);
- ...
- }
-
-
-Useful ofnode functions
------------------------
-
-The internal data structures of the livetree are defined in include/dm/of.h :
-
- :struct device_node: holds information about a device tree node
- :struct property: holds information about a property within a node
-
-Nodes have pointers to their first property, their parent, their first child
-and their sibling. This allows nodes to be linked together in a hierarchical
-tree.
-
-Properties have pointers to the next property. This allows all properties of
-a node to be linked together in a chain.
-
-It should not be necessary to use these data structures in normal code. In
-particular, you should refrain from using functions which access the livetree
-directly, such as of_read_u32(). Use ofnode functions instead, to allow your
-code to work with a flat tree also.
-
-Some conversion functions are used internally. Generally these are not needed
-for driver code. Note that they will not work if called in the wrong context.
-For example it is invalid to call ofnode_to_no() when a flat tree is being
-used. Similarly it is not possible to call ofnode_to_offset() on a livetree
-node.
-
-ofnode_to_np():
- converts ofnode to struct device_node *
-ofnode_to_offset():
- converts ofnode to offset
-
-no_to_ofnode():
- converts node pointer to ofnode
-offset_to_ofnode():
- converts offset to ofnode
-
-
-Other useful functions:
-
-of_live_active():
- returns true if livetree is in use, false if flat tree
-ofnode_valid():
- return true if a given node is valid
-ofnode_is_np():
- returns true if a given node is a livetree node
-ofnode_equal():
- compares two ofnodes
-ofnode_null():
- returns a null ofnode (for which ofnode_valid() returns false)
-
-
-Phandles
---------
-
-There is full phandle support for live tree. All functions make use of
-struct ofnode_phandle_args, which has an ofnode within it. This supports both
-livetree and flat tree transparently. See for example
-ofnode_parse_phandle_with_args().
-
-
-Reading addresses
------------------
-
-You should use dev_read_addr() and friends to read addresses from device-tree
-nodes.
-
-
-fdtdec
-------
-
-The existing fdtdec interface will eventually be retired. Please try to avoid
-using it in new code.
-
-
-Modifying the livetree
-----------------------
-
-This is not currently supported. Once implemented it should provide a much
-more efficient implementation for modification of the device tree than using
-the flat tree.
-
-
-Internal implementation
------------------------
-
-The dev_read\_...() functions have two implementations. When
-CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
-functions directly. This is useful when livetree is not enabled. The ofnode
-functions call ofnode_is_np(node) which will always return false if livetree
-is disabled, just falling back to flat tree code.
-
-This optimisation means that without livetree enabled, the dev_read\_...() and
-ofnode interfaces do not noticeably add to code size.
-
-The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
-disabled.
-
-Most livetree code comes directly from Linux and is modified as little as
-possible. This is deliberate since this code is fairly stable and does what
-we want. Some features (such as get/put) are not supported. Internal macros
-take care of removing these features silently.
-
-Within the of_access.c file there are pointers to the alias node, the chosen
-node and the stdout-path alias.
-
-
-Errors
-------
-
-With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
-For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
-the ofnode and dev_read\_...() functions return either one or other type of
-error. This is clearly not desirable. Once tests are added for all the
-functions this can be tidied up.
-
-
-Adding new access functions
----------------------------
-
-Adding a new function for device-tree access involves the following steps:
-
- - Add two dev_read() functions:
- - inline version in the read.h header file, which calls an ofnode function
- - standard version in the read.c file (or perhaps another file), which
- also calls an ofnode function
-
- The implementations of these functions can be the same. The purpose
- of the inline version is purely to reduce code size impact.
-
- - Add an ofnode function. This should call ofnode_is_np() to work out
- whether a livetree or flat tree is used. For the livetree it should
- call an of\_...() function. For the flat tree it should call an
- fdt\_...() function. The livetree version will be optimised out at
- compile time if livetree is not enabled.
-
- - Add an of\_...() function for the livetree implementation. If a similar
- function is available in Linux, the implementation should be taken
- from there and modified as little as possible (generally not at all).
-
-
-Future work
------------
-
-Live tree support was introduced in U-Boot 2017.07. There is still quite a bit
-of work to do to flesh this out:
-
-- tests for all access functions
-- support for livetree modification
-- addition of more access functions as needed
-- support for livetree in SPL and before relocation (if desired)
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Migration Schedule
-==================
-
-U-Boot has been migrating to a new driver model since its introduction in
-2014. This file describes the schedule for deprecation of pre-driver-model
-features.
-
-CONFIG_DM
----------
-
-* Status: In progress
-* Deadline: 2020.01
-
-Starting with the 2010.01 release CONFIG_DM will be enabled for all boards.
-This does not concern CONFIG_DM_SPL and CONFIG_DM_TPL. The conversion date for
-these configuration items still needs to be defined.
-
-CONFIG_DM_MMC
--------------
-
-* Status: In progress
-* Deadline: 2019.04
-
-The subsystem itself has been converted and maintainers should submit patches
-switching over to using CONFIG_DM_MMC and other base driver model options in
-time for inclusion in the 2019.04 rerelease.
-
-CONFIG_DM_USB
--------------
-
-* Status: In progress
-* Deadline: 2019.07
-
-The subsystem itself has been converted along with many of the host controller
-and maintainers should submit patches switching over to using CONFIG_DM_USB and
-other base driver model options in time for inclusion in the 2019.07 rerelease.
-
-CONFIG_SATA
------------
-
-* Status: In progress
-* Deadline: 2019.07
-
-The subsystem itself has been converted along with many of the host controller
-and maintainers should submit patches switching over to using CONFIG_AHCI and
-other base driver model options in time for inclusion in the 2019.07 rerelease.
-
-CONFIG_BLK
-----------
-
-* Status: In progress
-* Deadline: 2019.07
-
-In concert with maintainers migrating their block device usage to the
-appropriate DM driver, CONFIG_BLK needs to be set as well. The final deadline
-here coincides with the final deadline for migration of the various block
-subsystems. At this point we will be able to audit and correct the logic in
-Kconfig around using CONFIG_PARTITIONS and CONFIG_HAVE_BLOCK_DEVICE and make
-use of CONFIG_BLK / CONFIG_SPL_BLK as needed.
-
-CONFIG_DM_SPI / CONFIG_DM_SPI_FLASH
------------------------------------
-
-Board Maintainers should submit the patches for enabling DM_SPI and DM_SPI_FLASH
-to move the migration with in the deadline.
-
-Partially converted::
-
- drivers/spi/fsl_espi.c
- drivers/spi/mxc_spi.c
- drivers/spi/sh_qspi.c
-
-* Status: In progress
-* Deadline: 2019.07
-
-CONFIG_DM_PCI
--------------
-Deadline: 2019.07
-
-The PCI subsystem has supported driver model since mid 2015. Maintainers should
-submit patches switching over to using CONFIG_DM_PCI and other base driver
-model options in time for inclusion in the 2019.07 release.
-
-
-CONFIG_DM_VIDEO
----------------
-Deadline: 2019.07
-
-The video subsystem has supported driver model since early 2016. Maintainers
-should submit patches switching over to using CONFIG_DM_VIDEO and other base
-driver model options in time for inclusion in the 2019.07 release.
-
-CONFIG_DM_ETH
--------------
-Deadline: 2020.07
-
-The network subsystem has supported the driver model since early 2015.
-Maintainers should submit patches switching over to using CONFIG_DM_ETH and
-other base driver model options in time for inclusion in the 2020.07 release.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-Compiled-in Device Tree / Platform Data
-=======================================
-
-
-Introduction
-------------
-
-Device tree is the standard configuration method in U-Boot. It is used to
-define what devices are in the system and provide configuration information
-to these devices.
-
-The overhead of adding devicetree access to U-Boot is fairly modest,
-approximately 3KB on Thumb 2 (plus the size of the DT itself). This means
-that in most cases it is best to use devicetree for configuration.
-
-However there are some very constrained environments where U-Boot needs to
-work. These include SPL with severe memory limitations. For example, some
-SoCs require a 16KB SPL image which must include a full MMC stack. In this
-case the overhead of devicetree access may be too great.
-
-It is possible to create platform data manually by defining C structures
-for it, and reference that data in a `U_BOOT_DRVINFO()` declaration. This
-bypasses the use of devicetree completely, effectively creating a parallel
-configuration mechanism. But it is an available option for SPL.
-
-As an alternative, the 'of-platdata' feature is provided. This converts the
-devicetree contents into C code which can be compiled into the SPL binary.
-This saves the 3KB of code overhead and perhaps a few hundred more bytes due
-to more efficient storage of the data.
-
-
-How it works
-------------
-
-The feature is enabled by CONFIG OF_PLATDATA. This is only available in
-SPL/TPL and should be tested with:
-
-.. code-block:: c
-
- #if CONFIG_IS_ENABLED(OF_PLATDATA)
-
-A tool called 'dtoc' converts a devicetree file either into a set of
-struct declarations, one for each compatible node, and a set of
-`U_BOOT_DRVINFO()` declarations along with the actual platform data for each
-device. As an example, consider this MMC node:
-
-.. code-block:: none
-
- sdmmc: dwmmc@ff0c0000 {
- compatible = "rockchip,rk3288-dw-mshc";
- clock-freq-min-max = <400000 150000000>;
- clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
- <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
- clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
- fifo-depth = <0x100>;
- interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
- reg = <0xff0c0000 0x4000>;
- bus-width = <4>;
- cap-mmc-highspeed;
- cap-sd-highspeed;
- card-detect-delay = <200>;
- disable-wp;
- num-slots = <1>;
- pinctrl-names = "default";
- pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
- vmmc-supply = <&vcc_sd>;
- status = "okay";
- u-boot,dm-pre-reloc;
- };
-
-
-Some of these properties are dropped by U-Boot under control of the
-CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
-the following C struct declaration:
-
-.. code-block:: c
-
- struct dtd_rockchip_rk3288_dw_mshc {
- fdt32_t bus_width;
- bool cap_mmc_highspeed;
- bool cap_sd_highspeed;
- fdt32_t card_detect_delay;
- fdt32_t clock_freq_min_max[2];
- struct phandle_1_arg clocks[4];
- bool disable_wp;
- fdt32_t fifo_depth;
- fdt32_t interrupts[3];
- fdt32_t num_slots;
- fdt32_t reg[2];
- fdt32_t vmmc_supply;
- };
-
-and the following device declarations:
-
-.. code-block:: c
-
- /* Node /clock-controller@ff760000 index 0 */
- ...
-
- /* Node /dwmmc@ff0c0000 index 2 */
- static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
- .fifo_depth = 0x100,
- .cap_sd_highspeed = true,
- .interrupts = {0x0, 0x20, 0x4},
- .clock_freq_min_max = {0x61a80, 0x8f0d180},
- .vmmc_supply = 0xb,
- .num_slots = 0x1,
- .clocks = {{0, 456},
- {0, 68},
- {0, 114},
- {0, 118}},
- .cap_mmc_highspeed = true,
- .disable_wp = true,
- .bus_width = 0x4,
- .u_boot_dm_pre_reloc = true,
- .reg = {0xff0c0000, 0x4000},
- .card_detect_delay = 0xc8,
- };
-
- U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = {
- .name = "rockchip_rk3288_dw_mshc",
- .plat = &dtv_dwmmc_at_ff0c0000,
- .plat_size = sizeof(dtv_dwmmc_at_ff0c0000),
- .parent_idx = -1,
- };
-
-The device is then instantiated at run-time and the platform data can be
-accessed using:
-
-.. code-block:: c
-
- struct udevice *dev;
- struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev);
-
-This avoids the code overhead of converting the devicetree data to
-platform data in the driver. The `of_to_plat()` method should
-therefore do nothing in such a driver.
-
-Note that for the platform data to be matched with a driver, the 'name'
-property of the `U_BOOT_DRVINFO()` declaration has to match a driver declared
-via `U_BOOT_DRIVER()`. This effectively means that a `U_BOOT_DRIVER()` with a
-'name' corresponding to the devicetree 'compatible' string (after converting
-it to a valid name for C) is needed, so a dedicated driver is required for
-each 'compatible' string.
-
-In order to make this a bit more flexible, the `DM_DRIVER_ALIAS()` macro can be
-used to declare an alias for a driver name, typically a 'compatible' string.
-This macro produces no code, but is used by dtoc tool. It must be located in the
-same file as its associated driver, ideally just after it.
-
-The parent_idx is the index of the parent `driver_info` structure within its
-linker list (instantiated by the `U_BOOT_DRVINFO()` macro). This is used to
-support `dev_get_parent()`.
-
-During the build process dtoc parses both `U_BOOT_DRIVER()` and
-`DM_DRIVER_ALIAS()` to build a list of valid driver names and driver aliases.
-If the 'compatible' string used for a device does not not match a valid driver
-name, it will be checked against the list of driver aliases in order to get the
-right driver name to use. If in this step there is no match found a warning is
-issued to avoid run-time failures.
-
-Where a node has multiple compatible strings, dtoc generates a `#define` to
-make them equivalent, e.g.:
-
-.. code-block:: c
-
- #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
-
-
-Converting of-platdata to a useful form
----------------------------------------
-
-Of course it would be possible to use the of-platdata directly in your driver
-whenever configuration information is required. However this means that the
-driver will not be able to support devicetree, since the of-platdata
-structure is not available when devicetree is used. It would make no sense
-to use this structure if devicetree were available, since the structure has
-all the limitations metioned in caveats below.
-
-Therefore it is recommended that the of-platdata structure should be used
-only in the `probe()` method of your driver. It cannot be used in the
-`of_to_plat()` method since this is not called when platform data is
-already present.
-
-
-How to structure your driver
-----------------------------
-
-Drivers should always support devicetree as an option. The of-platdata
-feature is intended as a add-on to existing drivers.
-
-Your driver should convert the plat struct in its `probe()` method. The
-existing devicetree decoding logic should be kept in the
-`of_to_plat()` method and wrapped with `#if`.
-
-For example:
-
-.. code-block:: c
-
- #include <dt-structs.h>
-
- struct mmc_plat {
- #if CONFIG_IS_ENABLED(OF_PLATDATA)
- /* Put this first since driver model will copy the data here */
- struct dtd_mmc dtplat;
- #endif
- /*
- * Other fields can go here, to be filled in by decoding from
- * the devicetree (or the C structures when of-platdata is used).
- */
- int fifo_depth;
- };
-
- static int mmc_of_to_plat(struct udevice *dev)
- {
- #if !CONFIG_IS_ENABLED(OF_PLATDATA)
- /* Decode the devicetree data */
- struct mmc_plat *plat = dev_get_plat(dev);
- const void *blob = gd->fdt_blob;
- int node = dev_of_offset(dev);
-
- plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
- #endif
-
- return 0;
- }
-
- static int mmc_probe(struct udevice *dev)
- {
- struct mmc_plat *plat = dev_get_plat(dev);
-
- #if CONFIG_IS_ENABLED(OF_PLATDATA)
- /* Decode the of-platdata from the C structures */
- struct dtd_mmc *dtplat = &plat->dtplat;
-
- plat->fifo_depth = dtplat->fifo_depth;
- #endif
- /* Set up the device from the plat data */
- writel(plat->fifo_depth, ...)
- }
-
- static const struct udevice_id mmc_ids[] = {
- { .compatible = "vendor,mmc" },
- { }
- };
-
- U_BOOT_DRIVER(mmc_drv) = {
- .name = "mmc_drv",
- .id = UCLASS_MMC,
- .of_match = mmc_ids,
- .of_to_plat = mmc_of_to_plat,
- .probe = mmc_probe,
- .priv_auto = sizeof(struct mmc_priv),
- .plat_auto = sizeof(struct mmc_plat),
- };
-
- DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */
-
-Note that `struct mmc_plat` is defined in the C file, not in a header. This
-is to avoid needing to include dt-structs.h in a header file. The idea is to
-keep the use of each of-platdata struct to the smallest possible code area.
-There is just one driver C file for each struct, that can convert from the
-of-platdata struct to the standard one used by the driver.
-
-In the case where SPL_OF_PLATDATA is enabled, `plat_auto` is
-still used to allocate space for the platform data. This is different from
-the normal behaviour and is triggered by the use of of-platdata (strictly
-speaking it is a non-zero `plat_size` which triggers this).
-
-The of-platdata struct contents is copied from the C structure data to the
-start of the newly allocated area. In the case where devicetree is used,
-the platform data is allocated, and starts zeroed. In this case the
-`of_to_plat()` method should still set up the platform data (and the
-of-platdata struct will not be present).
-
-SPL must use either of-platdata or devicetree. Drivers cannot use both at
-the same time, but they must support devicetree. Supporting of-platdata is
-optional.
-
-The devicetree becomes inaccessible when CONFIG_SPL_OF_PLATDATA is enabled,
-since the devicetree access code is not compiled in. A corollary is that
-a board can only move to using of-platdata if all the drivers it uses support
-it. There would be little point in having some drivers require the device
-tree data, since then libfdt would still be needed for those drivers and
-there would be no code-size benefit.
-
-
-Build-time instantiation
-------------------------
-
-Even with of-platdata there is a fair amount of code required in driver model.
-It is possible to have U-Boot handle the instantiation of devices at build-time,
-so avoiding the need for the `device_bind()` code and some parts of
-`device_probe()`.
-
-The feature is enabled by CONFIG_OF_PLATDATA_INST.
-
-Here is an example device, as generated by dtoc::
-
- /*
- * Node /serial index 6
- * driver sandbox_serial parent root_driver
- */
-
- #include <asm/serial.h>
- struct sandbox_serial_plat __attribute__ ((section (".priv_data")))
- _sandbox_serial_plat_serial = {
- .dtplat = {
- .sandbox_text_colour = "cyan",
- },
- };
- #include <asm/serial.h>
- u8 _sandbox_serial_priv_serial[sizeof(struct sandbox_serial_priv)]
- __attribute__ ((section (".priv_data")));
- #include <serial.h>
- u8 _sandbox_serial_uc_priv_serial[sizeof(struct serial_dev_priv)]
- __attribute__ ((section (".priv_data")));
-
- DM_DEVICE_INST(serial) = {
- .driver = DM_DRIVER_REF(sandbox_serial),
- .name = "sandbox_serial",
- .plat_ = &_sandbox_serial_plat_serial,
- .priv_ = _sandbox_serial_priv_serial,
- .uclass = DM_UCLASS_REF(serial),
- .uclass_priv_ = _sandbox_serial_uc_priv_serial,
- .uclass_node = {
- .prev = &DM_UCLASS_REF(serial)->dev_head,
- .next = &DM_UCLASS_REF(serial)->dev_head,
- },
- .child_head = {
- .prev = &DM_DEVICE_REF(serial)->child_head,
- .next = &DM_DEVICE_REF(serial)->child_head,
- },
- .sibling_node = {
- .prev = &DM_DEVICE_REF(i2c_at_0)->sibling_node,
- .next = &DM_DEVICE_REF(spl_test)->sibling_node,
- },
- .seq_ = 0,
- };
-
-Here is part of the driver, for reference::
-
- static const struct udevice_id sandbox_serial_ids[] = {
- { .compatible = "sandbox,serial" },
- { }
- };
-
- U_BOOT_DRIVER(sandbox_serial) = {
- .name = "sandbox_serial",
- .id = UCLASS_SERIAL,
- .of_match = sandbox_serial_ids,
- .of_to_plat = sandbox_serial_of_to_plat,
- .plat_auto = sizeof(struct sandbox_serial_plat),
- .priv_auto = sizeof(struct sandbox_serial_priv),
- .probe = sandbox_serial_probe,
- .remove = sandbox_serial_remove,
- .ops = &sandbox_serial_ops,
- .flags = DM_FLAG_PRE_RELOC,
- };
-
-
-The `DM_DEVICE_INST()` macro declares a struct udevice so you can see that the
-members are from that struct. The private data is declared immediately above,
-as `_sandbox_serial_priv_serial`, so there is no need for run-time memory
-allocation. The #include lines are generated as well, since dtoc searches the
-U-Boot source code for the definition of `struct sandbox_serial_priv` and adds
-the relevant header so that the code will compile without errors.
-
-The `plat_` member is set to the dtv data which is declared immediately above
-the device. This is similar to how it would look without of-platdata-inst, but
-node that the `dtplat` member inside is part of the wider
-`_sandbox_serial_plat_serial` struct. This is because the driver declares its
-own platform data, and the part generated by dtoc can only be a portion of it.
-The `dtplat` part is always first in the struct. If the device has no
-`.plat_auto` field, then a simple dtv struct can be used as with this example::
-
- static struct dtd_sandbox_clk dtv_clk_sbox = {
- .assigned_clock_rates = 0x141,
- .assigned_clocks = {0x7, 0x3},
- };
-
- #include <asm/clk.h>
- u8 _sandbox_clk_priv_clk_sbox[sizeof(struct sandbox_clk_priv)]
- __attribute__ ((section (".priv_data")));
-
- DM_DEVICE_INST(clk_sbox) = {
- .driver = DM_DRIVER_REF(sandbox_clk),
- .name = "sandbox_clk",
- .plat_ = &dtv_clk_sbox,
-
-Here is part of the driver, for reference::
-
- static const struct udevice_id sandbox_clk_ids[] = {
- { .compatible = "sandbox,clk" },
- { }
- };
-
- U_BOOT_DRIVER(sandbox_clk) = {
- .name = "sandbox_clk",
- .id = UCLASS_CLK,
- .of_match = sandbox_clk_ids,
- .ops = &sandbox_clk_ops,
- .probe = sandbox_clk_probe,
- .priv_auto = sizeof(struct sandbox_clk_priv),
- };
-
-
-You can see that `dtv_clk_sbox` just has the devicetree contents and there is
-no need for the `dtplat` separation, since the driver has no platform data of
-its own, besides that provided by the devicetree (i.e. no `.plat_auto` field).
-
-The doubly linked lists are handled by explicitly declaring the value of each
-node, as you can see with the `.prev` and `.next` values in the example above.
-Since dtoc knows the order of devices it can link them into the appropriate
-lists correctly.
-
-One of the features of driver model is the ability for a uclass to have a
-small amount of private data for each device in that uclass. This is used to
-provide a generic data structure that the uclass can use for all devices, thus
-allowing generic features to be implemented in common code. An example is I2C,
-which stores the bus speed there.
-
-Similarly, parent devices can have data associated with each of their children.
-This is used to provide information common to all children of a particular bus.
-For an I2C bus, this is used to store the I2C address of each child on the bus.
-
-This is all handled automatically by dtoc::
-
- #include <asm/i2c.h>
- u8 _sandbox_i2c_priv_i2c_at_0[sizeof(struct sandbox_i2c_priv)]
- __attribute__ ((section (".priv_data")));
- #include <i2c.h>
- u8 _sandbox_i2c_uc_priv_i2c_at_0[sizeof(struct dm_i2c_bus)]
- __attribute__ ((section (".priv_data")));
-
- DM_DEVICE_INST(i2c_at_0) = {
- .driver = DM_DRIVER_REF(sandbox_i2c),
- .name = "sandbox_i2c",
- .plat_ = &dtv_i2c_at_0,
- .priv_ = _sandbox_i2c_priv_i2c_at_0,
- .uclass = DM_UCLASS_REF(i2c),
- .uclass_priv_ = _sandbox_i2c_uc_priv_i2c_at_0,
- ...
-
-Part of driver, for reference::
-
- static const struct udevice_id sandbox_i2c_ids[] = {
- { .compatible = "sandbox,i2c" },
- { }
- };
-
- U_BOOT_DRIVER(sandbox_i2c) = {
- .name = "sandbox_i2c",
- .id = UCLASS_I2C,
- .of_match = sandbox_i2c_ids,
- .ops = &sandbox_i2c_ops,
- .priv_auto = sizeof(struct sandbox_i2c_priv),
- };
-
-Part of I2C uclass, for reference::
-
- UCLASS_DRIVER(i2c) = {
- .id = UCLASS_I2C,
- .name = "i2c",
- .flags = DM_UC_FLAG_SEQ_ALIAS,
- .post_bind = i2c_post_bind,
- .pre_probe = i2c_pre_probe,
- .post_probe = i2c_post_probe,
- .per_device_auto = sizeof(struct dm_i2c_bus),
- .per_child_plat_auto = sizeof(struct dm_i2c_chip),
- .child_post_bind = i2c_child_post_bind,
- };
-
-Here, `_sandbox_i2c_uc_priv_i2c_at_0` is required by the uclass but is declared
-in the device, as required by driver model. The required header file is included
-so that the code will compile without errors. A similar mechanism is used for
-child devices, but is not shown by this example.
-
-It would not be that useful to avoid binding devices but still need to allocate
-uclasses at runtime. So dtoc generates uclass instances as well::
-
- struct list_head uclass_head = {
- .prev = &DM_UCLASS_REF(serial)->sibling_node,
- .next = &DM_UCLASS_REF(clk)->sibling_node,
- };
-
- DM_UCLASS_INST(clk) = {
- .uc_drv = DM_UCLASS_DRIVER_REF(clk),
- .sibling_node = {
- .prev = &uclass_head,
- .next = &DM_UCLASS_REF(i2c)->sibling_node,
- },
- .dev_head = {
- .prev = &DM_DEVICE_REF(clk_sbox)->uclass_node,
- .next = &DM_DEVICE_REF(clk_fixed)->uclass_node,
- },
- };
-
-At the top is the list head. Driver model uses this on start-up, instead of
-creating its own.
-
-Below that are a set of `DM_UCLASS_INST()` macros, each declaring a
-`struct uclass`. The doubly linked lists work as for devices.
-
-All private data is placed into a `.priv_data` section so that it is contiguous
-in the resulting output binary.
-
-
-Indexes
--------
-
-U-Boot stores drivers, devices and many other things in linker_list structures.
-These are sorted by name, so dtoc knows the order that they will appear when
-the linker runs. Each driver_info / udevice is referenced by its index in the
-linker_list array, called 'idx' in the code.
-
-When CONFIG_OF_PLATDATA_INST is enabled, idx is the udevice index, otherwise it
-is the driver_info index. In either case, indexes are used to reference devices
-using device_get_by_ofplat_idx(). This allows phandles to work as expected.
-
-
-Phases
-------
-
-U-Boot operates in several phases, typically TPL, SPL and U-Boot proper.
-The latter does not use dtoc.
-
-In some rare cases different drivers are used for two phases. For example,
-in TPL it may not be necessary to use the full PCI subsystem, so a simple
-driver can be used instead.
-
-This works in the build system simply by compiling in one driver or the
-other (e.g. PCI driver + uclass for SPL; simple_bus for TPL). But dtoc has
-no way of knowing which code is compiled in for which phase, since it does
-not inspect Makefiles or dependency graphs.
-
-So to make this work for dtoc, we need to be able to explicitly mark
-drivers with their phase. This is done by adding a macro to the driver::
-
- /* code in tpl.c only compiled into TPL */
- U_BOOT_DRIVER(pci_x86) = {
- .name = "pci_x86",
- .id = UCLASS_SIMPLE_BUS,
- .of_match = of_match_ptr(tpl_fake_pci_ids),
- DM_PHASE(tpl)
- };
-
-
- /* code in pci_x86.c compiled into SPL and U-Boot proper */
- U_BOOT_DRIVER(pci_x86) = {
- .name = "pci_x86",
- .id = UCLASS_PCI,
- .of_match = pci_x86_ids,
- .ops = &pci_x86_ops,
- };
-
-
-Notice that the second driver has the same name but no DM_PHASE(), so it will be
-used for SPL and U-Boot.
-
-Note also that this only affects the code generated by dtoc. You still need to
-make sure that only the required driver is build into each phase.
-
-
-Header files
-------------
-
-With OF_PLATDATA_INST, dtoc must include the correct header file in the
-generated code for any structs that are used, so that the code will compile.
-For example, if `struct ns16550_plat` is used, the code must include the
-`ns16550.h` header file.
-
-Typically dtoc can detect the header file needed for a driver by looking
-for the structs that it uses. For example, if a driver as a `.priv_auto`
-that uses `struct ns16550_plat`, then dtoc can search header files for the
-definition of that struct and use the file.
-
-In some cases, enums are used in drivers, typically with the `.data` field
-of `struct udevice_id`. Since dtoc does not support searching for these,
-you must use the `DM_HDR()` macro to tell dtoc which header to use. This works
-as a macro included in the driver definition::
-
- static const struct udevice_id apl_syscon_ids[] = {
- { .compatible = "intel,apl-punit", .data = X86_SYSCON_PUNIT },
- { }
- };
-
- U_BOOT_DRIVER(intel_apl_punit) = {
- .name = "intel_apl_punit",
- .id = UCLASS_SYSCON,
- .of_match = apl_syscon_ids,
- .probe = apl_punit_probe,
- DM_HEADER(<asm/cpu.h>) /* for X86_SYSCON_PUNIT */
- };
-
-
-
-Caveats
--------
-
-There are various complications with this feature which mean it should only
-be used when strictly necessary, i.e. in SPL with limited memory. Notable
-caveats include:
-
- - Device tree does not describe data types. But the C code must define a
- type for each property. These are guessed using heuristics which
- are wrong in several fairly common cases. For example an 8-byte value
- is considered to be a 2-item integer array, and is byte-swapped. A
- boolean value that is not present means 'false', but cannot be
- included in the structures since there is generally no mention of it
- in the devicetree file.
-
- - Naming of nodes and properties is automatic. This means that they follow
- the naming in the devicetree, which may result in C identifiers that
- look a bit strange.
-
- - It is not possible to find a value given a property name. Code must use
- the associated C member variable directly in the code. This makes
- the code less robust in the face of devicetree changes. To avoid having
- a second struct with similar members and names you need to explicitly
- declare it as an alias with `DM_DRIVER_ALIAS()`.
-
- - The platform data is provided to drivers as a C structure. The driver
- must use the same structure to access the data. Since a driver
- normally also supports devicetree it must use `#ifdef` to separate
- out this code, since the structures are only available in SPL. This could
- be fixed fairly easily by making the structs available outside SPL, so
- that `IS_ENABLED()` could be used.
-
- - With CONFIG_OF_PLATDATA_INST all binding happens at build-time, meaning
- that (by default) it is not possible to call `device_bind()` from C code.
- This means that all devices must have an associated devicetree node and
- compatible string. For example if a GPIO device currently creates child
- devices in its `bind()` method, it will not work with
- CONFIG_OF_PLATDATA_INST. Arguably this is bad practice anyway and the
- devicetree binding should be updated to declare compatible strings for
- the child devices. It is possible to disable OF_PLATDATA_NO_BIND but this
- is not recommended since it increases code size.
-
-
-Internals
----------
-
-Generated files
-```````````````
-
-When enabled, dtoc generates the following five files:
-
-include/generated/dt-decl.h (OF_PLATDATA_INST only)
- Contains declarations for all drivers, devices and uclasses. This allows
- any `struct udevice`, `struct driver` or `struct uclass` to be located by its
- name
-
-include/generated/dt-structs-gen.h
- Contains the struct definitions for the devicetree nodes that are used. This
- is the same as without OF_PLATDATA_INST
-
-spl/dts/dt-plat.c (only with !OF_PLATDATA_INST)
- Contains the `U_BOOT_DRVINFO()` declarations that U-Boot uses to bind devices
- at start-up. See above for an example
-
-spl/dts/dt-device.c (only with OF_PLATDATA_INST)
- Contains `DM_DEVICE_INST()` declarations for each device that can be used at
- run-time. These are declared in the file along with any private/platform data
- that they use. Every device has an idx, as above. Since each device must be
- part of a double-linked list, the nodes are declared in the code as well.
-
-spl/dts/dt-uclass.c (only with OF_PLATDATA_INST)
- Contains `DM_UCLASS_INST()` declarations for each uclass that can be used at
- run-time. These are declared in the file along with any private data
- associated with the uclass itself (the `.priv_auto` member). Since each
- uclass must be part of a double-linked list, the nodes are declared in the
- code as well.
-
-The dt-structs.h file includes the generated file
-`(include/generated/dt-structs.h`) if CONFIG_SPL_OF_PLATDATA is enabled.
-Otherwise (such as in U-Boot proper) these structs are not available. This
-prevents them being used inadvertently. All usage must be bracketed with
-`#if CONFIG_IS_ENABLED(OF_PLATDATA)`.
-
-The dt-plat.c file contains the device declarations and is is built in
-spl/dt-plat.c.
-
-
-CONFIG options
-``````````````
-
-Several CONFIG options are used to control the behaviour of of-platdata, all
-available for both SPL and TPL:
-
-OF_PLATDATA
- This is the main option which enables the of-platdata feature
-
-OF_PLATDATA_PARENT
- This allows `device_get_parent()` to work. Without this, all devices exist as
- direct children of the root node. This option is highly desirable (if not
- always absolutely essential) for buses such as I2C.
-
-OF_PLATDATA_INST
- This controls the instantiation of devices at build time. With it disabled,
- only `U_BOOT_DRVINFO()` records are created, with U-Boot handling the binding
- in `device_bind()` on start-up. With it enabled, only `DM_DEVICE_INST()` and
- `DM_UCLASS_INST()` records are created, and `device_bind()` is not needed at
- runtime.
-
-OF_PLATDATA_NO_BIND
- This controls whether `device_bind()` is supported. It is enabled by default
- with OF_PLATDATA_INST since code-size reduction is really the main point of
- the feature. It can be disabled if needed but is not likely to be supported
- in the long term.
-
-OF_PLATDATA_DRIVER_RT
- This controls whether the `struct driver_rt` records are used by U-Boot.
- Normally when a device is bound, U-Boot stores the device pointer in one of
- these records. There is one for every `struct driver_info` in the system,
- i.e. one for every device that is bound from those records. It provides a
- way to locate a device in the code and is used by
- `device_get_by_ofplat_idx()`. This option is always enabled with of-platdata,
- provided OF_PLATDATA_INST is not. In that case the records are useless since
- we don't have any `struct driver_info` records.
-
-OF_PLATDATA_RT
- This controls whether the `struct udevice_rt` records are used by U-Boot.
- It moves the updatable fields from `struct udevice` (currently only `flags`)
- into a separate structure, allowing the records to be kept in read-only
- memory. It is generally enabled if OF_PLATDATA_INST is enabled. This option
- also controls whether the private data is used in situ, or first copied into
- an allocated region. Again this is to allow the private data declared by
- dtoc-generated code to be in read-only memory. Note that access to private
- data must be done via accessor functions, such as `dev_get_priv()`, so that
- the relocation is handled.
-
-READ_ONLY
- This indicates that the data generated by dtoc should not be modified. Only
- a few fields actually do get changed in U-Boot, such as device flags. This
- option causes those to move into an allocated space (see OF_PLATDATA_RT).
- Also, since updating doubly linked lists is generally impossible when some of
- the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled.
-
-Data structures
-```````````````
-
-A few extra data structures are used with of-platdata:
-
-`struct udevice_rt`
- Run-time information for devices. When OF_PLATDATA_RT is enabled, this holds
- the flags for each device, so that `struct udevice` can remain unchanged by
- U-Boot, and potentially reside in read-only memory. Access to flags is then
- via functions like `dev_get_flags()` and `dev_or_flags()`. This data
- structure is allocated on start-up, where the private data is also copied.
- All flags values start at 0 and any changes are handled by `dev_or_flags()`
- and `dev_bic_flags()`. It would be more correct for the flags to be set to
- `DM_FLAG_BOUND`, or perhaps `DM_FLAG_BOUND | DM_FLAG_ALLOC_PDATA`, but since
- there is no code to bind/unbind devices and no code to allocate/free
- private data / platform data, it doesn't matter.
-
-`struct driver_rt`
- Run-time information for `struct driver_info` records. When
- OF_PLATDATA_DRIVER_RT is enabled, this holds a pointer to the device
- created by each record. This is needed so that is it possible to locate a
- device from C code. Specifically, the code can use `DM_DRVINFO_GET(name)` to
- get a reference to a particular `struct driver_info`, with `name` being the
- name of the devicetree node. This is very convenient. It is also fast, since
- no searching or string comparison is needed. This data structure is
- allocated on start-up, filled out by `device_bind()` and used by
- `device_get_by_ofplat_idx()`.
-
-Other changes
-`````````````
-
-Some other changes are made with of-platdata:
-
-Accessor functions
- Accessing private / platform data via functions such as `dev_get_priv()` has
- always been encouraged. With OF_PLATDATA_RT this is essential, since the
- `priv_` and `plat_` (etc.) values point to the data generated by dtoc, not
- the read-write copy that is sometimes made on start-up. Changing the
- private / platform data pointers has always been discouraged (the API is
- marked internal) but with OF_PLATDATA_RT this is not currently supported in
- general, since it assumes that all such pointers point to the relocated data.
- Note also that the renaming of struct members to have a trailing underscore
- was partly done to make people aware that they should not be accessed
- directly.
-
-`gd->uclass_root_s`
- Normally U-Boot sets up the head of the uclass list here and makes
- `gd->uclass_root` point to it. With OF_PLATDATA_INST, dtoc generates a
- declaration of `uclass_head` in `dt-uclass.c` since it needs to link the
- head node into the list. In that case, `gd->uclass_root_s` is not used and
- U-Boot just makes `gd->uclass_root` point to `uclass_head`.
-
-`gd->dm_driver_rt`
- This holds a pointer to a list of `struct driver_rt` records, one for each
- `struct driver_info`. The list is in alphabetical order by the name used
- in `U_BOOT_DRVINFO(name)` and indexed by idx, with the first record having
- an index of 0. It is only used if OF_PLATDATA_INST is not enabled. This is
- accessed via macros so that it can be used inside IS_ENABLED(), rather than
- requiring #ifdefs in the C code when it is not present.
-
-`gd->dm_udevice_rt`
- This holds a pointer to a list of `struct udevice_rt` records, one for each
- `struct udevice`. The list is in alphabetical order by the name used
- in `DM_DEVICE_INST(name)` (a C version of the devicetree node) and indexed by
- idx, with the first record having an index of 0. It is only used if
- OF_PLATDATA_INST is enabled. This is accessed via macros so that it can be
- used inside `IS_ENABLED()`, rather than requiring #ifdefs in the C code when
- it is not present.
-
-`gd->dm_priv_base`
- When OF_PLATDATA_RT is enabled, the private/platform data for each device is
- copied into an allocated region by U-Boot on start-up. This points to that
- region. All calls to accessor functions (e.g. `dev_get_priv()`) then
- translate from the pointer provided by the caller (assumed to lie between
- `__priv_data_start` and `__priv_data_end`) to the new allocated region. This
- member is accessed via macros so that it can be used inside IS_ENABLED(),
- rather than required #ifdefs in the C code when it is not present.
-
-`struct udevice->flags_`
- When OF_PLATDATA_RT is enabled, device flags are no-longer part of
- `struct udevice`, but are instead kept in `struct udevice_rt`, as described
- above. Flags are accessed via functions, such as `dev_get_flags()` and
- `dev_or_flags()`.
-
-`struct udevice->node_`
- When OF_PLATDATA is enabled, there is no devicetree at runtime, so no need
- for this field. It is removed, just to save space.
-
-`DM_PHASE`
- This macro is used to indicate which phase of U-Boot a driver is intended
- for. See above for details.
-
-`DM_HDR`
- This macro is used to indicate which header file dtoc should use to allow
- a driver declaration to compile correctly. See above for details.
-
-`device_get_by_ofplat_idx()`
- There used to be a function called `device_get_by_driver_info()` which
- looked up a `struct driver_info` pointer and returned the `struct udevice`
- that was created from it. It was only available for use with of-platdata.
- This has been removed in favour of `device_get_by_ofplat_idx()` which uses
- `idx`, the index of the `struct driver_info` or `struct udevice` in the
- linker_list. Similarly, the `struct phandle_0_arg` (etc.) structs have been
- updated to use this index instead of a pointer to `struct driver_info`.
-
-`DM_DRVINFO_GET`
- This has been removed since we now use indexes to obtain a driver from
- `struct phandle_0_arg` and the like.
-
-Two-pass binding
- The original of-platdata tried to order `U_BOOT_DRVINFO()` in the generated
- files so as to have parents declared ahead of children. This was convenient
- as it avoided any special code in U-Boot. With OF_PLATDATA_INST this does
- not work as the idx value relies on using alphabetical order for everything,
- so that dtoc and U-Boot's linker_lists agree on the idx value. Devices are
- then bound in order of idx, having no regard to parent/child relationships.
- For this reason, device binding now hapens in multiple passes, with parents
- being bound before their children. This is important so that children can
- find their parents in the bind() method if needed.
-
-Root device
- The root device is generally bound by U-Boot but with OF_PLATDATA_INST it
- cannot be, since binding needs to be done at build time. So in this case
- dtoc sets up a root device using `DM_DEVICE_INST()` in `dt-device.c` and
- U-Boot makes use of that. When OF_PLATDATA_INST is not enabled, U-Boot
- generally ignores the root node and does not create a `U_BOOT_DRVINFO()`
- record for it. This means that the idx numbers used by `struct driver_info`
- (when OF_PLATDATA_INST is disabled) and the idx numbers used by
- `struct udevice` (when OF_PLATDATA_INST is enabled) differ, since one has a
- root node and the other does not. This does not actually matter, since only
- one of them is actually used for any particular build, but it is worth
- keeping in mind if comparing index values and switching OF_PLATDATA_INST on
- and off.
-
-`__priv_data_start` and `__priv_data_end`
- The private/platform data declared by dtoc is all collected together in
- a linker section and these symbols mark the start and end of it. This allows
- U-Boot to relocate the area to a new location if needed (with
- OF_PLATDATA_RT)
-
-`dm_priv_to_rw()`
- This function converts a private- or platform-data pointer value generated by
- dtoc into one that can be used by U-Boot. It is a NOP unless OF_PLATDATA_RT
- is enabled, in which case it translates the address to the relocated
- region. See above for more information.
-
-The dm_populate_phandle_data() function that was previous needed has now been
-removed, since dtoc can address the drivers directly from dt-plat.c and does
-not need to fix up things at runtime.
-
-The pylibfdt Python module is used to access the devicetree.
-
-
-Credits
--------
-
-
-
-Future work
------------
-- Consider programmatically reading binding files instead of devicetree
- contents
-- Allow IS_ENABLED() to be used in the C code instead of #if
-
-
-.. Google, Inc
-.. 6/6/16
-.. Updated Independence Day 2016
-.. Updated 1st October 2020
-.. Updated 5th February 2021
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-PCI with Driver Model
-=====================
-
-How busses are scanned
-----------------------
-
-Any config read will end up at pci_read_config(). This uses
-uclass_get_device_by_seq() to get the PCI bus for a particular bus number.
-Bus number 0 will need to be requested first, and the alias in the device
-tree file will point to the correct device::
-
- aliases {
- pci0 = &pcic;
- };
-
- pcic: pci@0 {
- compatible = "sandbox,pci";
- ...
- };
-
-
-If there is no alias the devices will be numbered sequentially in the device
-tree.
-
-The call to uclass_get_device() will cause the PCI bus to be probed.
-This does a scan of the bus to locate available devices. These devices are
-bound to their appropriate driver if available. If there is no driver, then
-they are bound to a generic PCI driver which does nothing.
-
-After probing a bus, the available devices will appear in the device tree
-under that bus.
-
-Note that this is all done on a lazy basis, as needed, so until something is
-touched on PCI (eg: a call to pci_find_devices()) it will not be probed.
-
-PCI devices can appear in the flattened device tree. If they do, their node
-often contains extra information which cannot be derived from the PCI IDs or
-PCI class of the device. Each PCI device node must have a <reg> property, as
-defined by the IEEE Std 1275-1994 PCI bus binding document v2.1. Compatible
-string list is optional and generally not needed, since PCI is discoverable
-bus, albeit there are justified exceptions. If the compatible string is
-present, matching on it takes precedence over PCI IDs and PCI classes.
-
-Note we must describe PCI devices with the same bus hierarchy as the
-hardware, otherwise driver model cannot detect the correct parent/children
-relationship during PCI bus enumeration thus PCI devices won't be bound to
-their drivers accordingly. A working example like below::
-
- pci {
- #address-cells = <3>;
- #size-cells = <2>;
- compatible = "pci-x86";
- u-boot,dm-pre-reloc;
- ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000
- 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000
- 0x01000000 0x0 0x2000 0x2000 0 0xe000>;
-
- pcie@17,0 {
- #address-cells = <3>;
- #size-cells = <2>;
- compatible = "pci-bridge";
- u-boot,dm-pre-reloc;
- reg = <0x0000b800 0x0 0x0 0x0 0x0>;
-
- topcliff@0,0 {
- #address-cells = <3>;
- #size-cells = <2>;
- compatible = "pci-bridge";
- u-boot,dm-pre-reloc;
- reg = <0x00010000 0x0 0x0 0x0 0x0>;
-
- pciuart0: uart@a,1 {
- compatible = "pci8086,8811.00",
- "pci8086,8811",
- "pciclass,070002",
- "pciclass,0700",
- "x86-uart";
- u-boot,dm-pre-reloc;
- reg = <0x00025100 0x0 0x0 0x0 0x0
- 0x01025110 0x0 0x0 0x0 0x0>;
- ......
- };
-
- ......
- };
- };
-
- ......
- };
-
-In this example, the root PCI bus node is the "/pci" which matches "pci-x86"
-driver. It has a subnode "pcie@17,0" with driver "pci-bridge". "pcie@17,0"
-also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge,
-a PCI UART device "uart@a,1" is described. This exactly reflects the hardware
-bus hierarchy: on the root PCI bus, there is a PCIe root port which connects
-to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a
-PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART
-device are on the PCI bus. Like other devices in the device tree, if we want
-to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared
-in each of these nodes.
-
-If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
-to specify the driver to use for the device. The device tree takes precedence
-over U_BOOT_PCI_DEVICE. Please note with U_BOOT_PCI_DEVICE, only drivers with
-DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor
-U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or
-pci_generic_drv) will be used.
-
-
-Sandbox
--------
-
-With sandbox we need a device emulator for each device on the bus since there
-is no real PCI bus. This works by looking in the device tree node for an
-emulator driver. For example::
-
- pci@1f,0 {
- compatible = "pci-generic";
- reg = <0xf800 0 0 0 0>;
- sandbox,emul = <&emul_1f>;
- };
- pci-emul {
- compatible = "sandbox,pci-emul-parent";
- emul_1f: emul@1f,0 {
- compatible = "sandbox,swap-case";
- #emul-cells = <0>;
- };
- };
-
-This means that there is a 'sandbox,swap-case' driver at that bus position.
-Note that the first cell in the 'reg' value is the bus/device/function. See
-PCI_BDF() for the encoding (it is also specified in the IEEE Std 1275-1994
-PCI bus binding document, v2.1)
-
-The pci-emul node should go outside the pci bus node, since otherwise it will
-be scanned as a PCI device, causing confusion.
-
-When this bus is scanned we will end up with something like this::
-
- `- * pci@0 @ 05c660c8, 0
- `- pci@1f,0 @ 05c661c8, 63488
- `- emul@1f,0 @ 05c662c8
-
-When accesses go to the pci@1f,0 device they are forwarded to its emulator.
-
-The sandbox PCI drivers also support dynamic driver binding, allowing device
-driver to declare the driver binding information via U_BOOT_PCI_DEVICE(),
-eliminating the need to provide any device tree node under the host controller
-node. It is required a "sandbox,dev-info" property must be provided in the
-host controller node for this functionality to work.
-
-.. code-block:: none
-
- pci1: pci@1 {
- compatible = "sandbox,pci";
- ...
- sandbox,dev-info = <0x08 0x00 0x1234 0x5678
- 0x0c 0x00 0x1234 0x5678>;
- };
-
-The "sandbox,dev-info" property specifies all dynamic PCI devices on this bus.
-Each dynamic PCI device is encoded as 4 cells a group. The first and second
-cells are PCI device number and function number respectively. The third and
-fourth cells are PCI vendor ID and device ID respectively.
-
-When this bus is scanned we will end up with something like this::
-
- pci [ + ] pci_sandbo |-- pci1
- pci_emul [ ] sandbox_sw | |-- sandbox_swap_case_emul
- pci_emul [ ] sandbox_sw | `-- sandbox_swap_case_emul
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-.. (C) Copyright 2014-2015 Samsung Electronics
-
-PMIC framework based on Driver Model
-====================================
-
-Introduction
-------------
-This is an introduction to driver-model multi uclass PMIC IC's support.
-At present it's based on two uclass types:
-
-UCLASS_PMIC:
- basic uclass type for PMIC I/O, which provides common
- read/write interface.
-UCLASS_REGULATOR:
- additional uclass type for specific PMIC features, which are
- Voltage/Current regulators.
-
-New files:
-
-UCLASS_PMIC:
- - drivers/power/pmic/pmic-uclass.c
- - include/power/pmic.h
-UCLASS_REGULATOR:
- - drivers/power/regulator/regulator-uclass.c
- - include/power/regulator.h
-
-Commands:
-- common/cmd_pmic.c
-- common/cmd_regulator.c
-
-How doees it work
------------------
-The Power Management Integrated Circuits (PMIC) are used in embedded systems
-to provide stable, precise and specific voltage power source with over-voltage
-and thermal protection circuits.
-
-The single PMIC can provide various functions by single or multiple interfaces,
-like in the example below::
-
- -- SoC
- |
- | ______________________________________
- | BUS 0 | Multi interface PMIC IC |--> LDO out 1
- | e.g.I2C0 | |--> LDO out N
- |-----------|---- PMIC device 0 (READ/WRITE ops) |
- | or SPI0 | |_ REGULATOR device (ldo/... ops) |--> BUCK out 1
- | | |_ CHARGER device (charger ops) |--> BUCK out M
- | | |_ MUIC device (microUSB con ops) |
- | BUS 1 | |_ ... |---> BATTERY
- | e.g.I2C1 | |
- |-----------|---- PMIC device 1 (READ/WRITE ops) |---> USB in 1
- . or SPI1 | |_ RTC device (rtc ops) |---> USB in 2
- . |______________________________________|---> USB out
- .
-
-Since U-Boot provides driver model features for I2C and SPI bus drivers,
-the PMIC devices should also support this. By the pmic and regulator API's,
-PMIC drivers can simply provide a common functions, for multi-interface and
-and multi-instance device support.
-
-Basic design assumptions:
-
-- Common I/O API:
- UCLASS_PMIC. For the multi-function PMIC devices, this can be used as
- parent I/O device for each IC's interface. Then, each children uses the
- same dev for read/write.
-
-- Common regulator API:
- UCLASS_REGULATOR. For driving the regulator attributes, auto setting
- function or command line interface, based on kernel-style regulator device
- tree constraints.
-
-For simple implementations, regulator drivers are not required, so the code can
-use pmic read/write directly.
-
-Pmic uclass
------------
-The basic information:
-
-* Uclass: 'UCLASS_PMIC'
-* Header: 'include/power/pmic.h'
-* Core: 'drivers/power/pmic/pmic-uclass.c' (config 'CONFIG_DM_PMIC')
-* Command: 'common/cmd_pmic.c' (config 'CONFIG_CMD_PMIC')
-* Example: 'drivers/power/pmic/max77686.c'
-
-For detailed API description, please refer to the header file.
-
-As an example of the pmic driver, please refer to the MAX77686 driver.
-
-Please pay attention for the driver's bind() method. Exactly the function call:
-'pmic_bind_children()', which is used to bind the regulators by using the array
-of regulator's node, compatible prefixes.
-
-The 'pmic; command also supports the new API. So the pmic command can be enabled
-by adding CONFIG_CMD_PMIC.
-The new pmic command allows to:
-- list pmic devices
-- choose the current device (like the mmc command)
-- read or write the pmic register
-- dump all pmic registers
-
-This command can use only UCLASS_PMIC devices, since this uclass is designed
-for pmic I/O operations only.
-
-For more information, please refer to the core file.
-
-Regulator uclass
-----------------
-The basic information:
-
-* Uclass: 'UCLASS_REGULATOR'
-
-* Header: 'include/power/regulator.h'
-
-* Core: 'drivers/power/regulator/regulator-uclass.c'
- (config 'CONFIG_DM_REGULATOR')
-
-* Binding: 'doc/device-tree-bindings/regulator/regulator.txt'
-
-* Command: 'common/cmd_regulator.c' (config 'CONFIG_CMD_REGULATOR')
-
-* Example: 'drivers/power/regulator/max77686.c'
- 'drivers/power/pmic/max77686.c' (required I/O driver for the above)
-
-* Example: 'drivers/power/regulator/fixed.c'
- (config 'CONFIG_DM_REGULATOR_FIXED')
-
-For detailed API description, please refer to the header file.
-
-For the example regulator driver, please refer to the MAX77686 regulator driver,
-but this driver can't operate without pmic's example driver, which provides an
-I/O interface for MAX77686 regulator.
-
-The second example is a fixed Voltage/Current regulator for a common use.
-
-The 'regulator' command also supports the new API. The command allow:
-- list regulator devices
-- choose the current device (like the mmc command)
-- do all regulator-specific operations
-
-For more information, please refer to the command file.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-.. (C) Copyright 2015
-.. Texas Instruments Incorporated - http://www.ti.com/
-
-Remote Processor Framework
-==========================
-
-Introduction
-------------
-
-This is an introduction to driver-model for Remote Processors found
-on various System on Chip(SoCs). The term remote processor is used to
-indicate that this is not the processor on which U-Boot is operating
-on, instead is yet another processing entity that may be controlled by
-the processor on which we are functional.
-
-The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
-
-UCLASS_REMOTEPROC:
- - drivers/remoteproc/rproc-uclass.c
- - include/remoteproc.h
-
-Commands:
- - common/cmd_remoteproc.c
-
-Configuration:
- - CONFIG_REMOTEPROC is selected by drivers as needed
- - CONFIG_CMD_REMOTEPROC for the commands if required.
-
-How does it work - The driver
------------------------------
-
-Overall, the driver statemachine transitions are typically as follows::
-
- (entry)
- +-------+
- +---+ init |
- | | | <---------------------+
- | +-------+ |
- | |
- | |
- | +--------+ |
- Load| | reset | |
- | | | <----------+ |
- | +--------+ | |
- | |Load | |
- | | | |
- | +----v----+ reset | |
- +-> | | (opt) | |
- | Loaded +-----------+ |
- | | |
- +----+----+ |
- | Start |
- +---v-----+ (opt) |
- +->| Running | Stop |
- Ping +- | +--------------------+
- (opt) +---------+
-
-(is_running does not change state)
-opt: Optional state transition implemented by driver.
-
-NOTE: It depends on the remote processor as to the exact behavior
-of the statemachine, remoteproc core does not intent to implement
-statemachine logic. Certain processors may allow start/stop without
-reloading the image in the middle, certain other processors may only
-allow us to start the processor(image from a EEPROM/OTP) etc.
-
-It is hence the responsibility of the driver to handle the requisite
-state transitions of the device as necessary.
-
-Basic design assumptions:
-
-Remote processor can operate on a certain firmware that maybe loaded
-and released from reset.
-
-The driver follows a standard UCLASS DM.
-
-in the bare minimum form:
-
-.. code-block:: c
-
- static const struct dm_rproc_ops sandbox_testproc_ops = {
- .load = sandbox_testproc_load,
- .start = sandbox_testproc_start,
- };
-
- static const struct udevice_id sandbox_ids[] = {
- {.compatible = "sandbox,test-processor"},
- {}
- };
-
- U_BOOT_DRIVER(sandbox_testproc) = {
- .name = "sandbox_test_proc",
- .of_match = sandbox_ids,
- .id = UCLASS_REMOTEPROC,
- .ops = &sandbox_testproc_ops,
- .probe = sandbox_testproc_probe,
- };
-
-This allows for the device to be probed as part of the "init" command
-or invocation of 'rproc_init()' function as the system dependencies define.
-
-The driver is expected to maintain it's own statemachine which is
-appropriate for the device it maintains. It must, at the very least
-provide a load and start function. We assume here that the device
-needs to be loaded and started, else, there is no real purpose of
-using the remoteproc framework.
-
-Describing the device using platform data
------------------------------------------
-
-*IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
-SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION
-*WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED
-TO DM/FDT.
-
-Considering that many platforms are yet to move to device-tree model,
-a simplified definition of a device is as follows:
-
-.. code-block:: c
-
- struct dm_rproc_uclass_pdata proc_3_test = {
- .name = "proc_3_legacy",
- .mem_type = RPROC_INTERNAL_MEMORY_MAPPED,
- .driver_plat_data = &mydriver_data;
- };
-
- U_BOOT_DRVINFO(proc_3_demo) = {
- .name = "sandbox_test_proc",
- .plat = &proc_3_test,
- };
-
-There can be additional data that may be desired depending on the
-remoteproc driver specific needs (for example: SoC integration
-details such as clock handle or something similar). See appropriate
-documentation for specific remoteproc driver for further details.
-These are passed via driver_plat_data.
-
-Describing the device using device tree
----------------------------------------
-
-.. code-block: none
-
- / {
- ...
- aliases {
- ...
- remoteproc0 = &rproc_1;
- remoteproc1 = &rproc_2;
-
- };
- ...
-
- rproc_1: rproc@1 {
- compatible = "sandbox,test-processor";
- remoteproc-name = "remoteproc-test-dev1";
- };
-
- rproc_2: rproc@2 {
- compatible = "sandbox,test-processor";
- internal-memory-mapped;
- remoteproc-name = "remoteproc-test-dev2";
- };
- ...
- };
-
-aliases usage is optional, but it is usually recommended to ensure the
-users have a consistent usage model for a platform.
-the compatible string used here is specific to the remoteproc driver involved.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-How to port a serial driver to driver model
-===========================================
-
-Almost all of the serial drivers have been converted as at January 2016. These
-ones remain:
-
- * serial_bfin.c
- * serial_pxa.c
-
-The deadline for this work was the end of January 2016. If no one steps
-forward to convert these, at some point there may come a patch to remove them!
-
-Here is a suggested approach for converting your serial driver over to driver
-model. Please feel free to update this file with your ideas and suggestions.
-
-- #ifdef out all your own serial driver code (#ifndef CONFIG_DM_SERIAL)
-- Define CONFIG_DM_SERIAL for your board, vendor or architecture
-- If the board does not already use driver model, you need CONFIG_DM also
-- Your board should then build, but will not boot since there will be no serial
- driver
-- Add the U_BOOT_DRIVER piece at the end (e.g. copy serial_s5p.c for example)
-- Add a private struct for the driver data - avoid using static variables
-- Implement each of the driver methods, perhaps by calling your old methods
-- You may need to adjust the function parameters so that the old and new
- implementations can share most of the existing code
-- If you convert all existing users of the driver, remove the pre-driver-model
- code
-
-In terms of patches a conversion series typically has these patches:
-- clean up / prepare the driver for conversion
-- add driver model code
-- convert at least one existing board to use driver model serial
-- (if no boards remain that don't use driver model) remove the old code
-
-This may be a good time to move your board to use device tree also. Mostly
-this involves these steps:
-
-- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE
-- add your device tree files to arch/<arch>/dts
-- update the Makefile there
-- Add stdout-path to your /chosen device tree node if it is not already there
-- build and get u-boot-dtb.bin so you can test it
-- Your drivers can now use device tree
-- For device tree in SPL, define CONFIG_SPL_OF_CONTROL
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-.. (C) Copyright 2020
-.. Texas Instruments Incorporated - http://www.ti.com/
-
-SOC ID Framework
-================
-
-Introduction
-------------
-
-The driver-model SOC ID framework is able to provide identification
-information about a specific SoC in use at runtime, and also provide matching
-from a set of identification information from an array. This can be useful for
-enabling small quirks in drivers that exist between SoC variants that are
-impractical to implement using device tree flags. It is based on UCLASS_SOC.
-
-UCLASS_SOC:
- - drivers/soc/soc-uclass.c
- - include/soc.h
-
-Configuration:
- - CONFIG_SOC_DEVICE is selected by drivers as needed.
-
-Implementing a UCLASS_SOC provider
-----------------------------------
-
-The purpose of this framework is to allow UCLASS_SOC provider drivers to supply
-identification information about the SoC in use at runtime. The framework
-allows drivers to define soc_ops that return identification strings. All
-soc_ops need not be defined and can be left as NULL, in which case the
-framework will return -ENOSYS and not consider the value when doing an
-soc_device_match.
-
-It is left to the driver implementor to decide how the information returned is
-determined, but in general the same SOC should always return the same set of
-identifying information. Information returned must be in the form of a NULL
-terminated string.
-
-See include/soc.h for documentation of the available soc_ops and the intended
-meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for
-an example UCLASS_SOC provider driver.
-
-Using a UCLASS_SOC driver
--------------------------
-
-The framework provides the ability to retrieve and use the identification
-strings directly. It also has the ability to return a match from a list of
-different sets of SoC data using soc_device_match.
-
-An array of 'struct soc_attr' can be defined, each containing ID information
-for a specific SoC, and when passed to soc_device_match, the identifier values
-for each entry in the list will be compared against the values provided by the
-UCLASS_SOC driver that is in use. The first entry in the list that matches all
-non-null values will be returned by soc_device_match.
-
-An example of various uses of the framework can be found at test/dm/soc.c.
-
-Describing the device using device tree
----------------------------------------
-
-.. code-block:: none
-
- chipid: chipid {
- compatible = "sandbox,soc";
- };
-
-All that is required in a DT node is a compatible for a corresponding
-UCLASS_SOC driver.
+++ /dev/null
-.. 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_of_to_plat(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 -EINVAL;
- }
-
- 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,
- .of_to_plat = exynos_spi_of_to_plat,
- .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 <dm.h>
- #include <errno.h>
-
-
-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_plat {
- 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 of_to_plat() [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) = {
- ...
- .plat_auto = sizeof(struct exynos_spi_plat),
-
-
-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_of_to_plat(struct udevice *bus)
- {
- struct exynos_spi_plat *plat = bus->plat;
- 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_DRVINFO() declaration in your board file:
-
-.. code-block:: c
-
- struct exynos_spi_plat platdata_spi0 = {
- .periph_id = ...
- .frequency = ...
- .regs = ...
- .deactivate_delay_us = ...
- };
-
- U_BOOT_DRVINFO(board_spi0) = {
- .name = "exynos_spi",
- .plat = &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 = 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_plat *plat = dev_get_plat(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_plat *plat = bus->plat;
- 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_plat *pdata = dev_get_plat(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 = 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 -EINVAL if the supplied chip select is invalid, or 0 if it is valid.
-If you don't provide the cs_info() method, 0 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 tools/patman/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_plat:
- This is device_get_parent_plat(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.
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0+
-
-How USB works with driver model
-===============================
-
-Introduction
-------------
-
-Driver model USB support makes use of existing features but changes how
-drivers are found. This document provides some information intended to help
-understand how things work with USB in U-Boot when driver model is enabled.
-
-
-Enabling driver model for USB
------------------------------
-
-A new CONFIG_DM_USB option is provided to enable driver model for USB. This
-causes the USB uclass to be included, and drops the equivalent code in
-usb.c. In particular the usb_init() function is then implemented by the
-uclass.
-
-
-Support for EHCI and XHCI
--------------------------
-
-So far OHCI is not supported. Both EHCI and XHCI drivers should be declared
-as drivers in the USB uclass. For example:
-
-.. code-block:: c
-
- static const struct udevice_id ehci_usb_ids[] = {
- { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 },
- { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 },
- { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 },
- { }
- };
-
- U_BOOT_DRIVER(usb_ehci) = {
- .name = "ehci_tegra",
- .id = UCLASS_USB,
- .of_match = ehci_usb_ids,
- .of_to_plat = ehci_usb_of_to_plat,
- .probe = tegra_ehci_usb_probe,
- .remove = tegra_ehci_usb_remove,
- .ops = &ehci_usb_ops,
- .plat_auto = sizeof(struct usb_plat),
- .priv_auto = sizeof(struct fdt_usb),
- .flags = DM_FLAG_ALLOC_PRIV_DMA,
- };
-
-Here ehci_usb_ids is used to list the controllers that the driver supports.
-Each has its own data value. Controllers must be in the UCLASS_USB uclass.
-
-The of_to_plat() method allows the controller driver to grab any
-necessary settings from the device tree.
-
-The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in
-most cases, since they are all EHCI-compatible. For EHCI there are also some
-special operations that can be overridden when calling ehci_register().
-
-The driver can use priv_auto to set the size of its private data.
-This can hold run-time information needed by the driver for operation. It
-exists when the device is probed (not when it is bound) and is removed when
-the driver is removed.
-
-Note that usb_plat is currently only used to deal with setting up a bus
-in USB device mode (OTG operation). It can be omitted if that is not
-supported.
-
-The driver's probe() method should do the basic controller init and then
-call ehci_register() to register itself as an EHCI device. It should call
-ehci_deregister() in the remove() method. Registering a new EHCI device
-does not by itself cause the bus to be scanned.
-
-The old ehci_hcd_init() function is no-longer used. Nor is it necessary to
-set up the USB controllers from board init code. When 'usb start' is used,
-each controller will be probed and its bus scanned.
-
-XHCI works in a similar way.
-
-
-Data structures
----------------
-
-The following primary data structures are in use:
-
-- struct usb_device:
- This holds information about a device on the bus. All devices have
- this structure, even the root hub. The controller itself does not
- have this structure. You can access it for a device 'dev' with
- dev_get_parent_priv(dev). It matches the old structure except that the
- parent and child information is not present (since driver model
- handles that). Once the device is set up, you can find the device
- descriptor and current configuration descriptor in this structure.
-
-- struct usb_plat:
- This holds platform data for a controller. So far this is only used
- as a work-around for controllers which can act as USB devices in OTG
- mode, since the gadget framework does not use driver model.
-
-- struct usb_dev_plat:
- This holds platform data for a device. You can access it for a
- device 'dev' with dev_get_parent_plat(dev). It holds the device
- address and speed - anything that can be determined before the device
- driver is actually set up. When probing the bus this structure is
- used to provide essential information to the device driver.
-
-- struct usb_bus_priv:
- This is private information for each controller, maintained by the
- controller uclass. It is mostly used to keep track of the next
- device address to use.
-
-Of these, only struct usb_device was used prior to driver model.
-
-
-USB buses
----------
-
-Given a controller, you know the bus - it is the one attached to the
-controller. Each controller handles exactly one bus. Every controller has a
-root hub attached to it. This hub, which is itself a USB device, can provide
-one or more 'ports' to which additional devices can be attached. It is
-possible to power up a hub and find out which of its ports have devices
-attached.
-
-Devices are given addresses starting at 1. The root hub is always address 1,
-and from there the devices are numbered in sequence. The USB uclass takes
-care of this numbering automatically during enumeration.
-
-USB devices are enumerated by finding a device on a particular hub, and
-setting its address to the next available address. The USB bus stretches out
-in a tree structure, potentially with multiple hubs each with several ports
-and perhaps other hubs. Some hubs will have their own power since otherwise
-the 5V 500mA power supplied by the controller will not be sufficient to run
-very many devices.
-
-Enumeration in U-Boot takes a long time since devices are probed one at a
-time, and each is given sufficient time to wake up and announce itself. The
-timeouts are set for the slowest device.
-
-Up to 127 devices can be on each bus. USB has four bus speeds: low
-(1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2
-and newer (EHCI), and super (5Gbps) which is only available with USB3 and
-newer (XHCI). If you connect a super-speed device to a high-speed hub, you
-will only get high-speed.
-
-
-USB operations
---------------
-
-As before driver model, messages can be sent using submit_bulk_msg() and the
-like. These are now implemented by the USB uclass and route through the
-controller drivers. Note that messages are not sent to the driver of the
-device itself - i.e. they don't pass down the stack to the controller.
-U-Boot simply finds the controller to which the device is attached, and sends
-the message there with an appropriate 'pipe' value so it can be addressed
-properly. Having said that, the USB device which should receive the message
-is passed in to the driver methods, for use by sandbox. This design decision
-is open for review and the code impact of changing it is small since the
-methods are typically implemented by the EHCI and XHCI stacks.
-
-Controller drivers (in UCLASS_USB) themselves provide methods for sending
-each message type. For XHCI an additional alloc_device() method is provided
-since XHCI needs to allocate a device context before it can even read the
-device's descriptor.
-
-These methods use a 'pipe' which is a collection of bit fields used to
-describe the type of message, direction of transfer and the intended
-recipient (device number).
-
-
-USB Devices
------------
-
-USB devices are found using a simple algorithm which works through the
-available hubs in a depth-first search. Devices can be in any uclass, but
-are attached to a parent hub (or controller in the case of the root hub) and
-so have parent data attached to them (this is struct usb_device).
-
-By the time the device's probe() method is called, it is enumerated and is
-ready to talk to the host.
-
-The enumeration process needs to work out which driver to attach to each USB
-device. It does this by examining the device class, interface class, vendor
-ID, product ID, etc. See struct usb_driver_entry for how drivers are matched
-with USB devices - you can use the USB_DEVICE() macro to declare a USB
-driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage
-devices, and it will be used for all USB devices which match.
-
-
-
-Technical details on enumeration flow
--------------------------------------
-
-It is useful to understand precisely how a USB bus is enumerating to avoid
-confusion when dealing with USB devices.
-
-Device initialisation happens roughly like this:
-
-- At some point the 'usb start' command is run
-- This calls usb_init() which works through each controller in turn
-- The controller is probed(). This does no enumeration.
-- Then usb_scan_bus() is called. This calls usb_scan_device() to scan the
- (only) device that is attached to the controller - a root hub
-- usb_scan_device() sets up a fake struct usb_device and calls
- usb_setup_device(), passing the port number to be scanned, in this case
- port 0
-- usb_setup_device() first calls usb_prepare_device() to set the device
- address, then usb_select_config() to select the first configuration
-- at this point the device is enumerated but we do not have a real struct
- udevice for it. But we do have the descriptor in struct usb_device so we can
- use this to figure out what driver to use
-- back in usb_scan_device(), we call usb_find_child() to try to find an
- existing device which matches the one we just found on the bus. This can
- happen if the device is mentioned in the device tree, or if we previously
- scanned the bus and so the device was created before
-- if usb_find_child() does not find an existing device, we call
- usb_find_and_bind_driver() which tries to bind one
-- usb_find_and_bind_driver() searches all available USB drivers (declared
- with USB_DEVICE()). If it finds a match it binds that driver to create a
- new device.
-- If it does not, it binds a generic driver. A generic driver is good enough
- to allow access to the device (sending it packets, etc.) but all
- functionality will need to be implemented outside the driver model.
-- in any case, when usb_find_child() and/or usb_find_and_bind_driver() are
- done, we have a device with the correct uclass. At this point we want to
- probe the device
-- first we store basic information about the new device (address, port,
- speed) in its parent platform data. We cannot store it its private data
- since that will not exist until the device is probed.
-- then we call device_probe() which probes the device
-- the first probe step is actually the USB controller's (or USB hubs's)
- child_pre_probe() method. This gets called before anything else and is
- intended to set up a child device ready to be used with its parent bus. For
- USB this calls usb_child_pre_probe() which grabs the information that was
- stored in the parent platform data and stores it in the parent private data
- (which is struct usb_device, a real one this time). It then calls
- usb_select_config() again to make sure that everything about the device is
- set up
-- note that we have called usb_select_config() twice. This is inefficient
- but the alternative is to store additional information in the platform data.
- The time taken is minimal and this way is simpler
-- at this point the device is set up and ready for use so far as the USB
- subsystem is concerned
-- the device's probe() method is then called. It can send messages and do
- whatever else it wants to make the device work.
-
-Note that the first device is always a root hub, and this must be scanned to
-find any devices. The above steps will have created a hub (UCLASS_USB_HUB),
-given it address 1 and set the configuration.
-
-For hubs, the hub uclass has a post_probe() method. This means that after
-any hub is probed, the uclass gets to do some processing. In this case
-usb_hub_post_probe() is called, and the following steps take place:
-
-- usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn
- calls usb_hub_configure()
-- hub power is enabled
-- we loop through each port on the hub, performing the same steps for each
-- first, check if there is a device present. This happens in
- usb_hub_port_connect_change(). If so, then usb_scan_device() is called to
- scan the device, passing the appropriate port number.
-- you will recognise usb_scan_device() from the steps above. It sets up the
- device ready for use. If it is a hub, it will scan that hub before it
- continues here (recursively, depth-first)
-- once all hub ports are scanned in this way, the hub is ready for use and
- all of its downstream devices also
-- additional controllers are scanned in the same way
-
-The above method has some nice properties:
-
-- the bus enumeration happens by virtue of driver model's natural device flow
-- most logic is in the USB controller and hub uclasses; the actual device
- drivers do not need to know they are on a USB bus, at least so far as
- enumeration goes
-- hub scanning happens automatically after a hub is probed
-
-
-Hubs
-----
-
-USB hubs are scanned as in the section above. While hubs have their own
-uclass, they share some common elements with controllers:
-
-- they both attach private data to their children (struct usb_device,
- accessible for a child with dev_get_parent_priv(child))
-- they both use usb_child_pre_probe() to set up their children as proper USB
- devices
-
-
-Example - Mass Storage
-----------------------
-
-As an example of a USB device driver, see usb_storage.c. It uses its own
-uclass and declares itself as follows:
-
-.. code-block:: c
-
- U_BOOT_DRIVER(usb_mass_storage) = {
- .name = "usb_mass_storage",
- .id = UCLASS_MASS_STORAGE,
- .of_match = usb_mass_storage_ids,
- .probe = usb_mass_storage_probe,
- };
-
- static const struct usb_device_id mass_storage_id_table[] = {
- { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS,
- .bInterfaceClass = USB_CLASS_MASS_STORAGE},
- { } /* Terminating entry */
- };
-
- USB_DEVICE(usb_mass_storage, mass_storage_id_table);
-
-The USB_DEVICE() macro attaches the given table of matching information to
-the given driver. Note that the driver is declared in U_BOOT_DRIVER() as
-'usb_mass_storage' and this must match the first parameter of USB_DEVICE.
-
-When usb_find_and_bind_driver() is called on a USB device with the
-bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find
-this driver and use it.
-
-
-Counter-example: USB Ethernet
------------------------------
-
-As an example of the old way of doing things, see usb_ether.c. When the bus
-is scanned, all Ethernet devices will be created as generic USB devices (in
-uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed,
-usb_host_eth_scan() will be called. This looks through all the devices on
-each bus and manually figures out which are Ethernet devices in the ways of
-yore.
-
-In fact, usb_ether should be moved to driver model. Each USB Ethernet driver
-(e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so
-that it will be found as part of normal USB enumeration. Then, instead of a
-generic USB driver, a real (driver-model-aware) driver will be used. Since
-Ethernet now supports driver model, this should be fairly easy to achieve,
-and then usb_ether.c and the usb_host_eth_scan() will melt away.
-
-
-Sandbox
--------
-
-All driver model uclasses must have tests and USB is no exception. To
-achieve this, a sandbox USB controller is provided. This can make use of
-emulation drivers which pretend to be USB devices. Emulations are provided
-for a hub and a flash stick. These are enough to create a pretend USB bus
-(defined by the sandbox device tree sandbox.dts) which can be scanned and
-used.
-
-Tests in test/dm/usb.c make use of this feature. It allows much of the USB
-stack to be tested without real hardware being needed.
-
-Here is an example device tree fragment:
-
-.. code-block:: none
-
- usb@1 {
- compatible = "sandbox,usb";
- hub {
- compatible = "usb-hub";
- usb,device-class = <USB_CLASS_HUB>;
- hub-emul {
- compatible = "sandbox,usb-hub";
- #address-cells = <1>;
- #size-cells = <0>;
- flash-stick {
- reg = <0>;
- compatible = "sandbox,usb-flash";
- sandbox,filepath = "flash.bin";
- };
- };
- };
- };
-
-This defines a single controller, containing a root hub (which is required).
-The hub is emulated by a hub emulator, and the emulated hub has a single
-flash stick to emulate on one of its ports.
-
-When 'usb start' is used, the following 'dm tree' output will be available::
-
- usb [ + ] `-- usb@1
- usb_hub [ + ] `-- hub
- usb_emul [ + ] |-- hub-emul
- usb_emul [ + ] | `-- flash-stick
- usb_mass_st [ + ] `-- usb_mass_storage
-
-
-This may look confusing. Most of it mirrors the device tree, but the
-'usb_mass_storage' device is not in the device tree. This is created by
-usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While
-'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot
-USB device driver that talks to it.
-
-
-Future work
------------
-
-It is pretty uncommon to have a large USB bus with lots of hubs on an
-embedded system. In fact anything other than a root hub is uncommon. Still
-it would be possible to speed up enumeration in two ways:
-
-- breadth-first search would allow devices to be reset and probed in
- parallel to some extent
-- enumeration could be lazy, in the sense that we could enumerate just the
- root hub at first, then only progress to the next 'level' when a device is
- used that we cannot find. This could be made easier if the devices were
- statically declared in the device tree (which is acceptable for production
- boards where the same, known, things are on each bus).
-
-But in common cases the current algorithm is sufficient.
-
-Other things that need doing:
-- Convert usb_ether to use driver model as described above
-- Test that keyboards work (and convert to driver model)
-- Move the USB gadget framework to driver model
-- Implement OHCI in driver model
-- Implement USB PHYs in driver model
-- Work out a clever way to provide lazy init for USB devices
-
-
-.. 23-Mar-15
develop/index
-Driver-Model documentation
---------------------------
-
-The following holds information on the U-Boot device driver framework:
-driver-model, including the design details of itself and several driver
-subsystems.
-
-.. toctree::
- :maxdepth: 2
-
- driver-model/index
U-Boot API documentation
------------------------
projects / J-u-boot.git / commitdiff